From 7287386d792cebd834536c778a961e6ef7f544da Mon Sep 17 00:00:00 2001 From: Ryan Dombrowski Date: Wed, 12 Aug 2026 21:04:28 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20record=20the=20ratchet=20=E2=80=94=20co?= =?UTF-8?q?nsequential=20decisions=20get=20more=20deterministic=20over=20t?= =?UTF-8?q?ime?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The rationale stated the division of labour (the AI proposes; deterministic machinery decides) but not its direction: that the line is a ratchet which only turns one way, and that validation, governance, representation, acceptance, and evidence progressively move to machinery. Stated as a test to apply to any proposed change — does this move a consequential decision toward determinism, or away from it? — with what turning it has actually looked like in each of the five domains, and the corollary that a check which runs because it exists beats one that runs because someone remembered to list it. Co-Authored-By: Claude Fable 5 --- docs/ARCHITECTURE.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 553d115..76890e7 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -47,6 +47,24 @@ Three consequences worth understanding before changing anything: Corollary: **scripted mode is first-class.** The entire experience — streaming, gates, rendering, accept — works with no model at all. If the AI layer disappeared tomorrow, Composer would still be a governed authoring tool. +### The direction of travel + +The division of labour above is not a fixed line — it is a **ratchet**, and it only turns one way: + +> As Composer matures, consequential decisions should become progressively more deterministic, measurable, and reproducible. The AI proposes possibilities; deterministic machinery increasingly owns validation, governance, representation, acceptance, and evidence. + +Read that as a test to apply to any proposed change: *does this move a consequential decision toward determinism, or away from it?* A feature that makes the product better by making a judgment less checkable is the wrong trade, however good the demo looks. + +What turning the ratchet has actually looked like: + +- **Validation** — a rendering bug fixed once is a fix; an invariant asserting that *no* required catalog prop may be silently ignored is a ratchet. The second form found defects the first form had missed for months. +- **Governance** — rules are owner-authored data evaluated mechanically, never prose the model is asked to honour. +- **Representation** — the emitter refuses what it cannot represent and names the reason, rather than approximating and hoping the difference goes unnoticed. +- **Acceptance** — the gates that decide whether work may be saved run in one shared seam, so a browser project and a repository project cannot reach different verdicts about the same artifact. +- **Evidence** — the acceptance corpus, its expected classification, and the reasoning behind the architecture live in this repository, reproducible by anyone, rather than in the memory of whoever ran them last. + +The same test applies to enforcement itself: a check that runs because someone remembered to list it is weaker than one that runs because it exists. Prefer the mechanism that cannot be forgotten. + ## 5. The product model - **Project** — an identity plus a source of vocabulary. Three sources: a packaged **reference** design system, an **imported** project file, or a connected **repository** (through the local agent).