diff --git a/0-canon/RSR-PHILOSOPHY.adoc b/0-canon/RSR-PHILOSOPHY.adoc index 55b6bb507..a36afd193 100644 --- a/0-canon/RSR-PHILOSOPHY.adoc +++ b/0-canon/RSR-PHILOSOPHY.adoc @@ -80,6 +80,10 @@ not assumed. Prefer a build that breaks to a build that lies. * *Dissent:* Pending the required contest and review period; no completed dissent record exists yet. * *Effective version/hash:* Not assigned. +* *Proposal record:* `docs/decisions/ADR-007-elegance-by-default.adoc` — opened + retroactively on 2026-09-30, because this principle is already projected as + arrival-pack rule 15 (see the `contradiction` row in + `0-canon/constitution/KNOWN-TENSIONS.adoc`). * *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 diff --git a/docs/decisions/ADR-006-always-leave-it-working.adoc b/docs/decisions/ADR-006-always-leave-it-working.adoc index f1aea3d44..a8cb1b649 100644 --- a/docs/decisions/ADR-006-always-leave-it-working.adoc +++ b/docs/decisions/ADR-006-always-leave-it-working.adoc @@ -163,11 +163,12 @@ tensions register. estate: the bun migration, the signing campaign and the A2ML retirement are all that shape. Proposed containment: declare the shim cost before the cutover starts, or record the exception. -. *An enforced weekly version jump is a deadlock generator while `Immutable-Tags` - stands.* Four `hyperpolymath` repositories currently carry a ruleset with the `creation` - rule and an empty `bypass_actors` list, meaning no tag can be cut by anyone, the owner - included. A version-jump obligation on those repositories is unsatisfiable until that - is repaired (tracked as R9.2). *Ratification must not precede that repair.* +. *The `Immutable-Tags` blocker is resolved.* Before the repair, four `hyperpolymath` + repositories carried a ruleset with the `creation` rule and an empty `bypass_actors` + list, meaning no tag could be cut by anyone, the owner included. A version-jump + obligation was therefore unsatisfiable (tracked as R9.2). The 2026-09-23 repair and + 2026-09-30 confirmations recorded in step 6 satisfy that ratification precondition; + step 6 itself remains owed. == Enforcement — no new mechanism is proposed @@ -175,8 +176,8 @@ Both halves already have teeth, and inventing a hook would duplicate them: * *"Leave it working"* is enforced by the green-default-branch rulesets already armed on `standards` (23787415) and propagating under R5/R9. -* *"Jump to the next version"* is enforced by the R9 tag floor — *subject to the - `Immutable-Tags` repair above*. +* *"Jump to the next version"* is enforced by the R9 tag floor — the `Immutable-Tags` + repair precondition is met, as recorded in step 6. == Machine-readable impact — the exact projection delta @@ -208,5 +209,5 @@ projected as rule 15 while the canon states it must not be. |3. Review by the named constitutional authority and affected domain maintainers |owed — owner |4. Meaningful contest period; answer recorded challenges |owed |5. Record decision, dissent, effective version/hash, superseded material, migration limits |owed -|6. Regenerate derived registries; prove deterministic regeneration; merge after authorised review |owed — and blocked on the `Immutable-Tags` repair +|6. Regenerate derived registries; prove deterministic regeneration; merge after authorised review |owed. The `Immutable-Tags` precondition is *met*: all four repositories were repaired on 2026-09-23 (the owner-admin role and the integration `standards` already trusts were added as tag-ruleset bypass actors), and on 2026-09-30 each re-read `current_user_can_bypass = always`; `launch-scaffolder` has since cut `v0.1.0` |=== diff --git a/docs/decisions/ADR-007-elegance-by-default.adoc b/docs/decisions/ADR-007-elegance-by-default.adoc new file mode 100644 index 000000000..51f063156 --- /dev/null +++ b/docs/decisions/ADR-007-elegance-by-default.adoc @@ -0,0 +1,157 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) 2026 Jonathan D.A. Jewell += ADR-007: Elegance by default — retroactive ratification record (PROPOSAL) +:toc: preamble + +[cols="1,4"] +|=== +| Status | *Proposed* — step 1 of `0-canon/constitution/CHANGE-PROCEDURE.adoc`, opened *retroactively*. Not adopted. +| Date | 2026-09-30 +| Supersedes | nothing +| Authority sought | normative (an operating principle in `0-canon/RSR-PHILOSOPHY.adoc`), with projection into estate-common `CLAUDE.md` doctrine as arrival-pack rule 15 +|=== + +This record is *retroactive*. Unlike ADR-006, which opened its proposal before any +projection, _Elegance by default_ is already emitted into every generated `CLAUDE.md` +as arrival-pack rule 15, while the canon marks it *PROVISIONAL* and forbids that +projection. `0-canon/constitution/KNOWN-TENSIONS.adoc` records the disagreement as a +`contradiction` (severity *high*, status *measured*) and names two exits: complete the +ratification record, or remove rule 15 and regenerate. + +On 2026-09-23 the owner chose the first exit — *ratify it properly* — via the selection +UI (estate ruling ledger D209, posted to `standards#787`). This document is step 1 of +that. Steps 3–6 are *not* performed here and remain owed. + +== The request + +The principle originates in a repeated owner instruction, first recorded 2026-09-14: +the most elegant and correct long-term option is the default arm, and every choice put +to the owner must say which option that is. The 2026-09-14 instruction authorised +*drafting* the principle; it did not complete the procedure that makes a principle +canonical. The projection into rule 15 then ran ahead of the record. + +== Context — the problem being solved + +A choice presented to the owner as a list of merely _different_ options is not neutral: +whichever option is listed first or described most fluently becomes the +recommendation. Without a rule, the convenience of whoever wrote the question +substitutes for the long-run standard the estate is held to. The canonical text in +`RSR-PHILOSOPHY.adoc` states the three obligations (label it; justify any departure; +it binds unasked decisions too) and is not restated here. + +The *procedural* problem this ADR solves is narrower: the estate currently asserts two +incompatible things about the same principle. Every visiting agent reads rule 15 as +doctrine; the canon says it is not doctrine. A validator passing on either side does +not resolve that. + +== Decision proposed + +. Ratify _Elegance by default_ as an operating principle, with the canonical wording + currently in `0-canon/RSR-PHILOSOPHY.adoc` § _Elegance by default_ unchanged. +. On ratification, replace that section's *Proposal status — not canonical* banner with + the step-5 record (decision, dissent, effective version/hash, superseded material, + migration limits). +. Keep arrival-pack rule 15 as it is. It is the projection this ratification + authorises; no text change to `arrival-pack.ncl` is proposed. +. Close the KNOWN-TENSIONS `contradiction` row, citing the step-5 record. + +== Rationale + +* *The owner has already chosen this exit.* The KNOWN-TENSIONS row offers ratification + or removal; D209 selected ratification. Removing a rule the owner has ruled to keep, + only to re-add it after the record completes, would be two regenerations of every + downstream `CLAUDE.md` to arrive where the estate already stands. +* *The rule is exercised, not aspirational.* Agent sessions in this estate already + label the elegant arm in owner-facing choices and justify departures in the question + itself; the estate ruling ledger records owner selections made from labelled options + (for example D207 in `standards#787`, 2026-09-30). The procedure is catching up with + established practice, not introducing new behaviour. +* *It closes a soundness hole of the canon's own kind.* A canon that says "not + doctrine" beside a generator that emits it as doctrine is a check that cannot fail in + either direction — _always fail loudly_ applied to governance. + +== Alternatives considered + +[cols="1,3,2",options="header"] +|=== +|Alternative |Description |Why not + +|Remove rule 15 and regenerate +|The other KNOWN-TENSIONS exit: stop projecting until ratified. +|Procedurally clean, but contradicts the owner's recorded choice (D209) and costs two + estate-wide regenerations. Retained as the fallback if the contest period (step 4) + produces an unanswered challenge. + +|Status quo +|Leave the canon and the projection in disagreement. +|Explicitly forbidden by the KNOWN-TENSIONS row ("do not leave the two in + disagreement"). Rejected. + +|Ratify a narrower rule (owner-facing questions only) +|Drop obligation 3 ("binds unasked decisions too"). +|Obligation 3 is what stops the rule degrading into a formatting convention for + questions; an expedient choice taken silently is the case the principle exists to + surface. Offered for the contest period, not recommended. +|=== + +== Compatibility + +* *With _solutions at source_:* the same category of reasoning — a choice justified by + construction, not by who wrote it. Compatible. +* *With _holes before goals_ and _always fail loudly_:* compatible. Neither governs how + options are offered. +* *With ADR-006 _Always leave it working_:* compatible. ADR-006 governs the state work + is left in; this governs how choices are put. ADR-006 cites this contradiction as the + precedent its own projection delta must not repeat. +* *With the `manifesto`:* the manifesto prevails on wording. The estate-common block + carries `manifesto_pin = "DRAFT-unratified"` as a whole; ratifying this principle does + not by itself lift that pin, which is a separate decision. + +== Evidence status + +*Assumed, not measured.* That labelled choices produce better long-run outcomes than +unlabelled ones is reasoned, not measured against a control. What *is* measured is the +contradiction itself (KNOWN-TENSIONS status `measured`) and the projection's presence: +rule 15 is in `rsr-template-repo` `.machine_readable/arrival-pack/arrival-pack.ncl` at +`7cb285f` (2026-09-17) and later (15 numbered rules, rule 15 = _Elegance by default_), and +absent at `a983c00` (2026-08-26), where the same file lived at +`machine-readable/arrival-pack/arrival-pack.ncl` (6076 bytes, 14 numbered rules, no +occurrence of "elegan"). + +== Tensions introduced + +. *Containment until step 5.* Rule 15 remains projected during review and contest. The + only containment is the `DRAFT-unratified` manifesto pin on the whole estate-common + block. If the contest period is expected to be long, the fallback arm (remove and + regenerate) becomes the better containment; that call belongs to the reviewing + authority. +. *"Elegant" is a judgement, not a check.* No validator can decide which arm is + elegant. Enforcement is by labelling and review, not by a gate, and this ADR proposes + no gate. + +== Machine-readable impact + +*None to the projection engine.* Ratification changes only: + +* `0-canon/RSR-PHILOSOPHY.adoc` — the *Proposal status* banner is replaced by the step-5 + record; +* `0-canon/constitution/KNOWN-TENSIONS.adoc` — the `contradiction` row is closed; +* `rsr-template-repo` `.machine_readable/arrival-pack/arrival-pack.ncl` — *unchanged*. + +Step 6 requires downstream `CLAUDE.md` regeneration (`just claude-md`), validation, +and proof of deterministic regeneration, with all results recorded even when the +generated output is unchanged. These obligations apply regardless of whether the +manifesto pin moves; changing that pin remains a separate decision. + +== What remains owed + +[cols="1,4",options="header"] +|=== +|Step |Status +|1. Proposal |✅ this document (retroactive) +|2. Human- and machine-readable impact |✅ above +|3. Review by the named constitutional authority and affected domain maintainers |owed — authorised review by both is required before merging this proposal +|4. Meaningful contest period; answer recorded challenges |owed for ratification; not a prerequisite to merging this proposal +|5. Record decision, dissent, effective version/hash, superseded material, migration limits |owed for ratification; not a prerequisite to merging this proposal +|6. Regenerate derived registries; validate; prove deterministic regeneration; merge after authorised review |owed for ratification — regenerate downstream `CLAUDE.md`, validate, and record proof of deterministic regeneration even if output is unchanged, regardless of manifesto pin changes. Merging this proposal requires the authorised review in step 3; completion of steps 4–6 remains owed for ratification and is not a prerequisite to merging the proposal. +|===