From 02c0604970fd1d5fe7ed1fd2657faaffd3dd380d Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 23 Sep 2026 10:05:33 +0100 Subject: [PATCH] docs(canon): open step 1 for "Always leave it working" (PROVISIONAL) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The owner asked whether an AI can be bound to prototype-first, evolutionary delivery — a working thing at every budget boundary, with the version moving in named jumps rather than cracking mid-cut — and asked, honestly, whether doing so would inflate credit cost or produce a bittier project. The answer is no: the dominant cost in the current mode is re-understanding after an interruption, which is paid per interruption rather than per increment, so an always-working default branch caps the blast radius at one increment instead of one campaign. The two real risks are prototype permanence (contained by an explicit promote-or-delete obligation, and already governed by "holes before goals") and invariant inflation — an agent reading "a working thing every week" as "re-prove the whole estate weekly" — contained by defining "working" narrowly in the principle text itself. This does not adopt the principle. 0-canon/constitution/CHANGE-PROCEDURE.adoc permits steps 1 and 2 without the owner; steps 3-6 (review by the named constitutional authority, contest period, recorded decision, regeneration) are owed. So: - 0-canon/RSR-PHILOSOPHY.adoc gains "Always leave it working" marked PROVISIONAL, using the same [IMPORTANT] proposal-status block as "Elegance by default", and barred from the CLAUDE.md projection until its ratification record is complete. - docs/decisions/ADR-006 is the step-1 proposal record: authority affected, rationale, alternatives, compatibility, evidence status (assumed, not measured) and tensions — plus the exact one-rule arrival-pack delta ratification would apply, so step 6 is a single follow-up commit. - The arrival-pack is deliberately NOT edited. Adding rule 16 before ratification would repeat the defect this PR also records. That defect is real and now registered: "Elegance by default" is emitted as estate-common doctrine rule 15 in every generated CLAUDE.md while the canon states it MUST NOT be until ratified. AUTHORITY-AND-PRECEDENCE.adoc requires a `contradiction` tension where requirements conflict, so KNOWN-TENSIONS.adoc gains that row. Two tensions are declared rather than hidden: irreversible cutovers (runtime swap, format change, retiring a still-required gate) admit no always-working increment without a shim, and the shim is the cost; and an enforced version jump is unsatisfiable on the four repos whose Immutable-Tags ruleset carries `creation` with an empty bypass list, so ratification must not precede that repair. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YJ6PbZUYBcjJv7FTRfyogo --- 0-canon/RSR-PHILOSOPHY.adoc | 96 +++++++- 0-canon/constitution/KNOWN-TENSIONS.adoc | 1 + .../ADR-006-always-leave-it-working.adoc | 212 ++++++++++++++++++ 3 files changed, 302 insertions(+), 7 deletions(-) create mode 100644 docs/decisions/ADR-006-always-leave-it-working.adoc diff --git a/0-canon/RSR-PHILOSOPHY.adoc b/0-canon/RSR-PHILOSOPHY.adoc index 4a47d7f55..55b6bb507 100644 --- a/0-canon/RSR-PHILOSOPHY.adoc +++ b/0-canon/RSR-PHILOSOPHY.adoc @@ -10,9 +10,9 @@ 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. +prevails. The _Elegance by default_ and _Always leave it working_ sections below are +explicitly non-canonical proposals and are excluded from that projection until their +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 @@ -51,8 +51,9 @@ were the cure is itself a soundness hole (see _fail loudly_). 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 +never the symptom). Two proposed principles follow — *elegance by default*, on the +manner of offering a choice, and *always leave it working*, on the state work is left +in. Neither has canonical force unless and until its proposal record shows completed ratification. == Holes before goals @@ -117,6 +118,86 @@ The default is a *starting point, not a prediction*. The owner may take the othe with full information, and often will; what may not happen is an expedient choice made in ignorance that it was the expedient one. +== Always leave it working + +[IMPORTANT] +==== +*Proposal status — not canonical.* + +* *Owner decision:* Pending ratification. The 2026-09-23 owner instruction asked + whether this methodology is safe to adopt and, if so, requested its adoption. That + instruction authorises *drafting* this proposal; adoption as permanent policy + requires the review, contest period and recorded decision that + `0-canon/constitution/CHANGE-PROCEDURE.adoc` mandates, which no emergency + containment applies to here. +* *Dissent:* Pending the required contest and review period; no completed dissent + record exists yet. +* *Effective version/hash:* Not assigned. +* *Proposal record:* `docs/decisions/ADR-006-always-leave-it-working.adoc` — authority + affected, rationale, alternatives, compatibility, evidence status and tensions, with + the exact arrival-pack projection delta ratification would apply. +* *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 + `0-canon/constitution/CHANGE-PROCEDURE.adoc`. +==== + +*Stop only at a state that works. Every increment ends with the default branch green +and the thing runnable end to end; the version then moves in one named jump, never in +a cut left half-made.* + +Work in this estate is interrupted, not concluded. A session ends when its budget ends, +not when the change is finished, and the thing that is actually expensive is not the +code that was left unwritten — it is the *re-understanding*. An interrupted migration +forces whoever arrives next to rebuild the entire mental model from nothing before they +can safely touch anything, and that reconstruction costs more than the increment it is +trying to resume. Leaving the tree working is therefore not a quality nicety paid for +with extra effort; it is the mechanism that caps the blast radius of an interruption at +*one increment* instead of *one campaign*, and it is what makes spend predictable rather +than merely large. + +The corollary is a bound on ambition, not on quality. A working system is grown from a +smaller working system, never assembled from parts that first work together at the end; +a design that can only be correct once every piece lands has no safe stopping point in +it at all, and will be interrupted anyway. So the unit of work is the smallest change +that leaves the thing runnable, and the schedule is fixed while the scope flexes — what +ships at the boundary is whatever is green, and the version number moves because a +boundary was reached, not because a feature list was exhausted. + +Three obligations follow, and none is optional: + +. *Stop at a working state.* An increment is finished when the default branch is green + and the thing runs, not when the code is written. If the budget will not cover + reaching that state, the correct move is to reduce the increment, not to begin it and + leave the cut open. +. *Promote or delete a prototype — never park it.* A prototype exists to answer one + question. Once answered it is either promoted to real work or removed. A prototype + retained "for now" is precisely a place the system can be wrong without saying so, so + _holes before goals_ governs it: parking one is creating a hole, not deferring a goal. +. *Name the jump.* Version moves as a declared step with a recorded boundary, so that + "what is on `main`" is always a thing someone chose to publish. An increment that + cannot say which version it lands in has not identified its own stopping point. + +*"Working" is deliberately narrow, and widening it is the failure mode.* It means the +default branch is green and the thing runs — not that the estate has been re-proven, +not that every repository has been re-censused, not that every open finding is closed. +Read expansively, this principle inverts into an obligation to re-establish the whole +world at every boundary, which is unaffordable and would make the cadence itself the +most expensive thing in the estate. The invariant is local to the increment. A new +scanner finding surfaced at a boundary remains an issue with acceptance criteria, never +a blocker on stopping. + +*The one genuine exclusion is the irreversible cutover.* Where old and new cannot +coexist — a runtime swap, a format change every consumer must adopt at once, retiring a +gate that is still required somewhere — there is no increment that leaves both states +working, and pretending otherwise produces exactly the half-made cut this principle +exists to prevent. Such work is made incremental only by building a shim first: a +feature flag, a strangler façade, or a parallel run with both paths live. *The shim is +the cost, it is real, and it is declared before the cutover starts* — not discovered +halfway through. Where the shim is genuinely not affordable, the cutover is scheduled as +a single bounded increment with a tested rollback, and that exception is recorded rather +than assumed. + == The full Doctrine The complete, always-current operating Doctrine is maintained as estate-common @@ -127,8 +208,9 @@ 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. +boundaries are real; and equivalence as identity. _Elegance by default_ and +_Always leave it working_ join this list only after their proposal records above are +complete. == See also diff --git a/0-canon/constitution/KNOWN-TENSIONS.adoc b/0-canon/constitution/KNOWN-TENSIONS.adoc index 0741fbfc4..94eab4f1e 100644 --- a/0-canon/constitution/KNOWN-TENSIONS.adoc +++ b/0-canon/constitution/KNOWN-TENSIONS.adoc @@ -18,6 +18,7 @@ Status values used here are: `contradiction`, `architectural tension`, `implemen |Trustfile concern creep |implementation debt |high |Separate full standard, profile, projection, enforcement |Reconcile Trust artifacts after source-pack review |known incomplete work |ALARP vs absolute `MUST` claims |terminology drift |high |Require exception or contradiction record |Add normative-language guidance |designed |Minimal trusted bases vs estate-wide capability accretion |architectural tension |high |Require scoped capabilities and dependency evidence |Inventory trusted-base growth |assumed +|Unratified principle already projected as binding doctrine |contradiction |high |Canon marks _Elegance by default_ *PROVISIONAL* and bars its projection until ratification is recorded, yet the arrival-pack already emits it as estate-common doctrine rule 15 in every generated `CLAUDE.md`; partially contained only by the whole estate-common block carrying `manifesto_pin = "DRAFT-unratified"` |Either complete the ratification record under `CHANGE-PROCEDURE.adoc` or remove rule 15 from `arrival-pack.ncl` and regenerate; do not leave the two in disagreement |measured |=== Entries remain open until an authorised decision records resolution or accepted containment. A validator passing does not close a tension. diff --git a/docs/decisions/ADR-006-always-leave-it-working.adoc b/docs/decisions/ADR-006-always-leave-it-working.adoc new file mode 100644 index 000000000..f1aea3d44 --- /dev/null +++ b/docs/decisions/ADR-006-always-leave-it-working.adoc @@ -0,0 +1,212 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) 2026 Jonathan D.A. Jewell += ADR-006: Always leave it working — a fourth operating principle (PROPOSAL) +:toc: preamble + +[cols="1,4"] +|=== +| Status | *Proposed* — step 1 of `0-canon/constitution/CHANGE-PROCEDURE.adoc`. Not adopted. +| Date | 2026-09-23 +| Supersedes | nothing +| Authority sought | normative (an operating principle in `0-canon/RSR-PHILOSOPHY.adoc`), with projection into estate-common `CLAUDE.md` doctrine +|=== + +This document exists because `CHANGE-PROCEDURE.adoc` step 1 requires a proposal +identifying authority affected, rationale, alternatives, compatibility, evidence +status and tensions before a principle may enter the canon. Steps 3–6 — review by +the named constitutional authority, a meaningful contest period, the recorded +decision, and regeneration of derived registries — are *not* performed here and +remain owed. + +== The request + +The owner asked, on 2026-09-23: + +[quote] +____ +is there a way to get claude and other ais to commit to a prototyping first, then +evolutionary software design methodology, so that there's almost always a working +thing by the end of the week, when credit runs out, and that everything jumps in +version to the next version rather than doing it all in this bitwise thing that +often just cracks mid-cycle when the credit runs down. or is this a really bad +thing to do that will infinitely raise the cost of the credit involved or lead to +an inferior more bitty project[?] +____ + +The question was explicitly two-sided: adopt it *only if* it is not a cost or +quality trap. This ADR records the answer to that question as well as the proposal +itself, because the risk analysis is the substance of the decision. + +== Context — the problem being solved + +Work in this estate is *interrupted, not concluded*. A session ends when its budget +ends. The current de facto methodology is to carry one large campaign across many +sessions, which produces two recurring failures, both already recorded in estate +memory rather than hypothesised here: + +* *Half-landed campaigns.* Two campaigns were abandoned mid-flight and account for + 57% of the 249 open PRs measured on 2026-09-15. +* *Reconstruction cost dominating work cost.* The expensive operation is not writing + the increment; it is rebuilding the mental model of an interrupted migration from a + cold context. This session is itself the evidence: a single request spanning + roughly twenty compactions, most of whose token volume was re-establishing state. + +Neither failure is caused by insufficient effort. Both are caused by *the absence of +a defined stopping point* — the estate's three ratified principles govern the locus +of work (at the source), its order (holes first) and its manner (loudly), and none +of them says what must be true when you stop. That gap is the subject of this +proposal. + +== Decision proposed + +Adopt a fourth principle, *Always leave it working*, as drafted in +`0-canon/RSR-PHILOSOPHY.adoc`, and on ratification project it into the estate-common +arrival-pack doctrine so that it binds every visiting agent, not only Claude. + +The principle is the conjunction of three established practices, named here so the +proposal is not mistaken for an invention: + +* *Walking skeleton / tracer bullet* (Cockburn; Hunt & Thomas) — build a thin + end-to-end slice that runs, then thicken it. +* *Evolutionary design under Gall's Law* — a working complex system is invariably + found to have evolved from a working simple system; one designed complex from + scratch does not work and cannot be patched into working. +* *Release train* — the date is fixed and the scope flexes. This is what "jumps to + the next version" means operationally: the version moves because a boundary was + reached, not because a feature list was exhausted. + +== Rationale — and the direct answer to the cost question + +*The owner's feared risk does not materialise; the methodology lowers cost rather +than raising it.* The dominant cost in the current bitwise mode is re-understanding +after a crack, and that cost is paid per *interruption*, not per increment. An +always-working default branch caps the blast radius of an interruption at one +increment instead of one campaign. Spend becomes predictable, which is a stronger +property than merely lower. + +Two risks are real, and neither is the one feared: + +. *Prototype permanence.* Evolutionary design degrades when prototypes are retained + rather than promoted or deleted. This is contained by naming it as an obligation, + and it is already governed: an unreplaced prototype is a place the system can be + wrong without saying so, which is a soundness hole under _holes before goals_. +. *Invariant inflation — the AI-specific risk, and the one that genuinely would + raise cost.* An agent reading "a working thing every week" as "re-prove the whole + estate every week" would convert a cheap local invariant into an unaffordable + global one. This is contained by defining "working" narrowly *in the principle + itself* — default branch green and the thing runs — and by restating that a new + scanner finding is an issue with acceptance criteria, not a blocker on stopping + (owner ruling, 2026-09-15). + +== Alternatives considered + +[cols="1,3,2",options="header"] +|=== +|Alternative |Description |Why not + +|Status quo +|Continue campaign-scale work with no defined stopping point. +|It is the measured source of both failure modes above. Rejected. + +|Big-bang with tested rollback +|Permit large non-incremental changes provided rollback is proven. +|Rollback restores the *old* state; it does not preserve the *understanding*, which + is the expensive thing. Retained only as the declared exception for irreversible + cutovers, not as the default. + +|Time-box only (no working-state invariant) +|Fix the cadence but not the required end state. +|A weekly boundary that may land a half-made cut is the current behaviour with a + calendar attached. The invariant, not the cadence, is the load-bearing half. + +|Working-state invariant only (no version jump) +|Require green-and-runnable but not a named version boundary. +|Viable and strictly weaker. Without a named boundary there is no record of what was + chosen for publication, so "what is on `main`" stays implicit. Offered as the + fallback arm if the version-jump obligation is contested. +|=== + +== Compatibility + +* *With _solutions at source_:* compatible. Reducing an increment to reach a working + state is not a symptom patch; where the source cannot be reached in one pass, that + principle already requires recording the source fix as work still owed, which is + the same discipline applied to scope. +* *With _holes before goals_:* mutually reinforcing. Obligation 2 (promote or delete a + prototype) is derived from it rather than competing with it. +* *With _always fail loudly_:* compatible, and dependent on it. "Green" is only a + meaningful stopping condition where a check that cannot fail is already forbidden. +* *With arrival-pack rule 8, "wire first — unwired is not done":* adjacent, not + duplicative. Rule 8 governs whether a *single change* is connected; this principle + governs what must be true of the *tree* when work stops. Both can hold; neither + implies the other. +* *With the `manifesto`:* no conflict exists today. The manifesto contains no text on + prototyping, evolutionary design, increments, releasability or working state + (searched 2026-09-23). Note that the manifesto prevails on wording, so an owner + restatement in their own voice would supersede this drafting. + +== Evidence status + +*Assumed, not measured.* The interruption-cost argument is reasoned from measured +inputs (the 57%-of-open-PRs abandonment figure; the observed compaction volume of +this session) but the central claim — that an always-working default branch reduces +total spend — has not been measured against a control in this estate, and no such +experiment is proposed. This must not be recorded as `designed` or `measured` in the +tensions register. + +== Tensions introduced + +. *Irreversible cutovers admit no always-working increment.* Where old and new cannot + coexist — a runtime swap, a format change all consumers must adopt at once, retiring + a still-required gate — incrementality requires a shim (feature flag, strangler + façade, parallel run) and *the shim is the cost*. This is not a corner case in this + 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.* + +== Enforcement — no new mechanism is proposed + +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*. + +== Machine-readable impact — the exact projection delta + +Ratification (step 6, "regenerate derived registries") applies exactly one change to +the projection engine `.machine_readable/arrival-pack/arrival-pack.ncl` in +`rsr-template-repo`: a sixteenth doctrine rule, appended to the estate-common block. +No other file changes; every repository `CLAUDE.md` is regenerated by `just claude-md`. + +.... +16. **Always leave it working** — stop only at a state that works: the default branch + green and the thing runnable end to end, with the version moving in one named jump. + Reduce the increment rather than leaving a cut open. Promote or delete a prototype, + never park it. "Working" is narrow — green and it runs — never "re-prove the estate". + Irreversible cutovers need a shim first, and the shim cost is declared up front. +.... + +⚠ *This delta MUST NOT be applied before the ratification record is complete.* Applying +it early is the precise defect recorded as a `contradiction` in +`0-canon/constitution/KNOWN-TENSIONS.adoc` for _Elegance by default_, which is presently +projected as rule 15 while the canon states it must not be. + +== What remains owed + +[cols="1,4",options="header"] +|=== +|Step |Status +|1. Proposal |✅ this document +|2. Human- and machine-readable impact |✅ above +|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 +|===