From cc0f7652b38f02db31687f4bc13cbf1d361c88c3 Mon Sep 17 00:00:00 2001 From: Peter Bao Tran <145724936+utptran@users.noreply.github.com> Date: Fri, 23 Oct 2026 23:16:42 -0500 Subject: [PATCH] =?UTF-8?q?Add=20=C2=A79.19:=20the=20reasoning=20travels?= =?UTF-8?q?=20with=20the=20change?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Why: Tests record what the code does, not why it was designed that way. Today that reasoning lives in pull request discussions, which are platform data: a mirror of a repository carries its commits and loses its discussions. The JFA Principles require protocol software to be "auditable whole," and an outsider holding only a mirror cannot audit a change whose reasoning stayed on the platform. Choices: - Commit message, not PR description: the PR description is the platform data the problem began with. - No separate decision file: CONTRIBUTING already bans parallel proposal files, because git history is the version record and a parallel file drifts from the text it describes. - No squash merges: a squash replaces the commits the check approved with a new one written after the check, so the reasoning could pass review and still never reach history. - Form left to each CONTRIBUTING file: §14.7 keeps the bylaws lean; they set the duty and cite the guides for the details. Raised 2026-10-19 in #federation-volunteers (Jodson Graves, Peter Bao Tran). Translations to follow after adoption. Signed-off-by: Peter Bao Tran <145724936+utptran@users.noreply.github.com> --- P1-001_Bylaws_v1.0.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/P1-001_Bylaws_v1.0.md b/P1-001_Bylaws_v1.0.md index 54d4a1e..9904d03 100644 --- a/P1-001_Bylaws_v1.0.md +++ b/P1-001_Bylaws_v1.0.md @@ -233,6 +233,8 @@ Where these bylaws give a matter to a channel or a federation rather than to the **9.17 Maintaining the suite.** Repairs to the suite that leave every identifier, anchor, and binding unchanged are ordinary maintenance, made in the open in the Governance Federation Channel and requiring no ballot. Any member may propose a repair, and any member may run the suite: it is published and executable by anyone under §9.4, and a result no one outside the Institute can reproduce is not a result. **9.18 A failing suite is business.** If the suite fails against the current official document, the failure is entered in the open-questions document under §9.3 and stands as business in the Governance Federation Channel until it is resolved by repair of the suite or by amendment of the document. While a failure stands, the Institute recognizes no conformance claim, membership condition, or publication as satisfied by the invariant the failure touches. + +**9.19 The reasoning travels with the change.** Every change to a repository the Institute stewards under §9.1 records why it was made in the message of the commit that carries it, so that a reader holding only a mirror of the repository can audit the change whole: tests show what the code does, and the recorded reasoning shows why it was designed that way. Discussion held on a hosting platform is not part of the record, and no separate proposal or decision file is required or accepted in its place. Each repository's contribution guide sets the form; a check run on every proposed change refuses a commit that carries none, and no merge method that replaces checked commits after that check is used. A question raised in review and not resolved by the change is entered in the open-questions document under §9.3. --- ## Article X — Member Duties @@ -405,6 +407,7 @@ A deployment switches to a hybrid or full mutual credit system only when all thr | §9.16 | Registry changes are amendments; identifiers never reused | Conformance suite registry (lineage notes) | | §9.17 | Suite published and runnable by anyone; repairs need no ballot | Official document, Principles (lean, auditable) | | §9.18 | A failing suite is open business, not a silent pass | Concept triage, carried (meta); §9.3 | +| §9.19 | The reasoning for a change lives in the commit history, which survives a mirror; platform discussion does not | Official document, Principles (lean, auditable); §9.3; §2.5 | | §10.1, §10.2 | Orchestrator and operator duties; operator responsibility as the frame | Dispute-mechanics design §1 (bylaws-level per 2026-08-27 revision) | | §10.2 (Covenant Compliance) | Bidirectional covenant assessment at every exchange point; operator adjudicates and executes remedies | Official document, Covenant Layer; dispute-mechanics design §§3, 4 | | §10.2 (Credit Setting) | Community-wide limit, one number, never derived from reputation | Official document, line 9 (L9) |