From c6814264f108e78fab8340520945927375265768 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Mon, 14 Sep 2026 20:23:51 +0000 Subject: [PATCH] Fix CodeRabbit issues in PR #783 --- RSR-PHILOSOPHY.adoc | 66 ++++++++++++------- ai-instruction/opus.adoc | 2 +- ai-instruction/sonnet.adoc | 2 +- docs/DEBTFILE-SPEC.adoc | 25 +++++++ scripts/check-debtfile-structure.sh | 28 +++++++- scripts/tests/debtfile-structure-test.sh | 59 +++++++++++++++++ scripts/tests/run-debtfile-test.sh | 19 ++++++ .../TESTING-TAXONOMY.adoc | 9 ++- 8 files changed, 182 insertions(+), 28 deletions(-) diff --git a/RSR-PHILOSOPHY.adoc b/RSR-PHILOSOPHY.adoc index fa258f098..1b4fa9bb0 100644 --- a/RSR-PHILOSOPHY.adoc +++ b/RSR-PHILOSOPHY.adoc @@ -5,11 +5,14 @@ :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. 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,11 +44,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 three siblings: *holes before goals*, *always fail -loudly*, and *elegance by default*. Together they govern the order of work (holes -first), the manner of work (loudly, never silently green), the locus of work (at the -source, never the symptom), and the standard of work (the elegant, long-term-correct -arm, named even where it is not the arm taken). +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 @@ -62,6 +66,21 @@ 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.* @@ -74,11 +93,13 @@ justified by the construction that produced it. Three obligations follow, and none is optional: -. *Label it.* Exactly one option is marked as the elegant and correct long-term arm. - 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. If two options genuinely tie, say so explicitly; silence is not - a tie. +. *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 @@ -96,13 +117,14 @@ in ignorance that it was the expedient one. 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 four 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 diff --git a/ai-instruction/opus.adoc b/ai-instruction/opus.adoc index ee950ed46..a2439f768 100644 --- a/ai-instruction/opus.adoc +++ b/ai-instruction/opus.adoc @@ -196,7 +196,7 @@ 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 -`+standards/RSR-PHILOSOPHY.adoc+`, _Elegance by default_. +`+RSR-PHILOSOPHY.adoc+`, _Elegance by default_. === Trust level & verification diff --git a/ai-instruction/sonnet.adoc b/ai-instruction/sonnet.adoc index 38e1ae70f..dba0ebc8a 100644 --- a/ai-instruction/sonnet.adoc +++ b/ai-instruction/sonnet.adoc @@ -141,7 +141,7 @@ 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 -`+standards/RSR-PHILOSOPHY.adoc+`, _Elegance by default_. +`+RSR-PHILOSOPHY.adoc+`, _Elegance by default_. === Trust level & verification diff --git a/docs/DEBTFILE-SPEC.adoc b/docs/DEBTFILE-SPEC.adoc index 64e89c612..253e2e892 100644 --- a/docs/DEBTFILE-SPEC.adoc +++ b/docs/DEBTFILE-SPEC.adoc @@ -105,11 +105,19 @@ Location: `.machine_readable/Debtfile.a2ml`, one per repository. - policy: remediable | flag-only - tri: eliminate | substitute | control (optional, Safety Triangle) - tracking: (optional) +- taxonomy-choice: non-default (required for a testing-taxonomy departure) +- taxonomy-default-arm: +- taxonomy-non-default-arm: +- taxonomy-departure-reason: - accepted-until: YYYY-MM-DD ---- `##
` 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 @@ -133,6 +141,23 @@ identifiers or reverted owner decisions. 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 diff --git a/scripts/check-debtfile-structure.sh b/scripts/check-debtfile-structure.sh index 4c477476c..f48d8f83e 100755 --- a/scripts/check-debtfile-structure.sh +++ b/scripts/check-debtfile-structure.sh @@ -45,6 +45,7 @@ entries=0 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; } @@ -90,6 +91,20 @@ validate() { *) 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 +115,10 @@ validate() { 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 +129,14 @@ while IFS= read -r raw || [ -n "$raw" ]; do '- 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" diff --git a/scripts/tests/debtfile-structure-test.sh b/scripts/tests/debtfile-structure-test.sh index c762e7fbd..610ef8aba 100755 --- a/scripts/tests/debtfile-structure-test.sh +++ b/scripts/tests/debtfile-structure-test.sh @@ -75,6 +75,65 @@ expect 0 "count below ceiling is fine (debt paid down, ceiling not yet lowered)" - accepted-until: 2030-01-01 EOF +expect 0 "a complete testing-taxonomy departure records both arms and its reason" <<'EOF' +### alpha +- description: a temporary local test is tolerated +- probe: echo 2 +- count: 2 +- ceiling: 4 +- severity: high +- policy: remediable +- taxonomy-choice: non-default +- taxonomy-default-arm: adapt the proven Idris2 test +- taxonomy-non-default-arm: retain the temporary local test +- taxonomy-departure-reason: upstream fixture is gated on the next release +- accepted-until: 2030-01-01 +EOF + +expect 1 "a partial testing-taxonomy choice record is rejected" <<'EOF' +### alpha +- description: a temporary local test is tolerated +- probe: echo 2 +- count: 2 +- ceiling: 4 +- severity: high +- policy: remediable +- taxonomy-choice: non-default +- taxonomy-default-arm: adapt the proven Idris2 test +- taxonomy-non-default-arm: retain the temporary local test +- accepted-until: 2030-01-01 +EOF + +expect 1 "testing-taxonomy default and non-default arms must differ" <<'EOF' +### alpha +- description: a temporary local test is tolerated +- probe: echo 2 +- count: 2 +- ceiling: 4 +- severity: high +- policy: remediable +- taxonomy-choice: non-default +- taxonomy-default-arm: retain the local test +- taxonomy-non-default-arm: retain the local test +- taxonomy-departure-reason: no actual departure was named +- accepted-until: 2030-01-01 +EOF + +expect 1 "an unknown taxonomy-choice selector is rejected" <<'EOF' +### alpha +- description: a temporary local test is tolerated +- probe: echo 2 +- count: 2 +- ceiling: 4 +- severity: high +- policy: remediable +- taxonomy-choice: convenient +- taxonomy-default-arm: adapt the proven Idris2 test +- taxonomy-non-default-arm: retain the temporary local test +- taxonomy-departure-reason: upstream fixture is gated on the next release +- accepted-until: 2030-01-01 +EOF + expect 1 "a non-integer count is rejected" <<'EOF' ### alpha - description: d diff --git a/scripts/tests/run-debtfile-test.sh b/scripts/tests/run-debtfile-test.sh index d713f9024..60c5787f9 100755 --- a/scripts/tests/run-debtfile-test.sh +++ b/scripts/tests/run-debtfile-test.sh @@ -80,6 +80,25 @@ else fail=$((fail+1)); echo " FAIL --write did not ratchet down"; sed -n '1,20p' Debtfile.a2ml fi +# Governance metadata validated by check-debtfile-structure.sh is opaque to the +# runner and must survive its targeted count/ceiling rewrite unchanged. +entry 'echo 2' 4 4 > Debtfile.a2ml +cat >> Debtfile.a2ml <<'EOF' +- taxonomy-choice: non-default +- taxonomy-default-arm: adapt the proven Idris2 test +- taxonomy-non-default-arm: retain the temporary local test +- taxonomy-departure-reason: upstream fixture is gated on the next release +EOF +bash "$SCRIPT" --write Debtfile.a2ml >/dev/null 2>&1 || true +if grep -q '^- taxonomy-choice: non-default$' Debtfile.a2ml \ + && grep -q '^- taxonomy-default-arm: adapt the proven Idris2 test$' Debtfile.a2ml \ + && grep -q '^- taxonomy-non-default-arm: retain the temporary local test$' Debtfile.a2ml \ + && grep -q '^- taxonomy-departure-reason: upstream fixture is gated on the next release$' Debtfile.a2ml; then + pass=$((pass+1)); echo " ok --write preserves testing-taxonomy choice metadata" +else + fail=$((fail+1)); echo " FAIL --write changed testing-taxonomy choice metadata"; sed -n '1,24p' Debtfile.a2ml +fi + entry 'echo 9' 4 4 > Debtfile.a2ml bash "$SCRIPT" --write Debtfile.a2ml >/dev/null 2>&1 || true if grep -q '^- ceiling: 4$' Debtfile.a2ml; then diff --git a/testing-and-benchmarking/TESTING-TAXONOMY.adoc b/testing-and-benchmarking/TESTING-TAXONOMY.adoc index 493f7ed0b..0962c6a4d 100644 --- a/testing-and-benchmarking/TESTING-TAXONOMY.adoc +++ b/testing-and-benchmarking/TESTING-TAXONOMY.adoc @@ -82,9 +82,12 @@ Judge elegance on long-run grounds only: correctness, absence of deferred breaka special cases, and a fix at the generator rather than at the instance. Never on how quickly a category can be marked satisfied. Where the other arm is taken, record both arms and the reason for departing — in the `Debtfile` where a shortfall is being -tolerated, in the N/A justification where the category is being declined. An -unlabelled choice between a sound test and a convenient one is how a suite quietly -becomes evidence for something nobody checked. +tolerated, using the required `taxonomy-choice`, `taxonomy-default-arm`, +`taxonomy-non-default-arm`, and `taxonomy-departure-reason` encoding defined in +link:../docs/DEBTFILE-SPEC.adoc#testing-taxonomy-choice[Debtfile Specification: +Testing-taxonomy choice encoding]; or in the N/A justification where the category +is being declined. An unlabelled choice between a sound test and a convenient one is +how a suite quietly becomes evidence for something nobody checked. This is the estate doctrine _elegance by default_ applied to testing; see link:../RSR-PHILOSOPHY.adoc[`RSR-PHILOSOPHY.adoc`].