docs: propose "elegance by default" as the fourth operating principle (PROPOSAL — owner ratification)

EXPLAINME.adoc

@@ -52,6 +52,8 @@ link:REGISTRY.adoc[REGISTRY.adoc]).
 
 | Guix-first package management
 | Reproducible builds via Guix.
+| Elegance is the default arm (proposed)
+| Provisional methodology pending the ratification record in link:RSR-PHILOSOPHY.adoc[RSR-PHILOSOPHY.adoc]; it is not yet an effective architecture decision.
 |===
 
 == How to use this repo

RSR-PHILOSOPHY.adoc

@@ -5,11 +5,18 @@
 :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.
+This is the *canonical* statement of the ratified 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 _Elegance by default_ section below is an explicitly non-canonical
+proposal and is excluded from that projection until its recorded ratification is
+complete.
+
+Material explicitly marked *PROVISIONAL* is a proposal within this otherwise
+canonical document. It is not operating doctrine and must not be projected into
+`CLAUDE.md` until its ratification record is complete.
 
 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.
@@ -41,10 +48,12 @@ own, a change gated on owner ratification — remediate the downstream *and* rec
 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).
+This principle stands beside its two ratified 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). A proposed fourth principle, *elegance by default*, follows;
+it has no canonical force unless and until the proposal record shows completed
+ratification.
 
 == Holes before goals
 
@@ -59,17 +68,67 @@ No silent green. A check that cannot fail is not a check; a fallback that hides
 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.
 
+== Elegance by default
+
+[IMPORTANT]
+====
+*Proposal status — not canonical.*
+
+* *Owner decision:* Pending ratification. The 2026-09-14 owner instruction
+  authorised drafting this proposal, not its adoption as permanent policy.
+* *Dissent:* Pending the required contest and review period; no completed dissent
+  record exists yet.
+* *Effective version/hash:* Not assigned.
+* *Propagation:* This principle MUST NOT be treated as canonical or added to the
+  estate-common `CLAUDE.md` policy until the owner decision, dissent, effective
+  version/hash, superseded material, and migration limits are recorded under
+  `constitution/CHANGE-PROCEDURE.adoc`.
+====
+
+*Treat the most elegant and correct long-term solution as the default choice — and say
+which option that is, every time a choice is put to the owner.*
+
+A set of options presented as merely _different_ is not neutral. Whichever option is
+listed first, or described most fluently, becomes the recommendation whether or not
+anyone intended it — so an unlabelled list quietly substitutes the convenience of
+whoever wrote it for the standard the estate is held to. That is the same category error
+as a symptom patched in place of a source: a choice backed by authority rather than
+justified by the construction that produced it.
+
+Three obligations follow, and none is optional:
+
+. *Label it.* When there is one elegant and correct long-term arm, mark exactly that
+  option *Elegant arm*. If two or more options genuinely tie, mark every tied option
+  *Elegant arm (tie)* and state explicitly that they are co-equal on the long-run
+  criteria; do not give any tied option the unqualified label. Elegance is judged on
+  long-run grounds alone — correctness, no deferred breakage, no special cases, fixing
+  the generator rather than the instance — and never on effort, speed, or convenience.
+  A close call is not a tie, and silence is never a tie.
+. *Justify any departure.* A recommendation that is not the elegant arm must name both
+  arms and state, in the offer itself, why the departure is made on this occasion — an
+  irreversible step already taken, a live outage, a precondition still gated. An
+  unexplained departure is a defect in the question, not a matter of style. The two
+  labels are never merged to avoid having to write the explanation.
+. *It binds unasked decisions too.* This is a methodology, not a formatting rule for
+  questions. Where the non-elegant arm is taken without asking, that is reported, not
+  absorbed.
+
+The default is a *starting point, not a prediction*. The owner may take the other arm
+with full information, and often will; what may not happen is an expedient choice made
+in ignorance that it was the expedient one.
+
 == 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.
+addition to the three ratified 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. _Elegance by default_ joins
+this list only after the proposal record above is complete.
 
 == See also
 

ai-instruction/opus.adoc

@@ -187,6 +187,16 @@ releases).
 `+standards/session-management-standards+`, flip TaskCreate
 `+activeForm+` to `+CLOSING DOWN — <repo>+` and end the final message
 with literal `+SAFE TO CLOSE+` on its own line.
+. *Elegance is the default arm.* Every choice put to Jonathan must LABEL
+which option is the most elegant and correct long-term one, judged on
+long-run grounds alone — correctness, no deferred breakage, no special
+cases, fixing the generator rather than the instance — and never on
+effort, speed, or convenience. Where your recommendation differs, name
+both arms and state in the offer itself why you depart on this occasion;
+an unexplained departure is a defect in the question, not a matter of
+style. This binds unasked design calls too: where you take the
+non-elegant arm without asking, report it rather than absorb it. See
+`+RSR-PHILOSOPHY.adoc+`, _Elegance by default_.
 
 === Trust level & verification
 

ai-instruction/sonnet.adoc

@@ -134,6 +134,14 @@ integration boundary works end-to-end before moving on.
 . *No stubbing by default* — wire it through; do not leave
 `+unimplemented!()+` / `+todo!()+` / placeholder returns unless the
 prompter explicitly said to stub.
+. *Elegance is the default arm.* The companion to "`Ask, don’t
+invent`": where you must choose, do not choose silently. Name the option
+that is most elegant and correct in the long run — judged on
+correctness and the absence of deferred breakage, never on which is
+quickest — and where you take a different one, say which and why. A
+design decision recorded without the arm it rejected is exactly the
+plausible-looking fabrication the rule above warns about. See
+`+RSR-PHILOSOPHY.adoc+`, _Elegance by default_.
 
 === Trust level & verification
 

docs/DEBTFILE-SPEC.adoc

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MPL-2.0
 = Debtfile Specification
 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-v1.0.0, 2026-08-07
+v1.1.0, 2026-09-14
 :toc:
 :toclevels: 3
 
@@ -105,11 +105,19 @@ Location: `.machine_readable/Debtfile.a2ml`, one per repository.
 - policy: remediable | flag-only
 - tri: eliminate | substitute | control      (optional, Safety Triangle)
 - tracking: <owner/repo#N>                   (optional)
+- taxonomy-choice: non-default               (required for a testing-taxonomy departure)
+- taxonomy-default-arm: <long-term-correct arm>
+- taxonomy-non-default-arm: <tolerated arm actually chosen>
+- taxonomy-departure-reason: <why the non-default arm is being tolerated>
 - accepted-until: YYYY-MM-DD
 ----
 
 `## <Section>` headings group entries and are otherwise ignored.
 
+The four `taxonomy-*` fields are required together only when an entry records a
+departure under `testing-and-benchmarking/TESTING-TAXONOMY.adoc`; otherwise omit
+all four.
+
 === Fields
 
 `probe`:: A shell command emitting one non-negative integer on stdout. This is
@@ -129,10 +137,44 @@ per the standing owner directive in `.claude/CLAUDE.md`: licence changes are
 manual, per-file and owner-only, and every prior bulk sweep scrambled
 identifiers or reverted owner decisions.
 
+`taxonomy-default-arm`, `taxonomy-selected-arm`, `taxonomy-departure-reason`::
+The required, machine-checkable encoding for an entry that records a testing
+taxonomy choice. The first two fields are stable identifiers matching
+`[a-z0-9][a-z0-9._-]*`; they record the elegant long-term arm and the different
+arm actually selected. `taxonomy-departure-reason` records why the non-default
+arm is accepted on this occasion. All three fields must appear together, the
+two arm identifiers must differ, and the reason must be non-empty. Neither
+`description` nor `tracking` substitutes for any member of this group: those
+fields continue to describe the debt and point to its external work item.
+
+[source]
+----
+- taxonomy-default-arm: adapt-proven-idris2-test
+- taxonomy-selected-arm: write-local-test
+- taxonomy-departure-reason: the proven suite cannot yet exercise this host API
+----
+
 `accepted-until`:: An expiry. Once passed, the entry fails the runner even while
 holding under its ceiling. Debt without an expiry is debt nobody revisits — the
 697-issue pile is what that looks like.
 
+[[testing-taxonomy-choice]]
+=== Testing-taxonomy choice encoding
+
+A Debtfile entry that tolerates the non-default arm of a testing-taxonomy choice
+MUST use the dedicated `taxonomy-*` fields shown above. `taxonomy-choice` is the
+literal `non-default`; `taxonomy-default-arm` names the elegant, long-term-correct
+arm; `taxonomy-non-default-arm` names the different arm actually chosen; and
+`taxonomy-departure-reason` states why that departure is being tolerated now.
+
+These values MUST NOT be hidden in `description` or `tracking`: those fields
+describe the debt and point to its work item, respectively, and neither identifies
+the rejected arm unambiguously. The structural validator rejects a partial choice
+record, an unknown `taxonomy-choice` value, empty arm or reason values, and identical
+default and non-default arms. The runner does not interpret this governance
+metadata; its `--write` pass preserves it unchanged while updating only `count` and
+`ceiling`.
+
 [[probe-discipline]]
 == Probe discipline
 
@@ -326,7 +368,7 @@ just debt-ratchet-down    # re-measure and write back (lowers ceilings only)
 Three suites under `scripts/tests/`, discovered automatically by
 `.github/workflows/self-test.yml`:
 
-* `debtfile-structure-test.sh` — 14 cases
+* `debtfile-structure-test.sh` — 19 cases
 * `run-debtfile-test.sh` — 16 cases
 * `debt-ratchet-test.sh` — 12 cases
 

scripts/check-debtfile-structure.sh

@@ -45,11 +45,13 @@
 seen_ids=" "
 
 name="" probe="" count="" ceiling="" severity="" policy="" accepted=""
+taxonomy_seen=0 taxonomy_choice="" taxonomy_default="" taxonomy_non_default="" taxonomy_reason=""
 
 note() { printf '  %s\n' "$*"; }
 bad()  { printf '  ❌ %s\n' "$*"; fail=1; }
 
 is_uint() { case "${1:-}" in ''|*[!0-9]*) return 1;; *) return 0;; esac; }
+has_nonspace() { case "${1:-}" in *[![:space:]]*) return 0;; *) return 1;; esac; }
 
 validate() {
   [ -n "$name" ] || return 0
@@ -90,6 +92,20 @@
     *)  bad "'$name' policy '$policy' is not one of remediable|flag-only" ;;
   esac
 
+  if [ "$taxonomy_seen" -ne 0 ]; then
+    case "$taxonomy_choice" in
+      non-default) ;;
+      '') bad "'$name' has taxonomy choice fields but no '- taxonomy-choice: non-default'" ;;
+      *)  bad "'$name' taxonomy-choice '$taxonomy_choice' is not 'non-default'" ;;
+    esac
+    [ -n "$taxonomy_default" ] || bad "'$name' has no '- taxonomy-default-arm:'"
+    [ -n "$taxonomy_non_default" ] || bad "'$name' has no '- taxonomy-non-default-arm:'"
+    [ -n "$taxonomy_reason" ] || bad "'$name' has no '- taxonomy-departure-reason:'"
+    if [ -n "$taxonomy_default" ] && [ "$taxonomy_default" = "$taxonomy_non_default" ]; then
+      bad "'$name' taxonomy-default-arm and taxonomy-non-default-arm must name different arms"
+    fi
+  fi
+
   if [ -n "$accepted" ]; then
     case "$accepted" in
       [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]) ;;
@@ -100,7 +116,10 @@
   fi
 }
 
-reset_block() { name="$1"; probe=""; count=""; ceiling=""; severity=""; policy=""; accepted=""; }
+reset_block() {
+  name="$1"; probe=""; count=""; ceiling=""; severity=""; policy=""; accepted=""
+  taxonomy_seen=0; taxonomy_choice=""; taxonomy_default=""; taxonomy_non_default=""; taxonomy_reason=""
+}
 
 while IFS= read -r raw || [ -n "$raw" ]; do
   line="${raw#"${raw%%[![:space:]]*}"}"
@@ -111,6 +130,14 @@
     '- ceiling: '*)       ceiling="${line#- ceiling: }" ;;
     '- severity: '*)      severity="${line#- severity: }" ;;
     '- policy: '*)        policy="${line#- policy: }" ;;
+    '- taxonomy-choice:'*)
+                           taxonomy_seen=1; taxonomy_choice="${line#- taxonomy-choice:}"; taxonomy_choice="${taxonomy_choice# }" ;;
+    '- taxonomy-default-arm:'*)
+                           taxonomy_seen=1; taxonomy_default="${line#- taxonomy-default-arm:}"; taxonomy_default="${taxonomy_default# }" ;;
+    '- taxonomy-non-default-arm:'*)
+                           taxonomy_seen=1; taxonomy_non_default="${line#- taxonomy-non-default-arm:}"; taxonomy_non_default="${taxonomy_non_default# }" ;;
+    '- taxonomy-departure-reason:'*)
+                           taxonomy_seen=1; taxonomy_reason="${line#- taxonomy-departure-reason:}"; taxonomy_reason="${taxonomy_reason# }" ;;
     '- accepted-until: '*) accepted="${line#- accepted-until: }" ;;
   esac
 done < "$DEBT"