diff --git a/applications/README.md b/applications/README.md index c96dca9..7c50d5e 100644 --- a/applications/README.md +++ b/applications/README.md @@ -1,12 +1,58 @@ -# applications/ +# Applications — the framework applied to a kind of work -The framework denominated in a domain. Each application is a **projection** of the general principle, -not a restatement of it. + -- **pdlc/** · the product lifecycle, ruled (Rounds 28 to 30; `DDD-dec-114`) — three owners: the What owner (what the product must do, everything the How needs, with product assurance), the When owner (the business: the order of all new demand and when each change reaches users), and the How owner (the SDLC, with implementation assurance and the order of owed and own-ground work). A pull system for new demand with an option pool, three kinds of demand, and responsibility placed per decision -- **sdlc/** · software delivery — the agentic/DAG design framework that was the whole of DDD through v3, now correctly positioned as one projection of the actor-general core. Within the PDLC, the SDLC is the How owner's arrangement and a composite act of the PDLC: every SDLC act's layer path begins PDLC ▸ SDLC ([`sdlc/sdlc.md`](sdlc/sdlc.md), `[PROPOSED]`, `DDD-dec-115`). The directories sit side by side, and the nesting is a relation in the act map, not a directory layout -- **organizations/** · organisation design as a directory of four claims, `DDD-org-01..04`, all projected +Each folder here applies Decision-Driven Design to one kind of work, in that work's own terms. +Start in the folder that matches yours. -*Conservation of Specification Demand* is what *Conservation of Determination Demand* is called when -the actor is building software. That relationship — general principle, domain projection — is the -structure the framework prescribes for itself. +**What an application is.** The framework denominated in a domain. Each application is a +**projection** of the general principle, not a restatement of it. *Conservation of Specification +Demand* is what *Conservation of Determination Demand* is called when the actor is building +software. That relationship, general principle and domain projection, is the structure the +framework prescribes for itself. + +| Folder | What it is | How settled it is | Start with | +|---|---|---|---| +| [`pdlc/`](pdlc/) | The product lifecycle. Three owners: the What owner (what the product must do, everything the How needs, with product assurance), the When owner (the business: the order of all new demand, and when each change reaches users), and the How owner (the SDLC, with implementation assurance and the order of owed and own-ground work). A pull system for new demand with an option pool, three kinds of demand, and responsibility placed per decision | Ruled | [`pdlc/README.md`](pdlc/README.md) | +| [`sdlc/`](sdlc/) | Software delivery: the agentic/DAG design framework that was the whole of Decision-Driven Design through v3, now positioned as one projection of the actor-general core. Within the PDLC, the SDLC is the How owner's arrangement and a composite act of the PDLC: every SDLC act's layer path begins PDLC ▸ SDLC ([`sdlc/sdlc.md`](sdlc/sdlc.md)). The two directories sit side by side; the nesting is a relation in the act map, not a directory layout | The SDLC specification (`sdlc.md`) is ruled. The What, the How and the authority profile are ruled, each with the open points and unconfirmed readings it marks. See [`sdlc/README.md`](sdlc/README.md) for each document | [`sdlc/README.md`](sdlc/README.md) | +| [`organizations/`](organizations/) | Organisation design as a directory: four claims, and no documents of its own yet | All four claims are projected: predictions, not findings | [`organizations/README.md`](organizations/README.md) | + +The repository presents the method as ready to try, not ready to use. + +## How these documents are written + +Every document here opens with who it is for, what you can do after reading it, and how settled it +is. Decided is the default and goes unmarked. A point that is proposed but not yet ruled is marked +*(proposed, not yet ruled)*, a point no one has settled is marked *(open)*, and a reading Emil has +not confirmed is marked *(Claude's reading, not yet confirmed by Emil)*. A document that has any +such point lists them near the end, under "Not settled yet". + +Running text keeps decision, claim and promotion ids out. Every document closes with "Where this +comes from", which maps its sections to the decisions, claims and session records they rest on. +Reference material stays in its numbered section, because other files cite sections by number. +Deliberation stays in the session records. + +**What these documents do not carry.** None of them is canon. Where a document and the decision +or claim it rests on disagree, the decision or claim governs, and the document is wrong. + +## Where this comes from + +| Section | Rests on | +|---|---| +| What an application is | The principle repository's canon, pinned in `graph/upstream.yaml` | +| `pdlc/`, ruled | `DDD-dec-114` (Rounds 28 to 30 of `meta/sessions/2026-11-07-sdlc-and-pdlc/`) | +| `sdlc/`: `sdlc.md` ruled | `DDD-dec-115`, S-11: Round 28 ruled the specification's proposals, and Round 30 entered by amendment. The earlier text of this page called `sdlc.md` `[PROPOSED]`; that was wrong (release session v0.7.0, finding F-2) | +| `sdlc/`: the What, the How, the authority profile | `DDD-dec-41`, `-42`, `-63`, `-64` (the What, ratified by the merge of #42); `DDD-dec-55` to `-61` and `DDD-dec-119` (the How); `DDD-dec-85`, `-86`, `-92`, `-93` (the authority profile, ratified by the merge of #45) | +| `organizations/` | `DDD-dec-05` (a directory, not a repository); `DDD-org-01` to `-04`, projected (`DDD-dec-40`) | +| Ready to try, not ready to use | `DDD-dec-74` | +| How these documents are written | `DDD-dec-94` and `spec/doc-format.md`; `DDD-dec-95` (this folder's format); the register phrases, Round 2 of `meta/sessions/2026-11-09-applications-for-readers-redo/` | +| What these documents do not carry | `DDD-dec-94` (only canon carries authority) | + +The earlier text of this page is at `84aa466:applications/README.md`. diff --git a/applications/organizations/README.md b/applications/organizations/README.md index 853a053..6d90451 100644 --- a/applications/organizations/README.md +++ b/applications/organizations/README.md @@ -1,43 +1,79 @@ -# applications/organizations/ +# Organisation design — four predictions to test -Organisation design as a **directory**, not a repository (`DDD-dec-05`): four claims, no -documents of its own yet. Promotion to a repository requires core-like documents and an -identified external checker — not before. + -These are the organisation-design claims exactly as they stand in `core/claims/` -(`DDD-org-01..04`) — statements and falsifiers only, no new prose. All four are **projected** -and **session-authored** (flagged `UNVERIFIED — Emil review` in their claim files); they rest on -principle-layer claims pinned upstream in `graph/upstream.yaml`. Nothing here is canon. +Use this if you design or run an organisation and want to know what Decision-Driven Design +predicts about it. Organisation design is a **directory**, not a repository: four claims, and no +documents of its own yet. Promotion to a repository requires core-like documents and an identified +external checker, and not before. -## DDD-org-01 — graph discipline predicts organisational outcomes +**How settled this is.** All four claims are **projected**: predictions that have not been +tested, not findings. They were ratified as projected, and each was written in a session +(session-authored). They rest on principle-layer claims pinned upstream. Nothing here is canon. -*Status: projected.* +Below are the claims exactly as they stand in their claim files: each statement and its +falsifier, word for word, with no new prose. + +## 1. Graph discipline predicts organisational outcomes + +*Projected.* > Graph discipline — status floors at the consumer boundary, manifests, correction flow to a single canon — predicts organisational outcomes: pivot cost, trust damage from shipping projected claims as established, decision-review latency after thesis change. -**Falsifier.** Organisations measurably differing in graph discipline show no difference in pivot cost or correction latency after size and sector controls. +**It is wrong if:** -## DDD-org-02 — statused Stable Dependency Principle +> Organisations measurably differing in graph discipline show no difference in pivot cost or correction latency after size and sector controls. -*Status: projected.* +## 2. The Stable Dependency Principle, with status + +*Projected.* > The Stable Dependency Principle, statused: decisions whose reversal cost exceeds what their basis claims' hazard can absorb (high commitment level on low-status claims) concentrate pivot cost and produce incident-discovered cascades; organisations cannot see these violations because their assumption layer carries no status field. -**Falsifier.** Decisions flagged by fragility (hazard × afferent decisions × reversal cost) generate no more rework or incident findings than unflagged decisions of equal size. +**It is wrong if:** + +> Decisions flagged by fragility (hazard × afferent decisions × reversal cost) generate no more rework or incident findings than unflagged decisions of equal size. -## DDD-org-03 — priority as a governed decision +## 3. Priority as a governed decision -*Status: projected.* +*Projected.* > Priority as a governed decision: backlogs ordered by decisions basedOn statused value-claims — with claim priority set by value of information and decision priority by cost of delay, reversal cost, and basis readiness — churn less and predict delivered value better than intuition-ordered backlogs; roadmap churn is the cascade from silently demoted value-claims. -**Falsifier.** Teams with statused value-claims and explicit basedOn priority show no less roadmap churn or no better value prediction than matched intuition-ordered teams; or churn events do not trace to value-claim status changes on audit. +**It is wrong if:** -## DDD-org-04 — cross-domain retrodiction of institutional discipline +> Teams with statused value-claims and explicit basedOn priority show no less roadmap churn or no better value prediction than matched intuition-ordered teams; or churn events do not trace to value-claim status changes on audit. -*Status: projected.* +## 4. Institutional discipline across industries, retrodicted + +*Projected.* > Cross-domain retrodiction: the intensity of an industry's institutionalised graph discipline — permits, licensure, stage-gates, mandatory inspection — is predicted by reversal cost and feedback latency. Construction and manufacturing evolved formal status floors because irreversibility forced them; software's informality is explained by cheap retries, and its formalisation pressure rises with consequence and with agent-generated code collapsing generation cost while verification cost stands. -**Falsifier.** Industries matched on reversal cost and feedback latency showing grossly different discipline intensity, or discipline intensity tracking regulation-historical accident better than the two parameters after controls. +**It is wrong if:** + +> Industries matched on reversal cost and feedback latency showing grossly different discipline intensity, or discipline intensity tracking regulation-historical accident better than the two parameters after controls. + +## Where this comes from + +| Section | Rests on | +|---|---| +| A directory, not a repository; the promotion criterion | `DDD-dec-05` | +| How settled this is | `DDD-dec-40` (2026-10-26): each claim ratified as projected, its claim file its exposition. Each claim file's notes say "Session-authored" | +| 1 | `core/claims/DDD-org-01.yaml` | +| 2 | `core/claims/DDD-org-02.yaml` (credit: Martin's Stable Dependency Principle) | +| 3 | `core/claims/DDD-org-03.yaml` (credits: Reinertsen; Bezos's Type 1/Type 2 doors) | +| 4 | `core/claims/DDD-org-04.yaml` | +| Rests on principle-layer claims | `graph/upstream.yaml` | +The earlier text of this page said the claims were "flagged `UNVERIFIED — Emil review` in their +claim files". They are not: `DDD-dec-40` ratified all four as projected on 2026-10-26, and the +claim files carry no such flag. The earlier text is at +`84aa466:applications/organizations/README.md`. diff --git a/applications/pdlc/README.md b/applications/pdlc/README.md index f4a3f4a..7346551 100644 --- a/applications/pdlc/README.md +++ b/applications/pdlc/README.md @@ -1,39 +1,63 @@ # The PDLC Projection + + **The product lifecycle.** The PDLC places responsibility for a product among three owners: - the **What owner** holds what the product must do: everything the How needs in order to implement, including product assurance (how sure we can be that users do the act we designed) - and its observability needs (Rounds 17–19); + and its observability needs; - the **When owner**, the business and go-to-market, holds the order of all new demand and when - each change reaches users (Round 22); + each change reaches users; - the **How owner** holds the SDLC, the process of getting approved changes to production, with implementation assurance, the order of owed and own-ground work, and the DORA keys as its - answerability (Rounds 19, 20, 22). + answerability. -The SDLC is a composite act within the PDLC (`DDD-dec-114`, Rounds 8 and 9). +The SDLC is a composite act within the PDLC. -**Register: ruled (Rounds 28 to 30).** `DDD-dec-114` files the rulings. -Claude's construction in this directory was ruled item by item in Round 28 (R1 to R30), with the forecast settled in Rounds 29 and 30. +**How settled this is.** Decided. The construction in this directory was ruled item by item, and +the forecast was settled afterwards. Nothing here has run on a real product yet. | Document | What it is | |---|---| -| **[pdlc](pdlc.md)** · ruled (Rounds 28 to 30) | The PDLC: the stance (delivery does not decide when), the three owners, the What owner's output (everything the How needs), the two assurances (product and implementation), evidence in use and observation needs, the placement rule, the four loci, priority as a When decision, the three kinds of demand and their sources of pull, the option pool for new demand, ready for users and toggles, the seam to the SDLC, falsifiers and open items | -| **[graph/](graph/)** · ruled (Round 28, R30) | `lc:`, the lifecycle vocabulary (`ontology.ttl`); its shapes (`shapes.ttl`); the PDLC's acts on the act map (`acts.ttl`); an illustrative option pool (`example-pool.ttl`); and `check.py`, which validates the whole act map, PDLC and SDLC, with planted defects | +| **[pdlc](pdlc.md)** · decided | The PDLC: the stance (delivery does not decide when), the three owners, the What owner's output (everything the How needs), the two assurances (product and implementation), evidence in use and observation needs, the placement rule, the four loci, priority as a When decision, the three kinds of demand and their sources of pull, the option pool for new demand, ready for users and toggles, the seam to the SDLC, falsifiers and open items | +| **[graph/](graph/)** · decided | `lc:`, the lifecycle vocabulary (`ontology.ttl`); its shapes (`shapes.ttl`); the PDLC's acts on the act map (`acts.ttl`); an illustrative option pool (`example-pool.ttl`); and `check.py`, which validates the whole act map, PDLC and SDLC, with planted defects | ## Where things live -- **The What** stays in [`../sdlc/what.md`](../sdlc/what.md), where `DDD-dec-42` placed it. It is - **owned here**, by the What owner, and read by the SDLC as ground (Round 8: "Stays, read as - ground"). -- **The SDLC** is in [`../sdlc/sdlc.md`](../sdlc/sdlc.md) (`DDD-dec-115`). It sits beside this - directory, not inside it. The nesting is a relation in the act map (every SDLC act's layer path - begins PDLC ▸ SDLC), not a directory layout. Whether the directory should one day nest is open - (`pdlc.md` §13, O-1). +- **The What** stays in [`../sdlc/what.md`](../sdlc/what.md), where it was placed. It is + **owned here**, by the What owner, and read by the SDLC as ground. +- **The SDLC** is in [`../sdlc/sdlc.md`](../sdlc/sdlc.md). It sits beside this directory, not + inside it. The nesting is a relation in the act map (every SDLC act's layer path begins + PDLC ▸ SDLC), not a directory layout. Whether the directory should nest has been decided + for now: it does not (`pdlc.md` §15, O-1). - **The authority** over a product, the genesis grant and the scopes the three owners hold, is the authority profile, [`../sdlc/authority.md`](../sdlc/authority.md) §2–3. -**Not Delivery.** The PDLC is not the Product Framework's Delivery revived; `DDD-dec-42` O-2 -retired that. It carries no releases, versions or timeline as artefacts. Ordering and delivery -are recorded decisions, and forecasts are computed from the SDLC's record. +**Not Delivery.** The PDLC is not the Product Framework's Delivery revived; that was retired +when the What moved into `applications/sdlc/`. It carries no releases, versions or timeline as artefacts. Ordering and +delivery are recorded decisions, and forecasts are computed from the SDLC's record. Run: `python3 applications/pdlc/graph/check.py` and `python3 applications/sdlc/acts/check.py`. + +## Where this comes from + +| Part | Rests on | +|---|---| +| The three owners | `DDD-dec-114`: What owner, Rounds 17–19; When owner, Round 22; How owner, Rounds 19, 20, 22 | +| The SDLC as a composite act | `DDD-dec-114`, Rounds 8 and 9 | +| How settled | Rounds 28 to 30: Round 28 ruled Claude's construction item by item (R1 to R30); Rounds 29 and 30 settled the forecast. `graph/` was ruled by Round 28, R30 | +| The What's place | `DDD-dec-42`; Round 8 ("Stays, read as ground") | +| The SDLC's place | `DDD-dec-115`; O-1, closed by Round 28, R9 | +| Not Delivery | `DDD-dec-42` O-2 | + +The rulings are verbatim in +[`meta/sessions/2026-11-07-sdlc-and-pdlc/rulings.md`](../../meta/sessions/2026-11-07-sdlc-and-pdlc/rulings.md). +Supersedes `84aa466:applications/pdlc/README.md`, rewritten for readers by +`meta/sessions/2026-11-09-applications-for-readers-redo/`; no rule changed. diff --git a/applications/pdlc/pdlc.md b/applications/pdlc/pdlc.md index 8fa9e39..7754203 100644 --- a/applications/pdlc/pdlc.md +++ b/applications/pdlc/pdlc.md @@ -1,17 +1,28 @@ # The PDLC — the product lifecycle -**Register: ruled (Rounds 28 to 30).** This specification -is the exposition of `DDD-dec-114`. It has two layers: -- **What the decision files.** The decision files Emil's rulings of 2026-11-06 to 2026-11-09: - Rounds 3 to 22, 27 and 28 (verbatim in - [`meta/sessions/2026-11-07-sdlc-and-pdlc/rulings.md`](../../meta/sessions/2026-11-07-sdlc-and-pdlc/rulings.md)). - Rounds 16 to 28 entered by amendment before landing (Round 21). -- **What Round 28 ruled.** Round 28 ruled Claude's construction, item by item, as listed there - (R1 to R30), with R4's numbers ruled by Round 30: the tables, the shapes, the metrics, the checks, the forms of the two - proposed What elements and the falsifiers. Where a sentence states a ruling, the round is - named. Prose that no listed item covers is exposition, and the decision governs it. - -Where this text and `DDD-dec-114` disagree, the decision governs, and the text is wrong. + + +Use this to set up who decides what over a product's life. There are three owners. The What owner +says what the product must do. The When owner orders new demand and decides when users get each +change. The How owner runs delivery. After reading it you can: + +- place each boundary decision with one owner, and see which ground the other owners supply; +- run new demand through an option pool; +- send defects and technical work straight to delivery; +- read the forecast the When owner plans with. + +**How settled this is.** Decided. The tables, shapes, metrics, checks and falsifiers were ruled +item by item, and so were the forecast's percentiles and its calibration test. The decision this +document sets out governs it: where the two disagree, the decision is right and this text is +wrong. Prose that no ruled item covers is explanation, not rule. The points still open are listed +under "Not settled yet". Nothing here has run on a real product yet. **Upstream basis.** The coordinates, the address and the accountability argument are canon in `actor-indexed-determination`, pinned in [`graph/upstream.yaml`](../../graph/upstream.yaml) at @@ -25,80 +36,79 @@ Where this text and `DDD-dec-114` disagree, the decision governs, and the text i +**Where to start.** §2 and §6 say who owns what. §9 and §10 say how work enters. §1 is the +forecast. §14 lists what would show this design wrong. + --- ## 0. The weakest point **The owners are this projection's, not canon's.** Canon names no owner roles. The What, When and How owners are a placement of responsibility argued from upstream core/05 §5 and mapped onto -method step 7 (complete accountability). That step is itself `[PROPOSED]`, with nothing filed -beyond one line ([`method/07`](../../method/07-complete-accountability.md)). If the placement -rule fails, the three owners fall with it. It fails when a boundary decision cannot be split into -one owner's act and another's ground (§6). - -**The second weakness: two proposed What elements.** The PDLC leans on two What elements that do -not exist yet: the product-assurance declaration and the observation need (§4, §5). Until the -What's schema carries them (successor items), product assurance and observability needs live in -prose. The How owner's capability to instrument well is then the only thing that makes the -evidence come back. That capability is a classification pin, and Round 16 names it as the -backstop, not the guard. +method step 7 (complete accountability). That step is itself *(proposed, not yet ruled)*, with +nothing filed beyond one line ([`method/07`](../../method/07-complete-accountability.md)). If the +placement rule fails, the three owners fall with it. It fails when a boundary decision cannot be +split into one owner's act and another's ground (§6). + +**The second weakness: two What elements that do not exist yet.** The PDLC leans on the +product-assurance declaration and the observation need (§4, §5). Their form is decided, but the +What's schema does not carry them yet (§15, O-8). Until it does, product assurance and +observability needs live in prose. The How owner's capability to instrument well is then the only +thing that makes the evidence come back. That capability is a classification pin, and it is the +backstop, not the guard (§5). **The third weakness is empirical.** Nothing here has run. The forecast (§1), the option metrics (§10), the meter (§3) and the seam's price (§13) are computations over a record that does not -exist yet. The SDLC starts writing it from edition 1 (`DDD-dec-115`). +exist yet. The SDLC starts writing it from its first edition ([`../sdlc/sdlc.md`](../sdlc/sdlc.md) §13). ## 1. The stance: delivery does not decide when -*Ruled (Round 6, wording approved by Round 14; refined by Round 19):* "Delivery does not decide -when. The How owner's duty is to take approved work to production as fast as the quality -constraints allow. The cadence that results is the forecast everyone else plans against." +Delivery does not decide when. The How owner's duty is to take approved work to production as +fast as the quality constraints allow. The cadence that results is the forecast everyone else +plans against. - **The quality constraints** are the What, its ground and tolerance, and the **product - assurance** (Round 19). Both are the What owner's. -- **Implementation assurance is the How owner's own** (Round 19, §4). Lowering it is the How - owner's choice, guarded by outcomes read across seams (Rounds 19, 20). + assurance**. Both are the What owner's. +- **Implementation assurance is the How owner's own** (§4). Lowering it is the How owner's choice, + guarded by outcomes read across seams. - **The How owner's duty.** The shortest lead time within the What and the product assurance. - **The forecast is computed, not promised.** An issue's expected delivery follows from two things: - its position in the When owner's order (the rank recorded at o2a); - - the measured throughput, read from the SDLC's occurrence record (`DDD-dec-115` S-6). + - the measured throughput, read from the SDLC's occurrence record + ([`../sdlc/sdlc.md`](../sdlc/sdlc.md) §13). - **The measures.** The measures are DORA's four keys, as [`production-as-ground.md`](../sdlc/production-as-ground.md) §2 reads them. They are the How - owner's answerability (Round 20; [`../sdlc/sdlc.md`](../sdlc/sdlc.md) §18). - -**The computation: probabilistic forecasting** (ruled, Round 29; it replaces R27's sketch). + owner's answerability ([`../sdlc/sdlc.md`](../sdlc/sdlc.md) §18). -*Ruled (Round 29):* "we produce a certainty and that certiainty will them generate a best worst -and median that the when owner can then use for their planning. We can only ever estimate and the -better the how performs the smaller the different between worst and best will be" … "we should use -probalistic forecastin for this". +**The computation: probabilistic forecasting.** The forecast gives a certainty, and from it a +best, a median and a worst date that the When owner uses for planning. It is only ever an +estimate. The better the How performs, the smaller the difference between worst and best. - **Inputs.** The daily throughput of new demand: o13 occurrences with `lc:demandKind lc:NewDemand`, counted per day, over a recorded window. Flow time is also read from the record. - **Flow time** F runs from o2b to o13 for new demand, from the record (ruled, Round 27). It is - based on the Kanban cycle time. The Kanban Guide (v2025.5) defines cycle time as "The elapsed - time between when a work item started and when a work item finished", and lets a team call it - flow time ("Cycle Time could be Flow Time"). Its started and finished points are o2b and o13, - as the guide leaves them to each system's Definition of Workflow. It differs from a board that - ends at delivery and counts every item in two ways: + **Flow time** F runs from o2b to o13 for new demand, from the record. It is based on the Kanban + cycle time. The Kanban Guide (v2025.5) defines cycle time as "The elapsed time between when a + work item started and when a work item finished", and lets a team call it flow time ("Cycle + Time could be Flow Time"). Its started and finished points are o2b and o13, as the guide leaves + them to each system's Definition of Workflow. It differs from a board that ends at delivery and + counts every item in two ways: - finished is landed dark, not delivered (o16 is the When owner's); - only new demand is counted. - F is not DORA's lead time, - which starts at the first commit. + F is not DORA's lead time, which starts at the first commit. - **The forecast.** An issue at rank k, not yet started, is forecast by Monte Carlo simulation. - Each of many trials (at least 1000) draws a day's throughput at random from the recorded days, again and again, until k items have landed. - The days drawn are that trial's result. - - **Best, median and worst** are percentiles of the results: the 15th, 50th and 85th (ruled, - Round 30). + - **Best, median and worst** are percentiles of the results: the 15th, 50th and 85th. The When owner plans with all three. The method is the same every time, over the same record and seed, so the certainty is in the method. The dates stay estimates. - **An issue already started** is forecast from flow time instead: the percentiles of recorded flow times longer than its current age (Kanban's work item age). - **The spread.** Worst minus best is the How owner's measure. The steadier the How's throughput - and flow time, the narrower the spread for the same rank (Round 29). It sits beside the DORA - keys as the How owner's answerability, read across the How → When seam. + and flow time, the narrower the spread for the same rank. It sits beside the DORA keys as the + How owner's answerability, read across the How → When seam. - **Encoded.** In [`graph/forecast.py`](graph/forecast.py), with the shape `lc:ForecastShape`. `graph/check.py` forecasts rank 2 over the SDLC's example record. That record has one new-demand landing in 7 days. It checks the result against the exact negative-binomial @@ -106,7 +116,7 @@ probalistic forecastin for this". the computation only. - **Capacity is shared.** Owed and own-ground work (§9) share the How owner's capacity. They show in the forecast only as a lower λ for new demand, which is the only form in which the - When owner sees them (Round 22). + When owner sees them. - **When it changes.** The forecast changes when the order changes (a When decision), when throughput or flow time change (the How owner's performance), or when product assurance changes (a What decision). @@ -118,61 +128,60 @@ is expected to move dates: a team is asked to "pull in" a feature, and the date the delivery side negotiates. Here the delivery side has nothing to negotiate. Its only lever is lead time, and it is already obliged to minimise it. A date is held by changing the order (When), or by cutting scope or product assurance (both What). It is never held by pushing the How owner -(§6, rule 1). Emil, Round 6: "many have the idea that delivery can have an impact on when -something is delivered. But its the how owners responsibility to have approved work go -production as fast as possible within the quality constraints." +(§6, rule 1). Many have the idea that delivery can affect when something is delivered. But it is +the How owner's responsibility to have approved work go to production as fast as possible within +the quality constraints. ## 2. The three owners -Each owner is a **scope under the product's genesis grant** (authority.md §2–3, `DDD-dec-87`, -`DDD-dec-85`): a grant held by one person, delegating from the genesis, accepted by its holder. -The genesis holder may hold any of the three. Each owner may be several holders, one per scope. -For the What owner, `what.md` §5.1 already divides the What into scopes over element kinds. "The -What owner" means the holder of the scope that covers the element in question. +Each owner is a **scope under the product's genesis grant** (authority.md §2–3): a grant held by +one person, delegating from the genesis, accepted by its holder. The genesis holder may hold any +of the three. Each owner may be several holders, one per scope. For the What owner, `what.md` §5.1 +already divides the What into scopes over element kinds. "The What owner" means the holder of the +scope that covers the element in question. -| Owner | Owns | Acts it holds | Ruled by | -|---|---|---|---| -| **What owner** | The What: everything the How needs in order to implement (§3), including the acceptance relation and tolerance, its observability needs, and **product assurance** on the use act (§4). The mix between the software's share and the users' share. Its own evidence of the product in use (§5) | o1 (What and assurance loci), oC (classify a reported defect, §9), oR (ready for users), oU (holds the allocation of the acts of use) | Rounds 6, 7, 10, 16–19, 22 | -| **When owner** | The order of all **new** demand, and when each change reaches users. It is the business, where new demand enters, and the go-to-market owner | o2a (release for work: pull, decline, expire), o16 (turn a toggle on), a date promised outside (outside the arrangement) | Rounds 5, 10, 11, 22 | -| **How owner** | The SDLC: the process of getting approved changes to production. **Implementation assurance** (§4). The order of **owed** and **own-ground** demand (§9). Telemetry of the product in use, which it adds (§5) | o1 (How locus), oG (frame own-ground work), every SDLC act from o1b to o13 ([`../sdlc/sdlc.md`](../sdlc/sdlc.md)) | Rounds 5, 8, 16, 19, 20, 22 | +| Owner | Owns | Acts it holds | +|---|---|---| +| **What owner** | The What: everything the How needs in order to implement (§3), including the acceptance relation and tolerance, its observability needs, and **product assurance** on the use act (§4). The mix between the software's share and the users' share. Its own evidence of the product in use (§5) | o1 (What and assurance loci), oC (classify a reported defect, §9), oR (ready for users), oU (holds the allocation of the acts of use) | +| **When owner** | The order of all **new** demand, and when each change reaches users. It is the business, where new demand enters, and the go-to-market owner | o2a (release for work: pull, decline, expire), o16 (turn a toggle on), a date promised outside (outside the arrangement) | +| **How owner** | The SDLC: the process of getting approved changes to production. **Implementation assurance** (§4). The order of **owed** and **own-ground** demand (§9). Telemetry of the product in use, which it adds (§5) | o1 (How locus), oG (frame own-ground work), every SDLC act from o1b to o13 ([`../sdlc/sdlc.md`](../sdlc/sdlc.md)) | -**The When owner is the go-to-market owner** (Round 10). Relative importance is judged by when a -feature will have the best market impact. That is why ordering new demand belongs to the When -owner, and why the When owner is also the biggest contributor to the option pool (Round 11). +**The When owner is the go-to-market owner.** Relative importance is judged by when a feature will +have the best market impact. That is why ordering new demand belongs to the When owner, and why +the When owner is also the biggest contributor to the option pool. -**The How owner understands digital product development** (Round 16). In canon terms that is a -capability requirement on the occupant of the How scope: pinning by classification, the loosest -of `core/04`'s pinning resolutions. §5 says how the encoded observation needs lower the -dependence on it. +**The How owner understands digital product development.** In canon terms that is a capability +requirement on the occupant of the How scope: pinning by classification, the loosest of +`core/04`'s pinning resolutions. §5 says how the encoded observation needs lower the dependence +on it. -**Ground.** *Ruled (Round 14):* "Their ground is their own to control, but the seams between them -supplies some to each". Each owner controls its own ground. Ground that crosses a seam is -supplied by its producer and is read-only for the receiver. +**Ground.** Each owner's ground is its own to control, but the seams between them supply some to +each. Ground that crosses a seam is supplied by its producer and is read-only for the receiver. ### 2.1 The seam table, checked against the act map -The prompt asks that every row be an output of one owner's act and appear in the ground reading -of another owner's act. Rows 1 to 8 are Round 14's table, not ruled. The telemetry row is Round -16's, ruled. The last two are Claude's additions from Round 22. The act map is -[`graph/acts.ttl`](graph/acts.ttl) with [`../sdlc/acts/acts.ttl`](../sdlc/acts/acts.ttl). +Each row is checked to be an output of one owner's act that appears in the ground reading of +another owner's act. Rows 1 to 8 come from the original listing of the ground the seams supply, +and are ruled as listed. The scope-cut act in row 2 and the telemetry row were ruled before them. The last two rows, added when the three kinds of demand were adopted, are ruled as listed +too. The act map is [`graph/acts.ttl`](graph/acts.ttl) with +[`../sdlc/acts/acts.ttl`](../sdlc/acts/acts.ttl). | From → To | Ground supplied | Produced by | Read by | Check | |---|---|---|---|---| | When → What | A pulled option (a need) | o2a (When) | o1 (dependency "the pulled option") | **Holds** | -| When → What | A scope-cut proposal | **oS**, propose a scope or assurance cut (When; Round 28, R7) | o1 (`lc:readsEarlier m:oS`) | **Holds, since Round 28.** It was a gap: no act produced it. Not an option, because an option is never a What change, and not a What decision, because the When owner proposes and the What owner decides | -| What → When | Each element's outcome and acceptance | Earlier o1s (What) | o2a (`lc:readsEarlier m:o1`) | **Holds** (fixed in the first session) | +| When → What | A scope-cut proposal | **oS**, propose a scope or assurance cut (When) | o1 (`lc:readsEarlier m:oS`) | **Holds**, now that oS exists. It was a gap: no act produced it. Not an option, because an option is never a What change, and not a What decision, because the When owner proposes and the What owner decides | +| What → When | Each element's outcome and acceptance | Earlier o1s (What) | o2a (`lc:readsEarlier m:o1`) | **Holds** (fixed when the map was first drawn) | | What → When | The ready-for-users verdict | oR (What) | o16 (dependency) | **Holds** | | What → How | The What, the product assurance | o1 (What and assurance loci) | o1b (dependency, new demand), and the How owner's implementation-assurance decisions | **Holds** | -| When → How | A released issue, in order | o2a (the pull and its rank) | o2b (dependency, `lc:forKind lc:NewDemand`) | **Holds, for new demand only** (Round 22). Owed and own-ground issues cross no When → How seam | +| When → How | A released issue, in order | o2a (the pull and its rank) | o2b (dependency, `lc:forKind lc:NewDemand`) | **Holds, for new demand only.** Owed and own-ground issues cross no When → How seam | | How → When | The record: cadence, lead time, change failure rate | The dispatcher's occurrence records, o3 to o13 | o2a (`lc:readsEarlier m:o13`); the forecast | **Holds** | | How → What | The change in production, dark, with its verdicts | o13, with o9 and o10's verdicts | oR (dependency) | **Holds** | -| **How → What** | **Telemetry of the product in use** (Round 16, ruled) | o13 deploys the instrumentation. oU, occupied by the software, emits the data | oR (presence, for each observation need: `lc:checksObservation`); oC and later o1s (`lc:readsEarlier m:oU`): the What owner's evidence for superseding the What (method step 10) | **Holds.** Presence is checked before ready-for-users (§5). The data is read after delivery | -| What → How | A classification verdict: owed (Round 22) | oC (What) | o1b (dependency, `lc:forKind lc:OwedDemand`) | **Holds** | -| What → When | A classification verdict: new (Round 22) | oC (What) | o2a, through the option the What owner proposes at o0 | **Holds, indirectly.** A defect classified new becomes an option. The When owner reads it as an option, never as a defect | +| **How → What** | **Telemetry of the product in use** | o13 deploys the instrumentation. oU, occupied by the software, emits the data | oR (presence, for each observation need: `lc:checksObservation`); oC and later o1s (`lc:readsEarlier m:oU`): the What owner's evidence for superseding the What (method step 10) | **Holds.** Presence is checked before ready-for-users (§5). The data is read after delivery | +| What → How | A classification verdict: owed | oC (What) | o1b (dependency, `lc:forKind lc:OwedDemand`) | **Holds** | +| What → When | A classification verdict: new | oC (What) | o2a, through the option the What owner proposes at o0 | **Holds, indirectly.** A defect classified new becomes an option. The When owner reads it as an option, never as a defect | -**Finding F-2: the order of o1 and o2a** (first session). Round 11's ruled reading has the When -owner pull an option at o2a, which the What owner then frames at o1. The map follows it: o0 → o2a -→ o1 → o1b → o2b, for new demand. +**The order of o1 and o2a.** The When owner pulls an option at o2a, and the What owner then frames +it at o1. The map follows this order: o0 → o2a → o1 → o1b → o2b, for new demand. **Falsifier: a piece of ground two owners both need to write.** Two candidates, both resolved by splitting what each owner writes: @@ -182,11 +191,11 @@ splitting what each owner writes: ## 3. The What owner's output -*Ruled (Round 18):* "its more than the needs it's everything the how needs in order to implement -including the assurance". At o1 the What owner frames the full ground and tolerance for the How's -acts. [`what.md`](../sdlc/what.md) §1.1 puts it this way: "the What as a whole is the software's -declared ground, over which decisions are made, and the tolerance each act must meet." The table -reads each part against `what.md` at `1ab1de0`. +The What owner's output is more than the needs. It is everything the How needs in order to +implement, including the assurance. At o1 the What owner frames the full ground and tolerance for +the How's acts. [`what.md`](../sdlc/what.md) §1.1 puts it this way: "the What as a whole is the +software's declared ground, over which decisions are made, and the tolerance each act must meet." +The table reads each part against `what.md` at `1ab1de0`. | `what.md` | The What owner declares | What the How gets from it | |---|---|---| @@ -200,65 +209,62 @@ reads each part against `what.md` at `1ab1de0`. | §3.7 Subjects and authorization | Subject kinds and their claims: who may act in the product | The authorization to implement, separate from authority over the product | | §4.1 Declared targets | Platform contexts, interaction classes, design-system and content-store editions | The targets the How realises against | | §4.2 Obligations | Reification exists, reification coverage, content coverage | The pairs that must be covered or declared missing | -| **Observation need** (form ruled, Round 28; not yet in the What schema) (§5) | Where in the product the evidence of use comes from, what data is needed, and which acceptance or outcome it evidences (Round 17) | The telemetry to add, as a declared requirement, with its presence checked before ready-for-users | -| **Product-assurance declaration** (form ruled, Round 28; not yet in the What schema) (§4) | How sure we must be that users perform the designed act, located and inherited downward (Rounds 18, 19) | The level of evidence the observation needs must reach, and the user-side share the What owner adds. Not the How's checks: those are implementation assurance (Round 19) | +| **Observation need** (form decided; not yet in the What schema) (§5) | Where in the product the evidence of use comes from, what data is needed, and which acceptance or outcome it evidences | The telemetry to add, as a declared requirement, with its presence checked before ready-for-users | +| **Product-assurance declaration** (form decided; not yet in the What schema) (§4) | How sure we must be that users perform the designed act, located and inherited downward | The level of evidence the observation needs must reach, and the user-side share the What owner adds. Not the How's checks: those are implementation assurance | -**The meter.** *Ruled (Round 18):* "Yes (Recommended)". The What-locus share of o6 directions is -the PDLC's meter of whether the What gave the How everything it needed. Every o6 occurrence -records the locus of the decision it supplied (`lc:suppliedLocus`, [`../sdlc/sdlc.md`](../sdlc/sdlc.md) -§13). The meter is the count of o6 with `lc:suppliedLocus lc:What`, divided by all o6, per issue -and per What element. It is read across the How → What seam. A What-locus direction is a -decision the What owed and did not give, supplied late at human price. A falling share means the -What is getting more complete. +**The meter.** The What-locus share of o6 directions is the PDLC's meter of whether the What gave +the How everything it needed. Every o6 occurrence records the locus of the decision it supplied +(`lc:suppliedLocus`, [`../sdlc/sdlc.md`](../sdlc/sdlc.md) §13). The meter is the count of o6 with +`lc:suppliedLocus lc:What`, divided by all o6, per issue and per What element. It is read across +the How → What seam. A What-locus direction is a decision the What owed and did not give, +supplied late at human price. A falling share means the What is getting more complete. ## 4. Two assurances -*Ruled (Round 19):* "Assurance is the feature so its how sure can we be that our users does the -act we designed. Not how sure are we the feature is implemented correctly that is the Assurance -that the how must own". Assurance is a coordinate of each act's `DDD-frame-01` tuple, so there -are two, on two acts. +Product assurance is about the feature: how sure we can be that our users do the act we designed. +It is not how sure we are that the feature is implemented correctly. That is the assurance the How +must own. Assurance is a coordinate of each act's tuple in canon's frame, so there are two, on two +acts. | | Product assurance | Implementation assurance | |---|---|---| | **On the act** | oU, the use act, occupied by users and software | The How's acts: build, accept, land (o4 to o13) | | **Asks** | How sure can we be that users do the act we designed? | How sure are we that the feature is implemented correctly against the What? | | **Owner** | What owner | How owner | -| **Met by** | The software, and the user-side share: training, guidance, procedure (Round 7) | Mechanical checks (o9), o10's depth, independence of acceptance (Round 13) | -| **Evidenced by** | Observation needs and evidence in use (Rounds 16, 17) | The gates' verdicts, then change failure rate and the ready-for-users verdicts | +| **Met by** | The software, and the user-side share: training, guidance, procedure | Mechanical checks (o9), o10's depth, independence of acceptance | +| **Evidenced by** | Observation needs and evidence in use | The gates' verdicts, then change failure rate and the ready-for-users verdicts | | **Judged at** | oR, ready for users | o9 to o11, and afterwards by the outcomes | -| **Declared in** | The What, as a product-assurance declaration (form ruled, Round 28; not yet in the What schema) | A How decision, per What element or per act ([`../sdlc/sdlc.md`](../sdlc/sdlc.md) §5) | +| **Declared in** | The What, as a product-assurance declaration (form decided; not yet in the What schema) | A How decision, per What element or per act ([`../sdlc/sdlc.md`](../sdlc/sdlc.md) §5) | **Product assurance decides two things:** which observation needs the What must carry, and how much user-side share is required. A high level needs strong evidence that users perform the act, and may need training as well as software. The ready-for-users verdict judges whether both are there. -**The product-assurance declaration** (form ruled, Round 28; not yet in the What schema). A What element, located like a §3.6 demand: -within the product, a system, a flow, a step, a Decider or a Projector. It is inherited downward, -so an element without its own declaration takes its nearest ancestor's. It states how sure we must -be that users perform the designed act. Two levels, ruled (Round 28, R2): +**The product-assurance declaration** (form decided; not yet in the What schema). A What element, +located like a §3.6 demand: within the product, a system, a flow, a step, a Decider or a +Projector. It is inherited downward, so an element without its own declaration takes its nearest +ancestor's. It states how sure we must be that users perform the designed act. It has two levels: - **observed**: the act's completion is observed in use; - **evidenced**: the act's completion is observed, and the acceptance it serves is evidenced by an outcome measure. -The declaration is not an o9 check list, an o10 depth or an independence rule. Round 19 corrects -Round 18 on exactly this point: those belong to implementation assurance. +The declaration is not an o9 check list, an o10 depth or an independence rule. Those belong to +implementation assurance. An earlier ruling put them here, and a later one corrected it on exactly +this point. -**The guard on implementation assurance.** *Ruled (Round 19):* "Outcomes, read across seams -(Recommended)". *Ruled (Round 20):* "And if they don't thats fine - then it was properly not -giving any value." +**The guard on implementation assurance** is outcomes, read across seams. - **Lowered verification shows** as change failure rate and failed ready-for-users verdicts. Both are in the record the What and When owners read, and the How owner answers for them. - **If lowering moves neither,** the verification removed gave no value. The How owner may keep tuning implementation assurance down until the outcomes move. -- **A withdrawn falsifier.** In Round 19, Claude proposed the falsifier "implementation assurance - falls, and neither measure moves". Emil ruled it wrong in Round 20, and it is withdrawn. Its - replacement, Claude's, ruled by Round 28 (R20), is §14, falsifier 4. +- **A withdrawn falsifier.** An earlier falsifier, Claude's, "implementation assurance falls, and neither + measure moves", was ruled wrong and is withdrawn. Its replacement is §14, falsifier 4. ## 5. Evidence in use and observation needs -*Ruled (Round 16):* "I agree the telemetry is the hows to add and the rest is the what to gather. -Which is why you need a how owner that understands digital product development". +Telemetry is the How owner's to add, and the rest of the evidence is the What owner's to gather. +That is why the How owner must understand digital product development. | Evidence of the product in use | Whose | How it reaches the What owner | |---|---|---| @@ -266,29 +272,29 @@ Which is why you need a how owner that understands digital product development". | User research, support signals, training outcomes, and all other evidence | What owner's own ground | Its own gathering. No seam | The What owner judges product acceptance (oR) and supersedes the What from this evidence (method -step 10, `[PROPOSED]`). Without the Round 16 row, nothing brought the product in use back to it. +step 10, which is itself *(proposed, not yet ruled)*). Without the telemetry row, nothing brought +the product in use back to it. -**Observation needs.** *Ruled (Round 17):* "what people needs to add their observability needs to -the specification so its clear where in the product they get their data and what data they -need". The form below is Claude's proposal, ruled by Round 28 (R24): +**Observation needs.** People must add their observability needs to the specification, so that it +is clear where in the product they get their data and what data they need. The form: - **A located What element.** An observation need is located like a §3.6 demand: the product, a system, a flow, a step, a Decider or a Projector. - **What it declares.** The data needed, and the acceptance or outcome it evidences. - **Not a quality demand.** It has no bound, so it is not a third kind of quality demand. §3.6 admits exactly two: "a quality demand is one of exactly two kinds". It is its own element kind. - **Its How side** is a contract over `telemetry` facts, anchored to the need. That is the - pattern how.md's H-9 gives a runtime bound's measurement wiring (`DDD-dec-60`, superseded by - `DDD-dec-70` with the telemetry facts unchanged). + pattern how.md §4.2 gives a runtime bound's measurement wiring, with the telemetry facts + unchanged by the later decision on provenance. - **Checked for presence before ready-for-users.** The verdict records, per need, whether the telemetry exists (`lc:checksObservation`), and a ready verdict with any need unmet is refused (`lc:ReadyNeedsTelemetryShape`). - **Its own decision.** Adding it changes the What's schema (`ontology.ttl`, `shapes.ttl`), which - goes by its own decision (successor items). + goes by its own decision (§15, O-8). -**The capability pin and the guard** (Round 16; Claude's reading, ruled by Round 28, R26). +**The capability pin and the guard.** - **The pin.** "A How owner that understands digital product development" is, in canon terms, - pinning by classification: an occupant selected for a capability envelope (`core/04`, - `term:capability`). It is the loosest pin, and the costliest to rely on alone. + pinning by classification: an occupant selected for a capability envelope (`core/04`). It is + the loosest pin, and the costliest to rely on alone. - **The encoded needs are the guard.** With each What element naming the evidence of success it needs, the How owner's instrumenting is a declared requirement, checked mechanically before ready-for-users. @@ -296,9 +302,9 @@ need". The form below is Claude's proposal, ruled by Round 28 (R24): ## 6. The placement rule -*Ruled (Round 10):* "Adopt it (Recommended)". Responsibility is placed **per decision, not per -role**. For each boundary decision exactly one owner holds the act, with control and liability. -Another owner's verdict enters it only as read-only ground. +Responsibility is placed **per decision, not per role**. For each boundary decision exactly one +owner holds the act, with control and liability. Another owner's verdict enters it only as +read-only ground. **The argument, from upstream core/05 §5.** - **Separable.** Accountability decomposes into answerability, liability and control, which @@ -321,7 +327,7 @@ Another owner's verdict enters it only as read-only ground. | A date promised outside | Outside the arrangement | When owner | The forecast, computed from the record (How) | | Cutting scope to meet a date | o1, What locus | What owner | The When owner's proposal (When) | -**The three rules** (Round 10): +**The three rules:** 1. **The When owner may propose a What change but never make one.** A date is held by cutting scope or product assurance (both the What owner's) or by changing the order, never by pushing the How owner. @@ -329,22 +335,23 @@ Another owner's verdict enters it only as read-only ground. 3. **A dispute escalates to the genesis grant holder.** Escalation "routes a determination to an accountability-bearing actor — not merely to a more capable one" (core/05 §5). -**Relative importance** (Round 10). The What owner declares each element's outcome and acceptance. -The When owner judges importance by when a feature will have the best market impact. +**Relative importance.** The What owner declares each element's outcome and acceptance. The When +owner judges importance by when a feature will have the best market impact. -**Answerability, per owner.** For the How owner, answerability is the DORA keys (Round 20). For -the What owner, it is the meter (§3) and the ready-for-users verdicts against what users then do -(§5). For the When owner, it is the option metrics (§10) and the market outcome of its order. +**Answerability, per owner.** For the How owner, answerability is the DORA keys. For the What +owner, it is the meter (§3) and the ready-for-users verdicts against what users then do (§5). For +the When owner, it is the option metrics (§10) and the market outcome of its order. -**Mapped to method step 7** (ruled, Round 28, R28; the step itself is still `[PROPOSED]` in `method/`). Step 7's one filed line reads: "Attribution, -principal, authority, stake, remediation per allocation." For each row of the table: +**Mapped to method step 7.** The mapping is decided. The step itself is still *(proposed, not yet +ruled)* in `method/`. Step 7's one filed line reads: "Attribution, principal, authority, stake, +remediation per allocation." For each row of the table: - **Attribution.** The act's record, signed under the owner's scope (authority.md §4.1). - **Principal.** The scope's holder. - **Authority.** The grant. - **Stake.** The outcome it bears on. - **Remediation.** Supersession by a later decision under the same scope, or escalation. -Canon names no owner roles. This mapping is Claude's. +Canon names no owner roles. This mapping is Claude's, not canon's. **Falsifier.** A boundary decision that cannot be split into one owner's act and another's ground. It is then jointly owned, it belongs to the genesis grant holder, and the rule has failed @@ -352,37 +359,35 @@ for it. ## 7. The four loci -*Ruled (Round 4):* "Yes, four values (Recommended)". An issue declares its locus: the coordinate -of DDD-frame-01's tuple ⟨task, ground, acceptance relation, tolerance, arrangement, assurance⟩ -that the change moves. *Ruled (Round 3):* it is declared on the issue, and the dispatcher refuses -an issue without one. +An issue declares its locus: the coordinate of the act's tuple ⟨task, ground, acceptance +relation, tolerance, arrangement, assurance⟩ that the change moves. There are four values. The +locus is declared on the issue, and the dispatcher refuses an issue without one. | Locus | Coordinates moved | Acceptance path | |---|---|---| -| **What** | Acceptance relation, tolerance | The occupant drafts a decision anchored to the What element it changes. The What owner accepts it. Tools never change the What (`DDD-dec-42` O-5) | -| **Assurance** | **Product** assurance (Round 19) | The What owner accepts it. It sets the observation needs and the user-side share required (§4). A change to implementation assurance is **How**-locus | -| **Ground** | Ground | Each owner's own ground is controlled by that owner. A ground-locus issue declares whose ground it changes, and that owner accepts it. Ground crossing a seam is supplied by its producer and read-only for the receiver (Round 14) | -| **How** | Arrangement: How decisions and the code realising them, one locus (Round 3); implementation assurance (Round 19) | Handed to the SDLC (o1b onward), accepted at o10 by a holder of Approve for the How scope. A change to the SDLC arrangement itself is How one layer up ([`../sdlc/sdlc.md`](../sdlc/sdlc.md) §10) | +| **What** | Acceptance relation, tolerance | The occupant drafts a decision anchored to the What element it changes. The What owner accepts it. Tools never change the What | +| **Assurance** | **Product** assurance | The What owner accepts it. It sets the observation needs and the user-side share required (§4). A change to implementation assurance is **How**-locus | +| **Ground** | Ground | Each owner's own ground is controlled by that owner. A ground-locus issue declares whose ground it changes, and that owner accepts it. Ground crossing a seam is supplied by its producer and read-only for the receiver | +| **How** | Arrangement: How decisions and the code realising them, one locus; implementation assurance | Handed to the SDLC (o1b onward), accepted at o10 by a holder of Approve for the How scope. A change to the SDLC arrangement itself is How one layer up ([`../sdlc/sdlc.md`](../sdlc/sdlc.md) §10) | **Locus and kind are different axes.** The locus says which coordinate a change moves. The demand kind (§9) says why the work exists. An owed issue is usually How-locus: the software is brought back to the What. An own-ground issue is How-locus or ground-locus (the How owner's ground). A new-demand issue may be any locus. -**Why planning is not a locus.** Planning moves no coordinate (Round 4). Time in canon is the -causal time index (`DDD-address-01`). +**Why planning is not a locus.** Planning moves no coordinate. Time in canon is the causal time +index. - **Derived order** comes from the causal index. - **Chosen order** is the When owner's decision for new demand, recorded at o2a as the rank, and - the How owner's for owed and own-ground demand (Round 22). + the How owner's for owed and own-ground demand. The coordinate **task** is not a locus value: it is what the issue itself names, so a new task is -a new option (ruled, Round 28, R13). +a new option. ## 8. Priority is a When decision -*Ruled (Round 12):* "this also solves the classic problem of a product owner, owning the priority -which is inherently wrong. That's a when decision". Round 22 sharpens it: the When owner orders -new demand, and the How owner orders owed and own-ground work (§9). +A product owner owning the priority is inherently wrong: priority is a When decision. The When +owner orders new demand, and the How owner orders owed and own-ground work (§9). **The Scrum Guide's own wording** (the 2020 Scrum Guide, November 2020, the current edition, [scrumguides.org/scrum-guide.html](https://scrumguides.org/scrum-guide.html), read 2026-11-07): @@ -403,23 +408,22 @@ ordered list of what is needed to improve the product." - **Two decisions in one role.** The classic product owner holds a What decision (creating the items) and a When decision (ordering them) at once. - **Ground they do not hold.** Priority is importance relative to the queue and the market window. - That ground is the When owner's (Round 10). + That ground is the When owner's. - **Liability without control.** A product owner who sets priority bears liability without control for its market outcome (core/05 §5). - **Three kinds of demand in one list.** The backlog also orders all three kinds of demand in one list (§9). -**One person may hold both scopes.** *Ruled (Round 12):* "Yes, acts kept apart (Recommended)". -Each act is recorded under its own scope. With no second party, the genesis grant holder reviews. +**One person may hold both scopes, with the acts kept apart.** Each act is recorded under its own +scope. With no second party, the genesis grant holder reviews. **Falsifier.** An organisation where the same person holds both scopes and the record cannot tell their When decisions from their What decisions. ## 9. Sources of pull: three kinds of demand -*Ruled (Round 22):* "determination pull will come from different sources … Which is why bugs or -technical debt is hard to put into the classic backlog". The kinds: "Adopt (Recommended)". The -classifier: "What owner (Recommended)". +Determination pull comes from different sources. That is why bugs and technical debt are hard to +put into the classic backlog. There are three kinds of demand, and the What owner classifies. | Kind | Is | Detected by | Ordered by | Through the pool? | |---|---|---|---|---| @@ -432,7 +436,7 @@ classifier: "What owner (Recommended)". | Source | Kind | Enters at | Ordered by | Pool | |---|---|---|---|---| | A market need (a customer segment cannot do something it will pay for) | New | o0, by the When owner | When | Yes | -| Users can't do the designed act: evidence in use shows the act is not performed (product assurance not met) | New, a What change: a different design, or a user-side share (Round 7) | o0, by the What owner | When | Yes | +| Users can't do the designed act: evidence in use shows the act is not performed (product assurance not met) | New, a What change: a different design, or a user-side share | o0, by the What owner | When | Yes | | The software deviates from the What: a defect against a Decider, a bound or an invariant in force | Owed, by the What owner's classification (oC) | o1b, without o2a | How | No | | A reported defect the What owner finds is the What being wrong, not the software | New, by the classification (oC) | o0, by the What owner | When | Yes | | Technical debt, the arrangement, the How owner's ground (a dependency's CVE, a platform end of life, a slow pipeline) | Own-ground | oG, by the How owner | How | No | @@ -461,7 +465,7 @@ nor new. **What the When owner sees.** It sees owed and own-ground work only as its effect on cadence: a lower throughput for new demand (§1). -**The guard, from both sides** (Round 20's guard applied to own-ground work): +**The guard, from both sides** (the outcome guard of §4, applied to own-ground work): - **Too little own-ground work** shows as rising change failure rate, lead time and time to restore. - **Too much** shows as falling cadence with no DORA improvement. @@ -495,29 +499,28 @@ An owed fix restores behaviour the What already promised. It is usually not behi and needs no o16. Its o13 records which earlier deployment it restores (`lc:restores`), which feeds change failure rate and time to restore ([`../sdlc/sdlc.md`](../sdlc/sdlc.md) §18). -**Falsifiers** (Round 22, proposed with the adopted kinds; ruled, Round 28, R19): +**Falsifiers:** - an item that cannot be classified as new, owed or own-ground; - an implementation bug that needs the When owner's ordering to get fixed. ## 10. The pull system and the option pool -*Ruled (Round 11, reading approved by Round 14; Round 22):* the When owner is the business, and -new demand enters the product there. The PDLC is a pull system for new demand: new work moves only -when the When owner pulls an option from the pool (o2a). The SDLC never pushes new demand. Owed and -own-ground demand do not go through the pool (§9). +The When owner is the business, and new demand enters the product there. The PDLC is a pull +system for new demand: new work moves only when the When owner pulls an option from the pool +(o2a). The SDLC never pushes new demand. Owed and own-ground demand do not go through the pool +(§9). **o0 propose an option.** Any owner may propose, and the When owner is the biggest contributor. The What owner contributes specification gaps, user feedback, regulation, and defects it -classifies as new. Round 11's reading had the How owner contribute arrangement changes and -technical debt. Under Round 22 those are own-ground demand and bypass the pool, so the How owner -contributes only the new demand it detects. +classifies as new. An earlier reading had the How owner contribute arrangement changes and +technical debt. Under the three kinds of demand those are own-ground demand and bypass the pool, +so the How owner contributes only the new demand it detects. -**What an option is.** *Ruled (Round 11):* "Yes, outcomes only (Recommended)". +**What an option is.** Outcomes only. - **An outcome or need.** An option states who cannot do what, and by when it matters. - **Never a What change.** The What owner turns a pulled option into What decisions at o1. -**How an option leaves.** *Ruled (Round 11):* "Yes, recorded (Recommended)". Every option leaves -by a recorded When-owner decision: +**How an option leaves.** Every option leaves by a recorded When-owner decision: | Exit | Record | |---|---| @@ -553,9 +556,9 @@ invented): - the When owner's share is 3/4 of proposed and 1/2 of pulled; - the decline rate is 0/3 and the expiry rate 1/3. -The pool once held a How-owner option, "a manual cache purge on every deploy". Round 26 removed -it, because under Round 22 technical debt is own-ground work and never enters the pool. It is -now issue #104 at the own-ground entry (oG), in [`../sdlc/acts/example-record.ttl`](../sdlc/acts/example-record.ttl). +The pool once held a How-owner option, "a manual cache purge on every deploy". It was removed, +because technical debt is own-ground work and never enters the pool. It is now issue #104 at the +own-ground entry (oG), in [`../sdlc/acts/example-record.ttl`](../sdlc/acts/example-record.ttl). An option stating `lc:demandKind` other than new is refused (`lc:OptionShape`). The example has no declined option now, and the two decline plants still exercise that shape. @@ -568,8 +571,7 @@ declined option now, and the two decline plants still exercise that shape. The act map is the form of method step 1. It is graph data in [`graph/acts.ttl`](graph/acts.ttl), with the SDLC's acts in [`../sdlc/acts/acts.ttl`](../sdlc/acts/acts.ttl): one map, validated together. -- **The PDLC's acts:** o0, o2a, oS (propose a scope or assurance cut, Round 28), o1, oC, oR, o16, - oU. +- **The PDLC's acts:** o0, o2a, oS (propose a scope or assurance cut), o1, oC, oR, o16, oU. - **On the SDLC side:** oG, own-ground framing, is the How owner's entry point. - **Kind-scoped dependencies.** o1b depends on o1 (new), oC (owed) or oG (own-ground), by `lc:forKind`. o2b reads o2a for new demand only. @@ -578,13 +580,13 @@ The ids o14 and o15 are not reused. ## 12. Release toggles, from the PDLC's side -*Ruled (Round 5):* "Release toggles (Recommended)". *Ruled (Round 10):* "Yes, as a constraint -(Recommended)". +New behaviour reaches users through release toggles, and readiness is a constraint on turning one +on. - **Turning a toggle on (o16) is the When owner's act.** - **o16 reads the What owner's ready-for-users verdict (oR).** The verdict covers the software's - share and the user-side share. Since Rounds 16 and 17, it also covers the presence of the - telemetry each observation need asks for. + share and the user-side share. It also covers the presence of the telemetry each observation + need asks for. - **The constraint.** Turning on an unready toggle is refused (`lc:ToggleOnShape`). A verdict that is ready while an observation need's telemetry is absent is refused (`lc:ReadyNeedsTelemetryShape`). @@ -593,8 +595,8 @@ The ids o14 and o15 are not reused. ## 13. The seam to the SDLC -*Ruled (Round 9, reading approved by Round 14):* the SDLC is a composite act within the PDLC. -Every SDLC occurrence's layer path begins PDLC ▸ SDLC. +The SDLC is a composite act within the PDLC. Every SDLC occurrence's layer path begins +PDLC ▸ SDLC. | Direction | What crosses | Where | |---|---|---| @@ -603,7 +605,7 @@ Every SDLC occurrence's layer path begins PDLC ▸ SDLC. | Into the SDLC | The What, and the product assurance | Read as ground, never written by the SDLC | | Out of the SDLC | Production state, dark | o13 → oR → o16 | | Out of the SDLC | Telemetry of the product in use | o13's instrumentation, oU's data → oR (presence), oC, o1 | -| Out of the SDLC | The record, with the DORA keys | The occurrence record (`DDD-dec-115` S-6, S-10) | +| Out of the SDLC | The record, with the DORA keys | The occurrence record ([`../sdlc/sdlc.md`](../sdlc/sdlc.md) §13, §18) | Own-ground issues start inside the SDLC (oG) and cross no seam on the way in. @@ -627,19 +629,19 @@ manufactures seam demand S. Paying it down is one-time specification work: 1. **A behaviour change that moves no coordinate.** An issue's change alters behaviour but moves no coordinate. 2. **A change that needs a "when".** A change that can only be stated with a "when" in it. -3. **A miscalibrated forecast** (Round 29). Either: +3. **A miscalibrated forecast.** Either: - landings fall between best and worst much less often than the percentiles say (about 70% of the time for 15th–85th), or the misses fall mostly on one side; - or the How owner's DORA keys improve and the spread does not narrow, so the forecast does not reflect the How's performance. - **Ruled (Round 30):** the forecast fails calibration if fewer than 60% of landings fall inside - the 15th–85th range, judged over the last 20 new-demand issues. + **The test:** the forecast fails calibration if fewer than 60% of landings fall inside the + 15th–85th range, judged over the last 20 new-demand issues. 4. **Blind outcome measures.** An escape reaches users that neither change failure rate nor the ready-for-users verdicts record. Then the outcome measures are blind, and the guard on - implementation assurance fails. Claude's (Round 20), ruled by Round 28 (R20). It replaces "the How owner - can shorten lead time by lowering assurance", which Round 19's split made wrong: the How owner - may lower implementation assurance, and is guarded by outcomes. + implementation assurance fails. It replaces "the How owner can shorten lead time by lowering + assurance", which the split into two assurances made wrong: the How owner may lower + implementation assurance, and is guarded by outcomes. 5. **Users reached before o16.** A landed change reaches users before o16. 6. **An unrecorded user-side share.** A feature meets its software acceptance, is turned on, and fails its product acceptance for want of a user-side share nothing recorded. @@ -665,12 +667,56 @@ leaving with no record) are part of this list. | # | Item | Closes it | |---|---|---| -| O-1 | **Ruled (Round 28, R9):** `applications/sdlc/` is not nested under `applications/pdlc/`, and `DDD-dec-42`'s placement stands | Closed | -| O-2 | **Ruled (Round 28, R10):** `DDD-org-03`'s governed priority is When decisions over new demand only | Closed | -| O-3 | **Ruled (Round 28, R7):** the scope-cut proposal is act oS, held by the When owner and read at o1 (§2.1) | Closed | -| O-4 | **Ruled (Round 30, "O-4 agreed as ruled").** Probabilistic forecasting (Round 29), with best and worst at the 15th and 85th percentiles and the median at the 50th. The forecast fails calibration if fewer than 60% of landings fall inside the 15th–85th range, over the last 20 new-demand issues (§1, §14 falsifier 3) | Closed | -| O-5 | **Ruled (Round 28, R8):** o2a comes before o1, F-2 as drawn | Closed | -| O-6 | Record kinds for the When owner's acts (o2a, o16, an option's exit) and for the classification (oC) in the authority profile | A successor session | -| O-7 | **Ruled (Round 28, R2):** the product-assurance levels are *observed* and *evidenced* (§4) | Closed | -| O-8 | The observation need and the product-assurance declaration as What elements. Their **form** is ruled (Round 28, R24, R25). The What schema change goes by its own decisions (successor items W-1 to W-3) | A successor session | -| O-9 | **The name "flow time" — ruled (Round 27).** Approved as described: the forecast's interval, o2b to o13, for new demand, kept apart from DORA's change lead time, o4 to o13 ([`../sdlc/sdlc.md`](../sdlc/sdlc.md) §18). It is based on the Kanban cycle time (`DDD-dec-114` P-14). Raised by Round 26 | **Closed** (Round 27) | +| O-1 | `applications/sdlc/` is not nested under `applications/pdlc/`, and the What's placement in `applications/sdlc/` stands | Closed | +| O-2 | The governed priority of the organisation-design claim `DDD-org-03` is When decisions over new demand only | Closed | +| O-3 | The scope-cut proposal is act oS, held by the When owner and read at o1 (§2.1) | Closed | +| O-4 | Probabilistic forecasting, with best and worst at the 15th and 85th percentiles and the median at the 50th. The forecast fails calibration if fewer than 60% of landings fall inside the 15th–85th range, over the last 20 new-demand issues (§1, §14 falsifier 3) | Closed | +| O-5 | o2a comes before o1, as drawn in §2.1 | Closed | +| O-6 | Record kinds for the When owner's acts (o2a, o16, an option's exit) and for the classification (oC) in the authority profile *(open)* | A successor session | +| O-7 | The product-assurance levels are *observed* and *evidenced* (§4) | Closed | +| O-8 | The observation need and the product-assurance declaration as What elements. Their **form** is decided. The What schema change goes by its own decisions (successor items W-1 to W-3) *(open)* | A successor session | +| O-9 | **The name "flow time"**: the forecast's interval, o2b to o13, for new demand, kept apart from DORA's change lead time, o4 to o13 ([`../sdlc/sdlc.md`](../sdlc/sdlc.md) §18). It is based on the Kanban cycle time | Closed | + +## Not settled yet + +- **Method step 7** (§0, §6) and **method step 10** (§5) are *(proposed, not yet ruled)* in + `method/`. The mapping onto step 7 is decided. If step 7 changes, the mapping must be read again. +- **O-6** *(open)*: record kinds for the When owner's acts and for the classification, in the + authority profile. Until then those acts have no record kind of their own. +- **O-8** *(open)*: the observation need and the product-assurance declaration in the What's + schema. Until then they live in prose, and the guard of §5 rests on the capability pin. + +## Where this comes from + +This document sets out `DDD-dec-114`, which files Emil's rulings of 2026-11-06 to 2026-11-09: +Rounds 3 to 22 and 27 to 30, verbatim in +[`meta/sessions/2026-11-07-sdlc-and-pdlc/rulings.md`](../../meta/sessions/2026-11-07-sdlc-and-pdlc/rulings.md). +Rounds 16 to 28 entered by amendment before landing (Round 21). Round 28 ruled Claude's +construction item by item (R1 to R30), and Rounds 29 and 30 ruled the forecast. Where this text +and `DDD-dec-114` disagree, the decision governs. + +| Section | Rests on | +|---|---| +| Upstream basis | `DDD-frame-01`, `DDD-frame-02`, `DDD-ground-06`, `term:answerability`, `term:liability`, `term:seam-identity`, `term:capability`, pinned at `v5.15.2` | +| §0 | Round 16 (the capability pin as backstop); `DDD-dec-115` (the record from edition 1); method step 7 `[PROPOSED]`; O-8 | +| §1 The stance | Round 6, wording approved by Round 14, refined by Round 19 (the two assurances); Round 20 (DORA keys as answerability); Round 22 (capacity shared); `DDD-dec-115` S-6 (the occurrence record), S-10 (the DORA keys) | +| §1 The forecast | Round 29 (probabilistic forecasting, replacing R27's sketch; quoted: "we produce a certainty…", "we should use probalistic forecastin for this"); Round 27 (flow time; `DDD-dec-114` P-14); Round 30 (the 15th, 50th and 85th percentiles); Round 6 (the departure; quoted in the record) | +| §2 | Rounds 5, 6, 7, 8, 10, 11, 16–20, 22; authority.md §2–3 (`DDD-dec-87`, `DDD-dec-85`); Round 10 (the When owner as go-to-market owner); Round 11 (biggest contributor); Round 16 (the How owner's capability); Round 14 (ground: "Their ground is their own to control, but the seams between them supplies some to each") | +| §2.1 | Round 14's listing; rows 1 to 8 ruled as listed by `DDD-dec-120` (2026-11-11, Round 3 of the redo session), and rows 10 and 11 by the same decision, amended before landing (Round 4), superseding only `DDD-dec-114` P-3's "It is not ruled here"; Round 28, R7 (oS); Round 16 (the telemetry row, ruled); Round 22 (the last two rows, then Claude's additions); F-2 of the first session and Round 28, R8 (o2a before o1) | +| §3 | Round 18 ("its more than the needs it's everything the how needs in order to implement including the assurance"; the meter, "Yes (Recommended)"); Round 17; Rounds 18, 19; Round 28, R24 and R25 (the forms) | +| §4 | Round 19 (the two assurances, quoted in the record); Round 7 (the user-side share); Round 13 (independence of acceptance); Rounds 16, 17; Round 28, R2 (the two levels), R25; Round 19 correcting Round 18; Round 19, "Outcomes, read across seams (Recommended)"; Round 20 ("And if they don't thats fine - then it was properly not giving any value"; the falsifier withdrawn); Round 28, R20 | +| §5 | Round 16 ("I agree the telemetry is the hows to add and the rest is the what to gather…"); method step 10 `[PROPOSED]`; Round 17 ("what people needs to add their observability needs to the specification…"); Round 28, R24; how.md H-9 (`DDD-dec-60`, superseded by `DDD-dec-70` with the telemetry facts unchanged); Round 28, R26 (the capability pin, Claude's reading, ruled); `core/04`, `term:capability` | +| §6 | Round 10 ("Adopt it (Recommended)"); upstream core/05 §5; Round 20 (DORA keys); Round 28, R28 (the step 7 mapping, Claude's, ruled); `DDD-flow-04` files the rule as a claim | +| §7 | Round 4 ("Yes, four values (Recommended)"); Round 3 (declared on the issue; How as one locus); Round 19; Round 14 (ground across a seam); `DDD-dec-42` O-5 (tools never change the What); `DDD-address-01` (the causal time index); Round 22; Round 28, R13 (task) | +| §8 | Round 12 ("this also solves the classic problem of a product owner, owning the priority which is inherently wrong. That's a when decision"; "Yes, acts kept apart (Recommended)"); Round 22; Round 10; the 2020 Scrum Guide | +| §9 | Round 22 ("determination pull will come from different sources … Which is why bugs or technical debt is hard to put into the classic backlog"; kinds "Adopt (Recommended)"; classifier "What owner (Recommended)"); Round 7; Round 20's guard; Round 28, R19 (the falsifiers); `DDD-dec-118` and `DDD-flow-01` to `-04` read this section | +| §10 | Round 11, reading approved by Round 14 ("Yes, outcomes only (Recommended)"; "Yes, recorded (Recommended)"); Round 22; Round 26 (the How-owner option removed) | +| §11 | Round 28, R30 (the `lc:` vocabulary), R7 (oS), R18 (kind-scoped dependencies) | +| §12 | Round 5 ("Release toggles (Recommended)"); Round 10 ("Yes, as a constraint (Recommended)"); Rounds 16 and 17 (telemetry presence) | +| §13 | Round 9, reading approved by Round 14; `DDD-dec-115` S-6, S-10; upstream core/06 | +| §14 | Round 29 (falsifier 3); Round 30 (the calibration test); Round 20 and Round 28, R20 (falsifier 4, Claude's); Round 19 (the split that made the earlier falsifier wrong); Round 22 and Round 28, R19 (falsifiers 11, 12) | +| §15 | O-1: Round 28, R9; `DDD-dec-42`. O-2: Round 28, R10; `DDD-org-03`. O-3: Round 28, R7. O-4: Round 30 ("O-4 agreed as ruled"). O-5: Round 28, R8. O-7: Round 28, R2. O-8: Round 28, R24, R25. O-9: Round 27, raised by Round 26; `DDD-dec-114` P-14 | + +Supersedes `84aa466:applications/pdlc/pdlc.md`, rewritten for readers by +`meta/sessions/2026-11-09-applications-for-readers-redo/` (`DDD-dec-94`, `DDD-dec-95`). No rule +changed. The equivalence table is that session's `equivalence/pdlc.md`. diff --git a/applications/sdlc/README.md b/applications/sdlc/README.md index f01828f..ff78872 100644 --- a/applications/sdlc/README.md +++ b/applications/sdlc/README.md @@ -1,24 +1,45 @@ -# The SDLC Projection - -**The framework, denominated in software delivery.** This is the agentic/DAG design framework that -constituted the whole of Decision-Driven Design through v3. In v4 it takes its proper place: the -**engineering projection** of the general principle — *Conservation of Specification Demand*, which is -what *Conservation of Determination Demand* is called when the actor is building software. +# The SDLC projection — the framework, denominated in software delivery + + + +This folder is the **engineering projection** of the general principle. The agentic/DAG design +framework constituted the whole of Decision-Driven Design through v3. In v4 it takes its proper +place: *Conservation of Specification Demand* is what *Conservation of Determination Demand* is +called when the actor is building software. Nothing here is deprecated. The reframing is a promotion: what looked like the framework was always *one projection* of it. ---- - -**Upstream basis.** This document is part of the software projection; it builds on the -principle repo's canon (`actor-indexed-determination`). The `core/NN` references below resolve -there, pinned at a version and a status in `graph/upstream.yaml`: +**Upstream basis.** This document builds on the principle repository's canon +(`actor-indexed-determination`). The `core/NN` references below resolve there, pinned at a version +and a status in `graph/upstream.yaml`: -## How this relates to `core/` +## The documents here + +| Document | For | How settled it is | +|---|---|---| +| [`what.md`](what.md), with its [ontology, shapes, examples and checker](what/) | The opinionated specification of what a software application is and does: domains, behaviour, screens, who may act, and the behavioural-conformance wire. Moved here from the Product Framework (its §3, and the §6.3.1 wire protocol), in the ruled identity form | Ruled, and ratified by the merge of the move. One point is *(open)*: whether an adopter may register abstract interaction objects, which is the How's open question | +| [`how.md`](how.md), with its [vocabulary](how-vocabulary.md) and [worked decisions](how-examples/) | The How as decisions: constraint, binding and contract, anchored in the What, held by Writ, shipped as packages and imported by `basedOn` | Ruled. What the How left "not ruled separately" until its merge was ratified by that merge. One point is *(open)*: whether adopters may register What kinds. Three of its readings are *(Claude's reading, not yet confirmed by Emil)*: the baseline's ratchet semantics and an earlier decision's consequence for declared gaps (both §8.2), and the vocabulary's namespace IRI, under which nothing is served yet. | +| [`authority.md`](authority.md), with its [vocabulary](authority-vocabulary.md) and [reference evaluator](authority/) | The authority profile: what makes a decision in force in a product, who may make it so, and how that authority is founded, delegated and transferred | Ruled, and ratified by the merge of its pull request. Its vocabulary shares the namespace reading above *(Claude's reading, not yet confirmed by Emil)* | +| [`sdlc.md`](sdlc.md), with its [act map, record shape and checker](acts/) | The SDLC as an arrangement: the How owner's, from a released issue to production, dark behind a toggle. Issues drive agent sessions started by a label (Claude Code Action first); takt's `ready/` shape with Varve's force and no squash; Varve's identity map ported; every occurrence recorded as graph data from edition 1, with the DORA computations over that record | Ruled | +| [`production-as-ground.md`](production-as-ground.md) | Pre-production predicates close over substitute ground; DORA's four keys instrument the encode/verify gap; the three tiers of feedback loop and which are eliminable | Reported, partially: a retrodiction against DORA's published findings, not a statistical test | +| [`product-cli/product-definition.md`](product-cli/product-definition.md) | The definition of the rewritten product-cli, the tool that implements the What | A product definition in drafts, with its rulings dated where they land | + +**The What is owned in the PDLC and read here as ground** ([`../pdlc/`](../pdlc/README.md)). It +stays in this directory, where it was placed, and the SDLC never writes it. + +## How the general framework reads in software | In `core/` (general) | Here (software) | |---|---| @@ -30,83 +51,95 @@ there, pinned at a version and a status in `graph/upstream.yaml`: | Encode/verify (`apparatus`) | pinning controlled ground; verifying third-party APIs and live env | | Floor-in-the-predicate (`03`) | which decisions a model can own (closing predicate) vs. which need a human | -The design docs below predate the `core/` layer. They remain correct as *engineering guidance*; where -they reach for a foundational justification, that justification now lives in `core/`, stated more -generally and more carefully. - ---- - -## The design documents - -**The four v3 design documents are not in this tree.** They were removed at the v4 restructuring -(commit `219ad6c`, under their former `docs/` paths) and have not been re-landed; restoring them is -an open decision that has not been taken. They are listed here as the record of what the v3 -framework comprised — recoverable from this repository's git history — not as links: - -1. **`01-foundations.md`** *(history: `docs/01-foundations.md`)* — LLMs as knowledge forecasters; work as a chain of - context-conditioned decisions; value actions as the terminus; roles and artifacts; the DAG, not the - pipeline. *Start here for the software framing.* - -2. **`02-entity-reference.md`** *(history: `docs/02-entity-reference.md`)* — the vocabulary made precise: processes, - decisions, actions, interpretations, roles, artifacts, sessions, schemas, bundles, audits, the - orchestration system, per-role autonomy. - -3. **`03-autonomy-levels.md`** *(history: `docs/03-autonomy-levels.md`)* — the 0–5 autonomy ladder, why autonomy is - per-role not per-system, and why this structure is what makes Levels 4–5 reachable. *Now with a - sharper foundation: per-role autonomy is exactly the actor model's pinning resolution (`core/04`), - and the ceiling on a role's autonomy is set by the closure of its acceptance predicate (`core/03`).* - -4. **`04-implementation.md`** *(history: `docs/04-implementation.md`)* — the build architecture: Rust + Oxigraph, curated - SPARQL for bundle assembly, the event substrate, the worker contract, emergent decisions during - action, the meta-loop, the model catalog. - -Written against v4: - -- **[what](what.md)** · moved 2026-10-28, not yet ratified — the opinionated specification of what a software application is and does (Product Framework §3 and §6.3.1, moved by `DDD-dec-41`…), in the identity form of `DDD-dec-63`; with its [ontology, shapes, example and checker](what/) -- **[how](how.md)** · `[PROPOSED]`, unruled — the How as decisions: constraint, binding and contract, anchored in the What, held by Writ, shipped as packages and imported by `basedOn`; with its [vocabulary](how-vocabulary.md) and [worked decisions](how-examples/) -- **production-as-ground** · pre-production predicates close over substitute ground; DORA's four keys instrument the encode/verify gap; the three tiers of feedback loop and which are eliminable -- **[sdlc](sdlc.md)** · ruled by Round 28 (`DDD-dec-115`) — the SDLC as an arrangement: the How owner's, from a released issue to production, dark behind a toggle. Issues drive agent sessions started by a label (Claude Code Action first); takt's `ready/` shape with Varve's force and no squash; Varve's identity map ported; every occurrence recorded as graph data from edition 1; with its [act map, record shape and checker](acts/) - -**The What is owned in the PDLC and read here as ground** ([`../pdlc/`](../pdlc/README.md), `DDD-dec-114`, Round 8): it stays in this directory, where `DDD-dec-42` placed it, and the SDLC never writes it. - -> **Note.** The four historical documents were written before the v4 register (they say "law" -> where `core/` now says "principle," and lean on the pre-review immune framing). If they are ever -> restored to the tree, that reconciliation is the restoring session's work, and the `core/` layer -> wins wherever they conflict. Until then, this README and `production-as-ground.md` are what the -> SDLC projection carries here; the reference implementation is -> [`product-cli`](https://github.com/mindovermachine-dev/product-cli). - ---- - ## Where the projection sharpens the design Three places where `core/` gives the SDLC framework something it did not have before: **Which role gets which decision** is no longer a matter of taste. `core/03` says a decision can be -owned by a model iff its acceptance predicate closes over digital ground; otherwise it needs an actor -selected for competence on open predicates (a senior, a domain expert). *Autonomy is bounded by -closure.* +owned by a model if and only if its acceptance predicate closes over digital ground. Otherwise it +needs an actor selected for competence on open predicates (a senior, a domain expert). *Autonomy is +bounded by closure.* **The orchestration layer is a seam**, and `core/06` prices it: an orchestrator is cheap to specify -and expensive per run, a bottleneck, and the poisonable centre of the system. The compound move — -harvesting recurring coordination decisions into encoded rules, with a check on each — is how a +and expensive per run, a bottleneck, and the poisonable centre of the system. The compound move, +harvesting recurring coordination decisions into encoded rules with a check on each, is how a DDD-shaped system gets cheaper over time instead of paying full judgment cost on every run. **Verification of third-party and environment ground** is not optional and not build-triggered. -`apparatus/encode-verify.md` says why: their truth moves on their clock, so the check must run on a -schedule, and an unreachable source is `Unknown`, never a pass. - ---- +[`apparatus/encode-verify.md`](../../apparatus/encode-verify.md) says why: their truth moves on their +clock, so the check must run on a schedule, and an unreachable source is `Unknown`, never a pass. ## Reference implementation -**[`product-cli`](https://github.com/mindovermachine-dev/product-cli)** — the authoring layer for this projection: -owns features, ADRs, test criteria, dependencies; builds the derived graph; assembles curated bundles; -runs audits; serves the engineering graph. The companion orchestration harness is designed against the -patterns in `04-implementation.md`. +**[`product-cli`](https://github.com/mindovermachine-dev/product-cli)** is the reference +implementation: the authoring layer for this projection. It owns features, ADRs, test criteria and +dependencies; builds the derived graph; assembles curated bundles; runs audits; and serves the +engineering graph. The companion orchestration harness is designed against the patterns in +`04-implementation.md` (one of the v3 design documents below). That describes the Rust tool, which is the reference until its retirement. It is frozen at the tag `rust-final`. Its rewrite implements the What alone, `what.md` and its §6 wire protocol, and records the author's decisions over it as `dpp/1` records that carry no force. The rewrite is defined here, beside the What it implements: [`product-cli/product-definition.md`](product-cli/product-definition.md). Its code, ADRs and tests stay in the product-cli repository. + +## The four v3 design documents + +**They are not in this tree.** They were removed at the v4 restructuring (commit `219ad6c`, under +their former `docs/` paths) and have not been re-landed. Restoring them is a decision that has not +been taken *(open)*. They are listed here as the record of what the v3 framework comprised, +recoverable from this repository's git history, and not as links. They predate the `core/` layer. +They remain correct as *engineering guidance*; where they reach for a foundational justification, +that justification now lives in `core/`, stated more generally and more carefully. + +1. **`01-foundations.md`** *(history: `docs/01-foundations.md`)*: LLMs as knowledge forecasters; + work as a chain of context-conditioned decisions; value actions as the terminus; roles and + artifacts; the DAG, not the pipeline. *Start here for the software framing.* +2. **`02-entity-reference.md`** *(history: `docs/02-entity-reference.md`)*: the vocabulary made + precise: processes, decisions, actions, interpretations, roles, artifacts, sessions, schemas, + bundles, audits, the orchestration system, per-role autonomy. +3. **`03-autonomy-levels.md`** *(history: `docs/03-autonomy-levels.md`)*: the 0–5 autonomy ladder, + why autonomy is per-role not per-system, and why this structure is what makes Levels 4–5 + reachable. *Now with a sharper foundation: per-role autonomy is exactly the actor model's pinning + resolution (`core/04`), and the ceiling on a role's autonomy is set by the closure of its + acceptance predicate (`core/03`).* +4. **`04-implementation.md`** *(history: `docs/04-implementation.md`)*: the build architecture: + Rust + Oxigraph, curated SPARQL for bundle assembly, the event substrate, the worker contract, + emergent decisions during action, the meta-loop, the model catalog. + +The four were written before the v4 register: they say "law" where `core/` now says "principle", +and lean on the pre-review immune framing. If they are ever restored to the tree, that +reconciliation is the restoring session's work, and the `core/` layer wins wherever they conflict. + +## Not settled yet + +- **The four v3 design documents** *(open)*: whether to restore them. Restoring them would put the + v3 engineering guidance back in the tree, reconciled to the v4 register. +- **The `sdlc:` namespace IRI** *(Claude's reading, not yet confirmed by Emil)*: no IRI under + `/ns/sdlc` is served or registered yet, and the choice is Emil's. Both vocabularies use it. +- **Whether an adopter may register What kinds** *(open)*, including abstract interaction objects: + `what.md` and `how.md` both point to it. Deciding it would say whether such a kind is a + vocabulary change in this repository or something an adopter can add. +- **Per document.** Each document above lists its own open points under its own "Not settled yet". + +## Where this comes from + +| Section | Rests on | +|---|---| +| The engineering projection; the mapping table; where the projection sharpens the design | Upstream canon at the pin: `term:floor` (`core/03`), `DDD-frame-01`, `term:seam-identity` (`core/06`), actors (`core/04`); `apparatus/encode-verify.md` | +| `what.md`, ruled and ratified | `DDD-dec-41` (the move), `DDD-dec-42` (placed in this directory), `DDD-dec-63` (identity form), `DDD-dec-64` (the move's own choices); ratified by the merge of PR #42 (`2b6e4a7`), each decision naming the pull request's acceptance as the ratification act | +| `how.md`, ruled | `DDD-dec-55` to `-61`, superseded on the same terms by `DDD-dec-65` to `-71`; ratified by the merge of PR #41 (`1d0f40c`); `DDD-dec-119` (Round 2 of `meta/sessions/2026-11-09-applications-for-readers-redo/`): the parts "not ruled separately" were ratified by that merge. The earlier text of this page called `how.md` "`[PROPOSED]`, unruled"; that was stale | +| `authority.md`, ruled | `DDD-dec-85`, `-86`, `-92`, `-93`; ratified by the merge of PR #45 (2026-11-02) | +| The `sdlc:` namespace IRI, a reading | `how-vocabulary.md` and `authority-vocabulary.md`, each marking it `UNVERIFIED — Emil review` | +| `sdlc.md`, ruled | `DDD-dec-115` (S-11: Round 28 ruled its proposals; Round 30 entered by amendment) | +| `production-as-ground.md` | its own status line, "reported, partially" | +| `product-cli/product-definition.md` | its own drafts and rulings; sdlc edition 1, `DDD-dec-113` | +| The What owned in the PDLC, read here as ground | `DDD-dec-114`, Round 8 ("Stays, read as ground"); `DDD-dec-42` placed it here | +| Reference implementation | product-cli; the rewrite's definition in `product-cli/product-definition.md` | +| The four v3 design documents | Removed at commit `219ad6c`, former paths `docs/01-foundations.md` to `docs/04-implementation.md` | +| How this page is written | `DDD-dec-94`, `DDD-dec-95` | + +The earlier text of this page said that, until the v3 documents are restored, "this README and +`production-as-ground.md` are what the SDLC projection carries here". That stopped being true when +`what.md`, `how.md`, `authority.md` and `sdlc.md` landed, and the sentence is removed. The earlier +text is at `84aa466:applications/sdlc/README.md`. diff --git a/applications/sdlc/authority-vocabulary.md b/applications/sdlc/authority-vocabulary.md index 9bd0b5a..6dab2f3 100644 --- a/applications/sdlc/authority-vocabulary.md +++ b/applications/sdlc/authority-vocabulary.md @@ -1,14 +1,27 @@ # The authority vocabulary — `sdlc:` -**Status:** with [`authority.md`](authority.md) (`DDD-dec-85`, `DDD-dec-86`). Written 2026-11-02; -not yet ratified. + + +The terms of the authority profile, [`authority.md`](authority.md): one per record kind, with the +shape each takes in a `dpp/1` record, the terms that are computed and never recorded, and where +Writ's terms meet them. Read it beside the profile when you write or check a record. + +**How settled this is.** Decided, with the profile, which was ratified when its pull request merged +on 2026-11-02. One point is Claude's reading, not yet confirmed by Emil: the namespace IRI below is +not served yet. **Namespace.** `https://decision-driven-design.dk/ns/sdlc#`, prefix `sdlc:`, beside the How's terms ([`how-vocabulary.md`](how-vocabulary.md)) and the What's ([`what/ontology.ttl`](what/ontology.ttl)). -`UNVERIFIED — Emil review`: no IRI under `/ns/sdlc` is served yet (successor item M-10 of the -move). +No IRI under `/ns/sdlc` is served yet *(Claude's reading, not yet confirmed by Emil)*. -**In records.** *Ruled (Round 1, F-2).* +**In records.** - **Where.** Every term below lives, in a `dpp/1` record, in the hashed dotted member `dk.decision-driven-design.authority`. Its `record` names the kind. - **Never `extensions`.** Nothing here is in `extensions`. @@ -34,7 +47,7 @@ header clocks (authority.md §6.2). A grant is named by its `id`, and a version | `sdlc:Transfer` | A genesis version naming a successor, pending until the successor's grant acceptance (§2.3) | as `sdlc:Genesis`, with `supersedes` the version in force and `holder` the successor | | `sdlc:Grant` | A delegation of a scope from a grant the grantor holds (§3) | `…record: "grant"`; `parent` (the grant `id` it delegates from), `grantee`, `scope`, `mayDelegate: "yes"` (optional), `firstKey` (when the grantee has no key), `fallbackOf` (for a fallback, §2.4, with no `scope`). `basedOn` pins the parent's version | | `sdlc:Scope` | A set of ontology classes, optionally narrowed to one element's `within*` subtree (§3.1) | `{classes: [class names], within: IRI, withinPath: [IRI, …, P]}`; the last two optional | -| `sdlc:mayDelegate` | Whether a grant may delegate (§3.2; Round 1, Q-8) | `…mayDelegate: "yes"`; absent means no | +| `sdlc:mayDelegate` | Whether a grant may delegate (§3.2) | `…mayDelegate: "yes"`; absent means no | | `sdlc:Fallback` | A grant that acts for its primary while the primary is unavailable, and never transfers (§2.4) | `sdlc:Grant` with `fallbackOf` equal to `parent` | | `sdlc:GrantAcceptance` | The grantee's signed acceptance of a grant version. A grant is live only from it (§3.3) | `…record: "grant-acceptance"`; `grant` (the version's reference), pinned in `basedOn` | | `sdlc:Revocation` | The end of a grant and of its chain below, from its position (§3.5) | `…record: "revocation"`; `revokes` (grant `id`), `under` (the revoker's grant `id`, above the revoked one) | @@ -45,13 +58,13 @@ header clocks (authority.md §6.2). A grant is named by its `id`, and a version | `sdlc:Attribution` | The naming of an identity as a machine, with the human responsible (§5.1) | `…record: "attribution"`; `machine`, `responsible` | | `sdlc:Acceptance` | A human holder's signed acceptance of one or more decision versions under a grant (§4.1) | `…record: "acceptance"`; `grant` (the version's reference), `accepts` (references), `touches` (§4.2), `baseline` (optional, §4.3). `basedOn` pins every accepted version and the grant | | `sdlc:touches` | The scope result recorded at signing: per decision, the items it touches (§4.2) | `…touches: {decision reference: [{class, element, path}]}` | -| `sdlc:BaselineEntry` | A known violation the acceptance takes the decision in force with: debt (§4.3; how.md D-6) | an element of `…baseline`: `{decision, subject, target}` | +| `sdlc:BaselineEntry` | A known violation the acceptance takes the decision in force with: debt (§4.3; `how.md`'s (decision, element, target)) | an element of `…baseline`: `{decision, subject, target}` | | `sdlc:AcceptanceRevocation` | The withdrawal of an acceptance from its position (§4.6) | `…record: "acceptance-revocation"`; `revokes` (the acceptance's reference), `under` (when not by its signer) | | `sdlc:Review` | A rejection or request for change, under a grant that could have accepted. No force (§4.5) | `…record: "review"`; `grant`, `reviews` (pinned), `verdict` (`"reject"`, `"request-change"`), `touches` | | `sdlc:Waiver` | A signed answer to an open question that changes no decision, live until a header-clock time (§4.4) | `…record: "waiver"`; `grant`, `question: {decision, target, provenance}`, `expires`, `touches`. `basedOn` pins the decision and the grant | | `sdlc:Refusal` | An attempted act the log refused, recorded with its reason (§5.1, §6.1) | not a record: an entry in its header's `refused`, `{ref, hash, reason}`, pinning the attempted record | | `sdlc:Header` | One position of the positioned log (§6.1) | not a `dpp/1` record: `{system, position, clock, previous, records, refused, hash}`, hashed by the hash law | -| violation description | A decision's evaluable declaration of what violates it (§7; `DDD-dec-52`) | `…violation: {language, binds, text}` | +| violation description | A decision's evaluable declaration of what violates it (§7) | `…violation: {language, binds, text}` | ## 2. Computed, never recorded @@ -65,7 +78,7 @@ header clocks (authority.md §6.2). A grant is named by its `id`, and a version ## 3. Where Writ's terms meet these -As Writ's definition states them (`[D2]`, `[D2.5]`). The profile is the authority on force, and +As Writ's definition states them. The profile is the authority on force, and Writ on enforcing it. | Here | Writ | @@ -74,6 +87,33 @@ Writ on enforcing it. | `sdlc:Grant`, `sdlc:Scope` | a grant naming a holder and a scope; a scope as named graphs narrowed by a SHACL target. Here it is classes and a `within*` subtree, which `sh:targetClass` with a subtree filter expresses | | `sdlc:Acceptance`, `sdlc:touches` | acceptance under grant; "scope is evaluated when the acceptance is signed and the result recorded with it" | | `sdlc:BaselineEntry` | the baseline on an acceptance, by decision IRI and fact IRIs; G11 | -| `sdlc:Waiver` | a waiver with a review-by. Here it is a header-clock time, and Writ follows (Round 1, Q-6) | +| `sdlc:Waiver` | a waiver with a review-by. Here it is a header-clock time, and Writ follows | | `sdlc:Attribution` | agent attribution, an agent identity mapped to the human responsible | | `sdlc:Header` | a Varve commit header: the writer's clock, covered by the header hash (`[D2.3]`, `[D2.11]`) | + +--- + +## Not settled yet + +- **The namespace IRI** *(Claude's reading, not yet confirmed by Emil)*. No IRI under + `/ns/sdlc` is served yet. Deciding it would say where the terms resolve. +- **Scopes over decision kinds, and roles.** A later decision extends a scope to decision kinds + and adds roles (see `authority.md`, "Not settled yet"). `sdlc:Scope` below still reads "a set + of ontology classes", and has not been reworked to it. + +## Where this comes from + +Written on 2026-11-02 with the profile, by the authority-profile session +(`meta/sessions/2026-11-02-authority-profile/`). Ratified by the merge of PR #45 on 2026-11-02. + +| Part | Rests on | +|---|---| +| The whole | `DDD-dec-85` (the charter), `DDD-dec-86` (Round 1); as amended by `DDD-dec-92` and `DDD-dec-93` | +| Namespace | The IRI not served: successor item M-10 of the What move; `UNVERIFIED — Emil review` in the old text | +| In records | Round 1, F-2 | +| `sdlc:mayDelegate` | Round 1, Q-8 | +| `sdlc:BaselineEntry` | `how.md` D-6 | +| violation description | `DDD-dec-52` | +| §3, Writ's terms | Writ's definition, `[D2]` and `[D2.5]`; the waiver's header-clock time: Round 1, Q-6 | + +Supersedes `84aa466:applications/sdlc/authority-vocabulary.md` in place. diff --git a/applications/sdlc/authority.md b/applications/sdlc/authority.md index 66cd78f..779986e 100644 --- a/applications/sdlc/authority.md +++ b/applications/sdlc/authority.md @@ -1,15 +1,37 @@ # The authority profile — force over a product -**Status: written 2026-11-02 to the plan ruled in Round 1, with Appendix A ruled in Round 2 and -Q-11 and the fixtures' re-founding ruled in Round 3; not yet ratified (Emil merges #45).** This is the -profile the Decision Provenance Protocol leaves to its adopters (`dpp-1.md` §9.4). It says what -makes a decision in force in a product, who may make it so, and how that authority is founded, -delegated and transferred. The session is `meta/sessions/2026-11-02-authority-profile/`. The -charter's rulings are `DDD-dec-85`, Round 1's are `DDD-dec-86`, Round 2's are `DDD-dec-92`, and Round 3's are `DDD-dec-93`. Emil ratifies by merging. + + +This is for anyone who builds, checks or relies on a product's decision log. The Decision +Provenance Protocol (`dpp/1`) defines records and leaves force to its adopters (`dpp-1.md` §9.4). +This profile supplies it. It says what makes a decision in force in a product, who may make it so, +and how that authority is founded, delegated and transferred. After reading it you can evaluate any +decision at any position of a positioned log, and say which acceptances, grants and keys make it +in force or keep it out. + +**How settled this is.** Everything here is decided. The profile was ratified when its pull request +merged on 2026-11-02, and no point in it is open or waiting for a ruling. One later decision +(2026-11-08) amends it: the product framework carries roles, and a scope also ranges over decision +kinds. §3.1, §3.2 and Appendix B's roles row have not yet been reworked to it ("Not settled yet"). It has been executed over +one hand-built worked example (§9) and over generated histories (§8.3). Neither shows that any +other implementation or any real log holds it. -**Register.** *Ruled* cites a decision. After Round 3 no `UNVERIFIED` mark remains and nothing is open. `UNVERIFIED — Emil review` marked a choice the writing had -to make that no ruling covers. Each such choice is also listed in Appendix A. Section numbers are -the ones `DDD-dec-86` cites. +**Who it binds.** Writ implements it. product-cli's draft log never claims it. A Context& package +is a product under it. + +**Where to start.** +- To know when a decision is in force: §4.7, then §4.1 and §4.2. +- To set up who may decide: §2 (the genesis) and §3 (grants). +- To sign: §5 (identities and keys) and §6 (positions and clocks). +- To claim conformance: §8. +- To see it all happen: §9. **Companions.** - The vocabulary is [`authority-vocabulary.md`](authority-vocabulary.md). @@ -18,9 +40,6 @@ the ones `DDD-dec-86` cites. - The worked example is the acme shop product's authority history: [`how-examples/log/acme.json`](how-examples/log/acme.json) and its records, checked by [`how-examples/check.py`](how-examples/check.py) (§9). -**Who it binds.** Writ implements it. product-cli's draft log never claims it. A Context& package -is a product under it. - --- ## 1. Scope @@ -42,19 +61,18 @@ force for one kind of system: a **product**, the decision space someone brought | Not here | Where it is | |---|---| -| The record, the reference, the resolver, the hash law | `dpp/1` (`DDD-dec-62`) | +| The record, the reference, the resolver, the hash law | `dpp/1` | | What a How decision is, its kinds, anchoring, packages, import | [`how.md`](how.md) | | What a What element is, its kinds, identity, What-versions | [`what.md`](what.md) | | Verdicts, readings, the gate's verbs, positions as Writ writes them | Writ | | The ratchet over code landings (a landing that shrinks a baseline) | Writ, G11. The profile states the rule (§4.3) and Writ enforces it | -| Attestations (`what.md` §3.2.3) | a successor item (Round 1, Q-10) | +| Attestations (`what.md` §3.2.3) | later work, not this profile | ### 1.3 Where the profile's fields live -*Ruled (Round 1, F-2):* "Anything a signature must cover (a grant's scope, a baseline, a waiver's -expiry, a key binding) is a top-level dotted member inside the canonical form, as how-vocabulary.md -does it. extensions is for what may change without a new version, and nothing authority-bearing -may." +The rule: anything a signature must cover (a grant's scope, a baseline, a waiver's expiry, a key +binding) is a top-level dotted member inside the canonical form, as `how-vocabulary.md` does it. +`extensions` is for what may change without a new version, and nothing authority-bearing may. - **One member.** Every field this profile defines is in the hashed dotted member `dk.decision-driven-design.authority`. Its `record` names the record kind (vocabulary §1). @@ -68,14 +86,16 @@ may." ### 1.4 The rulings this rests on -| Ruling | Decision | -|---|---| -| The genesis grant: definition, space, transfer, home | `DDD-dec-46`, restated by `DDD-dec-85` | -| "Signed": signature, acceptor and time, required for force | `DDD-dec-47`, read by Round 1, F-1 | -| Force comes from this profile: genesis, grants, scopes, acceptance, baseline, waiver | `DDD-dec-54` ruling 4 | -| Scopes over ontology classes; the multi-scope rule | `DDD-dec-64` P-7, Round 5 of the move | -| The charter's eight rulings | `DDD-dec-85` | -| F-1 to F-3, Q-1 to Q-10 | `DDD-dec-86` | +What the profile rests on, by subject. The decisions that hold each are in "Where this comes from". + +| Subject | +|---| +| The genesis grant: its definition, its space, transfer, and where it lives | +| What "signed" means: a signature, an acceptor and a time, required for force | +| That force comes from this profile: the genesis, grants, scopes, acceptance, baselines and waivers | +| Scopes over ontology classes, and the multi-scope rule | +| The charter's eight rulings | +| The rulings on the profile's plan, its readings, and its fixtures | --- @@ -83,7 +103,7 @@ may." ### 2.1 Definition -*Ruled, verbatim (2026-10-27, `DDD-dec-46`):* +The definition, as ruled: > The genesis grant is the root of change authority over one product. It is held by the human > principal who brought the product into being. It is unscoped within the product and scoped to @@ -94,14 +114,14 @@ may." A product is the decision space. Its What and its realisation are scopes within it, under one genesis. A package is a product with an empty What and its own genesis. In another product it is -provenance, never authority (`DDD-dec-85`). +provenance, never authority. ### 2.2 Founding -*Ruled (Round 1, Q-1): the genesis is founded, not accepted.* +The genesis is founded, not accepted. - **The founding record** is a `genesis` record. Its `by` and `holder` are the founder, and it - names the product IRI P (`DDD-dec-63` §1). Its `basedOn` is empty, so it delegates from nothing. + names the product IRI P. Its `basedOn` is empty, so it delegates from nothing. - **Self-bound key.** It carries `firstKey`, and it is signed by that key. The founding is therefore also the holder's first key binding (§5.3; the ledger's D7, as it fits). - **No acceptance.** A separate acceptance would be the same person's signature twice over the @@ -111,7 +131,7 @@ provenance, never authority (`DDD-dec-85`). ### 2.3 Transfer -*Ruled (`DDD-dec-46`; Round 1, Q-1, Q-2).* A transfer is a decision, never an edit. +A transfer is a decision, never an edit. 1. **The holder signs.** The holder signs a new version of the genesis decision. It supersedes the version in force and names the successor as `holder`. If the successor has no key in the @@ -119,21 +139,19 @@ provenance, never authority (`DDD-dec-85`). 2. **The successor accepts.** The successor signs a grant acceptance of that version (§3.3). Until then the transfer is pending, and the prior holder still holds. 3. **The prior grant closes.** On the successor's acceptance, the prior holder's genesis is closed, - not deleted. *Ruled (Q-2): closing is not a revocation.* Every grant delegates from the genesis - decision's `id`, not from a holder's version, so nothing delegated from the genesis falls at a - transfer. + not deleted. Closing is not a revocation. Every grant delegates from the genesis decision's + `id`, not from a holder's version, so nothing delegated from the genesis falls at a transfer. 4. **Only the holder transfers.** A fallback may not transfer (§2.4). ### 2.4 Unavailability and fallback -*Ruled (`DDD-dec-46`):* "Holder unavailability is filed unavailability with a fallback holder, who -may act and may not transfer." +The rule: holder unavailability is filed unavailability with a fallback holder, who may act and may +not transfer. - **A fallback is a grant.** It carries `fallbackOf` naming its primary. It is granted by the primary's holder and delegates from the primary. Its scope is the primary's at every position, so it carries none of its own. Like any grant, it is live only from its holder's acceptance - (§3.3). *Ruled (Round 2, A-6):* "any grant may have a fallback, and a fallback delegates from - its primary". + (§3.3). Any grant may have a fallback, and a fallback delegates from its primary. - **Unavailability.** It is a signed record naming the grant, with `from` and an optional `until`, both header-clock times (§6.2). The holder files it, or a holder above them in the chain does. The holder ends it early with an availability record. @@ -146,14 +164,15 @@ may act and may not transfer." ### 2.5 Loss -*Ruled (`DDD-dec-46`):* "Loss of the holder with no fallback cannot be repaired from inside: a new -genesis founds a new product, and the old product's decisions are imported by basedOn, which keeps -provenance and records that authority was re-founded." +The rule: loss of the holder with no fallback cannot be repaired from inside. A new genesis founds a +new product, and the old product's decisions are imported by `basedOn`, which keeps provenance and +records that authority was re-founded. -**Key loss is not holder loss.** *Ruled (Round 3, Q-11):* "A genesis holder who loses a key still -holds the genesis. What is needed is a new key binding, and the one party the holder pre-authorised -is the fallback." A-9 for the genesis reads: "by a new key binding vouched by a fallback; absent any -fallback, by the new-product path". Round 2's "by transfer" is withdrawn. +**Key loss is not holder loss.** A genesis holder who loses a key still holds the genesis. What is +needed is a new key binding, and the one party the holder pre-authorised is the fallback. For the +genesis, a holder with no live key gets one "by a new key binding vouched by a fallback; absent any +fallback, by the new-product path". The earlier ruling, that such a holder gets a key by +transfer, is withdrawn. - **The vouch.** The holder of a live fallback of the genesis signs a `key-binding` with `act: "vouch"`, naming the genesis holder and the new key, under their fallback grant (`under`). @@ -165,7 +184,7 @@ fallback, by the new-product path". Round 2's "by transfer" is withdrawn. from that position. - **No transfer.** The fallback still may not transfer. - **No path.** Only when the holder and every fallback have lost their keys is there no path. That - is the ruled new-product case above. + is the new-product case above. ### 2.6 Adopting the profile @@ -176,7 +195,7 @@ shop example does this (§9). Its stand-ins were signed by keys that no longer e founding names the same holder and P under a new key, superseding the stand-in genesis for provenance. -**Test fixtures, re-founded once.** *Ruled (Round 2, A-5; widened in Round 3, P-9):* +**Test fixtures, re-founded once.** - **The once.** Every test product in this repository whose stand-in records were signed by discarded keys is re-founded once. The founding is under a key kept with the fixture, with the same holder and the same product IRI. Its record states that it is a test-fixture re-founding, @@ -194,8 +213,8 @@ provenance. ### 3.1 Scope -*Ruled (`DDD-dec-85`; `DDD-dec-64` P-7).* A **scope** is a set of ontology classes, optionally -narrowed to one element's `sdlc:within*` subtree. +A **scope** is a set of ontology classes, optionally narrowed to one element's `sdlc:within*` +subtree. - **The record.** `scope` is `{classes, within?, withinPath?}`. `classes` is a non-empty list of class names (`sdlc:Field`, `sdlc:Binding`). `within` is an element IRI. `withinPath` is that @@ -213,7 +232,7 @@ narrowed to one element's `sdlc:within*` subtree. ### 3.2 Delegation -*Ruled (Round 1, Q-8):* "A grant delegates only if it says so, and only a subset of its own scope." +A grant delegates only if it says so, and only a subset of its own scope. - **A grant is a decision of its grantor.** Its `by` acts under the grant named as `parent`, which they hold, live and available. The grant pins that parent's version in `basedOn`, and is signed @@ -231,8 +250,7 @@ narrowed to one element's `sdlc:within*` subtree. ### 3.3 Grant acceptance -*Ruled (Round 1, Q-1):* a grant is live only from its grantee's signed acceptance. Authority is -never imposed. +A grant is live only from its grantee's signed acceptance. Authority is never imposed. - **The record.** A `grant-acceptance` names and pins the grant version. Its `by` is the grantee. - **Its key.** If the grantee has no key in the product, it is signed by the `firstKey` the grant @@ -250,8 +268,6 @@ never imposed. ### 3.5 Revocation -*Ruled (Round 1, Q-2).* - - **Who.** A grant is revoked by a `revocation` record from its grantor, or from any holder above it in the chain, made under that holder's grant (`under`). The genesis is never revoked. It is transferred (§2.3). @@ -269,8 +285,8 @@ never imposed. ### 4.1 The acceptance record -*Ruled (`DDD-dec-47`; Round 1, F-1):* "An acceptance is its own signed record whose by and at are -the acceptor and the time, and which pins the decision's version hash." +The rule: an acceptance is its own signed record whose `by` and `at` are the acceptor and the time, +and which pins the decision's version hash. An `acceptance` record: @@ -289,14 +305,14 @@ An `acceptance` record: ### 4.2 What a decision touches, and the multi-scope rule -- **Scope at signing.** *Ruled (`DDD-dec-85`):* "Scope is evaluated at signing and the result - recorded; a later change to the graph does not re-evaluate it." +- **Scope at signing.** Scope is evaluated at signing and the result recorded; a later change to + the graph does not re-evaluate it. - **What an acceptance records.** For each decision it accepts, it records in `touches` the items that decision touches. Each item is `{class, element, path}`: the class, the element, and the element's `within*` path as the graph had it at signing. -- **What a decision touches.** *Ruled (Round 2, A-11):* "'touches' means every element the - decision creates, changes or retires, per the scope wording" (what.md §5.1). It is ruled as - proposed, and is read so that a How decision is the one element it creates: +- **What a decision touches.** Every element the decision creates, changes or retires, per the + scope wording (`what.md` §5.1). This is read so that a How decision is the one element it + creates: - a What change touches each element it creates, changes or retires, with that element's kind; - a How decision touches the class of its kind (`sdlc:Constraint`, `sdlc:Binding`, `sdlc:Contract`) at its anchor; @@ -305,47 +321,43 @@ An `acceptance` record: - **Covering.** A grant covers an item if the item's class is in its effective classes, the class is not derived, and the grant's subtree, if any, is on the item's path. An acceptance covers the items its grant covers, and covers at least one, or it is refused. -- **The multi-scope rule.** *Ruled (`DDD-dec-64` P-7; `DDD-dec-85`):* "a decision touching kinds in - more than one scope needs a valid acceptance under each, from the same or different holders, in - force only when all are live." Here: a decision's items must all be covered by live acceptances, - together. Acceptances of one decision must record the same items. A later one that records - different items is refused. +- **The multi-scope rule.** As ruled: "a decision touching kinds in more than one scope needs a + valid acceptance under each, from the same or different holders, in force only when all are + live." Here: a decision's items must all be covered by live acceptances, together. Acceptances of + one decision must record the same items. A later one that records different items is refused. ### 4.3 Baselines -*Ruled (`DDD-dec-85`):* "Baseline on an acceptance; landings only shrink it; only a fresh -acceptance grows it." +The rule: a baseline is on an acceptance; landings only shrink it; only a fresh acceptance grows it. - **The entries.** A `baseline` is a list of entries on an acceptance. Each entry is `{decision, subject, target}`: the decision accepted, the element violating it, and the target. - This is `how.md` D-6's (decision, element, target). + This is `how.md`'s (decision, element, target). - **Under the signature.** The baseline is signed with the acceptance. - **Only by acceptance.** Only an acceptance carries one. Only a fresh acceptance of the decision grows it. - **Landings shrink it.** A landing that removes a baselined violation records the smaller baseline - at its position, without a signature (Writ `[D2]`; G11). + at its position, without a signature (Writ's definition; G11). - **What it marks.** A baseline entry marks debt. A boundary is an exclusion decision, never a baseline entry (`how.md` §8.2). ### 4.4 Waivers -*Ruled (`DDD-dec-85`):* "a signed, expiring answer to an open question that changes no decision." +A waiver is a signed, expiring answer to an open question that changes no decision. - **The record.** A `waiver` names the question: `{decision, target, provenance}`, an open question in Writ's sense (`how.md` §9.3). It carries the grant it is made under, `expires` and `touches`. - **Who may waive.** It is signed under a grant that could accept the decision (§4.2), by a human (§5.1). -- **When it expires.** *Ruled (Round 1, Q-6):* "expiry is a header-clock time, and Writ follows." - A waiver is live at a position iff that position's header clock is before `expires`. It must - expire after the clock of the position it lands at. +- **When it expires.** Expiry is a header-clock time, and Writ follows. A waiver is live at a + position iff that position's header clock is before `expires`. It must expire after the clock of + the position it lands at. - **What it changes.** No decision, and nothing in force. The gate reports the question as waived while the waiver is live, and open after. - **What it never covers.** A violation, or a coverage gap (`how.md` §8.2). ### 4.5 Reviews -*Ruled (Round 1, Q-4).* - - **What it is.** A `review` is a rejection (`"reject"`) or a request for change (`"request-change"`) of a landed decision version, which it pins. - **Who may review.** It is signed under a grant that could have accepted that version at that @@ -355,7 +367,7 @@ acceptance grows it." ### 4.6 Revoking an acceptance -*Ruled (Round 1, Q-2):* "an acceptance may be revoked." An `acceptance-revocation`: +An acceptance may be revoked. An `acceptance-revocation`: - **Who.** It is signed by the acceptance's own signer, or by a holder of a grant above the grant the acceptance was made under (`under`). @@ -374,7 +386,7 @@ A decision D is **in force at position p** iff: re-acceptance by p (§5.1, §5.3); 3. no decision in force at p supersedes it. -**Force is local.** *Ruled (`DDD-dec-85`):* "Force is local; `basedOn` carries provenance only." +**Force is local; `basedOn` carries provenance only.** - **Other systems.** A record in another system, a package's included, is never in force here. - **Imports.** A decision here that rests on one is in force only under acceptances here. An import is that (`how.md` §7). @@ -386,8 +398,6 @@ A decision D is **in force at position p** iff: ### 5.1 Human, machine, attribution -*Ruled (`DDD-dec-85`; Round 1, Q-5).* - - **Machine.** A machine identity is one named by a signed `attribution` record: identity M is software, and human H is responsible for it. - Any holder of a live grant may file one. @@ -409,13 +419,11 @@ A decision D is **in force at position p** iff: ### 5.2 Teams -*Ruled (Round 1, Q-5).* A team identity (a list, a group mailbox, a role account) is not a holder. -A holder is one person. A team is expressed as several grants. +A team identity (a list, a group mailbox, a role account) is not a holder. A holder is one person. +A team is expressed as several grants. ### 5.3 Keys -*Ruled (Round 1, Q-3).* - **Bindings.** - **Per product.** Keys are bound per product, and nothing in one product's key bindings has effect in another. @@ -432,15 +440,14 @@ A holder is one person. A team is expressed as several grants. **The `key-binding` record.** It has three acts, and a fourth for the genesis alone (§2.5): - **`add`.** It binds a further key. It is signed by a live key of the holder. If the holder has no - live key, a holder above them in the chain binds it, under their grant (ruled, Round 2, A-9; - for the genesis, §2.5). + live key, a holder above them in the chain binds it, under their grant (for the genesis, §2.5). - **`rotate`.** It binds a new key and closes an old one at the same position. It is signed by the key it closes. - **`close`.** It is signed by the holder, or by a holder above them, under their grant. A closed key never signs again in the product, and is never bound again. - **`vouch`.** Only for the genesis holder, by the holder of a live fallback of the genesis, naming the holder and the new key. It opens nothing. The holder's `add` that pins it, signed by - the new key, opens it (§2.5; Round 3, Q-11). + the new key, opens it (§2.5). **Compromise: `since`.** A `close` may carry `since`, a position at or before its own. - **What stands.** Acceptances signed by that key from `since` stay valid at their positions, so @@ -458,7 +465,7 @@ listed before a close in the same position was signed while the key was live. ### 6.1 The positioned log -*Ruled (Round 1, Q-6).* The profile requires a positioned log. Each header carries: +The profile requires a positioned log. Each header carries: - `position`, consecutive from `"1"`; - `clock`, the writer's clock, an RFC 3339 UTC time; @@ -467,22 +474,20 @@ listed before a close in the same position was signed while the key was live. - `refused`: each attempt refused here, as `{ref, hash, reason}`; - `hash`, the hash law of `dpp-1.md` §5 over the header without `hash`. -The header hash covers the clock, the previous header and every pin. That is the -provenance-conformant log of Writ `[D2.5]` ("whose header carries the writer's clock and is -covered by the header hash"), with the profile's records in it. +The header hash covers the clock, the previous header and every pin. That is Writ's +provenance-conformant log ("whose header carries the writer's clock and is covered by the header +hash"), with the profile's records in it. ### 6.2 Clocks -*Ruled (Round 1, Q-6, F-3).* - - **Header clocks only.** Every time-dependent evaluation reads the header clock of the position being evaluated, never a process clock: grant liveness, unavailability windows, key validity, waiver expiry, session leases. - **A record's own `at`** is its author's claim (`dpp-1.md` §11.4). It is never read for force. An - act of authority whose `at` differs from its header's clock is refused (ruled, Round 2, A-8). The - comparison is at the precision `at` carries: a date-only `at` must be the clock's date, and an - `at` with a time must be the clock. -- **`[D2.11]`, as Emil states it (Round 1, F-3):** + act of authority whose `at` differs from its header's clock is refused. The comparison is at the + precision `at` carries: a date-only `at` must be the clock's date, and an `at` with a time must + be the clock. +- **Writ's `[D2.11]`, as Emil states it:** - Header clocks are monotone by the writer's clamp: ts = max(clock, head). A backwards wall-clock step yields equal timestamps, never a refusal. The evaluator therefore accepts equal clocks and refuses only a clock that steps back. @@ -499,14 +504,13 @@ covered by the header hash"), with the profile's records in it. A system without a positioned log cannot claim this profile. It can claim `dpp/1` conformance. With a positioned log and no authority records, it can also claim Writ's *provenance-conformant* -class. product-cli's draft log is that, and never more (charter). +class. product-cli's draft log is that, and never more. --- ## 7. The violation-description field -*Ruled (Round 1, Q-10; `DDD-dec-52`).* The profile covers the violation description, the field -`DDD-dec-52` names on a decision. +The profile covers the violation description, the field a decision carries to say what violates it. - **Where it lives.** `dk.decision-driven-design.authority.violation` is `{language, binds, text}`. @@ -516,7 +520,7 @@ class. product-cli's draft log is that, and never more (charter). - **It confers no force.** A decision is in force or not by §4.7, whatever its violation description finds. - **What it is for.** It is the declaration that makes a verdict computable. The verdict is - computed, never stored (`DDD-dec-52`). + computed, never stored. - **No description.** A decision without one is allowed, and is idle where nothing rests on it (`how.md` §4.3). @@ -526,8 +530,7 @@ class. product-cli's draft log is that, and never more (charter). ### 8.1 One class -*Ruled (Round 1, Q-7).* -- **The class.** One class, **authority-conformant**, the name Writ `[D2.5]` uses. +- **The class.** One class, **authority-conformant**, the name Writ uses. - **Who claims it.** A positioned log (§6) whose records follow §2 to §5, and whose implementation satisfies the property list (§8.2) over generated histories. - **The claim.** It names this profile and the suite it ran. @@ -542,15 +545,15 @@ evaluation of that history. |---|---|---| | A1 | A decision is in force at p only if every item it touches is covered by acceptances valid at their own positions, at or before p, not revoked, not needing re-acceptance, each signed by a human holder under a grant live at its position | G2; the multi-scope rule | | A2 | No identity named a machine, and no record carrying `attributedTo`, produces a valid act of authority. Every such attempt is judged, and so recorded | G3 | -| A3 | Every live grant's chain runs through live grants to the product's one genesis, and every delegated scope is within its grantor's | genesis definition; Q-8 | -| A4 | No grant other than the genesis is live before a valid acceptance of it by its grantee | Q-1 | -| A5 | After a grant's revocation at r, neither it nor any grant below it is live at any p ≥ r, and no act under them after r is valid | Q-2 | -| A6 | A transfer's completion changes no grant's liveness | Q-2 | +| A3 | Every live grant's chain runs through live grants to the product's one genesis, and every delegated scope is within its grantor's | the genesis definition; the delegation rule (§3.2) | +| A4 | No grant other than the genesis is live before a valid acceptance of it by its grantee | grant acceptance (§3.3) | +| A5 | After a grant's revocation at r, neither it nor any grant below it is live at any p ≥ r, and no act under them after r is valid | revocation (§3.5) | +| A6 | A transfer's completion changes no grant's liveness | transfer is not revocation (§2.3) | | A7 | An acceptance's recorded scope result never changes after its position | scope at signing | -| A8 | Every valid act is signed by a key bound to its signer, and no key signs after its close | Q-3 | -| A9 | A baseline is carried only by a valid acceptance, on a decision it accepts. That landings only shrink it is Writ's G11 over code, and is not checked here | the baseline ruling | -| A10 | Waivers change nothing in force, and a waiver is live only before its expiry by header clock | the waiver ruling; Q-6 | -| A11 | A fallback acts only while its primary is filed unavailable at the act, and never transfers | `DDD-dec-46` | +| A8 | Every valid act is signed by a key bound to its signer, and no key signs after its close | keys (§5.3) | +| A9 | A baseline is carried only by a valid acceptance, on a decision it accepts. That landings only shrink it is Writ's G11 over code, and is not checked here | the baseline rule | +| A10 | Waivers change nothing in force, and a waiver is live only before its expiry by header clock | the waiver rule; header clocks (§6.2) | +| A11 | A fallback acts only while its primary is filed unavailable at the act, and never transfers | the fallback rule (§2.4) | | A12 | Evaluating the same log again, or a prefix of it as-of, gives the same judgements and the same state at every position | G1, G6 | | A13 | An acceptance of a record in another system is never valid | force is local | @@ -584,9 +587,9 @@ case. ## 9. The worked example: acme shop, under the profile -The How examples' test product, extended (Round 1, Q-9). Records are added, never edited. The log -is [`how-examples/log/acme.json`](how-examples/log/acme.json): 16 positions, hand-built, with no -writer behind it. Every key is a throwaway test key. +The How examples' test product, extended. Records are added, never edited. The log is +[`how-examples/log/acme.json`](how-examples/log/acme.json): 16 positions, hand-built, with no +writer behind it. Every key is a test key, kept with the fixture (below). | p | Header clock | Landed | What it shows | |---|---|---|---| @@ -603,7 +606,7 @@ writer behind it. Every key is a throwaway test key. | 13 | 2026-11-04 09:00 | `KEY-architect@1` | rotation: `ACC-1@3`, signed at p4 by the closed key, still verifies (§5.3) | | 14 | 09:30 | `WAIV-resid@1`, expiring 2026-11-11T00:00Z | a waiver on the open question `RESID`, azure, `deployment-observed`: live here | | 15 | 2026-11-12 09:00 | `REV-curfmt@1` | a review with no force (§4.5); the waiver has expired by header clock, and the question is open again | -| 16 | 2026-11-13 09:00 | `SCN@1`; `ACC-scn-what@1` (owner); `what@5` | added for sdlc edition 1 (`DDD-dec-113`, E-5): a What change touching only What kinds, in force on one acceptance; `what@5` names the new graph and the completed edition | +| 16 | 2026-11-13 09:00 | `SCN@1`; `ACC-scn-what@1` (owner); `what@5` | added for sdlc edition 1: a What change touching only What kinds, in force on one acceptance; `what@5` names the new graph and the completed edition | **What `how-examples/check.py` verifies against the What graph** (rdflib): @@ -623,21 +626,22 @@ profile is right, or that any real log implements it. - **The verdicts' date.** They are computed as of the readings (2026-10-28). A gate evaluating at p15's clock would find every reading older than `RESID`'s P1D, and would report every `RESID` verdict as an open question. The checker says so. -- **The keys.** *Ruled (Round 2, P-6):* "keep the test keys for the fixture's life". +- **The keys.** They are kept for the fixture's life. - They are in [`how-examples/test-keys/`](how-examples/test-keys/), declared there as the test holders' test keys, never used outside the fixture. - They are rotated only by a new founding that says so in its record. - The 25 records of 2026-11-02 were rebuilt once, before ratification, so that their keys are - these (session `rulings.md`, Round 2). - - The vendor package's re-founding key, `vendor-holder-p`, is kept there too (Round 3, P-9). + these. + - The vendor package's re-founding key, `vendor-holder-p`, is kept there too. --- ## Appendix A — Decisions: every departure from the charter's proposal -The charter's answers, and Round 1's rulings on them, are `DDD-dec-86`. A ruled departure is -listed with its ruling. Round 2 (`DDD-dec-92`) ruled every reading Round 1 left open, all as -proposed. Round 3 (`DDD-dec-93`) replaced A-9's genesis clause (Q-11) and widened A-5 (P-9). +Where the profile departs from the charter's proposal. The charter's answers, and Round 1's rulings +on them, are one decision. A ruled departure is listed with its ruling. Round 2 ruled every reading +Round 1 left open, all as proposed. Round 3 replaced A-9's genesis clause (Q-11) and widened A-5 +(P-9). The example's records cite these row labels, so they keep their numbers. | # | The proposal said | This profile says | Reason | State | |---|---|---|---|---| @@ -653,7 +657,7 @@ proposed. Round 3 (`DDD-dec-93`) replaced A-9's genesis clause (Q-11) and widene | A-10 | a machine is any identity with an `attributedTo` | a machine is named by an attribution record; `attributedTo` refuses, it does not classify | `attributedTo` is a record member, not an identity property | ruled, Q-5 | | A-11 | (not raised) | what a decision touches (§4.2): a What change, its elements' kinds; a How decision, its kind's class at its anchor; other How records, their record class | the multi-scope rule needs a computable "touches" | ruled, Round 2, with the scope wording (§4.2) | | A-12 | (not raised) | in sdlc edition 1 the derived element kind is `sdlc:Journey` | the ontology's own comment ("derived composition"). `sdlc:State` is a projection's state space, not an element kind | ruled, Round 2 | -| A-13 | thirteen properties | thirteen. The subset rule (Q-8) is part of A3, and A9 checks what the profile holds, leaving the ratchet over landings to G11 | the mutation run found no property checking the subset rule | ruled, Round 2: "as written" | +| A-13 | thirteen properties | thirteen. The subset rule is part of A3, and A9 checks what the profile holds, leaving the ratchet over landings to G11 | the mutation run found no property checking the subset rule | ruled, Round 2: "as written" | | A-14 | a refusal is recorded | in the header of its position, with its reason, not as a record of its own | a refusal is the log's act, not an authority act; the header's hash covers it | ruled, Round 2: it matches Writ's "written to the log with the agent as cause" | | A-15 | (not raised) | `status` carries no force | `dpp-1.md` §3.4 leaves its meaning to the profile, and force is computed | ruled, Round 2 | @@ -662,21 +666,76 @@ proposed. Round 3 (`DDD-dec-93`) replaced A-9's genesis clause (Q-11) and widene ## Appendix B — the ledger protocol's authority sections, and where each went Input, read at product-cli `70395df`, `ledger/spec/ledger-protocol.md`. "It was like that in the -ledger" is not a reason for anything here (charter). Each row says why it was kept, changed or -dropped. +ledger" is not a reason for anything here. Each row says why it was kept, changed or dropped. | Ledger | Here | Why | |---|---|---| -| Roles and the closed claim vocabulary (§5.6, LP-6.1) | dropped. A grant carries a scope of ontology classes, and the act kinds are the record kinds | scopes are ruled as classes (P-7). A role is a name for a scope nobody evaluates | +| Roles and the closed claim vocabulary (§5.6, LP-6.1) | dropped. A grant carries a scope of ontology classes, and the act kinds are the record kinds. **Amended by a later decision:** the product framework carries roles. A role is a named, reusable scope that a grant may cite, and it is evaluated wherever the grant is; a scope also ranges over decision kinds. This text has not yet been reworked to it | scopes are ruled as classes. A role is a name for a scope nobody evaluates. The amendment meets that ground by making a role evaluated | | `grant` with `order: primary \| fallback-N` and `limits` | a fallback is a grant with `fallbackOf` (§2.4); no ranks and no limits | the ruling gives a fallback one limit, no transfer | -| `gacc`, the grant acceptance (LP-6.3) | kept (§3.3) | ruled, Q-1 | +| `gacc`, the grant acceptance (LP-6.3) | kept (§3.3) | ruled | | `genesis: true` with `external_ref` | the genesis record, founded and self-bound (§2.2) | the product IRI P is in the record. A contract reference is the founder's business | | Unavailability and availability (§5.6) | kept (§2.4), with header-clock times | ruled | -| Revocation of a grant or an acceptance (`rev:`) | kept, as two record kinds (§3.5, §4.6) | ruled, Q-2 | -| Key bindings: add, rotate, revoke; D7 (§4.10–4.11) | add, rotate, close; first key by the grantor; `since` (§5.3) | ruled, Q-3 | +| Revocation of a grant or an acceptance (`rev:`) | kept, as two record kinds (§3.5, §4.6) | ruled | +| Key bindings: add, rotate, revoke; D7 (§4.10–4.11) | add, rotate, close; first key by the grantor; `since` (§5.3) | ruled | | A close ends the key across namespaces (LP-4.39); ruling 47, per namespace | per product (§5.3) | force is local | -| Re-acceptance after a closed key (LP-4.13) | "needs re-acceptance", from `since` (§5.3) | ruled with Q-3 | +| Re-acceptance after a closed key (LP-4.13) | "needs re-acceptance", from `since` (§5.3) | ruled with the key rules | | Namespace policy, `accept_role`, schemes, `require_sk` (§5.6, §6.3) | dropped | "configuration is a decision or does not exist" (Writ); the scope is the policy | | Decision classes and their floors (§6.4) | dropped. What a decision touches decides who may accept it (§4.2) | the class requirement table was never implemented, and scopes over classes do its work | | `allowed_signers` derived from bindings (§4.9) | not carried. The reference evaluator derives key windows from the log | a derived file is an implementation's | | Writer-behavioural refusals (LP-6.14: non-interactive, agent identity, software key) | the machine rule (§5.1) is structural; hardware keys are not required | "no configuration makes it possible" is a property of records, checkable from the log | + +## Not settled yet + +- **Roles and scopes over decision kinds, decided later and not yet worked in** (§3.1, §3.2, + Appendix B). A later decision says the product framework carries roles (a role is a named, + reusable scope a grant may cite, evaluated wherever the grant is) and that a scope ranges over + decision kinds as well as What element kinds. §3.1 and §3.2 still define a scope as a set of + ontology classes. Reworking them is the specification-feasibility work's. Which of its items the + roles row belongs to is that decision's own reading, not yet confirmed by Emil. + +--- + +## Where this comes from + +The profile was written on 2026-11-02 by the authority-profile session +(`meta/sessions/2026-11-02-authority-profile/`), to the plan Emil ruled in its Round 1, with +Appendix A ruled in Round 2, and Q-11 and the fixtures' re-founding ruled in Round 3. It was +ratified by the merge of PR #45 on 2026-11-02, the act its decisions name. Section numbers are the +ones `DDD-dec-86` cites. + +| Section | Rests on | +|---|---| +| Opening | `dpp-1.md` §9.4; the charter `DDD-dec-85`; Round 1 `DDD-dec-86`; Round 2 `DDD-dec-92`; Round 3 `DDD-dec-93` (superseding `-92` with two changes) | +| §1.2 | `dpp/1`, `DDD-dec-62`. Attestations: a successor item (Round 1, Q-10) | +| §1.3 | Round 1, F-2 (`DDD-dec-86`), quoted in the old text: "Anything a signature must cover … is a top-level dotted member inside the canonical form, as how-vocabulary.md does it. extensions is for what may change without a new version, and nothing authority-bearing may." | +| §1.4 | The genesis grant: `DDD-dec-46`, restated by `DDD-dec-85`, superseded by `DDD-dec-87`, which keeps the definition. "Signed": `DDD-dec-47`, read by Round 1, F-1; superseded by `DDD-dec-88`. Force from the profile: `DDD-dec-54` ruling 4, superseded by `DDD-dec-89`. Scopes and the multi-scope rule: `DDD-dec-64` P-7 (Round 5 of the What move), superseded by `DDD-dec-90`. The charter's eight rulings: `DDD-dec-85`. F-1 to F-3, Q-1 to Q-10: `DDD-dec-86` | +| §2.1 | The definition, verbatim: `DDD-dec-46` (2026-10-27), kept by `DDD-dec-87`. Packages as provenance: `DDD-dec-85` | +| §2.2 | Round 1, Q-1. The product IRI: `DDD-dec-63` §1. The self-bound key: the ledger's D7, as it fits | +| §2.3 | `DDD-dec-46`; Round 1, Q-1 and Q-2 ("closing is not a revocation") | +| §2.4 | `DDD-dec-46` (the rule, quoted in the old text); Round 2, A-6 (`DDD-dec-92`, kept by `-93`) | +| §2.5 | `DDD-dec-46` (the new-product path, quoted in the old text); Round 3, Q-11 (`DDD-dec-93`): key loss is not holder loss, A-9's genesis clause, Round 2's "by transfer" withdrawn | +| §2.6 | Round 2, A-5; widened in Round 3, P-9 (`DDD-dec-93`) | +| §3.1 | `DDD-dec-85`; `DDD-dec-64` P-7, now `DDD-dec-90`. Derived kinds: Round 2, A-12 | +| §3.2 | Round 1, Q-8 | +| §3.3 | Round 1, Q-1 | +| §3.5 | Round 1, Q-2 | +| §4.1 | `DDD-dec-47`, now `DDD-dec-88`; Round 1, F-1 | +| §4.2 | Scope at signing and the multi-scope rule: `DDD-dec-85`; `DDD-dec-64` P-7, now `DDD-dec-90`. What a decision touches: Round 2, A-11 ("'touches' means every element the decision creates, changes or retires, per the scope wording"), ruled as proposed | +| §4.3 | `DDD-dec-85`. The entry shape is `how.md` D-6's. Landings: Writ `[D2]`, G11 | +| §4.4 | `DDD-dec-85`; Round 1, Q-6 ("expiry is a header-clock time, and Writ follows") | +| §4.5 | Round 1, Q-4 | +| §4.6 | Round 1, Q-2 ("an acceptance may be revoked") | +| §4.7 | `DDD-dec-85` ("Force is local; `basedOn` carries provenance only") | +| §5.1, §5.2 | `DDD-dec-85`; Round 1, Q-5 | +| §5.3 | Round 1, Q-3; `add` with no live key: Round 2, A-9; `vouch`: Round 3, Q-11 | +| §6.1 | Round 1, Q-6. The provenance-conformant log: Writ `[D2.5]` | +| §6.2 | Round 1, Q-6 and F-3 (`[D2.11]` as Emil states it); A-8 (Round 2) | +| §6.3 | the charter (`DDD-dec-85`) | +| §7 | Round 1, Q-10; `DDD-dec-52` names the field and rules the verdict computed, never stored | +| §8.1 | Round 1, Q-7. The class name: Writ `[D2.5]` | +| §8.2 | The "Mirrors" column's rulings: `DDD-dec-46` (A3, A11); Round 1, Q-1 (A4), Q-2 (A5, A6), Q-3 (A8), Q-6 (A10), Q-8 (A3); `DDD-dec-85` (A7, A9, A10, A13) | +| §9 | Round 1, Q-9. p16: sdlc edition 1 (`DDD-dec-113`, E-5). The keys: Round 2, P-6 ("keep the test keys for the fixture's life"); the rebuild of the 25 records: the session's `rulings.md`, Round 2; `vendor-holder-p`: Round 3, P-9 | +| Appendix A | `DDD-dec-86` (Round 1), `DDD-dec-92` (Round 2), `DDD-dec-93` (Round 3) | +| Appendix B | Its rows: Q-1 (`gacc`), Q-2 (revocation), Q-3 (key bindings, re-acceptance), `DDD-dec-64` P-7 (scopes as classes). The roles row is amended by `DDD-dec-117` (2026-11-08, F-5): applying the amendment to the profile's text is successor work of the specification-feasibility session | + +Supersedes `84aa466:applications/sdlc/authority.md` in place. diff --git a/applications/sdlc/how-examples/README.md b/applications/sdlc/how-examples/README.md index bf82ba4..e9dc84c 100644 --- a/applications/sdlc/how-examples/README.md +++ b/applications/sdlc/how-examples/README.md @@ -1,83 +1,40 @@ # The How, worked — three decisions, two targets each -Companion to [`../how.md`](../how.md) §12. Every record is a `dpp/1` record (the token -`DDD-dec-62` rules, superseding `DDD-dec-53`), pinned by the hash law of `spec/decision-provenance/`. It was built by -[`build.py`](build.py) and is checked by [`check.py`](check.py). - -**Superseded against the landed What (2026-10-28).** Ruling 4 of 2026-10-28 accepted the -version 1 records provisionally: they anchored to What identifiers fixed before the identity form -existed, and each was to be "superseded by a version against the real identifiers, never edited". -The What has landed ([`../what.md`](../what.md)) in the ruled identity form (`DDD-dec-63`), so: - -- **Version 2 records.** Every version 1 record that anchors to a What element or names one now - has a version 2 that supersedes it: `GEN`, `GRANT-how`, both `TGT-*`, all four `IMP-*` and - `ACC-1`. So does the vendor's `REST`, which read the provisional `sdlc:localId`. A new package - version, `REL@3`, ships it. -- **Nothing edited.** No version 1 record changed: `build.py` loads each published version and - refuses to build if it would change one. -- **The landed What.** The What graph the checker reads is the landed example, - [`../what/examples/acme-shop.ttl`](../what/examples/acme-shop.ttl). `what/acme-shop.ttl` here is - the provisional graph, kept as history and no longer read. -- **New readings.** The projector readings are new (`facts/*.r2.ttl`): the same repositories at - later commits, whose code cites the landed IRIs. The `r1` files stay, unread. -- **The decisions.** `DDD-dec-65` to `DDD-dec-71` supersede `DDD-dec-55` to `DDD-dec-61` on the - same terms. -- **The What itself as decisions.** `GRANT-what@1`, `WHAT-found@1` (the founding decision, - anchored at the product node), `ACC-what@1`, and `what@1`, the first What-version (`DDD-dec-63` - §6). - -Version 1's pins still hold and are still checked, as history. It is still a test product, and -nothing here is acceptable into a real product. - -| Provisional (version 1) | Landed (version 2) | -|---|---| -| `…/shop/what#product` | `https://acme.example/products/shop`, the product IRI and product node | -| `…/what#domain-ordering` (the `PURE`, `REST` anchor) | the Ordering bounded context, `…/what/01M610JNAMH5Y3FP9BFRZJ6QSS`. In the landed What, Deciders and Commands sit in the domain's one bounded context, which is the narrowest element covering them (ruling 1) | -| `…/what#system-shop-api`, `#system-shop-bff` | `…/what/01M610JNAMV23W7Y9YQKZPJ4ZA`, `…/what/01M610JNAM8K9PG653537FE7EG` | -| `…/what#qd-residency-eu` | `…/what/01M610JNAMGQQ2DJENWGA6MWCK` | -| `…/what#decider-order`, `#command-*` (in the code's citations) | `…/what/01M610JNAMMP5V59XRNHD39R5A`, `…/what/01M610JNAMCQ2R6MG31Q07DWMX`, `…/what/01M610JNAMC74SDA3DVDE332WB` | - -**Under the authority profile (2026-11-02).** The product's authority history is now a positioned -log, [`log/acme.json`](log/acme.json), with 16 positions, judged by the profile's reference -evaluator ([`../authority.md`](../authority.md) §9; `DDD-dec-86`, Q-9). 25 records are added and -none is edited: - -- `GEN@3` founds the log. The stand-ins' keys were discarded, so no act under them can be signed - It is the acme fixture's one re-founding, as a test fixture and not as a transfer (authority.md - §2.6, A-5, ruled). The vendor package is re-founded the same way by its `GEN@2`, in `log/vendor.json` - (Round 3, P-9). -- Two class-scoped grants and their acceptances. -- Re-acceptances of the founding What decision and the six How records, with a baseline. -- `CUR@1`, one decision under two scopes: a new What field and a binding. `what@4` names the graph - after it ([`../what/examples/acme-shop-4.ttl`](../what/examples/acme-shop-4.ttl), with hashes in - `../what/vectors-4.json`). -- Two levels of delegation and a revocation that takes the lower one down. -- A key rotation. -- A waiver that expires by header clock. -- A review. -- Two refused attempts, recorded in their headers. -- `SCN@1` at p16 (`DDD-dec-113`, E-5): a What change that creates the scenario for (Place order, - Customer) and fills four descriptions, so that the What carries no findings under sdlc edition 1. - `what@5` names the graph after it ([`../what/examples/acme-shop-5.ttl`](../what/examples/acme-shop-5.ttl), - with hashes in `../what/vectors-5.json`) and the edition as completed. `what@3` and `what@4` keep the - edition hash they were published with. - -The stand-in authority records (`GEN@1`, `GEN@2`, `GRANT-*@1/2`, `ACC-1@1/2`, `ACC-what@1`) stay as -history, landed at no position, and under the profile they put nothing in force. `build.py` now -needs rdflib, because each acceptance records its scope result read from the What graph. It -refuses to rewrite a landed header. The history's keys are kept for the fixture's life in [`test-keys/`](test-keys/): test keys of the declared test holders, never used outside the fixture (Round 2 of 2026-11-02, P-6). A rebuild reproduces every record, and a later session can extend the history. + + +Companion to [`../how.md`](../how.md) §12. This folder is a worked example: a test vendor ships a +package of How decisions, and a test product, Acme Shop, imports them, holds them under the +authority profile and checks them in two targets. Every record is a `dpp/1` record, pinned by the +hash law of `spec/decision-provenance/`. It was built by [`build.py`](build.py) and is checked by +[`check.py`](check.py). + +**How settled this is.** It is a test product, and nothing here is acceptable into a real product. +The rules it exercises are the decided parts of the What, the How and the authority profile. The fact files are +hand-written, so the run shows that the rules execute as written; it shows nothing about whether +the How is right. + +## Run it ``` python3 applications/sdlc/how-examples/check.py # needs rdflib for the verdict step ``` -At this commit, with rdflib 7.6.0, the script prints 225 ok or note lines, 1 expected warning -(its anchor self-test) and 0 failures. All 64 records (26 of them written on 2026-11-02) -are conformant under the reference implementation on `main`, run unmodified. The records were rebuilt with `dpp/1` and fresh test -keys on 2026-10-28 (Round 3). The `decprov/1` set they replace was never conformant to any -protocol on `main`; it remains in this branch's history at `d11df86`. `build.py` still refuses to -build if the token on `main` and `DDD-dec-62` ever disagree. Without rdflib, the anchor and verdict -steps are reported as **SKIP**, never as passed. +At this commit, with rdflib 7.6.0, the script prints 238 ok or note lines, 1 expected warning (its +anchor self-test) and 0 failures. All 67 records are conformant under the reference implementation +on `main`, run unmodified. Without rdflib, the anchor and verdict steps are reported as **SKIP**, +never as passed. + +The records were rebuilt with `dpp/1` and fresh test keys on 2026-10-28. The `decprov/1` set they +replace was never conformant to any protocol on `main`; it remains in this branch's history at +`d11df86`. `build.py` still refuses to build if the token on `main` and the ruled token ever +disagree. ## The cast @@ -90,10 +47,9 @@ steps are reported as **SKIP**, never as passed. | A proposing agent | `spiffe://acme.example/agent/proposer` | nothing: it may propose, it never accepts | The four human keys of the version 1 and 2 records were throwaway ed25519 keys, made fresh on each -build and discarded when it ended. Since Round 2 of 2026-11-02 the authority history's keys are -kept in `test-keys/` instead. No real key is ever used -for a fixture or held by a session (Round 3, ruling 1). Signatures are `ssh-sig` over the -canonical form, namespace `decision-provenance`. +build and discarded when it ended. Since 2026-11-02 the authority history's keys are kept in +[`test-keys/`](test-keys/) instead. No real key is ever used for a fixture or held by a session. +Signatures are `ssh-sig` over the canonical form, namespace `decision-provenance`. ## The three decisions, written once @@ -109,15 +65,9 @@ effect list, region list or native file kind. A fourth, `REST@2` (a binding: every Command at `POST /commands/{wire name}`, what.md §6), is the charter's third "specified once" check. It supersedes `REST@1`, which read the provisional local -id, and is anchored at the Ordering bounded context. It reads the wire name, ruled in Round 2 -(`DDD-dec-64`, P-1: "REST@2 stands"). - -What-version 3 (`what@3`, Round 5: `DDD-dec-64` ruled) supersedes `what@2`, which superseded -`what@1`. Each kept the same graph, and each renamed the edition by the hash of the ontology and -shapes as amended before edition 1 was tagged. `what@2`'s pin is held to the files at `655db92`. -`what@2` supersedes `what@1`. The graph is the same. Round 2 amended the -ontology and shapes before sdlc edition 1 was tagged, and `what@2` names the edition by the hash -of the files as held. `what@1`'s pin stays the hash of the files at `2c4f276`. +id, and is anchored at the Ordering bounded context. It reads the wire name, as ruled ("REST@2 +stands"). Acme Shop imports four How decisions: `IMP-layer`, `IMP-pure`, `IMP-resid` and +`IMP-rest`. The package's version 2 (`REL@2`) supersedes the layer rule with `LAYER@2`, which adds a `test` layer. The importer still rests on version 1. `check.py` shows that through the versions @@ -153,9 +103,10 @@ one more target declaration. No fact projector or reporter edition exists. Writ's `code-facts.md` is "not written", and the editions name their fact source with `"status": "not built"`. So the fact files under `facts/` are hand-written: they are what an edition *would* emit. `facts/manifest.json` gives each one -its provenance: projector or reporter; Writ's value (`file`, `deployment-declared`, `deployment-observed`); the edition by pinned hash; the -subject (repository at commit, or deployable unit), and when it was read. The What graph in -`what/` is provisional too (`../how.md` §1.2). Each fact file contains one planted defect: +its provenance: projector or reporter; Writ's value (`file`, `deployment-declared`, +`deployment-observed`); the edition by pinned hash; the subject (repository at commit, or +deployable unit), and when it was read. The What graph in `what/` is provisional too +(`../how.md` §1.2). Each fact file contains one planted defect: | Planted | Decision | Expected | Got | |---|---|---|---| @@ -170,8 +121,8 @@ subject (repository at commit, or deployable unit), and when it was read. The Wh The expectations were written as the defects were planted, before the first run, and are in `expected.json`. They are **analytic**, not evidence: a fixture built to fire, fired. The run shows that the violation descriptions execute as written in both targets, that one decision -text serves both targets, and that an absent reading comes out as an open question. It shows nothing about -whether the How is right. +text serves both targets, and that an absent reading comes out as an open question. It shows +nothing about whether the How is right. `RESID@1` requires both provenance values, `deployment-declared` and `deployment-observed`, in its `factSources`. The `dpp/1` rebuild issued it with them. @@ -179,17 +130,17 @@ whether the How is right. ## What `check.py` checks 1. Every record is conformant under the reference implementation on `main`, **unmodified**. -2. Every reference reachable from `ACC-1@2`, `ACC-what@1`, `what@1` and `REL@3` (and, as history, from `ACC-1@1` and `REL@2`) names a record held - here whose hash matches its pin. A test edit of one word in `LAYER@1` turns both lines - red. +2. Every reference reachable from `ACC-1@2`, `ACC-what@1`, `what@1` and `REL@3` (and, as history, + from `ACC-1@1` and `REL@2`) names a record held here whose hash matches its pin. A test edit of + one word in `LAYER@1` turns both lines red. 3. Every signature verifies over its record's canonical form. 4. The authority profile, over the positioned log: every header's position, chain, monotone clock and pins; every act judged by `../authority/evaluate.py` as the header records it (landed valid, or refused with the header's reason); the multi-scope decision not in force at p5 and in force at p6; the revoked chain falling at p11 while `CURFMT@1` stays in force; the rotated key still verifying `ACC-1@3`; the waiver live at p14 and expired at p15. Against the What graph: - every recorded scope item's class and path, `CUR@1`'s and `SCN@1`'s deltas, every reported violation in the - baseline, and the waived question being an open question. + every recorded scope item's class and path, `CUR@1`'s and `SCN@1`'s deltas, every reported + violation in the baseline, and the waived question being an open question. 5. Six How records are in force at the last position, all version 2, re-accepted by `ACC-1@3`. The What decisions in force are `WHAT-found@1`, `CUR@1` and `SCN@1`. No record in force names a provisional identifier. The What-version in force, `what@5`, equals `../what/vectors-5.json`. @@ -197,8 +148,104 @@ whether the How is right. description reads is mapped by that target's edition. 7. Supersession across the import is shown and changes nothing in force. There are four notes: `IMP-layer@2` on `LAYER@1` and `REL@1`; `IMP-pure@2` and `IMP-resid@2` on `REL@1`. -8. Anchors (ruling 1). Each import's anchor is the narrowest element covering what it governs - today. Otherwise the checker prints a warning, which is not a failure. A self-test re-anchors - `PURE` at the product and expects the warning. The ruling calls that anchor legitimate for an +8. Anchors. Each import's anchor is the narrowest element covering what it governs today. + Otherwise the checker prints a warning, which is not a failure. A self-test re-anchors `PURE` + at the product and expects the warning. The anchor rule calls that anchor legitimate for an "every Decider" rule, so the warning is advisory. 9. The verdicts, per decision and per target, equal `expected.json`. + +## How the records came to be + +### Superseded against the landed What (2026-10-28) + +The version 1 records were accepted provisionally: they anchored to What identifiers fixed before +the identity form existed, and each was to be "superseded by a version against the real +identifiers, never edited". The What has landed ([`../what.md`](../what.md)) in the ruled identity +form, so: + +- **Version 2 records.** Every version 1 record that anchors to a What element or names one now + has a version 2 that supersedes it: `GEN`, `GRANT-how`, both `TGT-*`, all four `IMP-*` and + `ACC-1`. So does the vendor's `REST`, which read the provisional `sdlc:localId`. A new package + version, `REL@3`, ships it. +- **Nothing edited.** No version 1 record changed: `build.py` loads each published version and + refuses to build if it would change one. +- **The landed What.** The What graph the checker reads is the landed example, + [`../what/examples/acme-shop.ttl`](../what/examples/acme-shop.ttl). `what/acme-shop.ttl` here is + the provisional graph, kept as history and no longer read. +- **New readings.** The projector readings are new (`facts/*.r2.ttl`): the same repositories at + later commits, whose code cites the landed IRIs. The `r1` files stay, unread. +- **The decisions.** The How's decisions were superseded on the same terms. +- **The What itself as decisions.** `GRANT-what@1`, `WHAT-found@1` (the founding decision, + anchored at the product node), `ACC-what@1`, and `what@1`, the first What-version. + +Version 1's pins still hold and are still checked, as history. + +| Provisional (version 1) | Landed (version 2) | +|---|---| +| `…/shop/what#product` | `https://acme.example/products/shop`, the product IRI and product node | +| `…/what#domain-ordering` (the `PURE`, `REST` anchor) | the Ordering bounded context, `…/what/01M610JNAMH5Y3FP9BFRZJ6QSS`. In the landed What, Deciders and Commands sit in the domain's one bounded context, which is the narrowest element covering them (the anchor rule) | +| `…/what#system-shop-api`, `#system-shop-bff` | `…/what/01M610JNAMV23W7Y9YQKZPJ4ZA`, `…/what/01M610JNAM8K9PG653537FE7EG` | +| `…/what#qd-residency-eu` | `…/what/01M610JNAMGQQ2DJENWGA6MWCK` | +| `…/what#decider-order`, `#command-*` (in the code's citations) | `…/what/01M610JNAMMP5V59XRNHD39R5A`, `…/what/01M610JNAMCQ2R6MG31Q07DWMX`, `…/what/01M610JNAMC74SDA3DVDE332WB` | + +### What-versions 2 and 3 + +`what@2` supersedes `what@1`. The graph is the same. The ontology and shapes were amended before +sdlc edition 1 was tagged, and `what@2` names the edition by the hash of the files as held. +`what@1`'s pin stays the hash of the files at `2c4f276`. `what@3` supersedes `what@2` when the +move's own choices were ruled. It too kept the same graph and renamed the edition by the hash of +the ontology and shapes as amended before edition 1 was tagged. `what@2`'s pin is held to the +files at `655db92`. + +### Under the authority profile (2026-11-02) + +The product's authority history is a positioned log, [`log/acme.json`](log/acme.json), judged by +the profile's reference evaluator ([`../authority.md`](../authority.md) §9). On 2026-11-02 it had +15 positions, and 25 records were added, none edited: + +- `GEN@3` founds the log. The stand-ins' keys were discarded, so no act under them can be signed. + It is the acme fixture's one re-founding, as a test fixture and not as a transfer (authority.md + §2.6). The vendor package is re-founded the same way by its `GEN@2`, in `log/vendor.json`. +- Two class-scoped grants and their acceptances. +- Re-acceptances of the founding What decision and the six How records, with a baseline. +- `CUR@1`, one decision under two scopes: a new What field and a binding. `what@4` names the graph + after it ([`../what/examples/acme-shop-4.ttl`](../what/examples/acme-shop-4.ttl), with hashes in + `../what/vectors-4.json`). +- Two levels of delegation and a revocation that takes the lower one down. +- A key rotation. +- A waiver that expires by header clock. +- A review. +- Two refused attempts, recorded in their headers. + +The stand-in authority records (`GEN@1`, `GEN@2`, `GRANT-*@1/2`, `ACC-1@1/2`, `ACC-what@1`) stay as +history, landed at no position, and under the profile they put nothing in force. `build.py` needs +rdflib, because each acceptance records its scope result read from the What graph. It refuses to +rewrite a landed header. The history's keys are kept for the fixture's life in +[`test-keys/`](test-keys/): test keys of the declared test holders, never used outside the fixture. +A rebuild reproduces every record, and a later session can extend the history. + +### sdlc edition 1 (2026-11-06) + +`SCN@1` at p16, the log's sixteenth position: a What change that creates the scenario for (Place +order, Customer) and fills four descriptions, so that the What carries no findings under sdlc +edition 1. It is accepted by `ACC-scn-what@1`. `what@5` names the graph after it +([`../what/examples/acme-shop-5.ttl`](../what/examples/acme-shop-5.ttl), with hashes in +`../what/vectors-5.json`) and the edition as completed. `what@3` and `what@4` keep the edition hash +they were published with. + +## Where this comes from + +| Section | Rests on | +|---|---| +| `dpp/1` records | `DDD-dec-62`, superseding `DDD-dec-53` (the token, ruled 2026-10-28, Round 3) | +| Run it: the counts | Re-run on `84aa466` on 2026-11-10 by `meta/sessions/2026-11-09-applications-for-readers-redo/`: 238 ok or note lines, 1 expected warning, 0 failures; "67 of 67 records conformant". The earlier text said 225 lines and 64 records. The three records added since are `SCN@1`, `ACC-scn-what@1` and `what@5` (commit `8a5b4e9`, 2026-11-06). Of the 67, 27 were added on 2026-11-02 (25 under the authority profile, `308c9a8`; `what@3`, `d994a8d`; the vendor's `GEN@2`, `e120251`); the earlier text said 26 | +| The cast; no real key | The 2026-10-28 How session, Round 3, ruling 1; the test keys, the authority-profile session, Round 2, P-6 | +| The three decisions; `REST@2` | `DDD-dec-55` to `-61`, superseded on the same terms by `DDD-dec-65` to `-71`; `DDD-dec-119`; `REST@2` stands, `DDD-dec-64` P-1 (Round 2 of the What move) | +| Acme Shop imports four How decisions | `records/acme/IMP-layer`, `IMP-pure`, `IMP-resid`, `IMP-rest`; `check.py`: "6 records (two target declarations, four imports)" | +| Anchors | The anchor rule: ruling 1 of 2026-10-28, `DDD-dec-55` | +| Superseded against the landed What | Ruling 4 of 2026-10-28; the identity form, `DDD-dec-63`; `what@1`, `DDD-dec-63` §6; `DDD-dec-65` to `-71` supersede `DDD-dec-55` to `-61` | +| What-versions 2 and 3 | Round 2 of the What move (the ontology and shapes amended); `what@3`, Round 5, when `DDD-dec-64` was ruled | +| Under the authority profile | `DDD-dec-86` (Round 1, Q-9: the worked example); `GEN@3` as the one re-founding, A-5, ruled; the vendor's `GEN@2`, Round 3, P-9 (`DDD-dec-93`); test keys, Round 2, P-6 | +| sdlc edition 1 | `DDD-dec-113`, E-5 | + +The earlier text of this page is at `84aa466:applications/sdlc/how-examples/README.md`. diff --git a/applications/sdlc/how-examples/test-keys/README.md b/applications/sdlc/how-examples/test-keys/README.md index 28e158d..d6b45d4 100644 --- a/applications/sdlc/how-examples/test-keys/README.md +++ b/applications/sdlc/how-examples/test-keys/README.md @@ -1,13 +1,25 @@ # Test keys — the acme shop fixture only + + +For anyone rebuilding or extending the acme shop fixture: which key belongs to which test holder, +where it is bound in the log, and the rules for using it. **How settled this is:** decided; the +rules below were ruled with the authority profile. + **These are test keys.** Each belongs to a declared test holder of a test product's genesis: `GEN@3` of `https://acme.example/products/shop` or `GEN@2` of the vendor package (authority.md §9). None is used outside this fixture, and none belongs to a person. -*Ruled (authority-profile session, Round 2, 2026-11-02, P-6):* "keep the test keys for the -fixture's life. Commit them beside the fixture, marked as test keys of a declared test holder, -never used outside the fixture, and rotated only by a new founding that the record states as -such." +**The rule.** The test keys are kept for the fixture's life. They are committed beside the +fixture, marked as test keys of a declared test holder, never used outside the fixture, and +rotated only by a new founding that the record states as such. | File | Test holder | Bound in the log | |---|---|---| @@ -25,5 +37,14 @@ such." it after p13 is refused (§5.3). The records built before this ruling were signed with throwaway keys that were discarded. Both -test products were re-founded once under these kept keys: acme by `GEN@3`, the vendor by `GEN@2` -(Round 3, P-9). The next test product is founded under kept test keys from the start. +test products were re-founded once under these kept keys: acme by `GEN@3`, the vendor by `GEN@2`. +The next test product is founded under kept test keys from the start. + +## Where this comes from + +| Part | Rests on | +|---|---| +| The rule | The authority-profile session, Round 2, 2026-11-02, P-6 (`DDD-dec-92`, kept by `DDD-dec-93`), verbatim: "keep the test keys for the fixture's life. Commit them beside the fixture, marked as test keys of a declared test holder, never used outside the fixture, and rotated only by a new founding that the record states as such." | +| The two re-foundings | Round 2, A-5; widened to the vendor package in Round 3, P-9 (`DDD-dec-93`) | + +Supersedes `84aa466:applications/sdlc/how-examples/test-keys/README.md` in place. diff --git a/applications/sdlc/how-vocabulary.md b/applications/sdlc/how-vocabulary.md index b2c1d5c..bc47eff 100644 --- a/applications/sdlc/how-vocabulary.md +++ b/applications/sdlc/how-vocabulary.md @@ -1,18 +1,32 @@ # The How vocabulary — `sdlc:` -**Status:** with [`how.md`](how.md) (`DDD-dec-55` to `DDD-dec-61`). Ruled in part on 2026-10-28 and not yet ratified: binding as the word for kind 2 and in Writ; open question in place of unknown; `deployment-declared` and `deployment-observed` provenance (Round 2). The rest stands as proposed until the merge. + + +This is the vocabulary of [`how.md`](how.md): the terms a How decision record uses, the fact +terms its violation description reads, and where the What's and Writ's terms come in. Use it +when you write or read a How record, or build a tool that does. + +**How settled this is.** Decided, with `how.md`, and ratified when the pull request that carried +both merged. One point is Claude's reading, not yet confirmed by Emil: the namespace IRI (below). **Namespace.** `https://decision-driven-design.dk/ns/sdlc#`, prefix `sdlc:`. It sits beside Writ's `https://decision-driven-design.dk/ns/writ#` (Writ ADR 0007). The host is the one Emil operates for Writ's vocabulary. The path follows Writ's own reasoning: "`/ns/writ#` leaves room -for sibling vocabularies under one host". `UNVERIFIED — Emil review`: no IRI under `/ns/sdlc` is -served or registered yet, and the choice is Emil's. +for sibling vocabularies under one host". No IRI under `/ns/sdlc` is served or registered yet, +and the choice is Emil's *(Claude's reading, not yet confirmed by Emil)*. -**In records.** In a `dpp/1` record (`DDD-dec-62`), How content goes in one hashed dotted member, +**In records.** In a `dpp/1` record, How content goes in one hashed dotted member, `dk.decision-driven-design.sdlc`. That is the namespace host reversed, per protocol §3.7: "names SHOULD be reverse domain names under the operator's control". Fields the authority profile owns go in `dk.decision-driven-design.authority`. That covers the violation description, which -`DDD-dec-52` places in the profile, and the stand-ins for genesis, grant and acceptance. The +belongs to the profile, and the stand-ins for genesis, grant and acceptance. The How defines none of the authority fields. Hashed content is objects, arrays and strings only (protocol A-6), so numbers and booleans never appear in these members. @@ -21,8 +35,7 @@ How defines none of the authority fields. Hashed content is objects, arrays and - **How terms**: decision-level, defined here. - **Fact terms**: what violation descriptions read. They are defined here as a demand on Writ's code-facts page (`how.md` §9.4, D-1), not as a fact format. -- **What terms**: provisional. They are read from Product Framework v1.10.0 §3 and owned by the - move (`how.md` §1.2). +- **What terms**: defined by the What, and read here (§3). --- @@ -33,32 +46,32 @@ How defines none of the authority fields. Hashed content is objects, arrays and | `sdlc:HowDecision` | A decision about how a product's What is realised in code or deployments. It has a kind, an anchor and, usually, a violation description | a record whose `…sdlc.record` is `"decision"`. `statement`, `by`, `at`, `why` and `basedOn` are as in the protocol | | `sdlc:kind` | One of `constraint`, `binding`, `contract` | `…sdlc.kind` | | `sdlc:Constraint` | A How decision whose violation description reads code facts alone | `…sdlc.kind: "constraint"` | -| `sdlc:Binding` | A How decision whose violation description joins What elements to the code or content that realises them through `sdlc:realises`, and so carries a coverage obligation. *Ruled* (2026-10-28): the word, here and in Writ, whose Realisation contract becomes the Binding contract | `…sdlc.kind: "binding"`; `…sdlc.binds`: the What kind it ranges over | +| `sdlc:Binding` | A How decision whose violation description joins What elements to the code or content that realises them through `sdlc:realises`, and so carries a coverage obligation. The word is used here and in Writ, whose Realisation contract becomes the Binding contract | `…sdlc.kind: "binding"`; `…sdlc.binds`: the What kind it ranges over | | `sdlc:Contract` | A How decision over a deployable unit, read from reporter readings | `…sdlc.kind: "contract"`; `…sdlc.freshness`: an ISO 8601 duration string | | `sdlc:anchor` | The one What element a decision anchors to: the narrowest covering element. Or, in an empty What, the product as space (`how.md` §3) | `…sdlc.anchor`: an IRI | | `sdlc:binds` | For a binding, the What element kind its quantifier ranges over within the anchor | `…sdlc.binds`: a What term, e.g. `"sdlc:Decider"` | | `sdlc:standards` | Interface standards a decision names. They are not targets | `…sdlc.standards`: array of strings | -| `sdlc:factSources` | Which provenance a decision's violation description requires, from Writ's set: `file`/`compiler` for projector facts, `deployment-declared` and/or `deployment-observed` for a contract (ruled 2026-10-28, Round 2) | `…sdlc.factSources`: array of strings | -| violation description | Not a How term: the field `DDD-dec-52` assigns to the authority profile. The How requires it to be a SPARQL 1.1 `SELECT` with one row per violation (`?subject`, `?reason`). The evaluator may bind `?anchor` and `?target` | `…authority.violation`: `{language, binds, text}` | +| `sdlc:factSources` | Which provenance a decision's violation description requires, from Writ's set: `file`/`compiler` for projector facts, `deployment-declared` and/or `deployment-observed` for a contract | `…sdlc.factSources`: array of strings | +| violation description | Not a How term: the field the authority profile holds. The How requires it to be a SPARQL 1.1 `SELECT` with one row per violation (`?subject`, `?reason`). The evaluator may bind `?anchor` and `?target` | `…authority.violation`: `{language, binds, text}` | | `sdlc:Target` | A vocabulary of shapes plus the fact source that reads them | named in vocabulary editions and target declarations: `…sdlc.target` | | `sdlc:LanguageTarget` | A target read by a fact projector over a repository at a commit | `…sdlc.targetKind: "language"` | | `sdlc:PlatformTarget` | A target read by a reporter over a deployable unit | `…sdlc.targetKind: "platform"` | -| `sdlc:DesignSystemTarget`, `sdlc:ContentStoreTarget` | Targets whose shapes (CIOs; strings per locale) are expressed in turn in a language target. *Ruled* (2026-10-28): the product's What declares them (this design system at this edition, these locales against this content store), as it declares iOS. Their catalogue is their vocabulary edition, in a package with its own genesis. AIO-to-CIO and key-to-string bindings anchor to the AIO or the content key | `…sdlc.targetKind: "design-system"` or `"content-store"`; `…sdlc.over`: the language target | +| `sdlc:DesignSystemTarget`, `sdlc:ContentStoreTarget` | Targets whose shapes (CIOs; strings per locale) are expressed in turn in a language target. The product's What declares them (this design system at this edition, these locales against this content store), as it declares iOS. Their catalogue is their vocabulary edition, in a package with its own genesis. AIO-to-CIO and key-to-string bindings anchor to the AIO or the content key | `…sdlc.targetKind: "design-system"` or `"content-store"`; `…sdlc.over`: the language target | | `sdlc:VocabularyEdition` | A decision fixing, for one target at one edition, the native shape of each fact term, and the target's classifications (effects, jurisdictions) | `…sdlc.record: "vocabulary-edition"`, with `target`, `targetKind`, `edition`, `facts` (term → native shape), classification members, and `factSource` (`{kind, name, version, digest}` or `status`) | -| `sdlc:expressible` | A decision is expressible in a target iff the target's edition maps every fact term its violation description reads. Its shape there is derived from the edition and has no term of its own: "realisation" is not minted, in either repository (ruled 2026-10-28) | none: computed | -| `sdlc:TargetDeclaration` | A decision, anchored to a system, naming its language and deployment-platform targets, the repository, and the deployable unit that realises it. User-facing targets (platform contexts, design systems, content stores, locales) are declared by the What instead (ruling 3). Coverage ranges over both | `…sdlc.record: "target-declaration"`; `language`, `platform` (and design-system or content-store) objects, each naming its edition by reference | +| `sdlc:expressible` | A decision is expressible in a target iff the target's edition maps every fact term its violation description reads. Its shape there is derived from the edition and has no term of its own: "realisation" is not minted, in either repository | none: computed | +| `sdlc:TargetDeclaration` | A decision, anchored to a system, naming its language and deployment-platform targets, the repository, and the deployable unit that realises it. User-facing targets (platform contexts, design systems, content stores, locales) are declared by the What instead. Coverage ranges over both | `…sdlc.record: "target-declaration"`; `language`, `platform` (and design-system or content-store) objects, each naming its edition by reference | | `sdlc:Exclusion` | A decision that an obligation does not apply to one (element, target) pair. A boundary gap | `…sdlc.record: "exclusion"`; `anchor` (the element), `binding` (a reference), `target`. The reason is `why` | -| baseline entry | Not a How term: the authority profile's. The How requires that it attach to (binding, element, target) and be added only by a decision. It marks a debt gap | `sdlc:BaselineEntry`, `{decision, subject, target}` on an acceptance ([`authority-vocabulary.md`](authority-vocabulary.md); authority.md §4.3, 2026-11-02) | -| waiver | Not a How term: the authority profile's. Never used for a coverage gap | `sdlc:Waiver` ([`authority-vocabulary.md`](authority-vocabulary.md); authority.md §4.4, 2026-11-02) | +| baseline entry | Not a How term: the authority profile's. The How requires that it attach to (binding, element, target) and be added only by a decision. It marks a debt gap | `sdlc:BaselineEntry`, `{decision, subject, target}` on an acceptance ([`authority-vocabulary.md`](authority-vocabulary.md); authority.md §4.3) | +| waiver | Not a How term: the authority profile's. Never used for a coverage gap | `sdlc:Waiver` ([`authority-vocabulary.md`](authority-vocabulary.md); authority.md §4.4) | | `sdlc:Coverage` | For each in-force binding, element of its kind within its anchor, and declared target: realised, baselined, or excluded | none: computed | -| `sdlc:Package` | *Ruled* (2026-10-28): "a product with an empty What, a genesis, and a decision log", vocabulary editions included. The kinds it binds to are references in its decisions' anchors | a system of `dpp/1` records | +| `sdlc:Package` | "A product with an empty What, a genesis, and a decision log", vocabulary editions included. The kinds it binds to are references in its decisions' anchors | a system of `dpp/1` records | | `sdlc:Release` | One version of a package: the set its holder accepts and ships together | `…sdlc.record: "release"`; `basedOn` every member, pinned; signed by the holder; supersedes the previous release | | `sdlc:Import` | A decision in the importer's space, `basedOn` a package decision and its release, anchored in the importer's What. It may narrow the decision; it never alters it | `…sdlc.record: "import"`; `…sdlc.imports`: the reference; `why: {ref}` to the package decision | | `sdlc:Fork` | A local decision `basedOn` a package decision that changes its statement or violation description | a How decision whose `basedOn` contains the package decision | | `sdlc:Retention` | An importer's decision to keep resting on a superseded or withdrawn version, with its reason | `…sdlc.record: "retention"`, `basedOn` the withdrawal reading and the import | | `sdlc:Withdrawal` | A package's declaration that a version is unsafe to rest on | a record superseding that version with `status: "withdrawn"` | -| `sdlc:Reading` | A recorded batch of facts with provenance: source, provenance from Writ's closed set (`file`, `compiler`, … , `deployment-declared`, `deployment-observed`), input, edition, subject, time read | a manifest entry (`how-examples/facts/manifest.json`). How Writ records it is a demand on Writ (D-3) | -| open question | Not a How term: one of Writ's three verdicts (clean, violation, open question). A contract with no reading of a required source within freshness has a **reported gap**, and its verdict is an open question with the absent reporter as one candidate (G8). It replaces the proposal's `sdlc:Unknown`, which is not minted (ruled 2026-10-28) | Writ's | +| `sdlc:Reading` | A recorded batch of facts with provenance: source, provenance from Writ's closed set (`file`, `compiler`, … , `deployment-declared`, `deployment-observed`), input, edition, subject, time read | a manifest entry (`how-examples/facts/manifest.json`). How Writ records it is a demand on Writ (`how.md` §9.4, D-3) | +| open question | Not a How term: one of Writ's three verdicts (clean, violation, open question). A contract with no reading of a required source within freshness has a **reported gap**, and its verdict is an open question with the absent reporter as one candidate (G8). It replaces the proposal's `sdlc:Unknown`, which is not minted | Writ's | | `sdlc:Drift` | A difference between a unit's `deployment-declared` and `deployment-observed` facts | none: computed | | `sdlc:Idle` | A How decision with neither a violation description nor a dependent. Reported, never a violation | none: computed | @@ -89,25 +102,50 @@ reading it. `check.py` holds the same list. - `sdlc:ofUnit` comes from the reading's subject. - `sdlc:target`, `sdlc:realisesSystem` and `sdlc:onPlatform` come from target declarations. -## 3. What terms — provisional, the move's +## 3. What terms — the What's, read here `sdlc:Product`, `sdlc:Domain`, `sdlc:System`, `sdlc:Decider`, `sdlc:Command`, -`sdlc:QualityDemand` (Product Framework v1.10.0 §3.0, §3.1, §3.2.5, §3.3, §3.2.0, §3.6). Then -`sdlc:within`, the ownership edge, used transitively as `sdlc:within*`; `sdlc:localId`; and -`sdlc:referencesDomain` (old §9 `references_domain`). The AIO, context-of-use, content-key and -locale kinds that bindings into design-system and content-store targets range over are likewise -the move's. **None of these is defined here.** The How reads them, and when the move lands they -become pinned references. +`sdlc:QualityDemand`. Then `sdlc:within`, the ownership edge, used transitively as +`sdlc:within*`; and `sdlc:referencesDomain`. The AIO, context-of-use and content-key kinds, +and the locale (a property of the What, `sdlc:locale`, not a kind), that bindings into design-system and content-store targets range over are likewise the +What's. **None of these is defined here.** The How reads them. The What has moved, and they are +defined in its ontology ([`what/ontology.ttl`](what/ontology.ttl)); the worked example pins them +through a What-version. One provisional term is not carried by the What: `sdlc:localId`, which +the first REST binding read and which its successor replaced with the What's `sdlc:wireName`. -## 4. Mapping to Writ's vocabulary — Writ's page is not written; Draft 2 is cited as Emil states it +## 4. Mapping to Writ's vocabulary + +Writ's vocabulary page is not written. Draft 2 is cited as Emil states it. | How | Nearest `writ:` term (Writ definition, chapter 4) | |---|---| -| constraint | evaluates over projector facts (ruled 2026-10-28); the citation attributes the projector recognises (`[DesignDecision]`, `[Contract]`) are fact vocabulary, not a binding | -| binding | Writ's Binding contract (ruled 2026-10-28: Writ adopts the word, and narrows the contract to kind 2: a What element to a shape in a target) | -| contract | none as a term. Its facts are reporter facts with provenance `deployment-declared` or `deployment-observed` (Writ Draft 2, ruled 2026-10-28) | -| expressible | none. `writ:realisation` is never minted (ruled 2026-10-28) | +| constraint | evaluates over projector facts; the citation attributes the projector recognises (`[DesignDecision]`, `[Contract]`) are fact vocabulary, not a binding | +| binding | Writ's Binding contract (Writ adopts the word, and narrows the contract to kind 2: a What element to a shape in a target) | +| contract | none as a term. Its facts are reporter facts with provenance `deployment-declared` or `deployment-observed` (Writ Draft 2) | +| expressible | none. `writ:realisation` is never minted | | vocabulary edition | none. Writ: "a second language is a second realisation, not a second ontology". Consistent with it | | fact projector | Writ's Projector contract. Not the What's Projector (old §3.4), which is a read-model fold | | reporter | Writ Draft 2's reporters, a reports partition per reporter (as Emil states it) | | package | "a set of accepted decisions under this vocabulary" (Writ definition, chapter 5) | + +## Not settled yet + +- **The namespace IRI** *(Claude's reading, not yet confirmed by Emil)*. No IRI under + `/ns/sdlc` is served or registered, and the choice is Emil's. Deciding it would fix the IRIs the + terms above resolve to. + +## Where this comes from + +| Section | Rests on | +|---|---| +| Opening, register | with `how.md`: `DDD-dec-55` to `DDD-dec-61`, ruled in part on 2026-10-28 (binding as the word for kind 2 and in Writ; open question in place of unknown; `deployment-declared` and `deployment-observed` provenance, Round 2); the rest stood as proposed until the merge of PR #41 and is ratified by `DDD-dec-119` | +| Namespace | Writ ADR 0007; the IRI: formerly `UNVERIFIED — Emil review` | +| In records | `DDD-dec-62` (the token `dpp/1`); the violation description in the profile: `DDD-dec-52`; protocol §3.7, A-6 | +| §1 | binding: `DDD-dec-55` (2026-10-28); provenance values: `DDD-dec-60` (Round 2); design-system and content-store targets: `DDD-dec-57` (ruling 3); `expressible` and no "realisation": `DDD-dec-55`, `DDD-dec-57`; package: `DDD-dec-56`; open question replacing `sdlc:Unknown`: `DDD-dec-60`; import, fork, retention, withdrawal: `DDD-dec-59`; coverage, exclusion: `DDD-dec-58`; baseline and waiver: authority.md §4.3, §4.4 (2026-11-02) | +| §2 | `how.md` §9.4, D-1 | +| §3 | formerly "provisional, the move's", read from Product Framework v1.10.0 §3.0, §3.1, §3.2.5, §3.3, §3.2.0, §3.6 (old §9 `references_domain`); the What moved (`DDD-dec-41`, PR #42); `sdlc:wireName` and `REST@2`: `DDD-dec-64` P-1 | +| §4 | Writ definition, chapters 4 and 5; Round 2 of 2026-10-28 | + +This text replaces `84aa466:applications/sdlc/how-vocabulary.md` in place. Its section numbers are +unchanged, because `how.md`, the authority vocabulary and the What's ontology cite this file. + diff --git a/applications/sdlc/how.md b/applications/sdlc/how.md index 4c9d2b9..31f2f8d 100644 --- a/applications/sdlc/how.md +++ b/applications/sdlc/how.md @@ -1,16 +1,29 @@ # The How — a product's realisation, as decisions -**Status: ruled in part, 2026-10-28; not yet ratified.** This is Claude's answer to the charter -at `meta/sessions/2026-10-27-product-framework-how/prompt.md`. Emil ruled on it on 2026-10-28; -the ruling is verbatim in that directory's `rulings.md`, with a table of where each item landed. -The decisions are `DDD-dec-55` to `DDD-dec-61`. `DDD-dec-54` records the charter's own rulings, -which this document does not reopen. Emil ratifies by merging, after the move's identity form -lands and the supersessions of ruling 4 are written (§1.2). Sections a ruling settled say -*Ruled*. What was not ruled separately stays `[PROPOSED]` until the merge. - -**Register.** *Ruled* cites a decision. `[PROPOSED]` is Claude's, awaiting a ruling. `[OPEN]` -is not settled by this document. `UNVERIFIED — Emil review` marks a reading of ruled material -that Emil has not confirmed. + + +This is for the people who decide how a product's What becomes code and running deployments, +and for the people who build the tools that hold those decisions. After reading it you can say +what a How decision is, choose its kind and its anchor, write it once for every target, ship it +in a package, import it into another product, and say what a product claims when it says its How +is specified. + +**How settled this is.** Decided, and ratified when the pull request that carried it merged. +Two kinds of point are not settled. One question is open (§6, whether adopters may register What +kinds). Two passages are Claude's reading of decided material that Emil has not confirmed (§8.2). +Both are listed under "Not settled yet". The worked example is in +[`how-examples/`](how-examples/), and its checker runs. + +**Where to read.** To write a decision: §3 to §5. To ship or import one: §6 and §7. For +coverage and gaps: §8. For what the gate must hold: §9. For what "specified" means: §11. §1, §2 +and the appendices are the reasoning and the history. **Companions.** The vocabulary is [`how-vocabulary.md`](how-vocabulary.md). The worked decisions are in [`how-examples/`](how-examples/), with a checker that runs them. @@ -29,61 +42,47 @@ It does not define: | Not here | Where it is | |---|---| -| Force: genesis, grants, scopes, acceptance, baseline, waiver | the authority profile (`DDD-dec-47`; `DDD-dec-54` ruling 4): [`authority.md`](authority.md), 2026-11-02 | -| The gate's verbs, positions, partitions and guarantees | Writ (`DDD-dec-54` ruling 5) | -| The record, the reference, the resolver, the hash law | the Decision Provenance Protocol, token `dpp/1` (`DDD-dec-62`, superseding `DDD-dec-53`) | -| The What's element kinds and their identities | the moved What (`DDD-dec-41`, `DDD-dec-42`, `DDD-dec-51`) | -| Execution: work units, the Build seam, SPMC bundles, verdict events (old §5, §5.1, §5.3) | nowhere. Retired by `DDD-dec-42`, not carried forward | -| Delivery: features, releases, `done`, versions, direction, drift (old §7) | nowhere. Retired by `DDD-dec-42` | -| Generation of code from decisions (old §4.2 realisation declarations, §5.2) | out of scope (§10, `DDD-dec-61`) | -| Data conformance (old §13) | an add-on, outside the framework (`DDD-dec-44`) | - -### 1.2 Preconditions this document does not have — the weakest point first - -**Update, 2026-11-02 (the authority profile).** Precondition 3 is discharged: -[`authority.md`](authority.md). The examples' stand-in authority records are superseded under it, -in a positioned log (`how-examples/log/acme.json`), and the checker runs the profile's reference -evaluator in place of the stand-in check. - -**Update, 2026-10-28 (the move).** Preconditions 1 and 2 are discharged: the What has moved -([`what.md`](what.md)) and its identity form is ruled (`DDD-dec-63`). The provisional records -are superseded against the real identifiers (`how-examples/README.md`; `DDD-dec-65` to -`DDD-dec-71`). Precondition 3 stands until the authority profile's own pull request (move -session, Round 1, Q-4). The text below is left as written. - -The charter assumes four things the repository does not yet hold (`bootstrap.md`, arrival -findings 1–3). The How below is written against them anyway, and each assumption is marked -where it bites. - -1. **The What has not moved.** The What element kinds this document binds to (Decider, Command, - AIO, context of use, content key, locale, system, domain, quality demand) have no landed - definition in `applications/sdlc/`. They are read from Product Framework v1.10.0 §3, which - `DDD-dec-41` names as what moves. If the move renames or reshapes a kind, every binding over - it changes with it. -2. **What element identity has no form.** Anchoring needs stable identities (`DDD-dec-51`). The - move charter's risk 3 says that form is fixed "before any decision is written against them". - This document writes decisions against them, using provisional IRIs - (`https://acme.example/products/shop/what#domain-ordering`). *Ruled (2026-10-28, ruling 4):* - "accepted, provisionally. They live in the test product only; they are not acceptable into any - real product; and when the What lands with its identity form, each is superseded by a version - against the real identifiers, never edited." The obligation is recorded on each of - `DDD-dec-55` to `DDD-dec-61`. -3. **The authority profile is not written.** This document uses its six terms as the charter - lists them and redefines none of them. Where the How needs something of them, it says so as - a demand on the profile (§9.4). The worked examples use stand-in records for genesis, grant - and acceptance. Those stand-ins are the examples', not the profile's. -4. **Writ is defined, not built.** The repository Hafeok/writ is at `3b1c5af` (Draft 1). Its four - format pages are "not written". *Ruled (2026-10-28):* the definition is the authority, and it - is at Draft 2, which has reporters and a closed provenance set, to which `deployment-declared` - and `deployment-observed` are added. - Claude has not read Draft 2: the repository is behind it. Where this document cites Draft 2, it - cites Emil's statement of it (`rulings.md`, Round 1). - -The token: `DDD-dec-53` ruled `decprov/1`, but PR #40 merged `dpp/1` to `main` before PR #39 -ratified that ruling. *Ruled (2026-10-28, Round 3):* the token is `dpp/1`. `DDD-dec-62` supersedes -`DDD-dec-53`; `main` already ships the token, so nothing is renamed. The example records were -rebuilt with `dpp/1` and fresh test keys. The checker runs the reference implementation on `main` -unmodified and is green. +| Force: genesis, grants, scopes, acceptance, baseline, waiver | the authority profile: [`authority.md`](authority.md) | +| The gate's verbs, positions, partitions and guarantees | Writ | +| The record, the reference, the resolver, the hash law | the Decision Provenance Protocol, token `dpp/1` | +| The What's element kinds and their identities | the What: [`what.md`](what.md) | +| Execution: work units, the Build seam, SPMC bundles, verdict events | nowhere. Retired, and not carried forward | +| Delivery: features, releases, `done`, versions, direction, drift | nowhere. Retired | +| Generation of code from decisions | out of scope (§10) | +| Data conformance | an add-on, outside the framework | + +### 1.2 Preconditions, and how each was discharged + +The How was first written against four things the repository did not yet hold. Each assumption +was marked where it bit. Three are now discharged, and the text below keeps what each one +decided. + +1. **The What had not moved.** The What element kinds this document binds to (Decider, Command, + AIO, context of use, content key, locale, system, domain, quality demand) were read from the + Product Framework, which was to move. If the move renamed or reshaped a kind, every binding + over it would change with it. **Discharged:** the What has moved ([`what.md`](what.md)). +2. **What element identity had no form.** Anchoring needs stable identities. The How wrote + decisions against provisional IRIs (`https://acme.example/products/shop/what#domain-ordering`). + They were accepted provisionally, on three conditions: they live in the test product only; + they are not acceptable into any real product; and when the What lands with its identity form, + each is superseded by a version against the real identifiers, never edited. **Discharged:** the + identity form is decided, and the provisional records are superseded against the real + identifiers ([`how-examples/README.md`](how-examples/README.md)). +3. **The authority profile was not written.** This document uses its six terms and redefines + none of them. Where the How needs something of them, it says so as a demand on the profile + (§9.4). **Discharged:** [`authority.md`](authority.md). The examples' stand-in authority records + are superseded under it, in a positioned log (`how-examples/log/acme.json`), and the checker + runs the profile's reference evaluator in place of the stand-in check. +4. **Writ is defined, not built.** The repository Hafeok/writ was at `3b1c5af` (Draft 1), and its + four format pages were "not written". The definition is the authority. It is at Draft 2, + which has reporters and a closed provenance set, to which `deployment-declared` and + `deployment-observed` are added. Claude has not read Draft 2, because the repository is behind + it. Where this document cites Draft 2, it cites Emil's statement of it. + +**The token is `dpp/1`.** An earlier ruling named `decprov/1`, but `dpp/1` reached `main` first, +and the token was then decided as `dpp/1`. Nothing was renamed. The example records were rebuilt +with `dpp/1` and fresh test keys. The checker runs the reference implementation on `main` +unmodified, and is green. --- @@ -94,55 +93,54 @@ unmodified and is green. > deployments by a gate, shipped as a package by a vendor, and imported into another product by > `basedOn` under that product's genesis. -**Verdict: the thesis holds with four repairs; it does not need a replacement.** *Ruled -(2026-10-28):* three repairs accepted and one corrected. The correction is to the gate's -vocabulary: "unknown" becomes an open question (§9.3). -Each clause was tested against the old §§4–7 and against the worked decisions. The examples -exercise every clause except "shipped by a vendor" as a real distribution. +**Verdict: the thesis holds with four repairs; it does not need a replacement.** Three repairs +were accepted as proposed and one was corrected. The correction is to the gate's vocabulary: +"unknown" becomes an open question (§9.3). Each clause was tested against the old How's sections +on decisions, execution, verification and delivery, and against the worked decisions. The +examples exercise every clause except "shipped by a vendor" as a real distribution. | Clause | Holds? | Repair | |---|---|---| | a set of decisions | yes | Everything that varies by target lives in vocabulary editions. Those editions are decisions too (§6), so the set is closed | -| each anchored to a What element or to the product | **only with a reading** (ruled, §3) | A universally quantified decision ("every Decider…", "every component…") governs many elements, so it has no single element to anchor to. Read the product node as a What element, and anchor to the narrowest element that covers the scope (§3). Without this reading, every quantified decision in a non-empty What anchors to the product, which is the loophole `DDD-dec-54` ruling 1 forbids. `UNVERIFIED — Emil review` | +| each anchored to a What element or to the product | **only with a reading** (decided, §3) | A universally quantified decision ("every Decider…", "every component…") governs many elements, so it has no single element to anchor to. Read the product node as a What element, and anchor to the narrowest element that covers the scope (§3). Without this reading, every quantified decision in a non-empty What anchors to the product, which is the loophole the charter forbids | | accepted under the product's genesis | yes | none; the examples show the chain | -| held against code **and deployments** by a gate | yes, once deployment provenance is in Writ's set | Writ's Draft 1, which the repository holds, had no reporter. *Ruled:* Draft 2 has reporters, reporter inputs with their hashes and a reports partition per reporter. Deployment facts fitted none of its provenance values, so `deployment-declared` and `deployment-observed` are added (§9.2) | -| shipped as a package by a vendor | yes | *Ruled:* a package's What is empty, and `DDD-dec-46`'s "its What is its decisions" is superseded (§6) | +| held against code **and deployments** by a gate | yes, once deployment provenance is in Writ's set | Writ's Draft 1, which the repository holds, had no reporter. Draft 2 has reporters, reporter inputs with their hashes and a reports partition per reporter. Deployment facts fitted none of its provenance values, so `deployment-declared` and `deployment-observed` are added (§9.2) | +| shipped as a package by a vendor | yes | A package's What is empty, and the earlier clause "its What is its decisions" is superseded (§6) | | imported by `basedOn` under the importer's genesis | yes | The import is itself a decision in the importer's space, with its own anchor there (§7) | **A naming repair runs through all of it.** "Realisation" already had three meanings: Writ's -(a decision's code shape in one language), `DDD-dec-46`'s (a product's repository scope), and -the charter's kind 2. *Ruled:* kind 2 is **binding**, and Writ adopts the word. Its Realisation -contract becomes the Binding contract, and `writ:realisation` is never minted. "One word across -both repositories; the How vocabulary is the authority on what a decision is, Writ is the -authority on enforcing it." This document therefore uses "realisation" as a term nowhere. A +(a decision's code shape in one language), a product's repository scope, and the charter's +kind 2. Kind 2 is **binding**, and Writ adopts the word. Its Realisation contract becomes the +Binding contract, and `writ:realisation` is never minted. There is one word across both +repositories: the How vocabulary is the authority on what a decision is, and Writ is the +authority on enforcing it. This document therefore uses "realisation" as a term nowhere. A decision's shape in a target is derived and needs no name (§5). Whether a decision can be -checked in a target is **expressible**, the charter's own word. `DDD-dec-46`'s realisation scope -is left as ruled. +checked in a target is **expressible**, the charter's own word. The realisation scope of a +product's repository is left as decided. -*Ruled (2026-10-28, Round 2):* "Writ narrows, the How does not widen." Writ's Binding contract is -kind 2 only: a What element to a shape in a target. A constraint has no binding: it evaluates over -the projector's facts, and the citation attributes the projector recognises (`[DesignDecision]`, -`[Contract]`) are part of its fact vocabulary. A contract has no binding: it evaluates over a -reporter's facts. The three kinds map onto Writ as constraint → projector facts, binding → -Binding contract, contract → reporter facts. +**Writ narrows, the How does not widen.** Writ's Binding contract is kind 2 only: a What element +to a shape in a target. A constraint has no binding: it evaluates over the projector's facts, and +the citation attributes the projector recognises (`[DesignDecision]`, `[Contract]`) are part of +its fact vocabulary. A contract has no binding: it evaluates over a reporter's facts. The three +kinds map onto Writ as constraint → projector facts, binding → Binding contract, contract → +reporter facts. --- ## 3. Anchoring -*Ruled (`DDD-dec-54` ruling 1):* a How decision anchors to exactly one What element or to the -product. Anchoring to the product is the degenerate case an empty What forces. +A How decision anchors to exactly one What element or to the product. Anchoring to the product +is the degenerate case an empty What forces. -**The reading — *ruled* (2026-10-28, ruling 1, `DDD-dec-55`), as proposed.** "Every Decider in -the Ordering domain" anchors to the domain; "every Decider" anchors to the product. Anchoring to -the product "is the loophole only when a narrower element exists and was not used, and the -checker should warn on that." +**The reading.** "Every Decider in the Ordering domain" anchors to the domain; "every Decider" +anchors to the product. Anchoring to the product is the loophole only when a narrower element +exists and was not used, and the checker warns on that. -1. **The product node is a What element.** The old §3.0 makes the product "the root of the - What". In a non-empty What, anchoring to the product node is anchoring to a What element. -2. **The product as space is the degenerate case.** The decision space of `DDD-dec-46` is the - product as space. A decision anchors there only when the product's What is empty: a - repository with no What, or a package (§6). +1. **The product node is a What element.** The What makes the product the root of the What. In + a non-empty What, anchoring to the product node is anchoring to a What element. +2. **The product as space is the degenerate case.** A product's decision space is the product + as space. A decision anchors there only when the product's What is empty: a repository with no + What, or a package (§6). 3. **The anchor is the narrowest covering element.** A decision anchors to the narrowest What element whose subtree contains everything the decision governs. "Every Decider in Ordering" anchors to the domain `ordering`. A layer rule over every system's code anchors to the @@ -160,55 +158,60 @@ checker should warn on that." Decider") ranges over the instances of that kind inside its anchor's subtree. The evaluator binds `?anchor` to the anchor of the decision in force (§4.1). One decision text therefore serves any anchor it is imported at. -5. **A creating decision anchors to the element it creates.** `DDD-dec-42` left this open for - the What. For the How the question does not arise: How decisions create no What elements. +5. **A creating decision anchors to the element it creates.** This was left open for the What. + For the How the question does not arise: How decisions create no What elements. Read this way, an empty-What product can still adopt every constraint and contract. Bindings over it are vacuous, because there is nothing to bind. Writ's own reference customer is that case: "a Context& architecture package (Varve's layering as decisions) checked by Writ over Varve". Varve has no Product Framework What. +*In Acme Shop:* the Deciders and Commands sit in the Ordering domain's one bounded context, so +the imports of the pure-core and REST bindings anchor to that bounded context, the narrowest +element covering them. + --- ## 4. The kinds ### 4.1 What every How decision is -A How decision is a `dpp/1` record (shape in `how-vocabulary.md` §3). Beyond the protocol's +A How decision is a `dpp/1` record (shape in `how-vocabulary.md` §1). Beyond the protocol's members it carries: - **a kind**: constraint, binding or contract; - **an anchor**, per §3; -- **a violation description**, the field `DDD-dec-52` places on the decision record and in the - authority profile. Here it is a SPARQL 1.1 `SELECT` that returns one row per violation, each - with a `?subject` and a `?reason`. The evaluator may bind two variables: `?anchor`, to the - anchor of the decision as in force, and `?target`, to the target being evaluated. This is the - form Writ's definition names ("a rule is written as a query … and carries its violation - shape"). It is not a new rule language; -- **the provenance it requires**: for a contract, `deployment-declared`, `deployment-observed`, or both. These are Writ's values, ruled 2026-10-28 (§9.2). Constraints and bindings read projector facts (`file`, `compiler`). +- **a violation description**, the field the authority profile holds on the decision record. + Here it is a SPARQL 1.1 `SELECT` that returns one row per violation, each with a `?subject` and + a `?reason`. The evaluator may bind two variables: `?anchor`, to the anchor of the decision as + in force, and `?target`, to the target being evaluated. This is the form Writ's definition + names ("a rule is written as a query … and carries its violation shape"). It is not a new rule + language; +- **the provenance it requires**: for a contract, `deployment-declared`, `deployment-observed`, + or both. These are Writ's values (§9.2). Constraints and bindings read projector facts (`file`, + `compiler`). A verdict is computed from the decision in force at a position and the facts recorded at that -position. It is never stored (`DDD-dec-49`). What is recorded is the decision and the readings -(`DDD-dec-52`). +position. It is never stored. What is recorded is the decision and the readings. ### 4.2 The three kinds | | **Constraint** | **Binding** | **Contract** | |---|---|---|---| | Is over | code facts alone | a What element (or a kind within an anchor) and the code or content that realises it | a deployable unit | -| Typical anchors | the product node; a system | the element it binds, or the narrowest element covering the instances it quantifies over | a system (deployment identity); a quality demand (§3.6 Kind 2 and the wiring of Kind 1) | +| Typical anchors | the product node; a system | the element it binds, or the narrowest element covering the instances it quantifies over | a system (deployment identity); a quality demand (what.md §3.6 Kind 2 and the wiring of Kind 1) | | Facts | projector facts over a repository at a commit | the What graph, plus projector facts that carry `sdlc:realises` (the correspondence from code element to What element) | reporter facts about a unit, with provenance `deployment-declared` (from IaC or a manifest) or `deployment-observed` (from the platform's own API), as its violation description requires | | Evaluator | the violation description over the facts at p | the same, joining What and code through `sdlc:realises`. Coverage (§8) is part of its violation description | the same, per reading. No fresh reading means a reported gap and an **open question** (§9.3) | | Gates `land`? | yes | yes | facts with provenance `deployment-declared` only. An observed fact is not of the change | -| Worked | `LAYER@1` | `PURE@1`, `REST@1` | `RESID@1` | - -**Constraint.** The old layout model (§4.3) is a set of constraints over path facts. Each of -its rule kinds (`must-exist`, `may-exist-here`, `must-co-exist`, `must-not-exist`) is a violation -description. "No orphans" is different in one respect. It is a violation description over the -**decisions in force at p** as well as the facts: a file or component that no allow decision -covers is a violation. That is the charter's "everything not covered is a violation until a -decision covers it". It is the mirror of binding coverage. Bindings require that every What -element be covered by code. No-orphans requires that every piece of code be covered by a +| Worked | `LAYER@1` | `PURE@1`, `REST@2` | `RESID@1` | + +**Constraint.** The old How's repository layout model is a set of constraints over path facts. +Each of its rule kinds (`must-exist`, `may-exist-here`, `must-co-exist`, `must-not-exist`) is a +violation description. "No orphans" is different in one respect. It is a violation description +over the **decisions in force at p** as well as the facts: a file or component that no allow +decision covers is a violation. That is the charter's "everything not covered is a violation +until a decision covers it". It is the mirror of binding coverage. Bindings require that every +What element be covered by code. No-orphans requires that every piece of code be covered by a decision (§8.3). The old guards carry over without a rule of their own. Guard 1 ("every rule cites the principle it protects") is the protocol's required `why` plus `basedOn`. Guard 2 (prefer the allowlist) is advice, and stays advice. @@ -218,27 +221,27 @@ identities and code elements. In the examples that correspondence is the fact `s which each target's vocabulary edition maps to a native shape (`[Realises(…)]` in C#, a `@realises` JSDoc tag in TypeScript). Writ's definition lists "decision citations on code elements" among its code facts. That is the same fact, read the other way. A binding is the -only kind whose evaluator reads the What graph. Bindings absorb the old §4.2 "pure core", §4.4 -(the canonical REST projection), §4.5 (reification: `reify(AIO, context) → CIO`), §4.6 (content -resolution: `resolve(key, locale) → string`) and §3.2.5's split between system identity and -deployment identity. The last of these is shared with contract: the binding says which unit -realises a system; the contract says what that unit must satisfy. Old §5.2 does not go here; it -is generation (§10). +only kind whose evaluator reads the What graph. Bindings absorb the old How's pure core, its +canonical REST projection, reification (`reify(AIO, context) → CIO`), content resolution +(`resolve(key, locale) → string`), and the What's split between system identity and deployment +identity. The last of these is shared with contract: the binding says which unit realises a +system; the contract says what that unit must satisfy. The old code-generation seam does not go +here; it is generation (§10). **Contract.** A contract is over a deployable unit. That unit's identity (domain name, bundle -identifier, account, region) is How, per the old §3.2.5. Kind-2 architectural demands (old -§3.6) are What elements. The contract that holds them anchors to that element, as `RESID@1` -anchors to `qd-residency-eu`. Kind-1 runtime bounds are What elements too. *Which telemetry -measures them* is a contract over `telemetry` facts, anchored to the bound. The old text put -Kind 1 under "runtime-bound conformance" with no How home. This document gives it one (H-9). +identifier, account, region) is How. Kind-2 architectural demands (what.md §3.6) are What +elements. The contract that holds them anchors to that element, as `RESID@1` is imported at the +residency quality demand. Kind-1 runtime bounds are What elements too. *Which telemetry measures +them* is a contract over `telemetry` facts, anchored to the bound. The old text put Kind 1 under +"runtime-bound conformance" with no How home. This document gives it one (Appendix A). ### 4.3 A fourth kind? No -The candidate is the old §4.1 "principle licensed by a top decision". **`[PROPOSED]`: not a -kind.** A principle is a decision with no violation description that others are `basedOn`. The -gate evaluates nothing for it. It still matters to the gate in two ways. `explain` shows it in -every derivation that rests on it. And when it is superseded, every decision resting on it -shows "rests on superseded version" (§7.2). Adding a kind would give the gate a category with no +The candidate is the old How's "principle licensed by a top decision". **A principle is not a +kind.** It is a decision with no violation description that others are `basedOn`. The gate +evaluates nothing for it. It still matters to the gate in two ways. `explain` shows it in every +derivation that rests on it. And when it is superseded, every decision resting on it shows +"rests on superseded version" (§7.2). Adding a kind would give the gate a category with no evaluator. The old earn-their-place rule ("a principle belongs only if a work unit applies it or a @@ -260,7 +263,7 @@ description of its own: evaluator and the same coverage rule. They differ only in which vocabulary edition names the shape. One kind. - **Contract, declared** and **contract, observed** are one kind. A contract's violation - description says which provenance it requires (ruled 2026-10-28). Residency may be satisfied by + description says which provenance it requires. Residency may be satisfied by `deployment-declared`; "no public endpoint" needs `deployment-observed`. Where a rule requires both, it is one decision read over two provenances, and its two verdicts stay apart. - **Constraint** and **contract** could merge into "a violation description over some facts". @@ -282,12 +285,11 @@ sorts: - a **design system** or **content store**, whose shapes (CIOs; strings per locale) are expressed in turn in a language. These targets layer over a language target. -*Ruled (2026-10-28, ruling 3, `DDD-dec-57`):* design systems and content stores are "targets, not -catalogues". +Design systems and content stores are targets, not catalogues. - **The What declares them.** The product's What says "this design system at this edition, these - locales against this content store", exactly as it declares iOS. That is how `DDD-dec-44`'s "§11 - and §12 are What" is to be read. + locales against this content store", exactly as it declares iOS. That is how the earlier + decision that the Product Framework's §11 and §12 are What is to be read. - **The catalogue is the target's vocabulary edition.** The components, tokens and strings are held in a package with its own genesis, typically a design team's. - **The bindings are kind 2.** AIO-to-CIO and key-to-string decisions are How bindings, anchored @@ -297,16 +299,16 @@ catalogues". So targets are declared in two places. The What declares the user-facing ones: platform contexts such as iOS, design systems, content stores and locales. How target declarations (`TGT-shop-api@1`) declare the realisation ones: languages and deployment platforms. Coverage -ranges over both. `[PROPOSED]`, not ruled separately: the rest of this section and §5.2. +ranges over both. An **interface standard** (HTTP, OpenAPI, AsyncAPI, CloudEvents) is not a target. A decision may -name it, as `REST@1` names `POST`. A decision that chooses a standard is a different decision -from one that chooses another standard. The old §4.4 table ("use the standards") survives as +name it, as `REST@2` names `POST`. A decision that chooses a standard is a different decision +from one that chooses another standard. The old How's "use the standards" table survives as advice on which standards to name. ### 5.2 Specified once, realised per target -**`[PROPOSED]`.** A decision's statement and violation description use only: +A decision's statement and violation description use only: - How vocabulary terms; - What vocabulary terms; @@ -331,7 +333,7 @@ The charter's three checks, each written once, are in `how-examples/`: |---|---|---|---|---| | layer rule, `LAYER@1` | constraint | `.csproj`, ``, `` | workspace package, `"sdlc": {"layer"}`, workspace dependency | no | | pure core, `PURE@1` | binding | `[Realises]` on a type; effects `DateTime.UtcNow`, `HttpClient`, … | `@realises` on an export; effects `Date.now`, `node:http`, … | no | -| REST projection, `REST@1` | binding | `app.MapPost("/commands/{id}", …)` | `server.post("/commands/{id}", …)` | no | +| REST projection, `REST@2` | binding | `app.MapPost("/commands/{id}", …)` | `server.post("/commands/{id}", …)` | no | **Where it would fail.** A target whose facts cannot be stated in the How's fact terms breaks the property. An example would be a language with no notion of a component that one can depend @@ -343,22 +345,22 @@ publish a competing fact format (§9.4, D-1). **Purity is approximate in the examples.** `PURE@1` checks the realising element's component for effects, not the decide and evolve functions themselves. Behavioural conformance would check that the core computes what the Decider says. That needs facts from a runner that executes code -against the Decider's scenarios (H-14). Writ's Draft 2 provenance set has `runner`, as Emil -states it, so the demand is met there. The worked decisions do not use it. +against the Decider's scenarios (Appendix A). Writ's Draft 2 provenance set has `runner`, as +Emil states it, so the demand is met there. The worked decisions do not use it. --- ## 6. The package -*Ruled (`DDD-dec-46`; `DDD-dec-54` ruling 3):* a package is a product with its own genesis, -held by the vendor. In another product's space it is provenance, never authority. +A package is a product with its own genesis, held by the vendor. In another product's space it +is provenance, never authority. -**What a package contains — decision records, and nothing else (*ruled*, repair 3).** +**What a package contains — decision records, and nothing else.** | In the package | As | |---|---| | constraints, bindings, contracts | decision records | -| vocabularies (the proposal's "realisation vocabularies") | vocabulary-edition records, which are decisions. A change to how C# realises a layer is a change to the How, and so a decision (`DDD-dec-54` ruling 2) | +| vocabularies (the proposal's "realisation vocabularies") | vocabulary-edition records, which are decisions. A change to how C# realises a layer is a change to the How, and so a decision | | projector and reporter editions | named inside the vocabulary edition they implement: name, version, digest. The name is content; the binary is not | | a version of the package | a release record, `basedOn` everything in that version and signed by the holder (`REL@1`) | | analyzers, projectors, reporters, generators | **not content**. They are the package product's realisation, shipped alongside and referenced by digest | @@ -367,23 +369,24 @@ This tightens the proposal. The proposal listed vocabularies and editions beside they are decisions, or are named inside decisions. A package is then one thing: a decision log that another product can walk. -**A package carries no What — *ruled* (2026-10-28, ruling 2, `DDD-dec-56`).** The proposal said "only the element kinds it binds -to, never instances". Element kinds are not What elements. They are the framework's vocabulary, -here in the `sdlc` namespace, and a package references them by name. If a package's What held -kinds, every package would hold a private copy of the framework's ontology: the -two-sources-of-truth failure. So a package's What is empty. Its decisions anchor to the package -product: the degenerate case, and here the right one. +**A package carries no What.** The proposal said "only the element kinds it binds to, never +instances". Element kinds are not What elements. They are the framework's vocabulary, here in the +`sdlc` namespace, and a package references them by name. If a package's What held kinds, every +package would hold a private copy of the framework's ontology: the two-sources-of-truth failure. +So a package's What is empty. Its decisions anchor to the package product: the degenerate case, +and here the right one. -`DDD-dec-46`'s consequence clause said a package is a product "whose What is its decisions". -*Ruled:* that clause is superseded by `DDD-dec-56`, and `DDD-dec-42` stands. "The kinds a package -binds to are references in its decisions' anchors, not What elements of the package. A package -is a product with an empty What, a genesis, and a decision log." The decision log includes its -vocabulary editions (repair 3, ruled). +An earlier decision said a package is a product "whose What is its decisions". That clause is +superseded, and the earlier decision behind it stands: every decision anchors to a What element, +and every change of the What is made by a decision. The kinds a package binds +to are references in its decisions' anchors, not What elements of the package. A package is a +product with an empty What, a genesis, and a decision log. The decision log includes its +vocabulary editions. A package that needs a What kind the framework lacks, such as a new AIO like `range-select`, cannot ship it. A new kind is a change to the framework here. An instance of a new kind is a What -element in the importer's product. `[OPEN]`: whether the old §3.2.2 "an adopter may register -AIOs" survives the move. +element in the importer's product. Whether an adopter may register AIOs, as the Product +Framework allowed, survives the move *(open)*. --- @@ -391,10 +394,8 @@ AIOs" survives the move. ### 7.1 Import -*Ruled:* a package's decisions enter by import, `basedOn` the package's versions, in force only -under the importer's acceptances. - -**`[PROPOSED]`.** An import has three parts: +A package's decisions enter by import, `basedOn` the package's versions, in force only under the +importer's acceptances. An import has three parts: 1. **Landing.** The package's records, pinned, are recorded into the importer's log. A copy is not the record (protocol A-3). The pin is how the importer knows it holds what the vendor @@ -412,25 +413,25 @@ because a human holder of the How grant accepted it (`ACC-1@1`). ### 7.2 Supersession across the import -**`[PROPOSED]`, the proposal kept, with one condition.** When the vendor supersedes a decision, -nothing in the importer changes. The importer's decision is in force under its own acceptance, -resting on the version it pinned. `explain` shows "rests on superseded version". Re-import is a -new landing, a new import decision that supersedes the old one, and a new acceptance. +When the vendor supersedes a decision, nothing in the importer changes. The importer's decision +is in force under its own acceptance, resting on the version it pinned. `explain` shows "rests on +superseded version". Re-import is a new landing, a new import decision that supersedes the old +one, and a new acceptance. **The condition.** The protocol has no forward link (Q2): "a reader holding an old record cannot learn from the protocol that another system has superseded it". The importer learns of a -successor only by reading the package's versions listing (§6.4). For G1 (a verdict at p is a pure -function of the log up to p), that reading must itself be **recorded** in the importer's log. -`explain` shows supersession *as of the last recorded reading*, never from a live lookup. The -examples' checker reads the listing directly. It is a checker, not a gate. +successor only by reading the package's versions listing (protocol §6.4). For G1 (a verdict at p +is a pure function of the log up to p), that reading must itself be **recorded** in the +importer's log. `explain` shows supersession *as of the last recorded reading*, never from a live +lookup. The examples' checker reads the listing directly. It is a checker, not a gate. ### 7.3 Withdrawal -***Ruled* (2026-10-28, `DDD-dec-59`):** "the importer must answer with a re-import or a decision -to keep; the vendor blocks nothing." A package may declare a version withdrawn: unsafe to rest on. It does so with a -new record that supersedes it with `status: withdrawn` (protocol §3.4; the status is hashed, so -this is a new version). This is the only signal that is ever more than information. Even so, it -never acts by the vendor's authority: +The importer must answer with a re-import or a decision to keep; the vendor blocks nothing. A +package may declare a version withdrawn: unsafe to rest on. It does so with a new record that +supersedes it with `status: withdrawn` (protocol §3.4; the status is hashed, so this is a new +version). This is the only signal that is ever more than information. Even so, it never acts by +the vendor's authority: - **What it obliges.** Once a withdrawal reading is recorded, every importer decision resting on the withdrawn version is an **open answer** at every `check`, until the importer accepts one @@ -447,46 +448,46 @@ never acts by the vendor's authority: ### 8.1 The generalised obligation -**`[PROPOSED]`, the proposal kept.** Take every binding in force, every What element of the kind -it binds within its anchor, and every target the product declares for that element. For each -such triple, exactly one of the following holds, and the gate reports which: +Take every binding in force, every What element of the kind it binds within its anchor, and +every target the product declares for that element. For each such triple, exactly one of the +following holds, and the gate reports which: 1. the pair is realised: the binding's violation description finds no "unrealised" row; 2. the gap is **debt**: a baseline entry on the binding for that (element, target); 3. the gap is a **boundary**: an exclusion decision for that (element, target). The targets come from target declarations (§4.3), so coverage is computed and never listed by -hand. The old §4.5 (every reachable (AIO, context) pair) and §4.6 (every (key, locale) pair) are -instances of this, as `DDD-dec-45` ruled them into the What as obligations. `PURE@1` and -`REST@1` show it for Deciders and Commands. Their "no code element realises it in this target" -rows are the uncovered pairs. +hand. The What's obligations over every reachable (AIO, context) pair and every (key, locale) +pair are instances of this. `PURE@1` and `REST@2` show it for Deciders and Commands. Their "no +code element realises it in this target" rows are the uncovered pairs. ### 8.2 Is a declared gap a waiver, a baseline entry, or a third thing? Two of them The proposal said: a baseline entry. **Two different things, because gaps come in two different -kinds** — *ruled as proposed* (2026-10-28, `DDD-dec-58`). `DDD-dec-45` already names both: +kinds.** An earlier decision already names both: | Gap | Example | Is | Gate reports | Ratchet | |---|---|---|---|---| -| **debt**: should exist, does not yet | a missing translation (`DDD-dec-45`: "declared missing"); a Decider not yet ported to the second language | a **baseline entry** on the binding, per (element, target) | baselined, with the entry's position | shrinks. An entry may be removed by landing the code that realises the pair. It may be added only by a decision | -| **boundary**: cannot apply | a `display-collection` of images in a TUI (`DDD-dec-45`: "declared unreifiable") | an **exclusion**: a decision anchored to the element, with the reason | not applicable, with the reason (old §6.2's third finding) | none. It is not debt, and removing it would be wrong | +| **debt**: should exist, does not yet | a missing translation ("declared missing"); a Decider not yet ported to the second language | a **baseline entry** on the binding, per (element, target) | baselined, with the entry's position | shrinks. An entry may be removed by landing the code that realises the pair. It may be added only by a decision | +| **boundary**: cannot apply | a `display-collection` of images in a TUI ("declared unreifiable") | an **exclusion**: a decision anchored to the element, with the reason | not applicable, with the reason (the old verification anatomy's third finding) | none. It is not debt, and removing it would be wrong | -**Never a waiver.** A waiver, as the authority profile will define it, suspends a violation that +**Never a waiver.** A waiver, as the authority profile defines it, suspends a violation that applies. An unreifiable pair is not a violation that applies. Using a waiver for it would let -waivers silently stand in for boundaries. `UNVERIFIED — Emil review`: the ratchet semantics of -baseline are assumed here, because the profile is not written (§9.4, D-6). +waivers silently stand in for boundaries. The ratchet semantics of a baseline above were assumed +here before the authority profile was written (§9.4, D-6) *(Claude's reading, not yet confirmed +by Emil)*. -`DDD-dec-45`'s consequence (Claude's reading, not ruled) was that "a declared-unreifiable pair -and a declared-missing key are themselves decisions with a principal". This keeps that for the -exclusion. It refines it for the debt: a baseline entry is added by a decision, but the entry is -a member of the baseline, not a decision of its own. +An earlier decision's consequence was that "a declared-unreifiable pair and a declared-missing +key are themselves decisions with a principal" *(Claude's reading, not yet confirmed by Emil)*. +This keeps that for the exclusion. It refines it for the debt: a baseline entry is added by a +decision, but the entry is a member of the baseline, not a decision of its own. ### 8.3 The other direction Binding coverage asks whether every What element is realised. The no-orphans reading of a constraint asks the converse: whether every piece of code is covered by a decision (§4.2). The -old §14.5 saw the same symmetry at the intake ("who may say what") and at reification ("what is -shown where"). The How has it at both ends. +Product Framework saw the same symmetry at the intake ("who may say what") and at reification +("what is shown where"). The How has it at both ends. --- @@ -494,8 +495,8 @@ shown where"). The How has it at both ends. ### 9.1 What Writ enforces, stated against its definition -*Ruled:* the gate is Writ. The How does not restate Writ's verbs, positions, partitions or -guarantees. It states what Writ must hold: +The gate is Writ. The How does not restate Writ's verbs, positions, partitions or guarantees. It +states what Writ must hold: | The How requires | Held by (Writ's definition) | |---|---| @@ -504,18 +505,18 @@ guarantees. It states what Writ must hold: | no agent accepts | G3 | | constraint and binding verdicts, and contract verdicts over `deployment-declared` facts, gate a change | `land`, condition 3 | | every verdict names its decision, kind, anchor, import chain, and the readings it used | G7: `explain` never says unknown | -| a verdict is clean, violation, or open question | Writ's three verdicts (ruled 2026-10-28) | +| a verdict is clean, violation, or open question | Writ's three verdicts | | a missing fact is a reported gap, and a verdict that needs it is an open question with its candidates | G8, which covers reporters (§9.3) | | an exclusion and a baseline entry are visible at p and change verdicts only as declared | G1, G7 | ### 9.2 Which facts the gate may rely on -*Ruled (2026-10-28, `DDD-dec-60`; Round 2, ruling 3):* only facts recorded with provenance, from -Writ's closed G8 set `file, compiler, graph, runner, data, telemetry, attestation`. Two values are -added: `deployment-declared` (from IaC or a manifest) and `deployment-observed` (from the -platform's own API). They are "two provenance values, not two inputs": carrying the split as two -inputs under one value "would hide it where it matters, in the verdict". A contract's violation -description says which value it requires. In the How's terms, each reading carries: +Only facts recorded with provenance, from Writ's closed G8 set `file, compiler, graph, runner, +data, telemetry, attestation`. Two values are added: `deployment-declared` (from IaC or a +manifest) and `deployment-observed` (from the platform's own API). They are two provenance +values, not two inputs: carrying the split as two inputs under one value would hide it where it +matters, in the verdict. A contract's violation description says which value it requires. In the +How's terms, each reading carries: | Field | Projector reading | Reporter reading | |---|---|---| @@ -527,17 +528,17 @@ description says which value it requires. In the How's terms, each reading carri | read at | the landing position | the time of the reading, and the position at which it was recorded | | by / attributed to | the software identity that read; the human responsible, where known (protocol §3.4) | the same | -`facts/manifest.json` in the examples has this shape. Its `provenance` field is Writ's value. A fact with no provenance is not a fact -the gate may use. A reporter's own claim about its subject is not a fact about the subject until -it has been recorded with this provenance. +`facts/manifest.json` in the examples has this shape. Its `provenance` field is Writ's value. A +fact with no provenance is not a fact the gate may use. A reporter's own claim about its subject +is not a fact about the subject until it has been recorded with this provenance. ### 9.3 When a reporter is absent: a gap, and an open question -*Ruled (2026-10-28, `DDD-dec-60`), correcting the proposal's "unknown":* "A fact no reporter could -supply is a reported gap, and a verdict that would need it is an open question with the absent -reporter as one candidate (G8)." A contract names its fact sources and a freshness bound -(`RESID@1` requires both `deployment-declared` and `deployment-observed`, within `P1D`). For each -unit and each required provenance: +A fact no reporter could supply is a reported gap, and a verdict that would need it is an open +question with the absent reporter as one candidate (G8). This replaces the proposal's "unknown". +A contract names its fact sources and a freshness bound (`RESID@1` requires both +`deployment-declared` and `deployment-observed`, within `P1D`). For each unit and each required +provenance: - a recorded reading within the bound means the violation description runs, and the verdict is clean or violation; @@ -557,36 +558,35 @@ why the split is a provenance value: it shows in the verdict. | # | On | Demand | |---|---|---| | D-1 | Writ, `code-facts.md` | carry the fact terms the How reads (`how-vocabulary.md` §2), language-neutral, with per-language mapping supplied by an edition | -| D-2 | Writ, contracts | **Answered (ruled 2026-10-28).** Draft 2 has reporters, and `deployment-declared` and `deployment-observed` are added to its provenance set | -| D-3 | Writ, the log | reporter readings, and readings of another system's versions listing, are recorded at a position before any verdict uses them (G1). Reporter readings are answered by Draft 2's reports partition and hashed reporter inputs, as Emil states them. The versions-listing reading is still open | +| D-2 | Writ, contracts | **Answered.** Draft 2 has reporters, and `deployment-declared` and `deployment-observed` are added to its provenance set | +| D-3 | Writ, the log | reporter readings, and readings of another system's versions listing, are recorded at a position before any verdict uses them (G1). Reporter readings are answered by Draft 2's reports partition and hashed reporter inputs, as Emil states them. The versions-listing reading is still a demand, not yet met | | D-4 | Writ, `check` | the What graph is readable by `check` at p, since bindings join over it; and the evaluator binds `?anchor` and `?target` | | D-5 | Writ, `explain` | show anchor, kind, the import chain, and "rests on superseded version" from the last recorded reading | -| D-6 | the authority profile | a baseline entry attaches to (decision, element, target) and is added only by a decision. A waiver never covers a coverage gap. Map `acceptedBy` and `acceptedAt` to the acceptance record's `by` and `at`, since `dpp/1` A-10 removed them as record members and an undotted member may not be invented. The examples do this. **Answered (2026-11-02):** authority.md §4.1 (Round 1, F-1, ruled as read), §4.3 and §4.4 | -| D-7 | — | **Answered (ruled 2026-10-28, Round 3).** The token is `dpp/1` (`DDD-dec-62`). `main` already ships it, so nothing is renamed | -| D-8 | the move | fix the What element identity form and the kind names this document reads (§1.2) | +| D-6 | the authority profile | a baseline entry attaches to (decision, element, target) and is added only by a decision. A waiver never covers a coverage gap. Map `acceptedBy` and `acceptedAt` to the acceptance record's `by` and `at`, since `dpp/1` A-10 removed them as record members and an undotted member may not be invented. The examples do this. **Answered:** authority.md §4.1, §4.3 and §4.4 | +| D-7 | — | **Answered.** The token is `dpp/1`. `main` already ships it, so nothing is renamed | +| D-8 | the move | fix the What element identity form and the kind names this document reads (§1.2). **Answered:** the What has moved and its identity form is decided (§1.2) | --- ## 10. Generation -***Ruled*: out of scope, confirmed (2026-10-28, `DDD-dec-61`).** Writ records generation as open and "decided by -evidence" ("whether the action grammar … can generate code from accepted decisions rather than -only check it"). It places generation after its 1.0. The old §4.2 realisation declarations -(backend, delegation tier) and the §5.2 code-generation seam are not carried forward. +**Out of scope, confirmed.** Writ records generation as open and "decided by evidence" ("whether +the action grammar … can generate code from accepted decisions rather than only check it"). It +places generation after its 1.0. The old How's realisation declarations (backend, delegation +tier) and its code-generation seam are not carried forward. **One condition, so that generation stays additive.** A vocabulary edition maps each How fact -term to a native shape. That mapping is exactly what a generator would read. It is the old §4.3 -"dual-read" property: one declaration drives creation and gates it. So nothing in the How may -make an edition check-only. A generator that someday reads editions changes code, and code -changes go through `land`. It does not change the How: tools never change it -(`DDD-dec-54` ruling 2). +term to a native shape. That mapping is exactly what a generator would read. It is the old +layout model's "dual-read" property: one declaration drives creation and gates it. So nothing in +the How may make an edition check-only. A generator that someday reads editions changes code, and +code changes go through `land`. It does not change the How: tools never change it. --- ## 11. Conformance — what a product claims when it says its How is specified -**`[PROPOSED]`.** One level, matching the What's single level (`DDD-dec-51`): **specified and in -force.** A product's How conforms when all of these hold at a stated position: +One level, matching the What's single level: **specified and in force.** A product's How +conforms when all of these hold at a stated position: 1. Every How decision is a `dpp/1` record with a kind, an anchor under §3, and a violation description. Records without a violation description are allowed and are reported as idle @@ -604,46 +604,45 @@ force.** A product's How conforms when all of these hold at a stated position: **What it does not claim.** That the code satisfies the How. Satisfaction is a verdict at a position, computed and never stored. A product with a red `check` can still have a specified How. -Old conformance levels 2–4 (Realised, Verified, Delivered) went with the How and Delivery and -are not revived. +The old conformance levels 2–4 (Realised, Verified, Delivered) went with the old How and Delivery +and are not revived. --- ## 12. The worked decisions -In [`how-examples/`](how-examples/). There is one decision per kind (plus `REST@1`, the third +In [`how-examples/`](how-examples/). There is one decision per kind (plus `REST@2`, the third "specified once" check). Each is written once, imported and anchored in a product with two systems, evaluated in two targets, and accepted under a test genesis by a delegated human. The checker verifies every pin, signature and authority link, warns on wide anchors, and checks -expressibility per target and supersession across the import. Every record is conformant -under `main`'s reference implementation, unmodified. It also runs the violation -descriptions over +expressibility per target and supersession across the import. Every record is conformant under +`main`'s reference implementation, unmodified. It also runs the violation descriptions over hand-written facts in both targets. The facts are hand-written because no fact projector or reporter exists. The verdicts are analytic: planted defects, predicted before the run, fired as predicted. They show the descriptions execute as written, and nothing more. | Kind | Decision | Anchored at (importer) | Targets | Planted → verdict | |---|---|---|---|---| -| constraint | `LAYER@1` | `acme:product` | C#, TypeScript | upward reference → 1; orphan component → 1 | -| binding | `PURE@1` | `acme:domain-ordering` | C#, TypeScript | effect in the TS core → 1; C# → 0 | -| binding | `REST@1` | `acme:domain-ordering` | C#, TypeScript | wrong TS route → 1; C# → 0 | -| contract | `RESID@1` | `acme:qd-residency-eu` | Azure, AWS | US bucket, declared and observed → 1 each; Azure observed → **open question**, gap reported, absent reporter named | +| constraint | `LAYER@1` | the product node | C#, TypeScript | upward reference → 1; orphan component → 1 | +| binding | `PURE@1` | the Ordering bounded context | C#, TypeScript | effect in the TS core → 1; C# → 0 | +| binding | `REST@2` | the Ordering bounded context | C#, TypeScript | wrong TS route → 1; C# → 0 | +| contract | `RESID@1` | the residency quality demand | Azure, AWS | US bucket, declared and observed → 1 each; Azure observed → **open question**, gap reported, absent reporter named | --- ## 13. Open, for Emil -Ruled on 2026-10-28 and closed here: the anchor reading, a package's What, the design-system and -content-store catalogue, provisional anchoring, binding in Writ, deployment provenance, and the -token. Still open: +Everything in this document is decided except: + +1. *(open)* Whether adopters may register What kinds (§6, last paragraph). +2. *(Claude's reading, not yet confirmed by Emil)* The ratchet semantics of a baseline, and the + reading of an earlier decision's consequence for declared gaps (§8.2). -1. **Not ruled separately** (`rulings.md`, Round 1). These stand as proposed until the merge - ratifies them: - - the three kinds, no fourth and no split, the idle report, and the record types (§4); - - shapes derived from editions, and standards not being targets (§5); - - the recorded-reading condition on supersession, and narrow-never-alter (§7); - - Kind-1 wiring as contracts, and `deployment-declared` facts gating `land` (§4.2, §9); -2. `[OPEN]` Whether adopters may register What kinds (§6, last paragraph). +The parts that once stood as proposed until the merge (the three kinds, no fourth and no split, +the idle report and the record types; shapes derived from editions, and standards not being +targets; the recorded-reading condition on supersession, and narrow-never-alter; Kind-1 wiring as +contracts, and `deployment-declared` facts gating `land`) were ratified by the merge, and are +decided. --- @@ -655,34 +654,35 @@ as a kind with reporter facts; principle is not a kind; coverage generalised acr | # | The proposal said | This document says | Reason | Decision | |---|---|---|---|---| -| H-1 | kind 2 is "Realisation" | kind 2 is **binding**. As ruled, Writ adopts the word, and "realisation" is used as a term nowhere | "Realisation" already meant three things (Writ's vocabulary, `DDD-dec-46`, and the charter's second use) | `DDD-dec-55` | +| H-1 | kind 2 is "Realisation" | kind 2 is **binding**. Writ adopts the word, and "realisation" is used as a term nowhere | "Realisation" already meant three things (Writ's vocabulary, a product's repository scope, and the charter's second use) | `DDD-dec-55` | | H-2 | anchor to one What element or the product | the same, read as: the product node is a What element; anchor to the narrowest covering element; the product-as-space only when the What is empty | Without it, quantified decisions in a non-empty What have no legal anchor except the loophole | `DDD-dec-55` | | H-3 | every language-specific shape is a realisation under a vocabulary edition | a decision's shape in a target is **derived** from the edition, never authored per decision | If shapes were authored per decision, adding a target would need a record per decision, and that drifts. Derived, adding a target touches nothing but an edition | `DDD-dec-57` | | H-4 | a target is a language, a design system or a content store | adds **platform** targets; excludes interface standards (decisions may name them); design system and content store layer over a language | Contracts need platform vocabularies (`RESID@1`). HTTP in the REST projection is a choice of standard, not a target | `DDD-dec-57` | | H-5 | decisions; vocabularies; projector and reporter editions; nothing else | **decision records only**. Vocabularies are edition decisions; projector and reporter editions are named inside them; binaries are realisation | "Every change to the How is a decision" makes an edition a decision. The proposal's "editions as content" and "analyzers as realisation" were the same objects listed twice | `DDD-dec-56` | | H-6 | a package carries the element kinds it binds to | a package carries **no What** | Kinds are framework vocabulary, not What elements. A What of kinds per package would be a private copy of the ontology | `DDD-dec-56` | -| H-7 | a declared gap is a baseline entry | debt is a baseline entry; a **boundary** is an exclusion decision; a waiver never covers a gap | `DDD-dec-45` already distinguishes "missing" (debt) from "unreifiable" (boundary). A boundary must not shrink under a ratchet | `DDD-dec-58` | +| H-7 | a declared gap is a baseline entry | debt is a baseline entry; a **boundary** is an exclusion decision; a waiver never covers a gap | An earlier decision already distinguishes "missing" (debt) from "unreifiable" (boundary). A boundary must not shrink under a ratchet | `DDD-dec-58` | | H-8 | (not raised) | no-orphans is coverage of code by decisions, the mirror of binding coverage | It makes "no orphans" a violation description over in-force decisions, which is what the gate must evaluate | `DDD-dec-55` | -| H-9 | contracts hold the §3.6 Kind-2 demands | contracts also hold the **measurement wiring** of Kind-1 bounds; a contract over `telemetry` facts | Kind 1 had no How home once old §6 retired. A contract over `telemetry` facts is that home | `DDD-dec-60` | -| H-10 | state whether a package may withdraw a version | yes, by a superseding record with `status: withdrawn`. It obliges an answer (re-import or retention) and never blocks by the vendor's act | Provenance never authority (`DDD-dec-54` ruling 3), with an answer the importer cannot skip | `DDD-dec-59` | +| H-9 | contracts hold the Kind-2 demands | contracts also hold the **measurement wiring** of Kind-1 bounds; a contract over `telemetry` facts | Kind 1 had no How home once the old verification section retired. A contract over `telemetry` facts is that home | `DDD-dec-60` | +| H-10 | state whether a package may withdraw a version | yes, by a superseding record with `status: withdrawn`. It obliges an answer (re-import or retention) and never blocks by the vendor's act | Provenance never authority, with an answer the importer cannot skip | `DDD-dec-59` | | H-11 | `explain` shows "rests on superseded version" | the same, **from a recorded reading** of the package's versions listing | The protocol has no forward link (Q2), and G1 forbids live lookups in verdicts | `DDD-dec-59` | | H-12 | (not raised) | an import may narrow a decision (anchor lower) and never alter it. Altering is a fork, recorded as a local decision `basedOn` the package's | Otherwise a vendor decision could be in force in a form the vendor never signed | `DDD-dec-59` | | H-13 | principle is not a kind | kept, plus an **idle** report for decisions with neither a violation description nor a dependent | Carries the old earn-their-place rule as a report, not a violation | `DDD-dec-55` | | H-14 | facts from projectors and reporters | names a third source, a **runner** (execution against the What's scenarios), as a demand on Writ. Not used by the worked decisions | The pure-core binding exists to make behavioural conformance possible. Static facts cannot check it | `DDD-dec-60` | | H-15 | generation out of scope | confirmed, on condition that no edition may be made check-only | Keeps generation additive, as Writ's definition says it is | `DDD-dec-61` | -| H-16 | records use the ruled token | they do: `dpp/1`, as `main` ships it | Ruled 2026-10-28 (Round 3); `DDD-dec-53`'s `decprov/1` superseded | `DDD-dec-62` | +| H-16 | records use the ruled token | they do: `dpp/1`, as `main` ships it | The earlier token `decprov/1` is superseded | `DDD-dec-62` | | H-17 | (not raised) | target declarations and exclusions are record types, not kinds | Neither has a violation description of its own | `DDD-dec-55` | -**Rulings on this appendix (2026-10-28).** +**How each row was settled.** -- **Ruled as proposed here:** H-1 (with Writ adopting "binding"), H-2, H-5, H-6, H-7, H-10, and - H-15's out-of-scope. +- **Ruled as proposed on 2026-10-28:** H-1 (with Writ adopting "binding"), H-2, H-5, H-6, H-7, + H-10, and H-15's out-of-scope. - **Ruled otherwise:** the proposal's "unknown" became an open question with a reported gap (§9.3). -- **Settled by ruling 3:** the design-system and content-store part of H-4. +- **Settled by the ruling on targets:** the design-system and content-store part of H-4. - **Met by Writ's Draft 2, as Emil states it:** H-14's runner demand, and H-9's telemetry wiring as a provenance value. -- **Not ruled separately:** H-3, H-8, H-9, H-11, H-12, H-13 and H-17. They stand as proposed until - the merge. +- **Ratified by the merge:** H-3, H-8, H-9, H-11, H-12, H-13, H-17, the rest of H-4, H-15's + condition, and the proposals kept and not listed above. They were not ruled separately, and + stood as proposed until the merge. ## Appendix B — where the old §§4–7 went @@ -694,12 +694,63 @@ as a kind with reporter facts; principle is not a kind; coverage generalised acr | §4.2 the seam between them | contract, `deployment-declared` versus `deployment-observed`: drift (§9.3) | | §4.2 realisation declarations, delegation tier | generation: out of scope (§10) | | §4.3 repository layout model | constraints; no-orphans as coverage of code (§4.2, §8.3) | -| §4.4 interface contracts; canonical REST projection | standards named in decisions (§5.1); binding (`REST@1`) | -| §4.5 screen composition; Atomic Design; reification | bindings into a design-system target. Coverage and unreifiable pairs: §8 (`DDD-dec-45`). Atomic Design's levels and "tokens not literals": constraints a design-system package may ship | +| §4.4 interface contracts; canonical REST projection | standards named in decisions (§5.1); binding (`REST@2`, superseding `REST@1`) | +| §4.5 screen composition; Atomic Design; reification | bindings into a design-system target. Coverage and unreifiable pairs: §8. Atomic Design's levels and "tokens not literals": constraints a design-system package may ship | | §4.6 content resolution | bindings into a content-store target; coverage per locale: §8 | -| §5, §5.1, §5.3 work units, the Build seam, seam demand | retired (`DDD-dec-42`); not carried. Writ's `land` is the only write path | +| §5, §5.1, §5.3 work units, the Build seam, seam demand | retired; not carried. Writ's `land` is the only write path | | §5.2 the code-generation seam | out of scope (§10) | | §6.1–§6.2 verification requirements and anatomy | the gate is Writ: G1 for determinism, G7 for per-verdict derivation. "The oracle is derived, never authored in the check" becomes: violation descriptions read the What graph | -| §6.3 required verification kinds | layout and contract → constraint; seam and domain → binding; runtime-bound → contract (`telemetry`); behavioural → binding plus runner (H-14); data conformance → add-on (`DDD-dec-44`); pattern, journey, state and Decider justification → What-side checks, the move's | -| §6.3.1 conformance wire protocol | **moved with the What** (the move charter of 2026-10-28, "only the What moves (§3 and the §6.3.1 wire protocol)"): [`what.md`](what.md) §6. This row said "input to the runner demand (H-14); not carried" until the move; the charter's ruling governs. The runner demand H-14 now reads that wire | -| §7 Delivery | retired (`DDD-dec-42`) | +| §6.3 required verification kinds | layout and contract → constraint; seam and domain → binding; runtime-bound → contract (`telemetry`); behavioural → binding plus runner (H-14); data conformance → add-on; pattern, journey, state and Decider justification → What-side checks, the move's | +| §6.3.1 conformance wire protocol | **moved with the What** (only the What moves: its §3 and the §6.3.1 wire protocol): [`what.md`](what.md) §6. This row said "input to the runner demand (H-14); not carried" until the move; the move's charter governs. The runner demand H-14 now reads that wire | +| §7 Delivery | retired | + +--- + +## Not settled yet + +- **Whether adopters may register What kinds** (§6, §13) *(open)*. The Product Framework let an + adopter register AIOs. Deciding it would say whether a product may extend the framework's kinds + locally, or only through a change to the framework. +- **The ratchet semantics of a baseline** (§8.2) *(Claude's reading, not yet confirmed by Emil)*. + The How assumed them before the authority profile was written. The profile now states + baselines (authority.md §4.3: landings only shrink a baseline, and only a fresh acceptance grows + it). Whether that confirms this reading has not been ruled. +- **An earlier decision's consequence for declared gaps** (§8.2) *(Claude's reading, not yet + confirmed by Emil)*: that a declared-unreifiable pair and a declared-missing key are decisions + with a principal. The How keeps that for an exclusion, and refines it for debt: a debt entry is + added by a decision but is a member of the baseline, not a decision of its own. Confirming the + reading as stated would sit in tension with that refinement for debt. + +## Where this comes from + +| Section | Rests on | +|---|---| +| Opening, register | `DDD-dec-55` to `DDD-dec-61` (Emil, 2026-10-28, Rounds 1 to 3 of `meta/sessions/2026-10-27-product-framework-how/rulings.md`); `DDD-dec-54` (the charter's rulings, not reopened); ratified when PR #41 merged (`1d0f40c`); `DDD-dec-119` (2026-11-10: the merge ratified every part "not ruled separately") | +| §1.1 | authority profile: `DDD-dec-47`, `DDD-dec-54` ruling 4; Writ: `DDD-dec-54` ruling 5; token: `DDD-dec-62`, superseding `DDD-dec-53`; the What: `DDD-dec-41`, `DDD-dec-42`, `DDD-dec-51`; execution and delivery retired: `DDD-dec-42` (old §5, §5.1, §5.3, §7); generation: `DDD-dec-61` (old §4.2, §5.2); data conformance: `DDD-dec-44` (old §13) | +| §1.2 | the charter, `meta/sessions/2026-10-27-product-framework-how/prompt.md`, to which this document was Claude's answer; its `bootstrap.md`, arrival findings 1–3; precondition 1: `DDD-dec-41`, the What then read from Product Framework v1.10.0 §3; precondition 2: `DDD-dec-51`, the move charter's risk 3 (identity fixed "before any decision is written against them"), ruling 4 of 2026-10-28 (recorded on each of `DDD-dec-55` to `-61`), discharged by `DDD-dec-63` and `DDD-dec-65` to `DDD-dec-71`; precondition 3: discharged by `authority.md` (2026-11-02), formerly held open by the move session's Round 1, Q-4; precondition 4: Emil's statement of Writ Draft 2, Round 1; the token: `DDD-dec-62` (Round 3), PR #40 and PR #39 | +| §2 | the four repairs: Rounds 1 and 2; the anchor reading: `DDD-dec-55` (its former `UNVERIFIED` mark dropped as stale, accepted in Round 3 of the redo session, 2026-11-11, findings F-13); the loophole: `DDD-dec-54` ruling 1; reporters and provenance: `DDD-dec-60`; package's What: `DDD-dec-56`, superseding `DDD-dec-46`'s consequence clause; binding: `DDD-dec-55` (repair 2); "Writ narrows": Round 2; realisation scope: `DDD-dec-46`. Earlier "UNVERIFIED — Emil review" on the anchor reading in the table is removed: `DDD-dec-55` rules it | +| §3 | `DDD-dec-54` ruling 1; the reading: `DDD-dec-55` (ruling 1, as proposed); product as root: old Product Framework §3.0; decision space: `DDD-dec-46`; creating decision: `DDD-dec-42` | +| §4.1 | violation description: `DDD-dec-52`; verdicts never stored: `DDD-dec-49`; provenance: `DDD-dec-60` | +| §4.2 | `DDD-dec-55`; Kind-1 wiring (H-9): `DDD-dec-60`, ratified by `DDD-dec-119`; old §4.2–§4.6, §5.2, PF §3.2.5, PF §3.6 | +| §4.3, §4.4 | `DDD-dec-55`, ratified by `DDD-dec-119` (formerly `[PROPOSED]`); contract provenance: `DDD-dec-60`; old §4.1 | +| §5.1 | targets, not catalogues: `DDD-dec-57` (ruling 3); `DDD-dec-44` ("§11 and §12 are What"); the rest of §5.1: `DDD-dec-57`, ratified by `DDD-dec-119` (formerly `[PROPOSED]`); old §4.4 | +| §5.2 | stated once, no language or platform term: `DDD-dec-57`, ratified by `DDD-dec-119`; the closed list of terms a decision uses (formerly `[PROPOSED]`): `DDD-dec-119` through how.md's banner, its reach ruled in Round 3 of the redo session (2026-11-11); runner: `DDD-dec-60` (H-14) | +| §6 | `DDD-dec-46`; `DDD-dec-54` rulings 2 and 3; contents (repair 3): `DDD-dec-56`; no What: `DDD-dec-56` (ruling 2), superseding `DDD-dec-46`'s consequence, `DDD-dec-42` stands; the open point: old PF §3.2.2 | +| §7.1 | `DDD-dec-59` (its statement rules the three parts of an import); narrow-never-alter: `DDD-dec-59`'s list, ratified by `DDD-dec-119` (formerly `[PROPOSED]`) | +| §7.2 | `DDD-dec-59`'s list (the recorded-reading condition), ratified by `DDD-dec-119` (formerly `[PROPOSED]`) | +| §7.3 | `DDD-dec-59` (2026-10-28) | +| §8.1 | `DDD-dec-58` (its statement); `DDD-dec-45` (old §4.5, §4.6 as What obligations); formerly marked `[PROPOSED]`, ratified by `DDD-dec-119` | +| §8.2 | `DDD-dec-58` (ruled as proposed); `DDD-dec-45`; old §6.2. Readings: the ratchet semantics (formerly `UNVERIFIED — Emil review`) and `DDD-dec-45`'s consequence (Claude's reading, not ruled) | +| §8.3 | old PF §14.5 | +| §9.1 | Writ's definition; the three verdicts: 2026-10-28 | +| §9.2, §9.3 | `DDD-dec-60`; Round 2, ruling 3; freshness bound and gating: `DDD-dec-60`'s list, ratified by `DDD-dec-119` | +| §9.4 | D-2: Round 1; D-6: answered by authority.md (Round 1, F-1, ruled as read); D-7: `DDD-dec-62` (Round 3); D-8: answered by `DDD-dec-63` | +| §10 | `DDD-dec-61` (2026-10-28); the condition: `DDD-dec-61`, ratified by `DDD-dec-119`; tools never change the How: `DDD-dec-54` ruling 2; old §4.2, §4.3, §5.2 | +| §11 | `DDD-dec-51` (the What's single level); formerly `[PROPOSED]`, ratified by `DDD-dec-119` through how.md's banner, its reach ruled in Round 3 of the redo session (2026-11-11) | +| §12 | `how-examples/`; anchors and `REST@2` as in the current records (`IMP-layer@2`, `IMP-pure@2`, `IMP-rest@2`, `IMP-resid@2`; `REST@2` supersedes `REST@1`, `DDD-dec-64` P-1) | +| §13 | `DDD-dec-119` | +| Appendix A | the decisions named per row; settlement: Round 1 of 2026-10-28, and `DDD-dec-119` | +| Appendix B | `DDD-dec-42`, `DDD-dec-44`, `DDD-dec-45`; the move charter of 2026-10-28 | + +This text replaces `84aa466:applications/sdlc/how.md` in place. Its section numbers are unchanged, +because records, decisions and the What's files cite them. diff --git a/applications/sdlc/product-cli/product-definition.md b/applications/sdlc/product-cli/product-definition.md index 8019dc0..055c199 100644 --- a/applications/sdlc/product-cli/product-definition.md +++ b/applications/sdlc/product-cli/product-definition.md @@ -1,13 +1,19 @@ # Product: product definition -Draft 4, 2026-11-03 (Draft 3, 2026-10-30; Draft 2, 2026-10-30; Draft 1, 2026-10-21). Written outside-in: the promise first, the implementation last. Chapters 1 to 6 are the product; chapter 7 is how it happens to be built and may change without the product changing. + -This is the definition of the rewritten product-cli. It replaces the Rust workspace of the same name. `[D1.24]` (2026-11-03) It lives here, in decision-driven-design beside the What it implements; the tool, its ADRs and its tests live in `mindovermachine-dev/product-cli` (chapter 7). What carries over is listed in chapter 8; everything else is new, and "it was like that before" is not a reason for anything in this document. +This is the definition of the rewritten product-cli. It replaces the Rust workspace of the same name. It lives here, in decision-driven-design beside the What it implements; the tool, its ADRs and its tests live in `mindovermachine-dev/product-cli` (chapter 7). What carries over is listed in chapter 8; everything else is new, and "it was like that before" is not a reason for anything in this document. -Rulings are marked `[D1.n]` with their date where they land. -- **Drafts 2 and 3.** Draft 2 adds D1.2 to D1.9. Draft 3 adds D1.10 to D1.15, ruled with ADR-0010, ADR-0011 and ADR-0012; they rest on `dpp/1` (specification 1.0, draft of 2026-10-27, decision-driven-design `spec/decision-provenance/dpp-1.md`). -- **Draft 4** adds D1.16 to D1.25, ruled on 2026-11-03. D1.16 to D1.23 come from the gate checks of 2026-11-02 (A1 to A8); D1.24 supersedes D1.23, and D1.25 adds step 0 to the order of work. The checks were run against decision-driven-design `c7424ad`, Varve `c0a776b`, Writ `6737ac9` and the Rust tool `70395df`. -- **Superseded rulings** keep their number, with the ruling that replaces them named in place. The text below states the ruling in force. +Read it if you build or review the tool, or will author a What with it. It is written outside-in: the promise first, the implementation last. Chapters 1 to 6 are the product; chapter 7 is how it happens to be built and may change without the product changing. + +**How settled this is.** Draft 4, of 2026-11-03. Everything here is decided, except the points marked *(open)* and listed in "Not settled yet". Where a decision replaced an earlier one, the text states the decision in force and lists the replaced ones in "Where this comes from", with one exception: the rule that the tool holds no authority was superseded by a later decision on 2026-11-08, and the text has not yet been reworked to it. Each place it appears says so. The `sdlc:` edition it implements is edition 1, shipped in decision-driven-design `v0.6.0`. The tool is not yet built: chapter 7's order of work says how far it has got. ## 1. The promise @@ -15,10 +21,10 @@ A machine-checkable statement of what a product does, with an executable oracle Four consequences follow and are the whole product: -- `[D1.10]` (2026-10-30) **The What is authored in conversation, and every step of it is a decision.** An agent proposes; the author watches the graph, its findings and its open questions change live, and adopts or rejects each proposal. Each adoption is a `dpp/1` decision record with its reason, so specification moves at the speed of the conversation and every element of the What traces to the person who adopted it. +- **The What is authored in conversation, and every step of it is a decision.** An agent proposes; the author watches the graph, its findings and its open questions change live, and adopts or rejects each proposal. Each adoption is a `dpp/1` decision record with its reason, so specification moves at the speed of the conversation and every element of the What traces to the person who adopted it. - **The What is a graph with shapes, never prose with diagrams.** Anything that cannot be stated as a node, an edge or a shape is not yet specified, and the tool says so rather than accepting it. - **Behaviour is executable before any code exists.** A Decider and a Projector are simulated sound and complete against scenarios drawn from the flows. The same scenarios later judge realised code through a wire protocol the tool implements. -- **The tool puts nothing in force and decides nothing about realisation.** `[D1.11]` (2026-10-30) It records the author's decisions over the What as `dpp/1` records, which by its profile carry no force. It produces a canonical document. What that document is held against, who accepts it under which grant, and from which position it is in force, belong to Writ. +- **The tool puts nothing in force and decides nothing about realisation.** *(A later decision supersedes this: product-cli carries the same grants and roles as the other systems. This text has not yet been reworked to it; see "Not settled yet".)* It records the author's decisions over the What as `dpp/1` records, which by its profile carry no force. It produces a canonical document. What that document is held against, who accepts it under which grant, and from which position it is in force, belong to Writ. Everything below is how. @@ -50,7 +56,7 @@ Every verb takes `--product `; a repository holds one or more products und | `product product new\|list\|show` | the product root (§3.0): name, purpose, owned domains and systems | | `product domain new …` | captures a What node of one of the kinds listed below; refuses a change set with a violation (W1) | | `product domain show\|list\|rm` | inspects or removes nodes and their links | -| `product domain validate [--strict]` | `[D1.19]` (2026-11-03) violations; with `--strict`, also the warning findings of chapter 5 (W3, W4) | +| `product domain validate [--strict]` | violations; with `--strict`, also the warning findings of chapter 5 (W3, W4) | | `product domain export [--canonical] [--format ]` | the What, written by an exporter over the canonical graph. The default and `--canonical` give the canonical document, which is what Writ lands. `--format` selects another registered exporter. An unknown format, or an edition the exporter does not support, is refused with a diagnostic and no output. `--list-formats` prints each registered format: name, IRI, media type, supported editions, stability | | `product decider derive\|validate\|simulate ` | derives a Decider's signature from the event model, checks the authored logic against it, runs its scenarios | | `product projector derive\|validate\|simulate ` | the read-model peer | @@ -59,21 +65,21 @@ Every verb takes `--product `; a repository holds one or more products und | `product conformance run ` | drives a realised implementation through the wire protocol (§6) with the product's scenarios and reports outcomes | | `product question new\|list\|answer` | open questions as authored nodes: what the graph cannot yet decide, which nodes they concern, what they block | | `product diff [

] [--export ]` | what changed between two draft positions, or between the draft and a given export | -| `product proposal list\|show\|adopt\|reject\|review` | `[D1.12]` (2026-10-30) the agent's pending proposals; `adopt` and `reject` write the author's decision record, with its reason (below). `[D1.15]` (2026-10-30) `adopt` takes one or more numbers or ids, or `--all`; `review` steps through pending proposals one at a time (below) | -| `product view [--port ]` | `[D1.13]` (2026-10-30) the workbench: a live view of the draft log on localhost (below) | +| `product proposal list\|show\|adopt\|reject\|review` | the agent's pending proposals; `adopt` and `reject` write the author's decision record, with its reason (below). `adopt` takes one or more numbers or ids, or `--all`; `review` steps through pending proposals one at a time (below) | +| `product view [--port ]` | the workbench: a live view of the draft log on localhost (below) | | `product mcp [--http]` | the agent surface, same verbs, phase-gated (below); with `--http`, also starts the workbench | -**Node kinds for `domain new`:** `entity`, `value-object`, `relation`, `invariant`, `context`, `mapping`, `reference-data`, `event`, `command`, `view`, `trigger`, `ui-step`, `flow`, `system`, `journey`, `subject-kind`, `quality-demand`. `[D1.8]` (2026-10-30) `subject-kind` replaces `actor-kind`, following chapter 8's term. +**Node kinds for `domain new`:** `entity`, `value-object`, `relation`, `invariant`, `context`, `mapping`, `reference-data`, `event`, `command`, `view`, `trigger`, `ui-step`, `flow`, `system`, `journey`, `subject-kind`, `quality-demand`. `subject-kind` replaces `actor-kind`, following chapter 8's term. -> **Open.** Some kinds are in the vocabulary but have no `domain new` kind: +> *(open)* Some kinds are in the vocabulary but have no `domain new` kind: > - AIO, context of use, page graph and application root; > - WCAG criterion and attestation; > - `sdlc:DeclaredTarget` (`what.md` §4.1); -> - `sdlc:Interaction`, `sdlc:Field`, `sdlc:StateAnnotation` and `sdlc:ContentKey`, which are elements by `DDD-dec-64` P-3. +> - `sdlc:Interaction`, `sdlc:Field`, `sdlc:StateAnnotation` and `sdlc:ContentKey`, which are elements by the rule "anything a binding, a baseline, reads, a scope key or a wire request names is an element". > > Either they gain kinds, or the definition names the verb through which they are authored. -`[D1.2]` (2026-10-27) Exporting goes through one seam: every export, the canonical one included, is written by an exporter over the canonical graph (§4, "Exports"). +Exporting goes through one seam: every export, the canonical one included, is written by an exporter over the canonical graph (§4, "Exports"). ### The draft log @@ -81,7 +87,7 @@ The working copy is a positioned log of its own (Varve, embedded, kept in Git). ### Proposals and decisions -`[D1.12]` (2026-10-30) The draft log is a `dpp/1` conformant system (`dpp/1` §8). Every change that reaches its head is a decision record (`dpp/1` §3) with a non-empty `why`. +The draft log is a `dpp/1` conformant system (`dpp/1` §8). Every change that reaches its head is a decision record (`dpp/1` §3) with a non-empty `why`. - **The agent proposes.** An agent's write is a proposal: a change set, shape-checked (W1) and phase-gated (W9) when submitted, held beside the head and not in it. - Its record has `status: proposed`, `by` the agent's identity (`dpp/1` §3.4: software is `by`, never a person), `attributedTo` the author, and the agent's reason in `why`. @@ -95,7 +101,7 @@ The working copy is a positioned log of its own (Varve, embedded, kept in Git). ### The workbench -`[D1.13]` (2026-10-30) `product view` serves a live, local view of the draft log in a browser. It follows the draft log rather than any one writer, so it updates on every new position whoever wrote it: the CLI, an agent over stdio MCP, or an agent over HTTP MCP. It shows: +`product view` serves a live, local view of the draft log in a browser. It follows the draft log rather than any one writer, so it updates on every new position whoever wrote it: the CLI, an agent over stdio MCP, or an agent over HTTP MCP. It shows: - the structure, behaviour and surface of the What at the head; - the session: the current phase, what the last decision changed, and who decided it (agent proposal or author); @@ -106,7 +112,7 @@ Its only writes are adopt and reject, and they go through the same verbs as the ### Adopting on the fly -`[D1.15]` (2026-10-30) Adoption is the author's most frequent act, so it costs one action wherever the author is. +Adoption is the author's most frequent act, so it costs one action wherever the author is. - **Adoption needs no typing.** By default an adoption's `why` is a `ref` to the proposal, pinned in `basedOn` (`dpp/1` §3.4): "adopted for the reason the proposal gives". The author types a reason only to add one. - **Rejection needs one line, and the agent reads it.** `dpp/1` requires a non-empty `why`, so rejection asks for a short reason, with a few one-press reasons offered (out of scope, wrong, duplicate, not yet). The reason is returned to the agent as the outcome of its proposal, so a rejection is also the instruction for the next proposal. @@ -128,7 +134,7 @@ The same verbs, over stdio or HTTP, in a phase-gated session: structure (§3.0, - Read verbs from an earlier phase stay callable; writes lock to their phase. - Every write verb of an agent session creates a proposal, and requires a reason. - Open questions are phase-free and gate advancing. -- There is no adopt, no reject, no land, no grant and no signing on the agent surface: adoption is the author's, in the workbench, at the CLI, or by elicitation answered by the author (D1.15). An agent session ends with an export, which is handed to Writ by whoever holds a grant there. +- There is no adopt, no reject, no land, no grant and no signing on the agent surface: adoption is the author's, in the workbench, at the CLI, or by elicitation answered by the author ("Adopting on the fly"). An agent session ends with an export, which is handed to Writ by whoever holds a grant there. ## 4. The formats @@ -138,7 +144,7 @@ Section numbers in this chapter and the next are `applications/sdlc/what.md`'s. ### The vocabulary (`sdlc:`) -`[D1.1]` (2026-10-28) The vocabulary is `sdlc:`, owned by decision-driven-design (`applications/sdlc/`), where the What now lives; this tool implements it and owns nothing of it. `pf:` is retired. Element identity is the ruled form of `DDD-dec-63`: a stable product IRI P, flat element IRIs `P/what/` with names as labels, RDFC-1.0 as the canonical form, a What-version as a `dpp/1` record. The §4 to §7 classes are not carried. +The vocabulary is `sdlc:`, owned by decision-driven-design (`applications/sdlc/`), where the What now lives; this tool implements it and owns nothing of it. `pf:` is retired. Element identity is the What's ruled identity form (`what.md` §2.2 and §2.3): a stable product IRI P, flat element IRIs `P/what/` with names as labels, RDFC-1.0 as the canonical form, a What-version as a `dpp/1` record. The §4 to §7 classes are not carried. The content is the What subset of the Product Framework: - product, domain, system, bounded context; @@ -151,57 +157,55 @@ The content is the What subset of the Product Framework: - quality demand, subject kind and claim, scope rule, declared target; - open question. -`[D1.18]` (2026-11-03) **Terms.** This definition and every specification page cite the vocabulary's own terms: `sdlc:subject` on a trigger, `sdlc:keyedBy` on a Projector, `sdlc:wireName` and `sdlc:within`. CLI flags may use other names. Earlier drafts' `acts_as` and `keyed_by` read as these terms. +**Terms.** This definition and every specification page cite the vocabulary's own terms: `sdlc:subject` on a trigger, `sdlc:keyedBy` on a Projector, `sdlc:wireName` and `sdlc:within`. CLI flags may use other names. Earlier drafts' `acts_as` and `keyed_by` read as these terms. The vocabulary is versioned by edition. An export states its edition. A later edition never changes the meaning of an earlier one; migration is a new export. ### Shapes -`[D1.9]` (2026-10-30, amended by D1.20) The shapes and rules live with the vocabulary, in decision-driven-design (`applications/sdlc/`), versioned by the same edition. The content: +The shapes and rules live with the vocabulary, in decision-driven-design (`applications/sdlc/`), versioned by the same edition. The content: - SHACL shapes for every node kind (the per-node checks); - SPARQL rules for the graph-level checks (chapter 5). They are the author's feedback in this tool and, at the same edition, Writ's enumerated decisions over the same graph. One artefact, two roles; never two copies. -`[D1.20]` (2026-11-03) **How the edition is carried.** The edition is pinned by `(versionIRI, hash)`, as `DDD-dec-72` rules: `owl:versionIRI` and the sha256 over `ontology.ttl` then `shapes.ttl`, the bytes as tagged. +**How the edition is carried.** The edition is pinned by `(versionIRI, hash)`, as decision-driven-design rules for its editions: `owl:versionIRI` and the sha256 over `ontology.ttl` then `shapes.ttl`, the bytes as tagged. - The binary embeds both files byte for byte, because the version IRI does not dereference to them and the binary runs offline. - The build fails if the embedded bytes do not hash to the pin. - There is no edited copy, no second source and no runtime fetch. -The one hash law (D1.3) governs What graph content. The edition itself is pinned as files. +The one hash law ("The canonical export", below) governs What graph content. The edition itself is pinned as files. -`[D1.19]` (2026-11-03) **The validation regime and the severities** are the edition's (ruled in `DDD-dec-113`, E-1 and E-2; `what.md` §7.2): +**The validation regime and the severities** are the edition's (`what.md` §7.2): - **The data graph** is the What graph merged with the edition's `ontology.ttl`. Validation uses SHACL Core class semantics (`rdf:type/rdfs:subClassOf*` over that merged graph) with SHACL-SPARQL, and no RDFS or OWL entailment. - **The ontology** is never part of a What graph's hash or of an export. - **`sh:Violation`** refuses at write (W1, W5). - **`sh:Warning`** is a finding (W3, W4). It is reported, never refused. -A requirement added to an edition after an example is pinned enters as `sh:Warning`, and may become a violation only in a later edition (`DDD-dec-113`, E-2). +A requirement added to an edition after an example is pinned enters as `sh:Warning`, and may become a violation only in a later edition. If the edition keeps pattern conformance (`what.md` §3.2.0, every command traces to a trigger) a violation, then `domain new command` takes its trigger in the same change set, and an agent proposes them together. ### The canonical export -`[D1.3]` (2026-10-30, amended by D1.16) **The canonical document.** The landable graph document is the RDFC-1.0 canonical N-Quads serialisation of the What graph at one draft position, in the default graph, under the hash law of `DDD-dec-73`. It is the only graph document Writ lands. Writ must accept it as such; that is a change requested in Writ (Writ #22), not made here. +**The canonical document.** The landable graph document is the RDFC-1.0 canonical N-Quads serialisation of the What graph at one draft position, in the default graph, under decision-driven-design's hash law for the What (`what.md` §2.3). It is the only graph document Writ lands. Writ must accept it as such; that is a change requested in Writ (Writ #22), not made here. -`[D1.16]` (2026-11-03, superseding the logic clause of D1.3 and the whole of D1.7) **What the export contains.** -- **The graph.** One graph: the What nodes, with every Decider and Projector carrying `sdlc:logic` (a `sha256:` digest) and `sdlc:logicMediaType`, as `DDD-dec-63` §6 rules. +**What the export contains.** +- **The graph.** One graph: the What nodes, with every Decider and Projector carrying `sdlc:logic` (a `sha256:` digest) and `sdlc:logicMediaType`, as the What's identity form rules (`what.md` §2.3). - **The logic artefacts.** The authored logic itself, one file per digest, in the logic media type (below). The canonical export is the graph document plus the artefacts its digests name. A digest in the graph with no artefact beside it is a malformed export. The graph hash and the element hashes cover the logic through the digests. -`[D1.5]` (2026-10-30) **Determinism.** Two exports of the same draft position are byte-identical, graph and artefacts alike. Element IRIs are minted when a node is first written, so two authors who independently author the same What hold different IRIs and export different bytes. Identity comes from the draft log, not from content. +**Determinism.** Two exports of the same draft position are byte-identical, graph and artefacts alike. Element IRIs are minted when a node is first written, so two authors who independently author the same What hold different IRIs and export different bytes. Identity comes from the draft log, not from content. -**Element hashes.** Each element's hash is taken over its description, canonicalised on its own (`DDD-dec-63` §4, `what.md` §2.3). The description rule is `sdlc:`-specific, so it is implemented here over Varve's canonicaliser and never put into Varve. Its vectors over decision-driven-design's examples are offered there as a further cross-check. M-12's second implementation stays Varve's published vectors (`DDD-dec-73`). +**Element hashes.** Each element's hash is taken over its description, canonicalised on its own (`what.md` §2.3). The description rule is `sdlc:`-specific, so it is implemented here over Varve's canonicaliser and never put into Varve. Its vectors over decision-driven-design's examples are offered there as a further cross-check. The conforming second implementation of the canonical form that decision-driven-design is waiting for stays Varve's published vectors. ### The What-version record -`[D1.14]` (2026-10-30) is superseded by D1.17. - -`[D1.17]` (2026-11-03) Every export carries its manifest as a What-version `dpp/1` record. It is JSON, per `dpp/1` §3, not RDF; the PROV-O rendering of `dpp/1` §10 is non-normative and lossy. It has four parts. +Every export carries its manifest as a What-version `dpp/1` record. It is JSON, per `dpp/1` §3, not RDF; the PROV-O rendering of `dpp/1` §10 is non-normative and lossy. It has four parts. -- **The ruled shape.** It is `DDD-dec-63` §6's record, written unchanged: +- **The ruled shape.** It is the What-version record of `what.md` §2.3, written unchanged: - `id` is `what`; `version` is a sequence this system chooses, never the graph hash; - `supersedes` is the previous What-version; - the dotted member `dk.decision-driven-design.sdlc` holds `record: "what-version"`, `product` (P), `edition {versionIRI, hash}`, `canon: "rdfc-1.0"`, `graphHash`, and `elements`, an array of `{iri, hash}` sorted by IRI. @@ -218,7 +222,7 @@ The canonical export is the graph document plus the artefacts its digests name. ### Decision records and the profile -`[D1.12]` (2026-10-30) The draft log exposes its decision records through the `dpp/1` file binding (§6.6), at `.product/products//decisions/`, so a reader with the repository can walk them without the tool. The record shapes are `dpp/1`'s. +The draft log exposes its decision records through the `dpp/1` file binding (§6.6), at `.product/products//decisions/`, so a reader with the repository can walk them without the tool. The record shapes are `dpp/1`'s. This tool publishes a profile (`dpp/1` §9.4), and names it in its descriptor. It states: @@ -231,7 +235,7 @@ The profile is a format under read-forever like the others. It requires no signa ### Exports -`[D1.2]` (2026-10-27, amended by D1.16) Every export is a deterministic function of the canonical graph and its logic artefacts. The canonical graph is the pinned edition plus the RDFC-labelled, sorted triple set. Exporters receive only these. They read neither the draft log nor node-record internals. +Every export is a deterministic function of the canonical graph and its logic artefacts. The canonical graph is the pinned edition plus the RDFC-labelled, sorted triple set. Exporters receive only these. They read neither the draft log nor node-record internals. **Canonical and derived.** The canonical writer is the first exporter; its format IRI is the one Writ lands. Every other export is derived: @@ -257,9 +261,7 @@ The scenario format this tool owns is the authoring and reporting form of those ### Decider and Projector logic -`[D1.7]` (2026-10-30) is superseded by D1.16. - -`[D1.16]` (2026-11-03) **The logic is an authored artefact held by digest** (`DDD-dec-63` §6). It is not RDF and not part of the graph's triples; the graph carries its digest and media type. +**The logic is an authored artefact held by digest** (`what.md` §2.3). It is not RDF and not part of the graph's triples; the graph carries its digest and media type. The signature is in the graph and is derived: - `sdlc:decidesFor`, `sdlc:handles`, `sdlc:reads` and `sdlc:rejects` for a Decider; @@ -281,7 +283,7 @@ decision-driven-design's example logic (`what/examples/logic/*.yaml`, `applicati Each is a property test over generated What graphs and scenarios, and the suite is public. Every test observes bytes, in the draft log or in an export, never the return value of the verb that produced them. -`[D1.19]` (2026-11-03) W1 and W5 are the edition's violations. W3 and W4 are its warnings (`DDD-dec-113`). The checks themselves are the edition's shapes, not code in this tool. +W1 and W5 are the edition's violations. W3 and W4 are its warnings. The checks themselves are the edition's shapes, not code in this tool. - **W1. Shape before storage.** No change set enters the draft log if it carries a violation. A failed write leaves the log unchanged. - **W2. Derived, not declared.** A Decider's signature (the commands it handles, the events it may emit, the state it evolves) and a Projector's (the events it folds, the fields it may produce) are computed from the graph. An authored signature, or logic, that disagrees is refused. @@ -290,7 +292,7 @@ Each is a property test over generated What graphs and scenarios, and the suite - every event a Projector's View projects is folded by it; - every (command, subject kind) pair, from a step's `sdlc:offeredTo` or a trigger's `sdlc:subject`, has a scenario showing acceptance or a reachable rejection; - every View a step surfaces has a scope rule for every subject kind the step is offered to, or is public; - - `[D1.4]` (2026-10-30, amended by D1.18) `[D1.18]` (2026-11-03) every automated or external trigger acts as a subject kind (`sdlc:subject`). A user trigger's subject comes from the step's `sdlc:offeredTo` (`what.md` §3.7). + - every automated or external trigger acts as a subject kind (`sdlc:subject`). A user trigger's subject comes from the step's `sdlc:offeredTo` (`what.md` §3.7). - **W4. Justification.** Orphans are findings: - every aggregate field is read by some Decider; - every projected field is consumed by some step; @@ -298,20 +300,20 @@ Each is a property test over generated What graphs and scenarios, and the suite - every Decider has a reachable rejection. - **W5. Type boundary.** Each of these is refused at write, not reported later: - a UI step references only AIOs, never concrete controls; - - `[D1.4]` (2026-10-30, amended by D1.18) a trigger's `sdlc:subject`, when present, names a subject kind whose nature matches the trigger's `source`. An absent subject is accepted, and reported under W3 when the trigger is automated or external. A What without subjects therefore exports byte-identically; + - a trigger's `sdlc:subject`, when present, names a subject kind whose nature matches the trigger's `source`. An absent subject is accepted, and reported under W3 when the trigger is automated or external. A What without subjects therefore exports byte-identically; - a journey crosses systems only through a Translation. - **W6. Simulation before realisation.** Every Decider and Projector with scenarios is simulated sound and complete before an export is marked ready. A What with a failing scenario exports, but says so in its What-version record. - **W7. Canonical export.** Two exports of the same draft position are byte-identical, on every platform, graph and logic artefacts alike. Canonicalisation happens once, before any exporter runs. Every derived export is a deterministic function of the canonical graph and artefacts, and its record names that graph's canonical hash. - **W8. Round-trip.** Importing a canonical export yields a draft whose export is byte-identical to the input, graph and artefacts. - **W9. Phase order.** An agent session cannot author a node before the nodes it derives from exist. The gate is the session transport, not advice in a prompt. -- **W10. Nothing in force, nothing landed.** `[D1.11]` (2026-10-30) The tool holds no key and no grant, puts nothing in force, knows no Writ position, and writes to no log but its own draft log. Its decision records carry no force by its profile. Exporters produce documents only. -- **W11. Decision-provenance conformant.** `[D1.12]` (2026-10-30) The draft log is a conformant system under `dpp/1` §8, at specification 1.0, checked by the `dpp/1` conformance suite (Appendix C): +- **W10. Nothing in force, nothing landed.** *(A later decision supersedes this: product-cli carries the same grants and roles as the other systems. This text has not yet been reworked to it; see "Not settled yet".)* The tool holds no key and no grant, puts nothing in force, knows no Writ position, and writes to no log but its own draft log. Its decision records carry no force by its profile. Exporters produce documents only. +- **W11. Decision-provenance conformant.** The draft log is a conformant system under `dpp/1` §8, at specification 1.0, checked by the `dpp/1` conformance suite (Appendix C): - every record it exposes is conformant (§3.6), has a non-empty `why`, and has `system` equal to the draft log's identifier; - no hashed content changes under a published triple, and no version is reused (§3.8); - records it no longer holds answer "not held" (§6.8). - The export's What-version record rests on every decision in force (D1.17). A Writ decision that lands the export, by naming it in its `basedOn`, therefore reaches each author decision and each agent proposal by the walk of `dpp/1` §7 alone. -- **W12. Nothing an agent wrote is in the What unless a person adopted it.** `[D1.12]` (2026-10-30) Every change at the head of the draft log is attached to a decision record whose `by` is the author: either an adoption of a proposal, or the author's own write. A proposal never reaches the head on its own, and the agent surface has no verb that adopts. + The export's What-version record rests on every decision in force ("The What-version record"). A Writ decision that lands the export, by naming it in its `basedOn`, therefore reaches each author decision and each agent proposal by the walk of `dpp/1` §7 alone. +- **W12. Nothing an agent wrote is in the What unless a person adopted it.** Every change at the head of the draft log is attached to a decision record whose `by` is the author: either an adoption of a proposal, or the author's own write. A proposal never reaches the head on its own, and the agent surface has no verb that adopts. ## 6. The contracts between parts @@ -320,7 +322,7 @@ Five interfaces, each small, each expressed over the vocabulary. Exporting is no | Contract | In | Out | First implementation | |---|---|---|---| | **Draft store** | commits of What nodes and logic artefacts | positions, as-of reads, diffs | Varve, embedded, file backend in Git | -| **Shape engine** | a graph, and the embedded shapes and ontology of an edition | violations and warnings by node and shape | Varve's `Varve.Shacl` with `Varve.Shacl.Sparql`, under the regime of D1.19 | +| **Shape engine** | a graph, and the embedded shapes and ontology of an edition | violations and warnings by node and shape | Varve's `Varve.Shacl` with `Varve.Shacl.Sparql`, under the edition's validation regime (chapter 4, "Shapes") | | **Simulator** | a Decider or Projector, its logic artefact, scenarios | outcomes per scenario, derived signature, coverage and justification findings | an evaluator for the logic media type over the wire scalar alphabet | | **Runner protocol** | scenarios | requests on stdin; outcomes judged by exact ordered-emit and full-state equality from stdout | `what.md` §6's JSON shapes; a C# reference runner | | **Authoring session** | a product, a phase, an actor (agent or author) | the verbs permitted in that phase to that actor: proposals for an agent, adoption and direct writes for the author | MCP over stdio and HTTP; the workbench and the CLI for the author | @@ -336,10 +338,10 @@ This chapter may change without chapters 1 to 6 changing. | Part | Built from | Why | |---|---|---| | Draft store | Varve, embedded | positions and diffs over the draft for free; one RDF stack in the ecosystem | -| Shapes and rules | the edition's files, embedded and hash-checked at build (D1.20), evaluated by Varve's SHACL and SHACL-SPARQL | the same bytes Writ evaluates, so the author's check and the gate cannot disagree | +| Shapes and rules | the edition's files, embedded and hash-checked at build (chapter 4, "Shapes"), evaluated by Varve's SHACL and SHACL-SPARQL | the same bytes Writ evaluates, so the author's check and the gate cannot disagree | | Canonical form | Varve's `RdfCanonicaliser` (RDFC-1.0) | checked on 2026-11-02 to reproduce decision-driven-design's published graph hashes, and the lift input's hash, byte for byte | | Element hashes | this tool, over Varve's canonicaliser | the description rule is `sdlc:`'s, not Varve's | -| Node kinds | one C# record per kind, with a source generator emitting the RDF writer, the parser, the kind registry and the shape binding (ADR-0005) | the Rust version kept five hand-maintained parallel enumerations and failed silently when one was missed | +| Node kinds | one C# record per kind, with a source generator emitting the RDF writer, the parser, the kind registry and the shape binding (a product-cli ADR) | the Rust version kept five hand-maintained parallel enumerations and failed silently when one was missed | | Exporters | one interface over the canonical graph and artefacts, registered at compile time | Native AOT forbids runtime plugins; canonicalisation in one place | | Decision records | `dpp/1` records over the file binding, hashed by the `dpp/1` hash law (§5) | the draft log is walkable by any `dpp/1` reader, with no tool | | Workbench | a Blazor WebAssembly client, embedded in the binary and served by it | all C#, no Node; Blazor Server is not Native AOT compatible, static files and minimal APIs are | @@ -347,9 +349,7 @@ This chapter may change without chapters 1 to 6 changing. **Constraints.** 100% managed .NET, Native AOT and trimming compatible, Varve's constraints 1 to 5, every third-party package needs an ADR. Fixed layers, dependencies downward, public API baselines, every rule an analyzer that fails the build. -`[D1.23]` (2026-11-03) is superseded by D1.24. It put the rewrite in a new repository. - -`[D1.24]` (2026-11-03) **Where it lives.** +**Where it lives.** An earlier decision put the rewrite in a new repository; this one replaced it. - **The definition** lives in decision-driven-design, at `applications/sdlc/product-cli/product-definition.md`. A change to it is a pull request there, ratified by merge. Outside-in therefore crosses two repositories: a definition change merges here before any product-cli change that relies on it, and the product-cli change cites the commit. - **The tool**, its ADRs, its tests and its release descriptors live in `mindovermachine-dev/product-cli`, which `Hafeok/product-cli` redirects to. There is no new repository. - **The Rust workspace is frozen by tag.** The tag is `rust-final`, at `70395df`. @@ -359,27 +359,27 @@ This chapter may change without chapters 1 to 6 changing. - **The Rust tool's open issues** are closed as not carried, or re-filed against the rewrite, when the Rust tree leaves `main`. - **Retirement** means that the acceptance below holds, the lift tool is deleted, and no further Rust release is made. The tag stays. -`[D1.4]` (2026-10-30, amended by D1.21) **Acceptance.** The Rust tool's export of its self-hosted What is in `pf:` and cannot be byte-identical to an `sdlc:` export. Acceptance therefore goes through a one-time lift. +**Acceptance.** The Rust tool's export of its self-hosted What is in `pf:` and cannot be byte-identical to an `sdlc:` export. Acceptance therefore goes through a one-time lift. -`[D1.21]` (2026-11-03) **The lift.** +**The lift.** 1. **The frozen input.** It is pinned by RDFC-1.0 graph hash, not by bytes, because the Rust tool's Turtle is not byte-stable across builds: its re-export at `70395df` differs in bytes from the committed `.product/products/product-cli/product-cli.ttl` and is isomorphic to it. - - Repository and commit: `mindovermachine-dev/product-cli` at `70395df`, tagged `rust-final` (D1.24). + - Repository and commit: `mindovermachine-dev/product-cli` at `70395df`, tagged `rust-final` ("Where it lives"). - Command: `product domain export --product product-cli`. The Rust tool has no `--canonical`. - Size: 1,412 triples and 289 subjects, of which 32 are blank nodes. - Graph hash: `sha256:ad855b900abd76bdc8a26d91ce995e267856dad8c47d15e1ee509f41c5d07e06`. pyoxigraph and Varve agree on it. 2. **The lift map,** frozen, versioned and committed, never regenerated: - **Terms.** Every `pf:` class and predicate in the input is either mapped to an `sdlc:` term or dropped by name with a reason. - The How kinds are dropped: `ReificationRule`, `Cio`, design-system style and tokens, `versionedAs` and `targetsPlatform`. - - The ownership edges become `sdlc:within` (`DDD-dec-64` P-2): `inContext`, `ownsDomain`, `ownsSystem`, `systemOf`, `journeyOf` and `boundedBy`. + - The ownership edges become `sdlc:within`, the What's single containment edge: `inContext`, `ownsDomain`, `ownsSystem`, `systemOf`, `journeyOf` and `boundedBy`. - **IRI subjects.** Each gets one minted `P/what/`, with the old name as `rdfs:label`. The product IRI P is stated in the lift ADR. - - **Blank nodes.** All 32 become elements (P-3), each keyed by (owning subject IRI, predicate, its own description, sorted). The key is unique over the frozen input. + - **Blank nodes.** All 32 become elements, by the same rule that makes interactions and fields elements (chapter 3), each keyed by (owning subject IRI, predicate, its own description, sorted). The key is unique over the frozen input. - The 15 `pf:hasAttribute` nodes become `sdlc:Field` elements: `attrName` becomes `rdfs:label`, and `attrType` becomes `sdlc:fieldType`. - The 7 `pf:offers` and 10 `pf:surfaces` nodes become `sdlc:Interaction` elements within their UI step. - **Stored, not minted.** The ULIDs and the adopted wire names are stored in the map, each wire name with the reference to the review that adopted it. Lifting again therefore reproduces the golden bytes. - - **Wire names are authored, not carried.** The input has none. The lift ADR states the rule that proposes one for every kind that requires one (`what.md` §6, R-1, R-2), and review adopts each. + - **Wire names are authored, not carried.** The input has none. The lift ADR states the rule that proposes one for every kind that requires one (`what.md` §6), and review adopts each. 3. **Two fixtures.** - **The golden fixture.** The lift produces the new tool's canonical export of the self-hosted What. It imports through W1 and carries no violation under its edition. It is reviewed and committed. Lifting again with the same map is checked to reproduce the golden bytes, once, and the result is recorded. The self-hosted What holds no Decider, Projector, scenario, subject kind or scope rule, so this fixture fixes structure and surface only. - - **The behaviour fixture.** decision-driven-design's `what/examples/acme-shop-5.ttl` and its logic artefacts, at `v0.6.0`, imported through W1. It carries no findings under the edition. Its published element and graph hashes (`vectors-5.json`) are part of the test. *Amended 2026-11-06 (decision-driven-design `DDD-dec-113`, E-5):* it was `acme-shop-4.ttl` and `vectors-4.json`. That graph is pinned by `CUR@1` and `what@4`, and lacks the (Place order, Customer) scenario and the E-7 descriptions; `acme-shop-5.ttl` is it plus both. + - **The behaviour fixture.** decision-driven-design's `what/examples/acme-shop-5.ttl` and its logic artefacts, at `v0.6.0`, imported through W1. It carries no findings under the edition. Its published element and graph hashes (`vectors-5.json`) are part of the test. It was `acme-shop-4.ttl` and `vectors-4.json` until 2026-11-06. That graph is pinned by `CUR@1` and `what@4`, and lacks the (Place order, Customer) scenario and the descriptions edition 1 asks of every domain, bounded context and subject kind; `acme-shop-5.ttl` is it plus both. 4. **Acceptance.** - Both fixtures round-trip byte-identically (W7, W8). - The conformance suite passes: the framework CLI scenarios, and the seed round-trip property. @@ -387,17 +387,17 @@ This chapter may change without chapters 1 to 6 changing. **Order of work:** -0. `[D1.25]` (2026-11-03) Slice 0, the repository skeleton (ADR-0002, ADR-0003, ADR-0004): +0. Slice 0, the repository skeleton: - the eight layer projects, each with its public API baseline and a test that the layering analyzer refuses an upward reference; - the Native AOT publish of the host on every supported runtime in CI, with a smoke test of the published binary; - the package register: Varve, the analyzers, and the test-only packages. It needs no `sdlc:` edition, so it does not wait for step 1's upstream. -1. Pin the `sdlc:` edition and its shapes; the lift ADR and the lift map. Edition 1 shipped in decision-driven-design `v0.6.0` (`DDD-dec-113`). +1. Pin the `sdlc:` edition and its shapes; the lift ADR and the lift map. Edition 1 shipped in decision-driven-design `v0.6.0`. 2. The canonical graph, element hashes and the exporters (canonical N-Quads with artefacts, sorted Turtle), with their conformance suites; the What-version record; the logic media type's specification page and suite. 3. The lift and both fixtures. 4. Nodes and `validate`, each write a `dpp/1` record (W11). -5. `[D1.13]` (2026-10-30) The authoring loop: proposals and adoption, MCP with the structure phase, and the workbench. From here the main use is dogfooded. +5. The authoring loop: proposals and adoption, MCP with the structure phase, and the workbench. From here the main use is dogfooded. 6. Deciders, Projectors and the simulator, with the behaviour phase. 7. Scenarios and the runner protocol. 8. Open questions, and the surface phase. @@ -412,7 +412,7 @@ This chapter may change without chapters 1 to 6 changing. - features, releases, delivery targets or `done`. Those are decisions and valuations held in Writ over this tool's export. - - **Declared targets are in it.** A system's design system and content store, declared as `sdlc:DeclaredTarget` at an edition (`what.md` §4.1, `DDD-dec-57`), are What. Their catalogues are packages; the bindings are Writ's. + - **Declared targets are in it.** A system's design system and content store, declared as `sdlc:DeclaredTarget` at an edition (`what.md` §4.1), are What. Their catalogues are packages; the bindings are Writ's. - The framework document stays whole as an open standard; this tool implements one part of it and says which. - **Licence.** Apache-2.0, from the commit after `rust-final` that replaced the licence (`59553ee`, merged at `53bd547`). MIT governs everything at `rust-final` and before it, and the Rust tool's releases. - **What carries over from the Rust workspace.** @@ -420,20 +420,20 @@ This chapter may change without chapters 1 to 6 changing. - the name and the verb names; - `what.md` and its §6; - the wire-protocol JSON schemas, as moved into decision-driven-design; - - the self-hosted What, through the D1.21 lift, as the first fixture; + - the self-hosted What, through the lift (chapter 7), as the first fixture; - the framework CLI scenarios and the seed round-trip property, as the conformance suite. - - `[D1.9]` (2026-10-30) `schema/ontology/product-framework.ttl` and `schema/shapes/` are input to `sdlc:` in decision-driven-design and are not carried into this repository. + - `schema/ontology/product-framework.ttl` and `schema/shapes/` are input to `sdlc:` in decision-driven-design and are not carried into this repository. - **Not carried:** `ddd`, `spec`, `eval`, `ledger`, codegen, the build seam, `how`, `feature`, `build`, `seam`, `preview`, `target`, `deployable-unit`, `design-system`, `scope`, and the React explorer. -- **No authority, ever.** `[D1.11]` (2026-10-30) The tool records decisions; it never puts one in force. It holds no key and no grant, offers no acceptance under a grant, and knows no Writ position. `dpp/1` leaves authority to profiles (§1.3, §9.4), and this tool's profile claims none. The ledger that lived in the Rust repository is Writ's authority graph now; `writ import` reads the old `.decisions/` once. +- **No authority, ever.** *(A later decision supersedes this: product-cli carries the same grants and roles as the other systems. This text has not yet been reworked to it; see "Not settled yet".)* The tool records decisions; it never puts one in force. It holds no key and no grant, offers no acceptance under a grant, and knows no Writ position. `dpp/1` leaves authority to profiles (§1.3, §9.4), and this tool's profile claims none. The ledger that lived in the Rust repository is Writ's authority graph now; `writ import` reads the old `.decisions/` once. - **Two systems, one protocol.** The draft log and Writ's log are two `dpp/1` systems. The draft log holds the author's decisions over the What; Writ's log holds what is in force. They share no position, grant or key; they are joined only by `basedOn` references with pins, which carry provenance and never force. The tool never learns about Writ positions or grants; the moment it does, the boundary has leaked. - **Decision-driven, like Writ.** The tool holds no key, but the project does. - - `[D1.22]` (2026-11-03, amending the Draft 3 clause "governed by an embedded `writ` from its first commit") Writ has no implementation yet: its embedded log arrives with Writ #7, and `land` with #8. - - **Until #7,** this repository's ADRs are files under `docs/decisions/`, under the interim rule of Writ ADR 0008: ADR-level discipline is kept by review, and `main` is fast-forwarded only at an approved, checked head. + - Writ has no implementation yet: its embedded log arrives with Writ #7, and `land` with #8. + - **Until #7,** this repository's ADRs are files under `docs/decisions/`, under Writ's interim rule for ADRs: ADR-level discipline is kept by review, and `main` is fast-forwarded only at an approved, checked head. - **From #7,** `writ import` reads them once, with a baseline, and the repository is governed by its embedded `writ`. - **From #8,** code lands through `writ land`. This is the path Writ takes for its own ADRs. -- **Subjects are What (`what.md` §3.7, adopted from the unmerged v1.11.0 by ruling, 2026-10-28; the term is `SubjectKind`, since "actor" is canon's and "principal" is authority's).** +- **Subjects are What (`what.md` §3.7, adopted from the Product Framework's unmerged v1.11.0; the term is `SubjectKind`, since "actor" is canon's and "principal" is authority's).** - Subject kinds have a nature (human, process, external) and claims. - A trigger's `sdlc:subject` sits beside its unchanged `source`, nature matching source, so a What without subjects exports byte-identically. - The subject is a fourth argument of `decide`, beside `when` on the wire, never a payload field. @@ -442,27 +442,109 @@ This chapter may change without chapters 1 to 6 changing. - `sdlc:keyedBy` on the Projector makes scoping a keyed fold at the seam, not a filter over a shared one. - Authentication, and with it provider coverage, belongs to the How. - Authority within the product stays separate from authority over the specification, which is why Writ's grants are not `sdlc:`. - - The checks this tool needs that `what.md` §3.7 still marks `[OPEN]` are the subject half of W3 and claim justification. They are in edition 1 as warning shapes (`DDD-dec-113`, E-4), and are built here only by importing that edition. + - The checks this tool needs for subjects, the subject half of W3 and claim justification, are in edition 1 as warning shapes (`what.md` §3.7), and are built here only by importing that edition. - **Not in scope.** Code generation of any kind, including verification shells; delivery practice; any model inside a check. The proposer that turns an interview into nodes is an agent driving the verbs, outside the tool, and its output is judged by the same shapes as a human's. ## Cross-repository dependencies As of 2026-11-06. -| Ruling | Needs | Where | State | +| Needed for | Needs | Where | State | |---|---|---|---| -| D1.19 | the validation regime, and violations separated from warnings | decision-driven-design #49 | **met**: ruled in `DDD-dec-113` (E-1, E-2), landed by mindovermachine-dev/decision-driven-design#59 | -| D1.19, W3, W4 | the five §3.4 and §3.7 shapes not yet in `shapes.ttl` | decision-driven-design #50 | **met**: `DDD-dec-113` (E-4) | -| D1.1, D1.20 | `sdlc:` edition 1 tagged; until then its file hash moves | decision-driven-design | **met**: `v0.6.0`, tag object `bb47a720832c77f6a53c82b90388cd4a2c5c23bf` on `1ab1de005eb60ce2ea019e9942cd52b790aab0e7`, edition hash `sha256:a2006d9da588586bbf7ac19b3eec4861ff5a1aec0006a61784e9e0d842672f29` | -| D1.3, D1.17 | Writ lands canonical N-Quads as the What document, and holds the guest graph under `sdlc:` instead of `pf:` | Writ #22 | open | -| D1.22 | the embedded log (#7) and `land` (#8) | Writ | open | -| element hashes | product-cli's element-hash vectors, offered as a cross-check beside Varve's (`DDD-dec-73`, `DDD-dec-113` E-3) | decision-driven-design (M-12) | to deliver at step 2 | -| D1.3 | RDFC-1.0 in Varve | Varve | **met**: `RdfCanonicaliser` reproduces decision-driven-design's graph hashes | -| D1.19 | SHACL Core with SHACL-SPARQL, AOT-compatible | Varve | **met**: `Varve.Shacl` and `Varve.Shacl.Sparql` agree with pyshacl on both examples | -| D1.1 | `DDD-dec-63` on `main`, and the What half of `sdlc:` published | decision-driven-design | **met** | -| D1.17 | the What-version record's dotted member | decision-driven-design | **met**: fixed by `DDD-dec-63` §6 | -| D1.7 | an RDF form of the logic | decision-driven-design | **withdrawn** with D1.7 (D1.16) | -| D1.24 | the tag `rust-final` at `70395df` | product-cli | **met**: tag object `d0cf1f1ec40eb55c271b8d4dadfefcd260c03312` | -| D1.24 | the Rust tree removed from `main` | product-cli | **met**: mindovermachine-dev/product-cli#166, merged at `53bd54758ba71f7a810f91ddf3a6c83d5e653145` | -| D1.25 | slice 0, the repository skeleton | product-cli | **met**: `4ce90e9` | +| The validation regime (ch. 4, "Shapes") | the validation regime, and violations separated from warnings | decision-driven-design #49 | **met**: ruled for edition 1, landed by mindovermachine-dev/decision-driven-design#59 | +| The validation regime; W3, W4 | the five §3.4 and §3.7 shapes not yet in `shapes.ttl` | decision-driven-design #50 | **met**: in edition 1 | +| The vocabulary; how the edition is carried | `sdlc:` edition 1 tagged; until then its file hash moves | decision-driven-design | **met**: `v0.6.0`, tag object `bb47a720832c77f6a53c82b90388cd4a2c5c23bf` on `1ab1de005eb60ce2ea019e9942cd52b790aab0e7`, edition hash `sha256:a2006d9da588586bbf7ac19b3eec4861ff5a1aec0006a61784e9e0d842672f29` | +| The canonical export; the What-version record | Writ lands canonical N-Quads as the What document, and holds the guest graph under `sdlc:` instead of `pf:` | Writ #22 | open | +| Decision-driven, like Writ (ch. 8) | the embedded log (#7) and `land` (#8) | Writ | open | +| Element hashes | product-cli's element-hash vectors, offered as a cross-check beside Varve's | decision-driven-design (a further cross-check beside the canonical form's second implementation, not a substitute for it) | to deliver at step 2 | +| The canonical export | RDFC-1.0 in Varve | Varve | **met**: `RdfCanonicaliser` reproduces decision-driven-design's graph hashes | +| The validation regime | SHACL Core with SHACL-SPARQL, AOT-compatible | Varve | **met**: `Varve.Shacl` and `Varve.Shacl.Sparql` agree with pyshacl on both examples | +| The vocabulary | the What's identity form on `main`, and the What half of `sdlc:` published | decision-driven-design | **met** | +| The What-version record | the What-version record's dotted member | decision-driven-design | **met**: fixed by the identity form (`what.md` §2.3) | +| Decider and Projector logic | an RDF form of the logic | decision-driven-design | **withdrawn**: the logic is held by digest, not as RDF | +| Where it lives (ch. 7) | the tag `rust-final` at `70395df` | product-cli | **met**: tag object `d0cf1f1ec40eb55c271b8d4dadfefcd260c03312` | +| Where it lives (ch. 7) | the Rust tree removed from `main` | product-cli | **met**: mindovermachine-dev/product-cli#166, merged at `53bd54758ba71f7a810f91ddf3a6c83d5e653145` | +| Order of work, step 0 | slice 0, the repository skeleton | product-cli | **met**: `4ce90e9` | | — | `applications/sdlc/README.md` points to the Rust product-cli as the reference implementation | decision-driven-design | amended with this definition's arrival; the Rust tool is the reference until retirement | + +## Not settled yet + +- **The tool's authority, superseded and not yet reworked** (chapter 1, W10, chapter 8). A later + decision supersedes "no authority, ever": product-cli carries the same grants and roles as the + other systems, and a scope ranges over decision kinds as well as What element kinds. The + passages that say the tool holds no key and no grant state the superseded rule, and are marked + where they appear. Reworking them is the specification-feasibility work's, not this rewrite's. +- **Node kinds with no `domain new` kind** (chapter 3, "Commands"). AIO, context of use, page + graph and application root; WCAG criterion and attestation; `sdlc:DeclaredTarget`; + `sdlc:Interaction`, `sdlc:Field`, `sdlc:StateAnnotation` and `sdlc:ContentKey` are in the + vocabulary with no `domain new` kind. Either they gain kinds, or the definition names the verb + through which they are authored. Deciding it changes the surface of chapter 3. + +The cross-repository dependencies still open (Writ #22, Writ #7 and #8, and the element-hash +vectors due at step 2) are listed with their state in the table above. + +## Where this comes from + +**Drafts.** Draft 1, 2026-10-21; Draft 2, 2026-10-30; Draft 3, 2026-10-30; Draft 4, 2026-11-03. +Draft 2 added the rulings D1.2 to D1.9. Draft 3 added D1.10 to D1.15, ruled with product-cli's +ADR-0010, ADR-0011 and ADR-0012; they rest on `dpp/1` (specification 1.0, draft of 2026-10-27, +decision-driven-design `spec/decision-provenance/dpp-1.md`). Draft 4 added D1.16 to D1.25, ruled +on 2026-11-03. D1.16 to D1.23 come from the gate checks of 2026-11-02 (A1 to A8), run against +decision-driven-design `c7424ad`, Varve `c0a776b`, Writ `6737ac9` and the Rust tool `70395df`. +D1.24 supersedes D1.23, and D1.25 adds step 0 to the order of work. A superseded ruling keeps its +number, and the text states the ruling in force. + +| Chapter, section | Rests on | +|---|---| +| Opening, where the definition lives | D1.24 (2026-11-03) | +| 1. The promise: authored in conversation | D1.10 (2026-10-30) | +| 1. The promise: nothing in force | D1.11 (2026-10-30), superseded by `DDD-dec-117` (2026-11-08) | +| 3. Commands: `domain validate` | D1.19 (2026-11-03) | +| 3. Commands: `proposal` | D1.12 (2026-10-30); `adopt` by number or `--all`, and `review`, D1.15 (2026-10-30) | +| 3. Commands: `view` | D1.13 (2026-10-30) | +| 3. Node kinds: `subject-kind` replaces `actor-kind` | D1.8 (2026-10-30) | +| 3. Node kinds: elements | `DDD-dec-64` P-3 | +| 3. Exporting through one seam | D1.2 (2026-10-27) | +| 3. Proposals and decisions | D1.12 (2026-10-30) | +| 3. The workbench | D1.13 (2026-10-30) | +| 3. Adopting on the fly; MCP's "by elicitation" | D1.15 (2026-10-30) | +| 4. The vocabulary | D1.1 (2026-10-28); the identity form, `DDD-dec-63` | +| 4. Terms | D1.18 (2026-11-03) | +| 4. Shapes | D1.9 (2026-10-30), amended by D1.20 | +| 4. How the edition is carried | D1.20 (2026-11-03); the edition pin, `DDD-dec-72` | +| 4. The validation regime and the severities; the warning clause for later requirements | D1.19 (2026-11-03); `DDD-dec-113`, E-1 and E-2 | +| 4. The canonical document | D1.3 (2026-10-30), amended by D1.16; the hash law, `DDD-dec-73` | +| 4. What the export contains | D1.16 (2026-11-03), superseding the logic clause of D1.3 and the whole of D1.7; `DDD-dec-63` §6 | +| 4. Determinism | D1.5 (2026-10-30) | +| 4. Element hashes | `DDD-dec-63` §4; the second implementation, successor item M-12 of `DDD-dec-73`, kept by `DDD-dec-113` E-3 | +| 4. The What-version record | D1.17 (2026-11-03), superseding D1.14 (2026-10-30); `DDD-dec-63` §6 | +| 4. Decision records and the profile | D1.12 (2026-10-30) | +| 4. Exports | D1.2 (2026-10-27), amended by D1.16 | +| 4. Decider and Projector logic | D1.16 (2026-11-03), superseding D1.7 (2026-10-30); `DDD-dec-63` §6 | +| 5. Severities of the guarantees | D1.19 (2026-11-03); `DDD-dec-113` | +| 5. W3, automated and external triggers act as a subject kind | D1.4 (2026-10-30), amended by D1.18 (2026-11-03) | +| 5. W5, a trigger's subject matches its source | D1.4 (2026-10-30), amended by D1.18 | +| 5. W10 | D1.11 (2026-10-30), superseded by `DDD-dec-117` (2026-11-08) | +| 5. W11, W12 | D1.12 (2026-10-30); W11's What-version clause, D1.17 | +| 6. Shape engine | D1.19 | +| 7. Shapes and rules, embedded and hash-checked | D1.20 | +| 7. Node kinds, by source generator | product-cli ADR-0005 | +| 7. Where it lives | D1.24 (2026-11-03), superseding D1.23 (2026-11-03), which put the rewrite in a new repository | +| 7. Acceptance | D1.4 (2026-10-30), amended by D1.21 | +| 7. The lift | D1.21 (2026-11-03); `sdlc:within` as the single containment edge, `DDD-dec-64` P-2; blank nodes as elements, P-3; wire names, `what.md` §6 with `DDD-dec-64` R-1 and R-2 | +| 7. The behaviour fixture, moved to `acme-shop-5.ttl` | Amended 2026-11-06 by decision-driven-design `DDD-dec-113`, E-5 (the new graph) and E-7 (the descriptions) | +| 7. Order of work, step 0 | D1.25 (2026-11-03); product-cli ADR-0002, ADR-0003, ADR-0004 | +| 7. Order of work, step 1 | Edition 1, `DDD-dec-113` | +| 7. Order of work, step 5 | D1.13 (2026-10-30) | +| 8. Declared targets | `DDD-dec-57` | +| 8. `schema/` not carried | D1.9 (2026-10-30) | +| 8. No authority, ever | D1.11 (2026-10-30), superseded by `DDD-dec-117` (2026-11-08) | +| 8. Decision-driven, like Writ | D1.22 (2026-11-03), amending Draft 3's clause "governed by an embedded `writ` from its first commit"; the interim rule is Writ ADR 0008 | +| 8. Subjects are What | adopted from the Product Framework's v1.11.0 by ruling, 2026-10-28 | +| 8. The subject checks, in edition 1 | `DDD-dec-113`, E-4 | +| Cross-repository dependencies | as of 2026-11-06; the validation regime, `DDD-dec-113` E-1 and E-2; the five shapes, E-4; element hashes, `DDD-dec-73` and `DDD-dec-113` E-3; the What-version record's member, `DDD-dec-63` §6; the logic's RDF form withdrawn with D1.7 (D1.16) | + +The text this replaces is `84aa466:applications/sdlc/product-cli/product-definition.md`. One +statement there was stale and is corrected: chapter 8 said `what.md` §3.7 "still marks `[OPEN]`" +the subject half of W3 and claim justification. Edition 1 put those checks in `shapes.ttl`, and +`what.md` §3.7 has carried no open mark since. diff --git a/applications/sdlc/production-as-ground.md b/applications/sdlc/production-as-ground.md index 559c45a..fdf538d 100644 --- a/applications/sdlc/production-as-ground.md +++ b/applications/sdlc/production-as-ground.md @@ -1,20 +1,31 @@ # Production Is Ground -**Location:** proposed `applications/sdlc/production-as-ground.md`. An application of the encode/verify -split (`apparatus/encode-verify.md`) and the closure principle (`apparatus/closure-principle.md`) to -software delivery, tested against the DORA research programme. - -**Status: reported, partially. The correspondence with DORA's published findings is real and is -checked below, including two places the framework fails to add anything and one place it may be -wrong.** The framework was *not* validated against DORA's underlying data — that data is not public; -only aggregate findings are. This is a retrodiction check against published results, not a statistical -test, and it is presented as such. - ---- - -**Upstream basis.** This document is part of the software projection; it builds on the -principle repo's canon (`actor-indexed-determination`). The `core/NN` references below resolve -there, pinned at a version and a status in `graph/upstream.yaml`: + + +Read this if you lead a delivery team, or use the DORA metrics, and want to decide where your +team should check its changes. It argues that a test suite checks code against a copy of the +world, not the world, and uses that to sort checks into three tiers, each with its right place to +run. It ends with a number you can compute from your own incident history. It applies two ideas +from the framework's apparatus to software delivery, the +[encode/verify split](../../apparatus/encode-verify.md) and the +[closure principle](../../apparatus/closure-principle.md), and tests them against the DORA +research programme. + +**How settled this is: reported, partially. The correspondence with DORA's published findings is +real and is checked below, including two places the framework fails to add anything and one place +it may be wrong.** The framework was *not* validated against DORA's underlying data — that data is +not public; only aggregate findings are. This is a retrodiction check against published results, +not a statistical test, and it is presented as such. + +The ideas below that come from the principle's canon are pinned in +[`graph/upstream.yaml`](../../graph/upstream.yaml); "Where this comes from" names them. @@ -24,7 +35,7 @@ there, pinned at a version and a status in `graph/upstream.yaml`: A tempting formulation is: *"you cannot know whether software works before it is in production."* **That is too strong and the framework rejects it.** Compilers, type checkers, and test suites close -predicates. `core/03` holds: digital work with checkable predicates has zero intrinsic floor. Taken +predicates. The framework holds that digital work with checkable predicates has zero intrinsic floor. Taken literally, the strong claim would make nearly all software floor-exposed, which is false and would contradict the framework's own central result. @@ -37,7 +48,7 @@ The defensible version is about **ground**, not about knowledge: Which makes the gap an instance of something already named: > **A test suite is an encoded observation of ground you do not control.** It encodes what production -> was believed to look like when the test was written. Per `encode-verify.md`, *you cannot amortise an +> was believed to look like when the test was written. By the encode/verify split, *you cannot amortise an > observation of something you do not control* — so that belief has an expiry date and no alarm on it. Green tests over drifted fixtures is the **poisoned ground** signature exactly @@ -98,7 +109,7 @@ The framework says the same thing without needing to observe it: > **So AI increases unverified demand in flight.** Generation capacity grew; verification capacity did > not. The gap widens, and the framework's escape term grows with it. -This is `core/10`'s structure at the organisational scale: **production capacity outran verification +This is the framework's structure at the organisational scale: **production capacity outran verification capacity, and the surplus went into the escaped store.** Not a defect in the model's output — a mis-allocation, exactly the sort the conservation principle predicts when one store's throughput increases and the others do not. @@ -150,7 +161,7 @@ exception matters: The middle tier is why the naive two-way cut fails. *"Does this query hold at production traffic"* is a **technical** question whose predicate does not close statically — you can benchmark against substitutes, but the real answer requires real load. Likewise correctness against production's actual -`P(input)`, which is `core/09`'s deployment-distribution caveat arriving in practice: you do not have +`P(input)`, which is the framework's deployment-distribution caveat arriving in practice: you do not have production's input distribution in staging. **And this is what progressive delivery is *for*.** Canaries and shadow traffic are not a @@ -182,8 +193,8 @@ rate: **deployment is their primary verifier**, so every closable decision they to production to be checked there. Deploying faster discovers those errors sooner; it does not stop manufacturing them. -*Caveat, and it is real: classifying a decision by predicate closure is `core/03`'s undecidable-in- -general problem. In practice you do not need the general solution — the abundant cases (published +*Caveat, and it is real: classifying a decision by predicate closure is undecidable in general, as the +framework itself states. In practice you do not need the general solution — the abundant cases (published rules, static constraints, schema conformance) are obvious. But the framework should not claim the decision set can be cleanly partitioned, because it cannot.* @@ -250,7 +261,7 @@ your copy and the source of truth. **Why this is not obvious.** Both families reduce failure risk, and industry advice treats them as complementary rungs on one ladder. The framework says they are **different in kind**: one shrinks the encode/verify gap by *verifying against the source of truth*, the other shrinks it by *improving the -copy*. Per `encode-verify.md`, only the first can close it, because the second is still an encoded +copy*. By the encode/verify split, only the first can close it, because the second is still an encoded observation of ground you do not control. **How it could fail.** If test-environment fidelity predicts performance as strongly as progressive @@ -279,10 +290,10 @@ offered *to* the research programme, not one this framework can settle. - **The AI finding is the framework's best case** (§3): generation capacity outran verification capacity, and the surplus went to escape. Derived, not observed — and it yields a specific intervention. -- **Batch size and feedback latency are not the framework's contributions** (§4). Cite Reinertsen and +- **Batch size and feedback latency are not the framework's contributions** (§5). Cite Reinertsen and Lean. -- **The 2024 cluster anomaly is an open discrepancy** (§5), not a resolved one. -- **The progressive-delivery-over-fidelity prediction** (§6) is the only genuinely novel, falsifiable +- **The 2024 cluster anomaly is an open discrepancy** (§6), not a resolved one. +- **The progressive-delivery-over-fidelity prediction** (§7) is the only genuinely novel, falsifiable claim here — and it is offered to DORA, not settled by this document. --- @@ -292,3 +303,37 @@ offered *to* the research programme, not one this framework can settle. > **Production is the only ground that is not a copy. Everything shipped before it was verified against > an encoded belief about the world, and the whole apparatus of continuous delivery is an empirical > programme for shrinking the interval during which that belief goes unchecked.** + +--- + +## Not settled yet + +- **The 2024 cluster anomaly** (§6). DORA's medium cluster posted a lower change failure rate + than its high cluster, which a naive reading of the framework says should not happen. The + defence in §6 is weak, and it should not be treated as settled. It is booked as an open + discrepancy. +- **Progressive delivery over environment fidelity** (§7). The prediction has not been tested. + Testing it needs DORA's response-level data, which is not public, so it is offered to the + research programme, not settled here. +- **The partition is not clean** (§4.3). Classifying a decision by predicate closure is + undecidable in general. The abundant cases are obvious enough to act on, but the decision set + cannot be cleanly partitioned. + +## Where this comes from + +| Section | Rests on | +|---|---| +| Opening | `apparatus/encode-verify.md`; `apparatus/closure-principle.md`; the principle repository `actor-indexed-determination`, pinned in `graph/upstream.yaml` at `v5.15.2` | +| 1. The claim, stated carefully | Zero intrinsic floor for digital work with checkable predicates: upstream `core/03`, `DDD-floor-01` (reported) and `term:floor` (settled); the amortisation limit, `apparatus/encode-verify.md`; the poisoned-ground signature, `apparatus/closure-principle.md` | +| 2. What DORA measures | DORA's published four keys and batch-size account | +| 3. The finding that tests the framework | DORA 2024 and 2023 reports (AI adoption and batch size); the cost structure of upstream `core/10` | +| 4.1 Three tiers | The deployment-distribution caveat of upstream `core/09`, `DDD-measure-01` (projected) | +| 4.3 What this predicts | Undecidability of closure in general, upstream `core/03` | +| 5. Where the framework adds nothing | Reinertsen's queueing arguments; Lean batch-size theory | +| 6. Where the framework might be wrong | DORA 2024 cluster results | +| 7. A prediction | DORA's capability catalogue (test data management; progressive delivery); `apparatus/encode-verify.md` | + +The text this replaces is `84aa466:applications/sdlc/production-as-ground.md`. That text opened +with "Location: proposed `applications/sdlc/production-as-ground.md`", which was stale: the +document is at that path. Its §8 cited §4, §5 and §6 for points made in §5, §6 and §7; the +citations are corrected here, and no rule changed. diff --git a/applications/sdlc/sdlc.md b/applications/sdlc/sdlc.md index a095539..3d2ff58 100644 --- a/applications/sdlc/sdlc.md +++ b/applications/sdlc/sdlc.md @@ -1,28 +1,38 @@ # The SDLC — from a released issue to production, dark -**Register: ruled (Rounds 28 and 30).** This specification is the -exposition of `DDD-dec-115`. It has two layers: -- **What the decision files.** The decision files Emil's rulings: the request (2026-11-06), - Rounds 1 and 2, Round 13 as ruled by Round 14, and Rounds 19, 20, 22 and 28, which entered by - amendment before landing (Round 21) (verbatim in - [`meta/sessions/2026-11-07-sdlc-and-pdlc/rulings.md`](../../meta/sessions/2026-11-07-sdlc-and-pdlc/rulings.md)). -- **What Round 28 ruled.** Round 28 ruled Claude's construction, item by item, as listed in - `rulings.md` (R1 to R30): the step cards' readings, the landing's mechanics, the identity port - and its departures, the record's place, the DORA computations and the falsifiers. Where a - sentence states a ruling, the round is named. Prose that no listed item covers is exposition, - and the decision governs it. - -Where this text and `DDD-dec-115` disagree, the decision governs. - -**The arrangement is the SDLC and has no other name** (Round 15: "It is the SDLC so its the same -arrangement"). It is not Delivery (Round 1: "its not delivery because it doesnt care about -releases or a timeline. Its the pipeline for getting value out to production - so its a new -arrangement"). - -**Scope.** A product repository that adopts the SDLC. This repository's own trunk stays under -`DDD-dec-108` to `-110`, unchanged. - -**Upstream basis**, pinned at `v5.15.2` in [`graph/upstream.yaml`](../../graph/upstream.yaml): + + +This is for the How owner of a product: the person who owns how the product is built and how +changes reach production. It is also for whoever writes that product's workflows. After reading +it you can run a change from an issue to production, behind a toggle that is off. You will know +which act each check, approval and cost belongs to, who may perform it, and what the record keeps +of it. + +**How settled this is.** Decided. That covers the step cards' readings, the landing's mechanics, +the identity port and its departures, where the record lives, the DORA computations and the +falsifiers. The points still open are listed in §19 and in "Not settled yet". None of it has run on +a real product yet. §0 names the two assumptions that would break it. Where this text and its +decision disagree, the decision governs ("Where this comes from"). + +**Where to start.** For the shape of the work, read §1 and §3. To set up a repository, read §6 to +§9 and §12. To measure the work, read §13, §14 and §18. + +**This arrangement is the SDLC, and it has no other name.** It is not Delivery. Delivery cares +about releases and a timeline, and the SDLC cares about neither. It is the pipeline that gets +value to production, so it is a new arrangement. + +**Scope.** A product repository that adopts the SDLC. This repository's own trunk keeps its own +rules, unchanged. + +**Upstream basis.** The coordinates, the address and the accountability argument are canon in the +principle repository, pinned at `v5.15.2` in [`graph/upstream.yaml`](../../graph/upstream.yaml): @@ -38,18 +48,18 @@ under that, and neither has been exercised: - **Identity filtering stops injection.** The SDLC reads only listed humans' comments made by hand as instructions. A model session still reads the repository, the What and the tool output, and any of them can carry text shaped like an instruction. Claude Code Action's own - security notes say its sanitising "new bypass techniques may emerge" (§12). + security notes say of its sanitising that "new bypass techniques may emerge" (§12). - **GitHub accepts the gates App's fast-forward.** GitHub must accept the App's fast-forward of main to a SHA whose checks passed on `ready/**`. Varve's ADR 0088 states the human form of this as its revisit condition, and records no outcome. The App form has run nowhere (§6, §15). -If either fails, the arrangement's force fails with it, and the ruled shape stays. +If either fails, the arrangement's force fails with it, and the decided shape stays. ## 1. Its place -*Ruled (Round 9, reading approved by Round 14):* the SDLC is a composite act within the PDLC -([`../pdlc/pdlc.md`](../pdlc/pdlc.md)). It is owned by the How owner (Round 5: "the owner of the -how also owns the process of getting changes to production"). +The SDLC is a composite act within the PDLC ([`../pdlc/pdlc.md`](../pdlc/pdlc.md)). It is owned +by the How owner, because the owner of the How also owns the process of getting changes to +production. **Inputs, read as ground; the SDLC owns none of them:** - **an issue**, by one of three entries (§16): @@ -58,7 +68,7 @@ how also owns the process of getting changes to production"). - for own-ground demand, framed by the How owner itself (oG), the one entry that starts inside the SDLC; - **the What**: [`what.md`](what.md), owned in the PDLC; -- **the product assurance**: the What owner's (Round 19). +- **the product assurance**: the What owner's. Implementation assurance is not an input: it is the How owner's own (§5). @@ -66,32 +76,33 @@ Implementation assurance is not an input: it is the How owner's own (§5). - **production state, dark**: o13, read by the PDLC's ready-for-users act; - **the occurrence record**: from which the PDLC computes the forecast (§13), with the DORA keys (§18); -- **telemetry of the product in use**: the How owner adds it (Round 16). Its presence is checked - before ready-for-users (§17). +- **telemetry of the product in use**: the How owner adds it. Its presence is checked before + ready-for-users (§17). No calendar input enters. The SDLC is given an order for new demand and a product assurance, and it returns a cadence and its DORA keys. ## 2. The axes -*Ruled (Round 2):* "Accept for now". They are used in the spec and revisited after the first -recorded issues. Declared before any position is read on them (method step 1): +The axes are accepted for now. They are used in this specification and revisited after the first +recorded issues (§19, O-3). They are declared before any position is read on them (method step 1): | Axis | Values | Why it is an axis | |---|---|---| | **Surface read** | issue thread · session branch · candidate · trunk · production | The decisions that govern an act differ by what it reads. A check on a session branch is feedback. The same check on a candidate is acceptance evidence. A rule about production governs only acts that read production | -| **Change locus** | what · how · ground · assurance, **as declared on the issue** (Rounds 3, 4) | Who accepts a change, and how deep o10 goes, depends on the coordinate it moves (`DDD-dec-114` P-8). Declared at o1 and read from the issue, so it is ground, not a lens the occupant applies. In the map an act's position is "the issue's declared locus". A recorded occurrence carries the concrete value | +| **Change locus** | what · how · ground · assurance, **as declared on the issue** | Who accepts a change, and how deep o10 goes, depends on the coordinate it moves (the PDLC's locus, `../pdlc/pdlc.md` §7). Declared at o1 and read from the issue, so it is ground, not a lens the occupant applies. In the map an act's position is "the issue's declared locus". A recorded occurrence carries the concrete value | | **Authority read** | none · base identity map · approval at head | The governing decisions of o11 and o12 are about authority. An act that reads none cannot escape an authority rule. One that reads the base map is governed by main's map, never the candidate's | -The occupant is not an axis and not part of any address (`DDD-ground-06`). Every act carries it -as a separate lens. +The occupant is not an axis and not part of any address. That rests on a claim of the principle +repository that is projected, not yet established. Every act carries the occupant as a separate +lens. ## 3. The act map, o1b to o13 As graph data: [`acts/acts.ttl`](acts/acts.ttl), with the PDLC's acts in -[`../pdlc/graph/acts.ttl`](../pdlc/graph/acts.ttl), one map in the `lc:` vocabulary. Validated -with SHACL as the What is (the regime of `DDD-dec-113` E-1). Every act has exactly one address, -one holding owner, a layer path beginning PDLC ▸ SDLC, and an occupant lens outside the address. +[`../pdlc/graph/acts.ttl`](../pdlc/graph/acts.ttl), one map in the `lc:` vocabulary. It is +validated with SHACL, under the same regime as the What. Every act has exactly one address, one +holding owner, a layer path beginning PDLC ▸ SDLC, and an occupant lens outside the address. Within an issue, dependencies are acyclic. Run `python3 applications/pdlc/graph/check.py`. The stream, in causal order. Each line is a state change, and each act follows the acts whose @@ -113,22 +124,22 @@ o12 fast-forward main PDLC▸SDLC▸land and run trunk · declared · o13 deploy, dark PDLC▸SDLC▸land and run production · declared · none → production, dark reads o12 ``` -o8 (the squash) and o14 (the release tag) were retired in Round 2, and their ids are not reused. +o8 (the squash) and o14 (the release tag) are retired, and their ids are not reused. -**Readings from the causal index** (the act map's; ruled, Round 28, R12): +**Three readings from the act map's causal index:** - **o7 versus o9.** o7 checks a branch head, and o10 approves a different SHA: the candidate's. So o7 is the session's feedback and o9 is acceptance evidence. Only o9 is in o10's ground. - **o5 has many occurrences.** o5 is one address with many occurrences, told apart by the time - index (`DDD-address-01`), so runs are comparable (`DDD-address-05`). + index, so runs are comparable. - **o11 reads earlier changes.** o11 reads the base identity map, which earlier How-one-layer-up changes produced in other top acts (§10). A change to the arrangement escapes at every pulling - occurrence its predicate does not cover (`DDD-address-03`). + occurrence its predicate does not cover. ## 4. Step cards One card per occurrence. The stores are the four of the SDLC projection: encoded constraint · CI check · human/model judgment · the unhandled case -([`README.md`](README.md), "How this relates to `core/`"). "Cost and relocation" names where the +([`README.md`](README.md), "How the general framework reads in software"). "Cost and relocation" names where the act's demand sits and where it could move. **o1b — plan the realisation.** @@ -155,8 +166,7 @@ act's demand sits and where it could move. - *Discharges:* the session's ground at start: the prompt (the issue body at a recorded position) and the bootstrap (the dispatcher's header). - *Store:* encoded. The files are committed before any other change (§13). -- *Cost and relocation:* trivial. It makes every later occurrence's ground recoverable - (`DDD-dec-52`). +- *Cost and relocation:* trivial. It makes every later occurrence's ground recoverable. **o5 — work run.** - *Discharges:* the occupant's realisation decisions within the plan: code, and How decisions @@ -179,15 +189,14 @@ act's demand sits and where it could move. **o9 — gate the candidate.** - *Discharges:* every required check passes on the one SHA `ready/` names. It runs once on - that SHA (Round 2). + that SHA. - *Store:* CI check. - *Cost and relocation:* one full gate run per candidate. Every acceptance criterion written at o1 in criterion form and encoded here is demand moved out of o10. **o10 — approve .** -- *Discharges:* acceptance of the candidate, including production acceptance (Round 2: "o10 - carries production acceptance"). Every user-visible change is behind a toggle that defaults - off (§7). +- *Discharges:* acceptance of the candidate, including production acceptance: o10 carries + production acceptance. Every user-visible change is behind a toggle that defaults off (§7). - *Store:* human judgment, by a holder of Approve for the issue's locus. - *Cost and relocation:* human judgment per candidate over everything o9 does not cover. It shrinks as o9 grows (§14). @@ -214,75 +223,73 @@ act's demand sits and where it could move. ## 5. The issue as the seam between the work and its occupant -*Ruled (Round 3, reading approved by Round 14):* the issue is the seam that separates the work -from its occupant. +The issue is the seam that separates the work from its occupant. - **Plan before allocation.** On the issue, the realisation is planned (o1b) before anyone is allocated to do it (o2b). - **Allocation is its own act.** Allocation chooses an AI session or a human. - **Same addresses for either occupant.** Every act from o4 to o13 has the same address whoever - occupies it. AI and human occurrences of one act can therefore be compared at full address - (`DDD-address-05`), and the record (§13) is the same for both. + occupies it. AI and human occurrences of one act can therefore be compared at full address, and + the record (§13) is the same for both. -**Whether o10 needs another person** (Round 13, reading approved by Round 14). There is no special -rule for human occupants. It follows from the occupant's own grants in the identity map: +**Whether o10 needs another person.** There is no special rule for human occupants. It follows +from the occupant's own grants in the identity map: - **A human who holds Approve for the issue's locus** may accept their own work. They still make the act: they comment "approve " on the issue, so the record holds an o10 occurrence. - **A human who does not hold it** needs a holder's approve . - **An agent never holds Approve.** An AI-occupied issue always needs a human holder. -**Implementation assurance sets whether self-acceptance is enough** (Round 19). The grant says -who may approve. Implementation assurance says whether self-acceptance is enough. +**Implementation assurance sets whether self-acceptance is enough.** The grant says who may +approve. Implementation assurance says whether self-acceptance is enough. -*Ruled (Round 19):* implementation assurance, "how sure are we the feature is implemented -correctly", is "the Assurance that the how must own". It is the How owner's, on the How's acts. -It is three things, declared per What element or per act as a How decision: +Implementation assurance, "how sure are we the feature is implemented correctly", is the +assurance the How must own. It is the How owner's, on the How's acts. It is three things, declared +per What element or per act as a How decision: | Part | What it sets | Where it bites | |---|---|---| | **Mechanical checks** | Which checks must hold on the candidate: conformance cases from the Deciders, bound wiring, accessibility, toggle defaults | o9 | | **o10's depth** | What the approver must judge beyond o9: the residual decisions the diff touches that nothing verified (§14) | o10 | -| **Independence** | Whether acceptance must come from someone other than the occupant. Two levels, ruled (Round 28, R3): **self**, where a holder of Approve for the locus may accept their own work; **independent**, where the approver is a holder of Approve who is neither the occupant nor a delegate the occupant holds, and o11 refuses otherwise | o10, judged at o11 | +| **Independence** | Whether acceptance must come from someone other than the occupant. Two levels: **self**, where a holder of Approve for the locus may accept their own work; **independent**, where the approver is a holder of Approve who is neither the occupant nor a delegate the occupant holds, and o11 refuses otherwise | o10, judged at o11 | -It is a How decision, anchored to the What element it governs (how.md: a constraint, anchored), -or declared on the issue under the How scope. o9 and o11 read it as ground. +It is a How decision, anchored to the What element it governs (in `how.md`'s terms, a constraint, +anchored), or declared on the issue under the How scope. o9 and o11 read it as ground. **It is not product assurance.** Product assurance, how sure we can be that users do the act we designed, is the What owner's. It is judged at ready-for-users, not at o9 to o11 -(`../pdlc/pdlc.md` §4). The first version of this section put the independence levels under "the -What owner's" assurance. Round 19 moved them to the How. +(`../pdlc/pdlc.md` §4). An earlier version of this section put the independence levels under the +What owner's assurance. They were moved to the How. -**The How owner tunes it down until the outcomes move** (Round 20). Lowering any part shows, if it -mattered, as change failure rate or failed ready-for-users verdicts (§18). "And if they don't -thats fine - then it was properly not giving any value." So the How owner may keep removing -verification while both outcomes hold still, and restores it when either moves. +**The How owner tunes it down until the outcomes move.** Lowering any part shows, if it +mattered, as change failure rate or failed ready-for-users verdicts (§18). If neither moves, that +is fine: the verification removed was not giving any value. So the How owner may keep +removing verification while both outcomes hold still, and restores it when either moves. **Relation to Varve's ADR 0088.** - **Varve's rule.** Varve makes "review … non-blocking for a human's own commits and blocking for an agent's". A human lands their own work with no approval at all, and main is not production there. -- **Here main is production** (Round 2), so a non-blocking path would put a human's unreviewed - change in production with no act on record. Round 13's rule keeps the human's freedom where - their grant gives it, but makes self-acceptance an act. A self-approving holder still writes - approve . -- **This repository's form.** This also matches `DDD-dec-109`'s form for this repository, where - every pull request needs the approval, because a commit pushed under a human's account cannot - be told from the human's own. +- **Here main is production**, so a non-blocking path would put a human's unreviewed change in + production with no act on record. The rule above keeps the human's freedom where their grant + gives it, but makes self-acceptance an act. A self-approving holder still writes approve . +- **This repository's form.** This also matches this repository's own trunk rule, where every + pull request needs the approval, because a commit pushed under a human's account cannot be told + from the human's own. **Falsifier.** A self-accepted change escapes at an implementation-assurance level that required independent acceptance, and the gate did not refuse it. ## 6. The landing -*Ruled (Round 1, as amended by Round 2):* takt's shape with Varve's force. +takt's shape, with Varve's force. - **The candidate.** `ready/` replaces `land/`, and it is a ref on the session's own head with no squash. - **Trailers and gate.** Per-commit trailers stay, and o9 runs once. -- **Approval and landing.** "your approve on the issue; gates App fast-forwards; no - READY_PUSHER PAT". -- **Precedence.** Round 1's words "squash before approval with trailers kept" are replaced by - Round 2's "Drop it". Both are recorded, and the later governs (`DDD-dec-115`). +- **Approval and landing.** The approval is "approve " on the issue; the gates App + fast-forwards main; there is no READY_PUSHER personal access token. +- **No squash.** An earlier ruling said to squash before approval, with the trailers kept. A + later ruling dropped the squash. Both are recorded, and the later governs. -**The mechanics** (ruled, Round 28, R22): +**The mechanics:** 1. **The session branch** carries the issue number. That is takt's shape: its development branches are issue-number branches, named `"[0-9]*"` in takt's `on_dev.yml`. Pushes to it run o7. @@ -296,8 +303,8 @@ independent acceptance, and the gate did not refuse it. 4. **o10.** A holder of Approve comments `approve ` on the issue (§5, §9). 5. **o11.** The judge runs main's script on main's map on `issue_comment` and on `workflow_run` (o9 completed). Both are triggers whose workflow file is main's. It does not run on a push to - `ready/**`, because a push runs the pushed commit's workflow, and a session can push. That - follows `DDD-dec-109`, which dropped Varve's `land/**` push trigger for the same reason. The + `ready/**`, because a push runs the pushed commit's workflow, and a session can push. This + repository's own trunk rule dropped Varve's `land/**` push trigger for the same reason. The judge posts `agent review` on the SHA as the gates App. 6. **o12.** When o9's required checks and o11 are green on the SHA, the gates App fast-forwards main to it (`git push origin :main`, or the refs API with `force: false`), then deletes @@ -313,18 +320,18 @@ independent acceptance, and the gate did not refuse it. without a long-lived personal credential whose power is "whatever that PAT's owner has". - **`pr-to-ready.yml` is removed.** It "collapses the commits in the PR's development branch into a single synthetic commit and pushes it to a ready/* branch" on any submitted review. There is - no pull request here: approval is on the issue. And there is no squash (Round 2). + no pull request here: approval is on the issue. And there is no squash. - **`on_semver.yml` is removed.** It deploys to production from a semver tag. Here main deploys - to production (Round 2: "o14 leaves"), and the SDLC carries no releases (Round 1). + to production (o14 is retired), and the SDLC carries no releases. **Where Varve's force changes.** In Varve the fast-forward is the maintainer's own push (ADR -0088), and no Varve ADR has the gates App push main. Round 1 rules that the App does. It is new, -and it is unexercised (§15). +0088), and no Varve ADR has the gates App push main. Here the App does. It is new, and it is +unexercised (§15). ## 7. Production -*Ruled (Round 2):* "Main deploys to prod": o13 goes to production, and o10 carries production -acceptance. *Ruled (Round 5):* a change lands dark behind a toggle. +Main deploys to production: o13 goes to production, and o10 carries production acceptance. A +change lands dark, behind a toggle. - **o13** deploys main to production on every push to main: takt's `on_main.yml`, pointed at production instead of stage. @@ -340,17 +347,17 @@ acceptance. *Ruled (Round 5):* a change lands dark behind a toggle. - Retiring is never a way to turn on: a retirement removes a toggle that is on, and never one that is off. - **Turning a toggle on is the PDLC's** (o16, the When owner's, refused without a ready-for-users - verdict; `DDD-dec-114` P-4). + verdict; `../pdlc/pdlc.md` §12). - **Its state lives outside the trunk.** If it were a commit to main, every turning-on would pass through o9 to o12, the How owner's arrangement. The When owner's delivery decision would then wait on the SDLC's cadence, and that would cross the seam the wrong way. - - **The store: a service the When owner uses, recording the traceability of each release** - (ruled, Round 28, R5: "must be a service that the when owners uses with PROV for when a - feature is released"; Round 30: "it doesnt mean the whole PROV-O it just means that we need - the traceability for the act"). The branch-file alternative is rejected. + - **The store: a service the When owner uses, recording the traceability of each release.** + This was decided otherwise than proposed: the proposal's alternative, a state file on a + branch nothing deploys from, is rejected. "Traceability" here means traceability for the act, + not the whole of the W3C PROV-O model. - **What the service does.** It holds each toggle's on state outside the trunk. The When owner turns a toggle on through it (o16). It refuses an o16 that reads no ready-for-users verdict - that found the change ready (`DDD-dec-114` P-4). + that found the change ready. - **What it records for each release:** - who released it: the When owner (`lc:decidedBy`); - what was released: the toggle (`lc:toggle`); @@ -364,23 +371,22 @@ acceptance. *Ruled (Round 5):* a change lands dark behind a toggle. ## 8. The issue as the only channel -The request: "All communication should be done on the issue and it should control the developer -session behind it." +All communication happens on the issue, and the issue controls the developer session behind it. - **Who may allocate.** Only the How owner, named in `.github/identities.json` (§9). - The dispatcher reads the `issues.labeled` event's `sender` and compares login and user id with the map's How-scope holders. - A label applied by anyone else is removed, and the refusal is recorded (o3, `lc:Refused`). - **The locus.** The issue carries exactly one `locus:` label (`locus:what`, `locus:how`, - `locus:ground`, `locus:assurance`), set at o1 (Round 3). An issue without one is refused at - dispatch. `locus:assurance` means product assurance. A change to implementation assurance is - `locus:how` (Round 19). + `locus:ground`, `locus:assurance`), set at o1. An issue without one is refused at dispatch. + `locus:assurance` means product assurance. A change to implementation assurance is + `locus:how`. - **The kind.** The issue carries exactly one `kind:` label (`kind:new`, `kind:owed`, `kind:own-ground`), set at its entry (§16). An issue without one is refused at dispatch. - **Which comments are instructions.** Comments that are all of these: 1. by a human in the map, matched by login and user id; 2. made by hand: GitHub records no App (`performed_via_github_app` is null); - 3. not edited (an edit is not attributed to whoever made it; `DDD-dec-109` rule 5). + 3. not edited (an edit is not attributed to whoever made it). Everything else is **data**: a comment by anyone not listed, by a bot, through any App (including the session's own), or edited. The dispatcher passes data to the session labelled @@ -398,18 +404,18 @@ session behind it." ## 9. Identity and authorisation -*Ruled (Round 1):* "Process: the identity map" (option text: "ADR 0087 in full: humans with -delegates, agents with a responsible human, the exempt list, and its three rules (DCO, acceptance -authority, agent review), plus the ledger exit"). +The process is Varve's identity map: ADR 0087 in full, meaning humans with delegates, agents with +a responsible human, the exempt list, its three rules (DCO, acceptance authority, agent review), +and the exit to the ledger. Varve's identity map (ADR 0087, with its amendments of 2026-10-06, -07 and -08, and ADR 0239's of 2026-11-06, read at Varve `81fba3d`) is ported whole as the product repository's -`.github/identities.json`. The whole section is ruled (Round 28, R21). +`.github/identities.json`. The port's departures are listed in §11. **The map.** - **Humans.** "an id, the name and the emails they commit and sign off with, their GitHub login, and **delegates**, the ids of other humans allowed to act for them" (ADR 0087). This port adds - the GitHub user id, as `DDD-dec-109` does. + the GitHub user id, as this repository's own trunk rule does. - **Agents.** "an id, a name, their author emails, and their **responsible** human" (ADR 0087). This port adds the trailer and the App ids (D-1, §11). - **Exempt.** "automation whose messages cannot be configured, by author name", and the list "is @@ -450,10 +456,10 @@ is the authority profile: ## 10. The second top act: changes to the SDLC itself -A change to the arrangement of the work itself is How, one layer up (Round 4's option text: "the -old 'arrangement' locus becomes How one layer up"). That covers the workflows, the dispatcher, -the judging script and the identity map. Its acts sit at the same addresses with a different -layer path, so the record tells the two apart. +A change to the arrangement of the work itself is How, one layer up: the old "arrangement" locus +became How one layer up. That covers the workflows, the dispatcher, the judging script and the +identity map. Its acts sit at the same addresses with a different layer path, so the record tells +the two apart. **The stricter rule.** It is accepted by the How owner under a stricter rule: - **Main judges.** Main's script judges, never the candidate's. @@ -461,28 +467,29 @@ layer path, so the record tells the two apart. the candidate's. A change to the judge or the map therefore cannot approve itself. Its effect starts at the -occurrences after it lands. This is `DDD-address-03`'s case: the change is pulled by every later -o11, and escapes at every pulling occurrence its predicate does not cover. +occurrences after it lands. This is the case one of this repository's address claims describes +(projected, not yet established): the change is pulled by every later o11, and escapes at every +pulling occurrence its predicate does not cover. ## 11. Departures from ADR 0087 -Each is flagged as a departure from ADR 0087. D-1 to D-8 are ruled (Round 28, R21), and so is D-9 (R1). +Each row is a departure from ADR 0087. All nine are decided. | # | Departure | Why | |---|---|---| -| D-1 | An agent is identified by its `Claude-Session` trailer, its author email, or the App it writes through (`performed_via_github_app`). Varve identifies an agent by author email only (`AgentByEmail`) | `DDD-dec-109`'s form. Sessions and humans may share an account, so the email alone cannot tell them apart | -| D-2 | An edited approval comment does not count. Varve reads the current body of an edited comment | `DDD-dec-109` rule 5. A session can edit a human's comment under the human's account | -| D-3 | Every candidate needs an o10 act. Varve requires one only when the change has an agent's commits | Main is production (Round 2), and self-acceptance is still an act (Round 13, §5) | -| D-4 | **Owners' scopes.** approve must come from a holder of the scope of the issue's locus: the What owner's for What and assurance, the How owner's for How, the ground's owner for ground. o2b must come from the How owner. Varve has one undifferentiated Approve | `DDD-dec-114` P-1, P-2 | -| D-5 | **The issue as a place for approve .** Varve reads pull request conversation comments. GitHub serves an issue's and a pull request's conversation comments from the same endpoint (`issues/{n}/comments`), so the judge reads the issue's | Round 1: "your approve on the issue" | -| D-6 | **Whose issue comments are instructions** (§8). Varve's map says nothing about instructions to a session | The request: the issue "should control the developer session behind it" | +| D-1 | An agent is identified by its `Claude-Session` trailer, its author email, or the App it writes through (`performed_via_github_app`). Varve identifies an agent by author email only (`AgentByEmail`) | This repository's own trunk rule takes this form. Sessions and humans may share an account, so the email alone cannot tell them apart | +| D-2 | An edited approval comment does not count. Varve reads the current body of an edited comment | As in this repository's own trunk rule: a session can edit a human's comment under the human's account | +| D-3 | Every candidate needs an o10 act. Varve requires one only when the change has an agent's commits | Main is production, and self-acceptance is still an act (§5) | +| D-4 | **Owners' scopes.** approve must come from a holder of the scope of the issue's locus: the What owner's for What and assurance, the How owner's for How, the ground's owner for ground. o2b must come from the How owner. Varve has one undifferentiated Approve | The PDLC's owners and its placement rule (`../pdlc/pdlc.md` §2, §6) | +| D-5 | **The issue as a place for approve .** Varve reads pull request conversation comments. GitHub serves an issue's and a pull request's conversation comments from the same endpoint (`issues/{n}/comments`), so the judge reads the issue's | The approval is "approve " on the issue | +| D-6 | **Whose issue comments are instructions** (§8). Varve's map says nothing about instructions to a session | The issue is to control the developer session behind it | | D-7 | A human's delegates change only on an issue that human framed, approved by that human's own approve | There are no pull requests, so Varve's "that human's own pull request" has nowhere to live | -| D-8 | The gates App fast-forwards main. In Varve it is the maintainer's push (ADR 0088) | Round 1 | -| D-9 | **ADR 0239's delegate, not ported as an approver.** In Varve the maintainer's on-machine delegate (a Claude Code session with his key) posts `approve (delegate)` under his login, and "No gate can tell the delegate's act from the maintainer's". Round 13 says an agent never holds Approve. **Tension:** porting 0239 whole would let a session approve under a human's login. Proposed: 0239's `Delegated-by` trailer is ported for commits, but a delegate's approval is not an o10 | Round 1 asks for 0087 "in full", and Round 13 forbids agent approval. **Ruled (Round 28, R1)**: as proposed | +| D-8 | The gates App fast-forwards main. In Varve it is the maintainer's push (ADR 0088) | Decided with the landing (§6) | +| D-9 | **ADR 0239's delegate, not ported as an approver.** In Varve the maintainer's on-machine delegate (a Claude Code session with his key) posts `approve (delegate)` under his login, and "No gate can tell the delegate's act from the maintainer's". An agent never holds Approve (§5), so porting 0239 whole would let a session approve under a human's login. Decided: 0239's `Delegated-by` trailer is ported for commits, but a delegate's approval is never an o10 | ADR 0087 is ported "in full", and an agent never holds Approve. This row reconciles the two | ## 12. The first ecosystem: Claude Code Action -*Ruled (Round 1):* "Claude Code Action". What follows is quoted from the documentation read on +The first ecosystem is Claude Code Action. What follows is quoted from the documentation read on 2026-11-07: - **[GA]** [code.claude.com/docs/en/github-actions.md](https://code.claude.com/docs/en/github-actions.md) - **[SEC]** [anthropics/claude-code-action `docs/security.md`](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md) @@ -520,7 +527,7 @@ Nothing here is stated from memory. Where the docs are silent, it says so. requests. - [USE]: `branch_prefix` defaults to `claude/`. - **The docs do not say** whether the issue number appears in the branch name. The dispatcher - must make it so (§6), and this is unverified. + must make it so (§6). This is not verified. - **The docs do not document a branch restriction.** A session may be able to push any branch. That is why `ready/` is only a candidate and main moves only by the App (§6). - **Signing.** [SEC]: "By default, commits made by Claude are unsigned." `use_commit_signing` or @@ -535,18 +542,16 @@ Nothing here is stated from memory. Where the docs are silent, it says so. - **The issue body is the prompt**, read at a recorded position: the id of the last comment read, 0 for the body alone. - **The dispatcher's header is the bootstrap.** It holds the issue number and position, the - declared locus, the demand kind, the implementation-assurance level, the occupant, the base SHA, the dispatcher's run id and - the identity map's SHA. + declared locus, the demand kind, the implementation-assurance level, the occupant, the base SHA, + the dispatcher's run id and the identity map's SHA. - **Both are committed by o4**, as `.sdlc/sessions//prompt.md` and `bootstrap.md`, before any - other change. This is the convention this repository keeps for its own sessions - (`DDD-dec-20`). + other change. This is the convention this repository keeps for its own sessions. - **Each run records what it read.** Each o5 occurrence records the issue position and branch - head it read (`DDD-dec-52`: a dependency on a verdict is a dependency on the declaration and - ground reading it was computed from). + head it read, because a dependency on a verdict is a dependency on the declaration and the + ground reading it was computed from. -**The occurrence record, from edition 1.** *Ruled (Round 2):* "Yes, from edition 1 -(Recommended)" (option text: "Graph data per occurrence; the optimisation overview is computed, -not argued"). +**The occurrence record, from edition 1.** The record is graph data per occurrence, kept from +the first edition. The optimisation overview is computed from it, not argued. **One record per occurrence.** Its shape is `lc:OccurrenceShape` in [`acts/shapes.ttl`](acts/shapes.ttl): @@ -556,15 +561,15 @@ not argued"). | Act site | `lc:atAct` | One act of the map | | Issue | `lc:issue` | | | Address | `lc:address` | Concrete. The change locus is the issue's declared value, never the map's placeholder. Surface and authority must equal the act site's (`lc:OccurrenceAgreesWithMapShape`) | -| Time index | `lc:after` | The earlier occurrences whose state changes are in its ground reading (`DDD-address-01`) | -| Ground read | `lc:readsIssuePosition`, `lc:readsHead` | `DDD-dec-52`. A head is a full 40-character SHA | +| Time index | `lc:after` | The earlier occurrences whose state changes are in its ground reading | +| Ground read | `lc:readsIssuePosition`, `lc:readsHead` | What the occurrence read. A head is a full 40-character SHA | | Occupant | `lc:occupant`, `lc:occupantKind` | Beside the address, never in it. o10 is never occupied by a model (`lc:ModelOccurrenceShape`) | | Cost | `lc:tokensIn`, `lc:tokensOut`, `lc:wallSeconds`, `lc:humanWaitSeconds` | Tokens are absent when the run did not report them, and never estimated. Wall time and human wait are always recorded | | Wall-clock start | `lc:startedAt` | For measurement only, never the time index | | Verdict | `lc:verdict` | passed · failed · refused · done | | Supplied locus (o6 only) | `lc:suppliedLocus` | What · How · code only (`lc:DirectionLocusShape`) | -**Where it is stored** (ruled, Round 28, R23). +**Where it is stored.** - **The branch.** An orphan branch `sdlc/record` in the product repository, one Turtle file per occurrence at `record//-.ttl`. It is written only by the dispatcher, with the gates App's token. @@ -573,21 +578,21 @@ not argued"). - **Why the App.** A session can push any branch it can name (§12), so a record a session could write is not a record. -The checker is `python3 applications/sdlc/acts/check.py`, over an illustrative record of one -invented issues, #101 (new) and #103 (owed, restoring #101's deployment) -([`acts/example-record.ttl`](acts/example-record.ttl)). It has 10 planted defects, plus one on a -DORA reading. +The checker is `python3 applications/sdlc/acts/check.py`. It runs over an illustrative record of +three invented issues ([`acts/example-record.ttl`](acts/example-record.ttl)): #101 (new), #103 +(owed, restoring #101's deployment) and #104 (own-ground; only its charter is recorded). It has +10 planted defects, plus one on a DORA reading. -**Two fields, from Round 22.** +**Two fields for the kinds of demand.** - **`lc:demandKind`.** Every occurrence carries its issue's kind: new, owed or own-ground. A missing kind is refused. - **`lc:restores`.** On an owed issue's o13, it names the earlier o13 it restores, with `lc:failureObservedAt`. **It is the SDLC's output across the seam.** The PDLC computes the forecast from it: throughput -from new-demand o13 occurrences, and flow time (ruled, Round 27: based on the Kanban cycle time; `../pdlc/pdlc.md` §1, `DDD-dec-114` P-14) from o2b to o13 (`../pdlc/pdlc.md` §1). The DORA keys -come from it too (§18). The kind lets the PDLC read the How owner's split of capacity across new, -owed and own-ground work. +from new-demand o13 occurrences, and flow time, from o2b to o13 (`../pdlc/pdlc.md` §1). Flow +time is based on the Kanban cycle time. The DORA keys come from the record too (§18). The kind +lets the PDLC read the How owner's split of capacity across new, owed and own-ground work. ## 14. Hotspots and levers @@ -599,8 +604,8 @@ Hotspots are where demand recurs at actor price. They are computed from the reco - **The classes.** o6 is classified by the locus of the decision it supplied (`lc:suppliedLocus`): - **What.** The specification was incomplete upstream, in the PDLC. Lever: the What owner receives it as an o0 contribution, a specification gap. The What-locus share of o6 is the - PDLC's meter of the What's completeness (Round 18; `../pdlc/pdlc.md` §3), read across the - How → What seam. + PDLC's meter of the What's completeness (`../pdlc/pdlc.md` §3), read across the How → What + seam. - **How.** The How was not declared, or the realisation plan (o1b) was incomplete. Lever: a How decision, or a fuller plan template. - **Code only.** The occupant's own judgment. Lever: the occupant's instructions and skills. @@ -636,7 +641,7 @@ computation. - **A change cannot authorise itself through the map.** Falsified by a candidate that changes `.github/identities.json` or the judge and is approved under its own version. - **A cost has an address.** Falsified by a cost that cannot be attached to any occurrence's - address: then the axes are wrong (Round 2: "revisit after the first recorded issues"). + address: then the axes are wrong, and are revisited after the first recorded issues. - **Self-acceptance is gated by implementation assurance.** Falsified by a self-accepted change at an implementation-assurance level that required independent acceptance, which the gate did not refuse (§5). @@ -644,17 +649,17 @@ computation. (`../pdlc/pdlc.md` §14). - **The outcomes see escapes.** Falsified by an escape that reaches users and that neither change failure rate nor the ready-for-users verdicts record. Then the outcome measures are blind, and - Round 20's guard on implementation assurance fails. Claude's (Round 20), ruled by Round 28 (R20). It - replaces Claude's Round 19 falsifier "implementation assurance falls, and neither measure - moves", which Emil withdrew. + the guard on implementation assurance (§5: tune it down until the outcomes move) fails. This + replaces an earlier falsifier, "implementation assurance falls, and neither measure moves", + which was withdrawn. - **Owed work needs no When.** Falsified by an implementation bug that needs the When owner's - ordering to get fixed (Round 22). + ordering to get fixed. ## 16. Owed and own-ground demand -*Ruled (Round 22):* "Adopt (Recommended)" (option text: "Bugs (owed) and debt (own-ground) enter -the SDLC directly, ordered by How, answered for by DORA; When sees only cadence"). The classifier: -"What owner (Recommended)". The kinds are defined in `../pdlc/pdlc.md` §9. +Bugs (owed demand) and debt (own-ground demand) enter the SDLC directly. The How owner orders +them, and answers for them by the DORA keys. The When owner sees them only as cadence. The What +owner is the classifier. The kinds are defined in `../pdlc/pdlc.md` §9. | Kind | Arrives from | Enters at | Ordered by | Answered for by | |---|---|---|---|---| @@ -678,7 +683,7 @@ The When owner sees owed and own-ground work only as cadence. **An owed fix is usually not dark.** It restores behaviour the What already promises, so it needs no new toggle and no o16. Its o13 records which deployment it restores. -**The guard, from both sides** (Round 20's guard applied to Round 22): +**The guard, from both sides** (the guard of §5, applied to the kinds of demand): - **too little own-ground work** shows as rising change failure rate, lead time and time to restore; - **too much** shows as falling cadence with no DORA improvement. @@ -689,25 +694,26 @@ The How owner answers for both. The ready-for-users verdict is the PDLC's (What owner, oR). The SDLC supplies two things to it: - the change in production, dark, with its verdicts; -- the telemetry each observation need asks for (Rounds 16, 17). +- the telemetry each observation need asks for. **The check.** Before the verdict, it is checked that the telemetry exists in production for each observation need that the change's What elements carry: the contract over `telemetry` facts -anchored to the need has a reporter, and its facts arrive. This is the H-9 pattern (`DDD-dec-60`, -now `DDD-dec-70`). A fact no reporter could supply is a reported gap, never "unknown". +anchored to the need has a reporter, and its facts arrive. This is the How's pattern for +measurement wiring, a contract over `telemetry` facts (`how.md` §4.2). A fact no reporter could +supply is a reported gap, never "unknown". **In the record.** The verdict records each need checked (`lc:checksObservation`, with `lc:telemetryPresent`). A verdict that finds the change ready while any checked need's telemetry is absent is refused (`lc:ReadyNeedsTelemetryShape`, `../pdlc/graph/shapes.ttl`). -**Until the What schema has observation needs** (successor items), the needs are named by IRI as +**Until the What schema has observation needs** (successor work), the needs are named by IRI as strings, and the check is the What owner's judgment. ## 18. The DORA keys: the How owner's answerability -*Ruled (Round 20):* "the DORA metrics are what the How needs in order to prove that it is doing -its job". They are the How owner's answerability, in upstream core/05 §5's sense: "the obligation -to produce the chain". They cross the How → What and How → When seams, in the record. +The DORA metrics are what the How needs in order to prove that it is doing its job. They are the +How owner's answerability, in canon's sense: the obligation to produce the chain. They cross the +How → What and How → When seams, in the record. | Key | What it proves | Computed from the record | Query | |---|---|---|---| @@ -736,27 +742,90 @@ computes all four over the illustrative record. Each equals the value worked by failure rate 0.5, time to restore 21600 s. Every reading conforms. The numbers are invented, and show the computation only. -**Beside the four keys: the forecast's spread** (Round 29). The PDLC forecasts new demand +**Beside the four keys: the forecast's spread.** The PDLC forecasts new demand probabilistically, by Monte Carlo over the record's daily new-demand throughput (`../pdlc/pdlc.md` §1). Its spread, worst minus best for an issue at a given rank, narrows as the How's throughput -steadies: "the better the how performs the smaller the different between worst and best will be". -So the spread is part of the How owner's answerability too, read across the How → When seam. It is +steadies: the better the How performs, the smaller the difference between worst and best. So the +spread is part of the How owner's answerability too, read across the How → When seam. It is computed by `../pdlc/graph/forecast.py`, never authored. **Which occurrences feed each key:** o4 and o13 (lead time); o13 (frequency); o13 with -`lc:restores` (failure rate, time to restore). The flow time (ruled, Round 27: based on the Kanban cycle time; `../pdlc/pdlc.md` §1, `DDD-dec-114` P-14) the PDLC's forecast uses, o2b to o13, -is a different interval (`../pdlc/pdlc.md` §1). +`lc:restores` (failure rate, time to restore). The flow time the PDLC's forecast uses, o2b to +o13, based on the Kanban cycle time, is a different interval (`../pdlc/pdlc.md` §1). ## 19. Open items +The item numbers are this document's own. `pdlc.md` §15 has its own O-numbers, and each item is +cited with its document. + | # | Item | Closes it | |---|---|---| -| O-1 | How a second ecosystem is added: the dispatcher's interface to an ecosystem, and what the record needs from each | A successor session, after edition 1 runs | -| O-2 | **The Copilot relay problem.** takt's Copilot path relies on pull requests ("GitHubs Agentic mode for Copilot relies on PRs both in spec-driven mode and Copilot reviews", takt `pr-to-ready.yml`), and on squashing them into `ready/`. The SDLC has neither, so a Copilot ecosystem would need its pull-request conversation relayed to the issue, or the issue relayed to it | A successor session | -| O-3 | When the axes are revisited: after the first recorded issues (Round 2) | Emil, on the record | -| O-4 | **Ruled (Round 28, R5; Round 30):** the toggle state store is a service the When owner uses, recording the traceability of each release (§7) | Closed | -| O-5 | **Ruled (Round 28, R1):** ADR 0239's `Delegated-by` trailer is ported for commits; a delegate's approval is never an o10 (D-9) | Closed | -| O-6 | **Ruled (Round 28, R3):** the implementation-assurance independence levels are *self* and *independent* (§5) | Closed | -| O-7 | **Ruled (Round 28, R6):** the issue closes at o13, with delivery recorded against the toggle | Closed | -| O-8 | **An act that accepts the realisation plan** (Round 31). o1b plans the realisation on the issue, but no act accepts the plan before work starts: o2b reads it, and o10 accepts only the candidate, after the work. product-cli's issue sessions have one (product-cli ADR-0014 D5, mindovermachine-dev/product-cli#171, *Proposed* there): a run posts a plan and stops, and works only after the principal approves that plan comment on the issue. It is cheap judgment placed before the expensive acts (o5, o6 and o10; §14). **Proposed, not ruled:** a plan-acceptance act between o1b and o4, by the How owner or a holder of its grant, whose verdict is in o4's ground reading. **In the record** (§13): one occurrence per acceptance or refusal of a plan, at surface issue, the declared locus, and authority base map, as for o2b; `lc:after` names the o1b occurrence it accepts; `lc:readsIssuePosition` is the plan comment's position; the verdict is passed or refused; its wall time and human wait are recorded. o4's `lc:after` names it, and the bootstrap header carries the accepted plan's position. Whether a model may occupy it, as `lc:ModelOccurrenceShape` forbids at o10, is open. **In the meters** (§14, §18): its human wait is a new cost line. Its effect is read on the o5 ↔ o6 hotspot, as the How-class o6 per issue ("the realisation plan was incomplete") falling on issues whose plan was accepted. A refused plan is demand caught before o5. Placed after o2b, its wait falls inside flow time (o2b to o13); placed before o2b, it does not. It falls inside DORA's lead time (o4 to o13) in neither place. Its act id is assigned when it is ruled. o8 and o14 are retired and not reused (§3) | Emil | -| O-9 | **Reconciling product-cli's issue sessions with the SDLC** (Round 31). product-cli specifies issue sessions on its own (product-cli ADR-0014, mindovermachine-dev/product-cli#171): a `claude` label by one hard-coded maintainer, plan approval on the issue, landing by a maintainer fast-forward under its ADR-0007, and a traceability record per session. The SDLC uses an allocation label checked against the identity map (o2b, o3; §9), `approve ` on the candidate (o10, o11), the gates App's fast-forward (o12), and a record per act occurrence (§13). Also different: there, the dispatched run writes the plan itself, so o1b is occupied after o2b and o3, where §5 plans before allocation. product-cli is the natural first adopter. product-cli either adopts the SDLC (its ADR-0014 superseded, or mapped onto the act map) or records its departures | Emil, then product-cli | +| O-1 | *(open)* How a second ecosystem is added: the dispatcher's interface to an ecosystem, and what the record needs from each | A successor session, after edition 1 runs | +| O-2 | *(open)* **The Copilot relay problem.** takt's Copilot path relies on pull requests ("GitHubs Agentic mode for Copilot relies on PRs both in spec-driven mode and Copilot reviews", takt `pr-to-ready.yml`), and on squashing them into `ready/`. The SDLC has neither, so a Copilot ecosystem would need its pull-request conversation relayed to the issue, or the issue relayed to it | A successor session | +| O-3 | *(open)* When the axes are revisited: after the first recorded issues (§2) | Emil, on the record | +| O-4 | Closed. The toggle state store is a service the When owner uses, recording the traceability of each release (§7) | Closed | +| O-5 | Closed. ADR 0239's `Delegated-by` trailer is ported for commits; a delegate's approval is never an o10 (D-9) | Closed | +| O-6 | Closed. The implementation-assurance independence levels are *self* and *independent* (§5) | Closed | +| O-7 | Closed. The issue closes at o13, with delivery recorded against the toggle | Closed | +| O-8 | *(open)* **An act that accepts the realisation plan.** o1b plans the realisation on the issue, but no act accepts the plan before work starts: o2b reads it, and o10 accepts only the candidate, after the work. product-cli's issue sessions have one (product-cli ADR-0014 D5, mindovermachine-dev/product-cli#171, *Proposed* there): a run posts a plan and stops, and works only after the principal approves that plan comment on the issue. It is cheap judgment placed before the expensive acts (o5, o6 and o10; §14). *(proposed, not yet ruled)* A plan-acceptance act between o1b and o4, by the How owner or a holder of its grant, whose verdict is in o4's ground reading. **In the record** (§13): one occurrence per acceptance or refusal of a plan, at surface issue, the declared locus, and authority base map, as for o2b; `lc:after` names the o1b occurrence it accepts; `lc:readsIssuePosition` is the plan comment's position; the verdict is passed or refused; its wall time and human wait are recorded. o4's `lc:after` names it, and the bootstrap header carries the accepted plan's position. *(open)* Whether a model may occupy it, as `lc:ModelOccurrenceShape` forbids at o10. **In the meters** (§14, §18): its human wait is a new cost line. Its effect is read on the o5 ↔ o6 hotspot, as the How-class o6 per issue ("the realisation plan was incomplete") falling on issues whose plan was accepted. A refused plan is demand caught before o5. Placed after o2b, its wait falls inside flow time (o2b to o13); placed before o2b, it does not. It falls inside DORA's lead time (o4 to o13) in neither place. Its act id is assigned when it is ruled. o8 and o14 are retired and not reused (§3) | Emil | +| O-9 | *(open)* **Reconciling product-cli's issue sessions with the SDLC.** product-cli specifies issue sessions on its own (product-cli ADR-0014, mindovermachine-dev/product-cli#171): a `claude` label by one hard-coded maintainer, plan approval on the issue, landing by a maintainer fast-forward under its ADR-0007, and a traceability record per session. The SDLC uses an allocation label checked against the identity map (o2b, o3; §9), `approve ` on the candidate (o10, o11), the gates App's fast-forward (o12), and a record per act occurrence (§13). Also different: there, the dispatched run writes the plan itself, so o1b is occupied after o2b and o3, where §5 plans before allocation. product-cli is the natural first adopter. product-cli either adopts the SDLC (its ADR-0014 superseded, or mapped onto the act map) or records its departures | Emil, then product-cli | + +--- + +## Not settled yet + +- **How a second ecosystem is added** (§19, O-1). Deciding it would fix the dispatcher's + interface and what the record needs from each ecosystem. +- **The Copilot relay** (§19, O-2). Deciding it would say whether a Copilot ecosystem relays its + pull-request conversation to the issue, or the issue to it. +- **When the axes are revisited** (§2, §19, O-3). Revisiting them could change the address every + occurrence is recorded at. +- **A plan-acceptance act** (§19, O-8). The act itself is *(proposed, not yet ruled)*. Whether a + model may occupy it is *(open)*. Ruling it would add an act between o1b and o4, a cost line in + the meters, and a field in the bootstrap header. +- **product-cli's issue sessions** (§19, O-9) *(open)*. Deciding it would either supersede or map + product-cli's ADR-0014 onto this act map, or record its departures. +- **Two facts the record does not yet show** (§0, §12, §15). Whether identity filtering stops + injection, and whether GitHub accepts the App's fast-forward, are untested. So is the + dispatcher's placing of the issue number in the branch name, which the Action's docs do not + cover. These are assumptions to be falsified, not rulings to be made. + +## Where this comes from + +This specification is the exposition of `DDD-dec-115`. Where they disagree, the decision governs +and this text is wrong. The rulings are verbatim in +[`meta/sessions/2026-11-07-sdlc-and-pdlc/rulings.md`](../../meta/sessions/2026-11-07-sdlc-and-pdlc/rulings.md). +The decision files the request (2026-11-06), Rounds 1 and 2, Round 13 as ruled by Round 14, and +Rounds 19, 20, 22 and 28, which entered by amendment before landing (Round 21's rule). Round 28 +ruled Claude's construction item by item (R1 to R30): the step cards' readings, the landing's +mechanics, the identity port and its departures, the record's place, the DORA computations and +the falsifiers. Round 30 ruled the reading of R5. Prose that no listed item covers is exposition, +and the decision governs it. + +| Section | Rests on | +|---|---| +| Opening: the name, not Delivery | Round 15: "It is the SDLC so its the same arrangement"; Round 1: "its not delivery because it doesnt care about releases or a timeline. Its the pipeline for getting value out to production - so its a new arrangement" | +| Opening: scope | This repository's own trunk: `DDD-dec-108` to `-110` | +| Upstream basis | `DDD-frame-01`, `DDD-frame-02`, `DDD-ground-06` (pinned at `v5.15.2`) | +| §1 Its place | Round 9, reading approved by Round 14 (composite act in the PDLC); Round 5: "the owner of the how also owns the process of getting changes to production"; Round 19 (product assurance the What owner's); Round 16 (telemetry added by the How owner) | +| §2 The axes | Round 2: "Accept for now"; Rounds 3 and 4 (the declared locus); `DDD-dec-114` P-8 (the locus); `DDD-ground-06` (the occupant outside the address) | +| §3 The act map | `DDD-dec-113` E-1 (the SHACL regime); Round 2 (o8 and o14 retired); Round 28 R12 (the three causal-index readings); `DDD-address-01` (time index), `DDD-address-05` (comparable at full address), `DDD-address-03` (escape at pulling occurrences) | +| §4 Step cards | Round 28 (the cards' readings); `DDD-dec-52` (o4: ground recoverable); Round 2 (o9 runs once; o10 carries production acceptance: "o10 carries production acceptance") | +| §5 The seam | Round 3, reading approved by Round 14; Round 13, reading approved by Round 14 (o10 and the occupant's grants); Round 19 ("the Assurance that the how must own"; the independence levels moved from the What owner to the How); Round 28 R3 (self and independent); Round 20 (tune down until the outcomes move: "And if they don't thats fine - then it was properly not giving any value"); `DDD-address-05`; `DDD-dec-109` (this repository's trunk rule); Varve ADR 0088 | +| §6 The landing | Round 1, as amended by Round 2 (takt's shape with Varve's force; Round 1's "squash before approval with trailers kept" replaced by Round 2's "Drop it"; "your approve on the issue; gates App fast-forwards; no READY_PUSHER PAT"); Round 28 R22 (the mechanics); `DDD-dec-109` (the `land/**` push trigger dropped); Round 1 (the App pushes; no releases) | +| §7 Production | Round 2: "Main deploys to prod"; Round 5 (dark behind a toggle); `DDD-dec-114` P-4 (o16 needs a ready-for-users verdict); Round 28 R5, ruled otherwise than proposed: "must be a service that the when owners uses with PROV for when a feature is released"; Round 30: "it doesnt mean the whole PROV-O it just means that we need the traceability for the act", withdrawing Claude's PROV-O reading | +| §8 The issue as the only channel | The request: "All communication should be done on the issue and it should control the developer session behind it"; Round 3 (the locus label at o1); Round 19 (`locus:how` for implementation assurance); `DDD-dec-109` rule 5 (edits are not attributed) | +| §9 Identity and authorisation | Round 1: "Process: the identity map" (option text: "ADR 0087 in full: humans with delegates, agents with a responsible human, the exempt list, and its three rules (DCO, acceptance authority, agent review), plus the ledger exit"); Round 28 R21 (the whole section); `DDD-dec-109` (the user id) | +| §10 The second top act | Round 4's option text: "the old 'arrangement' locus becomes How one layer up"; `DDD-address-03` | +| §11 Departures | Round 28 R21 (D-1 to D-8), Round 28 R1 (D-9); D-1, D-2: `DDD-dec-109` and its rule 5; D-3: Rounds 2 and 13; D-4: `DDD-dec-114` P-1, P-2; D-5, D-8: Round 1; D-9: Round 1 ("in full") and Round 13 | +| §12 Claude Code Action | Round 1: "Claude Code Action"; the three documents cited in the section, read on 2026-11-07 | +| §13 Records | `DDD-dec-20` (charter first); `DDD-dec-52` (a dependency on a verdict is a dependency on its declaration and ground reading); Round 2: "Yes, from edition 1 (Recommended)" (option text: "Graph data per occurrence; the optimisation overview is computed, not argued"); Round 28 R23 (the record's place); Round 22 (the two fields); Round 27 and `DDD-dec-114` P-14 (flow time, based on the Kanban cycle time); `DDD-address-01` | +| §14 Hotspots | Round 18 (the What-locus share of o6 as the PDLC's meter) | +| §15 Falsifiers | Round 28 (ruled); Round 2 ("revisit after the first recorded issues"); Round 20, ruled by Round 28 R20 (the outcomes see escapes; it replaces Claude's Round 19 falsifier, which Emil withdrew); Round 22 (owed work needs no When) | +| §16 Owed and own-ground | Round 22: "Adopt (Recommended)" (option text: "Bugs (owed) and debt (own-ground) enter the SDLC directly, ordered by How, answered for by DORA; When sees only cadence"); the classifier: "What owner (Recommended)"; Round 20's guard | +| §17 Telemetry | Rounds 16 and 17; the H-9 pattern, `DDD-dec-60`, now `DDD-dec-70` | +| §18 DORA keys | Round 20: "the DORA metrics are what the How needs in order to prove that it is doing its job"; upstream `core/05` §5 (answerability: "the obligation to produce the chain"); Round 29 (the forecast's spread: "the better the how performs the smaller the different between worst and best will be"); Round 27 and `DDD-dec-114` P-14 (flow time) | +| §19 Open items | O-3: Round 2; O-4: Round 28 R5 and Round 30; O-5: Round 28 R1; O-6: Round 28 R3; O-7: Round 28 R6; O-8 and O-9: Round 31 (open items only; nothing ruled; `DDD-dec-115` not amended) | + +Reformatted in place on 2026-11-10 by `meta/sessions/2026-11-09-applications-for-readers-redo/` +(`DDD-dec-94`, `DDD-dec-95`). The text it replaces is `84aa466:applications/sdlc/sdlc.md`. diff --git a/applications/sdlc/what.md b/applications/sdlc/what.md index b69555b..6b0c9a1 100644 --- a/applications/sdlc/what.md +++ b/applications/sdlc/what.md @@ -1,17 +1,33 @@ # The What — what a software application is and does -**Status: moved, 2026-10-28; not yet ratified.** This is the Product Framework's What (§3, and the -§6.3.1 wire protocol), moved into this repository by the session at -`meta/sessions/2026-10-28-product-framework-what-move/`. It is rewritten against the rulings -`DDD-dec-41` to `DDD-dec-63`, and against that session's Round 1. Emil ratifies by merging. The -source is github.com/Hafeok/product-framework: v1.10.0 at `c895652`, and v1.11.0 at `55c9281` for -§3.7 and the sections it threads. v1.11.0 was never merged in that repository. It is adopted here -by ruling (Round 1, Q-1). - -**Register.** *Ruled* cites a decision. `DDD-dec-64` holds the move's own choices, all ruled -(Rounds 2 and 5). `[PROPOSED]` marks what still waits for a ruling. `[OPEN]` is not settled here. Quoted text is the Product Framework's, cited -by its section ("PF §3.1"). It is quoted where the rulings leave it right, and rewritten where -they do not. + + +Use this when you are about to build, change or take over a piece of software and need one place +that says what it is and does, before anyone decides how to build it. After reading it you can +write down a product's What (its domains, its systems, and the behaviour and screens they carry), +change it by decision, and hand it to the people and agents who realise it, with an executable +oracle they can be checked against. + +**How settled this is.** Decided throughout, except one point marked *(open)* in §3.2.2. The +document was moved here from the Product Framework and rewritten against the rulings on the move. +It was ratified when its pull request merged. + +**How to read it.** To write or change a What, read §1, §2.1, §3, §4 and §5. Tool builders and +anyone implementing a checker or a conformance runner also need §2.2–§2.3 (identity and hashes), +§6 (the conformance wire) and §7 (encoding and the validation regime). Passages set as quotations +are the Product Framework's own words, kept where the rulings leave them right. Each section's +source is in "Where this comes from" at the end. + +**The worked example** is a small shop, Acme Shop: one domain, Ordering, and two systems, +`shop-api` and `shop-bff`. Customers place orders and refund them, and staff see every order. +`shop-bff` targets the web, as a GUI. **Companions.** - The vocabulary is [`what/ontology.ttl`](what/ontology.ttl), sdlc edition 1. @@ -31,41 +47,47 @@ they do not. ### 1.1 What the What is -The What is the opinionated specification of what a software application is and does -(`DDD-dec-41`). A system is not a coordinate of any act. It is ground and tolerance: "the -specification that says how a given piece of software should work". Read with `DDD-dec-42`, the -What as a whole is the software's declared ground, over which decisions are made, and the -tolerance each act must meet. Step 1 of the method reads its addresses off the What instead of -inventing them. +The What is the opinionated specification of what a software application is and does. A system +is not a coordinate of any act. It is ground and tolerance: "the specification that says how a +given piece of software should work". The What as a whole is the software's declared ground, over +which decisions are made, and the tolerance each act must meet. Step 1 of the method reads its +addresses off the What instead of inventing them. ### 1.2 Not here | Not here | Where it is | |---|---| -| The How: how the What is realised in code and deployments | [`how.md`](how.md) (`DDD-dec-55`…) | -| Delivery: features, releases, `done`, versions, direction, drift | retired (`DDD-dec-42`), not carried | -| Work units, seams, verification as a process (PF §5, §6 except §6.3.1) | retired (`DDD-dec-42`). The gate is Writ (`DDD-dec-54`) | -| Two Pillars conformance (PF §8) | dropped (`DDD-dec-42`). This repository consumes canon by pin | -| Data conformance (PF §13) | an add-on that reads the What, outside the framework (`DDD-dec-44`) | -| Force: the genesis grant, grants, acceptance, baselines, waivers | the genesis grant and the authority profile, in their own pull request after this one (Round 1, Q-4). Defined by `DDD-dec-46` and `DDD-dec-47`. *Update, 2026-11-02:* [`authority.md`](authority.md) (`DDD-dec-85`, `DDD-dec-86`) | -| Catalogues: components, tokens, strings | packages with their own genesis (`DDD-dec-57`) | -| The §4–§7 classes of the old `pf:` ontology | not carried in any namespace. The `pf:` namespace ends with this move (Round 1, Q-3) | +| The How: how the What is realised in code and deployments | [`how.md`](how.md) | +| Delivery: features, releases, `done`, versions, direction, drift | retired, not carried | +| Work units, seams, verification as a process | retired. The gate is Writ | +| Two Pillars conformance | dropped. This repository consumes canon by pin | +| Data conformance | an add-on that reads the What, outside the framework | +| Force: the genesis grant, grants, acceptance, baselines, waivers | the genesis grant and the authority profile, [`authority.md`](authority.md) | +| Catalogues: components, tokens, strings | packages with their own genesis | +| The §4–§7 classes of the old `pf:` ontology | not carried in any namespace. The `pf:` namespace ends with this move | ### 1.3 The rulings this rests on -| Ruling | Decision | -|---|---| -| Only the What moves. How and Delivery are retired. Home is here. Two Pillars is dropped | `DDD-dec-41`, `DDD-dec-42` | -| Every decision anchors to a What element or to the product. Every change of the What is a decision | `DDD-dec-42`, `DDD-dec-55` | -| Tools never change the What. Everything gathered is signed by a human principal | `DDD-dec-43` | -| The design system and content store are targets the What declares. Their catalogues are packages. The bindings are How | `DDD-dec-44`, `DDD-dec-57` | -| Reification and content coverage are obligations. Their content is decisions | `DDD-dec-45` | -| Authoring scopes are central, and instantiate the genesis grant over a product | `DDD-dec-44`, `DDD-dec-46` | -| Verdicts are computed, never stored. What is recorded is the declaration and the ground reading | `DDD-dec-49`, `DDD-dec-52` | -| §9 is cut down to one graph and stable identity. §10 becomes one conformance level | `DDD-dec-51` | -| The identity form | `DDD-dec-63` | -| §3.7 from v1.11.0. `SubjectKind` and `subject`. No `pf:` | Round 1, Q-1, Q-3, Q-5 | -| Edition 1 completed for its tag: the validation regime, violations and warnings, the five §3.4 and §3.7 checks, the description checks, a context mapping's direction, `acme-shop-5.ttl` | `DDD-dec-113` | +Each line is a rule this document applies. The decision behind each is in "Where this comes from". + +- Only the What moves here. How and Delivery are retired, and Two Pillars is dropped. This + repository is the What's home. +- Every decision anchors to a What element or to the product. Every change of the What is a + decision. +- Tools never change the What. Everything gathered is signed by a human principal. +- The design system and content store are targets the What declares. Their catalogues are + packages. The bindings are How. +- Reification and content coverage are obligations. Their content is decisions. +- Authoring scopes are central, and instantiate the genesis grant over a product. +- Verdicts are computed, never stored. What is recorded is the declaration and the ground + reading. +- Encoding is cut down to one graph and stable identity, and conformance to one level. +- The identity form is §2.2–§2.3. +- Subjects and authorization (§3.7) are taken from the Product Framework's v1.11.0, with + `SubjectKind` and `subject` for its actor terms, and no `pf:` term. +- Edition 1 is completed for its tag: the validation regime, violations and warnings, the five + §3.4 and §3.7 checks, the description checks, a context mapping's direction, and + `acme-shop-5.ttl`. --- @@ -73,25 +95,23 @@ inventing them. ### 2.1 The What changes only by decision -*Ruled (`DDD-dec-42`, `DDD-dec-43`).* - - **A decision is not a What element.** Each decision anchors to the What element it governs. - **Every change is a decision.** The What changes only through decisions anchored to the elements they change. A What element's current form is the result of the decisions anchored to it, and the What's history is its decision history. - **Gathered material is a proposal.** Tools and processes where parts of the What already live are valid sources. What they supply is a proposed change, and it enters the What only when a - human principal signs and accepts it (§8). + human principal signs and accepts it (§5). -*Ruled (Round 6, `DDD-dec-63` §8):* "a decision that creates elements anchors to the narrowest -element that exists at the position it is proposed and covers every element it creates; for a new -domain that is the product, which is the empty-What case and not a loophole". An element being -created does not yet exist at that position, so it is never its own creating decision's anchor. -This is How ruling 1 (`DDD-dec-55`) applied to the What. +**Anchoring a decision that creates elements.** "A decision that creates elements anchors to the +narrowest element that exists at the position it is proposed and covers every element it creates; +for a new domain that is the product, which is the empty-What case and not a loophole". An element +being created does not yet exist at that position, so it is never its own creating decision's +anchor. This is the How's anchor rule (how.md §3) applied to the What. ### 2.2 Identity -*Ruled (`DDD-dec-63`).* Nothing in an identity carries meaning. +Nothing in an identity carries meaning. - **The product.** The product IRI P is named in the product's genesis record and is stable across genesis transfer. P is itself the product node, the root of the What. @@ -108,31 +128,27 @@ This is How ruling 1 (`DDD-dec-55`) applied to the What. bindings, scope keys). A blank node belongs to exactly one description. **Containment.** The one containment edge is `sdlc:within`. Every element but the product node -is within exactly one element, and a subtree is `within*`. *Ruled (`DDD-dec-64`, P-2):* it -replaces the old `in_context`, `owns_domain`, `owns_system`, `system_of`, `journey_of` and -`bounded_by`, with no typed sub-properties. One edge makes "the subtree an anchor covers" a single -transitive walk, which is what the How's anchors read (how.md §3). The relation's name is carried -by the kind pair and enforced by the shapes. A reader that needs ownership versus attachment reads -the kinds. +is within exactly one element, and a subtree is `within*`. It replaces the old `in_context`, +`owns_domain`, `owns_system`, `system_of`, `journey_of` and `bounded_by`, with no typed +sub-properties. One edge makes "the subtree an anchor covers" a single transitive walk, which is +what the How's anchors read (how.md §3). The relation's name is carried by the kind pair and +enforced by the shapes. A reader that needs ownership versus attachment reads the kinds. **What is an element.** Interactions, fields (attributes, payload fields, view fields and claims), state annotations, content keys and scenarios are elements, not the blank nodes -product-cli made of some of them. *Ruled (`DDD-dec-64`, P-3):* anything a binding, a baseline, -`reads`, a scope key or a wire request names is an element with its own IRI. Blank nodes are only -where nothing names the node. A binding anchors to an interaction or a content key -(`DDD-dec-57`), a Decider reads a field, and a scope key compares two fields. The cost is that -adding a field is a What decision, and that is the correct cost: a wire contract changed. +product-cli made of some of them. Anything a binding, a baseline, `reads`, a scope key or a wire +request names is an element with its own IRI. Blank nodes are only where nothing names the node. +A binding anchors to an interaction or a content key, a Decider reads a field, and a scope key +compares two fields. The cost is that adding a field is a What decision, and that is the correct +cost: a wire contract changed. ### 2.3 Versions of the What -*Ruled (`DDD-dec-63` §6).* - - **The record.** A What-version is a `dpp/1` record. It pins every What decision in force and lists every element by IRI and element hash. - **The canonical form** is RDFC-1.0 over RDF 1.2 canonical N-Quads. Language tags are lowercase, and ECHAR and UCHAR escapes are as Varve writes them. A graph is canonicalised alone, never across - named graphs, and a triple term never holds a blank node (`DDD-dec-73`, Round 3, superseding - `DDD-dec-63`). + named graphs, and a triple term never holds a blank node. - **The element hash** is taken over the element's description, canonicalised on its own. - **The graph hash** is taken over the whole canonical graph. - **Authored logic.** A Decider's logic and a Projector's fold are artefacts carried by @@ -142,19 +158,18 @@ adding a field is a What decision, and that is the correct cost: a wire contract - **No force.** A What-version confers none. Force stays with the decisions it pins. **The ontology is never hashed.** A What graph's hash and its export cover the What graph alone, -never the edition's `ontology.ttl`, which a validation merges in (§7.2; `DDD-dec-113`, E-1). +never the edition's `ontology.ttl`, which a validation merges in (§7.2). The examples' hashes are in `what/vectors.json` (`acme-shop.ttl`, `what@1` to `what@3`), `what/vectors-4.json` (`acme-shop-4.ttl`, `what@4`) and `what/vectors-5.json` (`acme-shop-5.ttl`, `what@5`). The first two graphs are pinned by published records and never change. -`what/check.py` computes them with pyoxigraph, -which conforms to the canonical form on every vector in `what/canonical-form-vectors.json`. pyld -(URDNA2015 over RDF 1.1 N-Quads) does not conform: it keeps uppercase language tags and -mis-escapes controls. It serves only as a cross-check on graphs where it cannot diverge. A -conforming second implementation is successor item M-12 (`DDD-dec-73`): Varve's published vectors. -*Recorded (`DDD-dec-113`, E-3):* product-cli's slice 0 admission test found Varve -`0.1.0-preview.15` reproducing `acme-shop.ttl`'s graph hash. product-cli's element-hash vectors, -when they come, are a further cross-check, not a substitute. +`what/check.py` computes them with pyoxigraph, which conforms to the canonical form on every +vector in `what/canonical-form-vectors.json`. pyld (URDNA2015 over RDF 1.1 N-Quads) does not +conform: it keeps uppercase language tags and mis-escapes controls. It serves only as a +cross-check on graphs where it cannot diverge. A conforming second implementation, from Varve's +published vectors, is still to come. Recorded since: product-cli's slice 0 admission test found +Varve `0.1.0-preview.15` reproducing `acme-shop.ttl`'s graph hash. product-cli's element-hash +vectors, when they come, are a further cross-check, not a substitute. --- @@ -163,55 +178,57 @@ when they come, are a further cross-check, not a substitute. > The What is the specification every role reads and agrees on. It is organised by a three-level > ownership hierarchy that fixes *where each part lives* and *what is shared* — so that several > surfaces of one product draw on the same concepts and the same rules rather than re-deciding -> them. (PF §3) +> them. **Product → domains and systems.** The product owns one or more domains and one or more systems. A system references whole domains. It does not own them. > The dividing line is a single principle: **the domain owns meaning and rules; a system owns > surface and journey.** … The decisive test: **if two systems would disagree about it, it is -> system-level; if they must agree, it is domain-level.** (PF §3) +> system-level; if they must agree, it is domain-level.** In the graph, ownership is `sdlc:within`. Domains, systems, journeys and product-wide quality demands are within the product node. A system's use of a domain is `sdlc:referencesDomain`. +*In Acme Shop:* the domain Ordering and the systems `shop-api` and `shop-bff` are within the +product node, and each system references Ordering. + ### 3.0 The product and its boundary The product node "carries little of its own — a name and purpose — because its job is *ownership -and boundary*, not behaviour" (PF §3.0). Its product-wide concerns are: +and boundary*, not behaviour". Its product-wide concerns are: - product-level quality demands (§3.6); - journeys (§3.0.1); - product-wide content keys and declared targets, where a design system or content store serves every system. -The old "direction the product is moving toward (§7.3)" is not carried. Direction was Delivery -(`DDD-dec-42`). +The direction the product is moving toward is not carried. Direction was Delivery. > The product's boundary is exactly the set of domains and systems it owns. A second product is a > second root: it may *reference* a shared domain across a declared boundary (the Translation -> pattern, §3.2.0, is how its systems would communicate), but it does not absorb it. (PF §3.0) +> pattern, §3.2.0, is how its systems would communicate), but it does not absorb it. -A second product is a second genesis (`DDD-dec-46`), with its own P. +A second product is a second genesis, with its own P. #### 3.0.1 Journeys — flows that span systems A journey is "a **product-level, derived composition**: a declared path through single-system -flows, linked at their crossing points, where **every crossing is a Translation**" (PF §3.0.1). -It composes flows (`sdlc:composesFlow`) and crosses through automated triggers of Translation -patterns (`sdlc:crossesVia`). It owns nothing. The rules carry over unchanged: +flows, linked at their crossing points, where **every crossing is a Translation**". It composes +flows (`sdlc:composesFlow`) and crosses through automated triggers of Translation patterns +(`sdlc:crossesVia`). It owns nothing. The rules carry over unchanged: > - **Every crossing is a Translation, or it is a finding.** … > - **A journey references; it does not contain.** … Remove a journey and nothing else changes … -> - **Systems stay independent.** … (PF §3.0.1) +> - **Systems stay independent.** … -The old journey payoff named "value-anchoring (§6/§7)" and blast radius. Blast radius stays: it is -a traversal of `sdlc:within` and the edges below. Value-anchoring went with Delivery. +Blast radius stays: it is a traversal of `sdlc:within` and the edges below. Value-anchoring went +with Delivery. ### 3.1 The domain model — structure and reference data A domain is "the home of *meaning and rules*: the shared definition of **what concepts mean**, how -they relate, and **how they behave**" (PF §3.1). Within it sit: +they relate, and **how they behave**". Within it sit: - bounded contexts, and in them entities, value objects, relations and invariants; - the event model: commands, events, views, Deciders and Projectors (§3.2–§3.4); - subject kinds (§3.7). @@ -226,49 +243,52 @@ they relate, and **how they behave**" (PF §3.1). Within it sit: > *exactly its invariant-bearing state* — what its Deciders must read at decision time — and > everything else a screen wants is a Projector's output, not a stored field (§3.4). > - **Machine-readable, with a constraint language.** The model must be expressible as a graph -> with validatable shapes (RDF + SHACL is the reference; an equivalent is conformant). (PF §3.1) +> with validatable shapes (RDF + SHACL is the reference; an equivalent is conformant). -**Every box says what it is** (`DDD-dec-113`, E-7). An entity carries a business-language -`sdlc:definition`, and so do a bounded context and a subject kind. A domain states its -`sdlc:purpose`, as a system does. The bounded-context, subject-kind and domain checks are -warnings, because they were added after the examples were pinned (§7.2). +**Every box says what it is.** An entity carries a business-language `sdlc:definition`, and so do +a bounded context and a subject kind. A domain states its `sdlc:purpose`, as a system does. The +bounded-context, subject-kind and domain checks are warnings, because they were added after the +examples were pinned (§7.2). -**A context mapping has a direction** (`DDD-dec-113`, E-8). A mapping names the concepts it -connects with `sdlc:mapsTo`. When it also names one with `sdlc:mapsFrom`, it has exactly one -`mapsTo`, and it reads: the concept in `mapsFrom` corresponds to the concept in `mapsTo`, and -`mapsFrom`'s meaning is the source. A mapping without `mapsFrom` is a warning, "direction -undeclared". DDD's strategic pattern kinds (Customer–Supplier, Conformist, Anticorruption Layer -and the rest) are not What: they describe teams or realisation, not meaning, and belong in the How. +**A context mapping has a direction.** A mapping names the concepts it connects with +`sdlc:mapsTo`. When it also names one with `sdlc:mapsFrom`, it has exactly one `mapsTo`, and it +reads: the concept in `mapsFrom` corresponds to the concept in `mapsTo`, and `mapsFrom`'s meaning +is the source. A mapping without `mapsFrom` is a warning, "direction undeclared". DDD's strategic +pattern kinds (Customer–Supplier, Conformist, Anticorruption Layer and the rest) are not What: +they describe teams or realisation, not meaning, and belong in the How. An entity's attributes are `sdlc:Field` elements within it. Their types come from the single -datatype vocabulary: string, integer, number (`xsd:decimal`), boolean and date (PF §3.2.0). +datatype vocabulary: string, integer, number (`xsd:decimal`), boolean and date (the source's datatype list). + +*In Acme Shop:* the entity `Order`, in the Ordering bounded context, has the fields +`customer_id`, `paid_total` and `refunded_total`, and the invariants "order has lines", "refund by +owner" and "refund within paid". **Reference data is What.** > Some instance data is *constitutive* — the system's behaviour is undefined without it: the set > of valid shipping methods, the tax categories, the product taxonomy, the currencies accepted. -> This is **reference data**, and it lives in the What … (PF §3.1) +> This is **reference data**, and it lives in the What … The test carries over: "If changing a datum changes what the system *means* … it is reference -data … If it is just more rows of the same kind … it is production data" (PF §3.1). +data … If it is just more rows of the same kind … it is production data". -**Production data is not What, and data conformance is not framework.** PF §3.1's three callouts -(data conformance reading both ways, asserted continuously, the data-divergence rate) describe -§13's profile. *Ruled (`DDD-dec-44`):* that is "a value add on not something thats part of the -framework". An add-on that reads the What may check production data against its shapes. Nothing -here depends on one. +**Production data is not What, and data conformance is not framework.** The source's three +callouts on data conformance (reading both ways, asserted continuously, the data-divergence rate) +describe a data-conformance profile. That profile is "a value add on not something thats part of +the framework". An add-on that reads the What may check production data against its shapes. +Nothing here depends on one. ### 3.2 The event model — behaviour > The description of **what happens over time**, peer to the domain model, in the same graph. -> (PF §3.2) - **Built from domain-typed primitives.** "Behaviour may not reference structure that does not - exist" (PF §3.2): every event changes a real entity, and every command targets one. + exist": every event changes a real entity, and every command targets one. - **State space.** A view declares its state space: `present`, plus any of `loading`, `empty` and `failed` it can exhibit (`sdlc:hasState`). - **Proportional depth.** "Concepts with rich or historical behaviour get full event models; - simple create/read/update/delete concepts get a minimal one or none" (PF §3.2). + simple create/read/update/delete concepts get a minimal one or none". #### 3.2.0 Building blocks and patterns @@ -281,41 +301,42 @@ The four blocks are Trigger, Command, Event and View. They compose into four pat | **Automation** | `Event(s) → View → Trigger(automated) → Command → Event(s)` | | **Translation** | `Event(s) [system A] → View → Trigger(automated) → Command → Event(s) [system B]` | -Their rules carry over from PF §3.2.0: +Their rules carry over: - an automated trigger "contains no business logic"; - a Translation's read side "reads events from exactly one source system", and its write side may fan out. -**A trigger's source and its subject.** *Ruled (Round 1, Q-1 and Q-5).* A trigger has exactly -one **source** (`user`, `external`, `automated`). Its source is the **channel**, and it "stays -three-valued because the patterns are checked by it" (PF v1.11.0 §3.2.0). *Who* acts through the -channel is a separate edge, `sdlc:subject`: the subject kind the trigger acts as. v1.11.0 called -this edge `acts_as`. The subject's nature must be one the source admits: `user` → human, -`automated` → process, `external` → external. +**A trigger's source and its subject.** A trigger has exactly one **source** (`user`, +`external`, `automated`). Its source is the **channel**, and it "stays three-valued because the +patterns are checked by it". *Who* acts through the channel is a separate edge, `sdlc:subject`: +the subject kind the trigger acts as. The source called this edge `acts_as`. The subject's nature +must be one the source admits: `user` → human, `automated` → process, `external` → external. + +*In Acme Shop:* the triggers for Place order and Refund order have source `user` and act as the +subject kind Customer. **Payload schemas.** A Command or Event "MAY declare a **payload schema**: a list of named -fields, each optionally typed from the datatype vocabulary" (PF §3.2.0). "With one system a -payload is a private convenience; between two systems … it is a **public wire contract** and must -be authored, not guessed." Payload fields are `sdlc:Field` elements within their Command or Event. -Their order is an RDF list (`sdlc:fieldOrder`) inside the owner's description. +fields, each optionally typed from the datatype vocabulary". "With one system a payload is a +private convenience; between two systems … it is a **public wire contract** and must be authored, +not guessed." Payload fields are `sdlc:Field` elements within their Command or Event. Their order +is an RDF list (`sdlc:fieldOrder`) inside the owner's description. **Slices.** "A single pattern instance on the graph is a **slice**: the smallest coherent unit that -can be handed to an implementer" (PF §3.2.0). A flow is a chain of slices. The old identification -of a slice with a work unit (§5), and the containment *feature ⊇ flow ⊇ slice*, went with Delivery -and work units. +can be handed to an implementer". A flow is a chain of slices. The old identification of a slice +with a work unit, and the containment *feature ⊇ flow ⊇ slice*, went with Delivery and work +units. #### 3.2.1 The UI step — the What of a screen > A **UI step** is the point in a flow where a person sees something and acts. It is **What**, > owned by product and design: it says what a screen is *for* and *means*, never how it looks. -> (PF §3.2.1) **The split between meaning and widget is a type.** "A UI step may reference only **Abstract -Interaction Objects** … never a concrete control … from a design system" (PF §3.2.1). Each -interaction of a step is an `sdlc:Interaction` element within it, typed as exactly one AIO. It -surfaces one projection, offers one command, or enters one payload field. A concrete control is -not a What term at all. It is a design-system target's vocabulary (`DDD-dec-57`), and the -AIO-to-CIO choice is a How binding anchored to the interaction (§4). +Interaction Objects** … never a concrete control … from a design system". Each interaction of a +step is an `sdlc:Interaction` element within it, typed as exactly one AIO. It surfaces one +projection, offers one command, or enters one payload field. A concrete control is not a What +term at all. It is a design-system target's vocabulary, and the AIO-to-CIO choice is a How +binding anchored to the interaction (§4). **The buildable core.** These are derived, not authored: - **intent**, the marked debt (below); @@ -323,81 +344,79 @@ AIO-to-CIO choice is a How binding anchored to the interaction (§4). - the **actions available**: commands, through action or input AIOs; - the **transitions**: `navigate` edges of the page graph. -**Offered to.** *Ruled (Q-1, Q-5).* A step is **offered to** one or more human subject kinds -(`sdlc:offeredTo`). This is "system-level, because the admin tool and the shop offer the same -command to different principals" (PF v1.11.0 §3.2.1). +**Offered to.** A step is **offered to** one or more human subject kinds (`sdlc:offeredTo`). This +is "system-level, because the admin tool and the shop offer the same command to different +principals". **Modelled meaning.** These are checkable elements, not prose: - **emphasis**; - **projection states as meaning**: a step "may annotate only states the projection actually has … and it must give a meaning to *every* state the projection can be in, or explicitly - waive one with a reason" (PF §3.2.1). Each is an `sdlc:StateAnnotation` within the step; + waive one with a reason". Each is an `sdlc:StateAnnotation` within the step; - **accessibility obligations** (§3.2.3); - **content references**: a step references `sdlc:ContentKey` elements with a declared role, - "never written as literal strings in the UI step" (PF §3.2.1). The words are not the What's - (§4). + "never written as literal strings in the UI step". The words are not the What's (§4). **Intent is specification debt.** This is carried as written: > **Whatever intent was used to decide must be promoted into the model.** … Intent therefore > shrinks monotonically toward a pure statement of purpose … the **intent-reliance rate** — how > often realising a screen required consulting intent to settle something the model did not -> determine. (PF §3.2.1) +> determine. -The rate is a What-side signal, and stays one. The old list of what intent is promoted into -included "a missing reification rule (§4.5)". Under `DDD-dec-45` the reification rule is not the -What's. What is promoted into the What is the missing AIO, context of use, or meaning -declaration. A missing reification is a missing binding, which is debt on the How's coverage -(how.md §8). +The rate is a What-side signal, and stays one. The source's list of what intent is promoted into +included "a missing reification rule". The reification rule is not the What's. What is promoted +into the What is the missing AIO, context of use, or meaning declaration. A missing reification +is a missing binding, which is debt on the How's coverage (how.md §8). #### 3.2.2 Abstract Interaction Objects and the context of use > **An AIO is meaning, not a widget.** `single-select` means "choose exactly one from a set"; it is > *not* a dropdown, a radio group, or a segmented control — those are the concrete forms it can -> take. (PF §3.2.2) +> take. **The base set.** Ten AIOs are framework vocabulary (`sdlc:aioTriggerAction` … `sdlc:aioEdit`), not What elements: `trigger-action`, `single-select`, `multi-select`, `text-entry`, `numeric-entry`, `date-entry`, `display-value`, `display-collection`, `navigate` and `edit`. "Input AIOs derive their shape from the domain model": an input interaction enters a command -payload field, whose type and allowed values come from the domain (PF §3.2.2). `[OPEN]` Whether -an adopter may register AIOs, as PF §3.2.2 allowed, is how.md §6's open question. Under this -ontology a registered AIO would be a vocabulary change in this repository, not a What element. +payload field, whose type and allowed values come from the domain. *(open)* Whether an adopter +may register AIOs, as the source allowed, is how.md §6's open question. Under this ontology a +registered AIO would be a vocabulary change in this repository, not a What element. **The context of use is a declared model.** A system declares its contexts of use (`sdlc:ContextOfUse` elements, each a value of one dimension: platform, form factor, modality, -terminal capability). "Platform is a context dimension like any other" (PF §3.2.2). "iOS, Android, -or both" is which platform contexts a system targets. "Context-of-use is What-side knowledge … -but it carries no realisation." It is what the How's bindings are written against (§4). +terminal capability). "Platform is a context dimension like any other". "iOS, Android, or both" is +which platform contexts a system targets. "Context-of-use is What-side knowledge … but it carries +no realisation." It is what the How's bindings are written against (§4). **The interaction class gates the other dimensions.** GUI brings form factor and pointer or touch. TUI brings terminal capabilities and rules form factor out. A system declares the classes -it targets (`sdlc:targetsClass`). "The AIO vocabulary itself does **not** change across classes" -(PF §3.2.2). +it targets (`sdlc:targetsClass`). "The AIO vocabulary itself does **not** change across classes". + +*In Acme Shop:* `shop-bff` targets the class GUI and one context of use, `web`, on the platform +dimension. #### 3.2.3 Accessibility as ingested criteria, not prose > The normative reference is **WCAG 2.2**, version-pinned; an instance ingests its structure > from the W3C machine-readable source … These are referenceable nodes, not authored text. -> (PF §3.2.3) A step or an interaction `sdlc:mustSatisfy` a criterion by its W3C IRI. Criteria are not What -elements, and nothing is re-minted under P (`DDD-dec-63` §4). +elements, and nothing is re-minted under P. - **Inherited and added.** Obligations are inherited from the AIOs a step uses, plus the criteria the step adds. The step's obligation is the computed union. - **Verification type.** Each criterion carries one: machine, assisted or manual. "A conformant accessibility verdict therefore states a **conformance level and its basis** … and never a bare - 'accessible: true'" (PF §3.2.3). + 'accessible: true'". - **Attestations.** A manual criterion is discharged by an attestation, "a dated, attributed - assertion that a named criterion was evaluated and met" (PF §3.2.3). Under this repository's - rulings an attestation is a signed record and a ground reading. It is not a stored verdict - (`DDD-dec-52`). How it is held is the authority profile's (Q-4). + assertion that a named criterion was evaluated and met". Here an attestation is a signed record + and a ground reading. It is not a stored verdict. How it is held is the authority profile's. #### 3.2.4 The page graph — navigation as one graph > Navigation is not a separate "shell" layered above the screens; it is **one graph whose nodes -> are pages (UI steps) and whose edges are `navigate` transitions.** (PF §3.2.4) +> are pages (UI steps) and whose edges are `navigate` transitions.** - **Flows.** A flow is a named, connected subgraph with an entry page (`sdlc:Flow`, `sdlc:entryPage`, `sdlc:inFlow`). @@ -416,20 +435,23 @@ A system is a surface: one way the product is used. It carries: - the targets it declares (§4). It owns its page graph, its flows, its UI steps and its triggers. "A flow belongs to exactly one -system; the behaviour it invokes is shared by all systems referencing that domain" (PF §3.2.5). +system; the behaviour it invokes is shared by all systems referencing that domain". System-specific quality demands are within the system (§3.6). > **System identity is What; deployment identity is How.** … The What says "Acme Shop is a > consumer e-commerce application, referencing the Ordering and Catalog domains, targeting iOS, > Android, and web"; the How says "iOS bundle `com.acme.shop`, web served at `shop.acme.com` from -> these runtimes." (PF §3.2.5) +> these runtimes." + +That quotation is the source's illustration, not the worked example, whose one domain is +Ordering and whose `shop-bff` targets the web. The How's side of this line is how.md §4.2: a target declaration binds a deployable unit to the system, and a contract states what the unit must satisfy. ### 3.3 The Decider — the executable form of behaviour -*Ruled (Q-1): the signature from v1.11.0.* +The signature is the source's v1.11.0 one: ``` decide(state, command, subject) -> Accepted[events] | Rejected[invariant] @@ -438,11 +460,11 @@ evolve(state, event) -> state > In business terms. A Decider is where the **business rules** live — but it is more than the > rules. The rules are its *rejections* … and a Decider also says *what results* when a command -> is allowed (the events it emits). (PF §3.3) +> is allowed (the events it emits). **The subject is an input, not a payload field.** The subject "is the authenticated principal issuing the command — its actor kind and its claims — **supplied by the system's authentication, -never by the caller**" (PF v1.11.0 §3.3). Here it is the subject kind and its claims (Q-5). +never by the caller**". Here it is the subject kind and its claims. **The signature is derived, and only the logic is authored.** - The Decider decides for one aggregate. @@ -454,30 +476,32 @@ never by the caller**" (PF v1.11.0 §3.3). Here it is the subject kind and its c The logic is an artefact held by digest (`sdlc:logic`, §2.3). +*In Acme Shop:* the Decider `Order` decides for the entity `Order`, handles Place order and +Refund order, and rejects with the entity's three invariants. + **The conformance rules.** - **No foreign commands.** - **Command coverage.** - **Output-alphabet containment.** -- **Actor coverage**, here subject coverage: "for every (command, actor kind) pair in its +- **Subject coverage** (the source's actor coverage): "for every (command, actor kind) pair in its alphabets, the Decider either accepts the command for that kind or has a reachable rejection - over its claims, and a scenario per pair shows which" (PF v1.11.0 §3.3). + over its claims, and a scenario per pair shows which". **The wire scalar alphabet.** Values are `boolean`, 64-bit signed `integer` and `string`. A `number` or `date` field "travels **as a string** on the conformance wire … until the alphabet is extended". "One list-valued position is admitted now, and only one: a **set-valued claim** … -travels in the actor block of a conformance request as an array of wire scalars" (PF v1.11.0 -§3.3). Here that block is the subject block (§6). +travels in the actor block of a conformance request as an array of wire scalars". Here that block +is the subject block (§6). **Scenarios.** "Before realisation, the Decider is *simulated* against scenarios drawn from the -flows (a flow gives a *given* of prior events, a *when* command, and a *then* of expected events)" -(PF §3.3). A scenario is an `sdlc:Scenario` element within its Decider or Projector. Its given -and its expected emissions are RDF lists inside its description. Its *when* names the subject it -is issued as. +flows (a flow gives a *given* of prior events, a *when* command, and a *then* of expected events)". +A scenario is an `sdlc:Scenario` element within its Decider or Projector. Its given and its +expected emissions are RDF lists inside its description. Its *when* names the subject it is +issued as. -**What this imposes on the How.** PF §3.3 said that the realised code "must keep its decision -logic in a pure core", stated "as a contract (§4.2)". Under the rulings, that is a How binding -over Deciders (how.md, `PURE@1`). The What states only the oracle: the Decider, its logic and its -scenarios. +**What this imposes on the How.** The source said that the realised code "must keep its decision +logic in a pure core", stated as a contract. Here that is a How binding over Deciders (how.md, +`PURE@1`). The What states only the oracle: the Decider, its logic and its scenarios. ### 3.4 The Projector — the executable form of a read model @@ -485,7 +509,7 @@ scenarios. project(state, event) -> state -- the read-model fold ``` -The Projector is "**symmetric to the Decider in every respect**" (PF §3.4): +The Projector is "**symmetric to the Decider in every respect**": - its signature is derived; - only the fold is authored; - it is simulated before realisation; @@ -496,80 +520,81 @@ Its rules are **no foreign events**, **event coverage** and **output containment > **The actor is not an input to the fold.** … `project` keeps its signature — no actor argument > — and **one fold serves every actor**; the scope is a selection applied at the seam over the > fold's output. … a Projector over a scoped View declares the field(s) its fold is **keyed by**, -> and every field a scope key reads must be one of them. (PF v1.11.0 §3.4) +> and every field a scope key reads must be one of them. -`sdlc:keyedBy` names those fields. "Actor" there reads "subject" here (Q-5). +`sdlc:keyedBy` names those fields. "Actor" there reads "subject" here. **State justification and Decider justification.** Both carry over as written. "A field belongs on an aggregate if and only if some Decider reads it", and "a Decider must have **at least one -reachable rejection**" (PF §3.4). Each is a finding that points at an unmodelled invariant. The -v1.11.0 twin, **claim justification**, joins them (§3.7). These are What-side checks, and all -are in `what/shapes.ttl` as warnings (§7.2): Decider justification on `DeciderShape`, state +reachable rejection**". Each is a finding that points at an unmodelled invariant. Their v1.11.0 +twin, **claim justification**, joins them (§3.7). These are What-side checks, and all are in +`what/shapes.ttl` as warnings (§7.2): Decider justification on `DeciderShape`, state justification as `StateJustificationShape`, and the Projector's event coverage as -`ProjectorEventCoverageShape` (`DDD-dec-113`, E-4). +`ProjectorEventCoverageShape`. ### 3.5 Named-algorithm primitives -*Ruled (`DDD-dec-64`, P-5):* "Named-algorithm primitives", with no subtitle. "Floor" is canon's, -so PF's old subtitle, "the Polanyi floor", is not carried. +Some computation is named rather than derived: a standard or algorithm the What refers to instead +of specifying step by step. The section has no subtitle. "Floor" is canon's word, so the source's +old subtitle, "the Polanyi floor", is not carried. > A computation is mechanically derivable from spec **exactly to the degree its variability is -> declared data over a generic interpreter.** (PF §3.5) +> declared data over a generic interpreter.** A named-algorithm primitive (`sdlc:NamedAlgorithm`) is specified by **reference** (the algorithm or standard it implements), by an **I/O contract** in the domain's terms, and by an **oracle** of reference input and output pairs, held by digest. It is "explicitly **exempt from derivation and -from behavioural simulation**" (PF §3.5). PF checked it by "oracle conformance (§6.3)". Under the -rulings, that check is a How binding over primitives, and the What carries the oracle. "An -undisclosed algorithm masquerading as a mechanical projection is the dishonesty the -[primitive] exists to prevent" (PF §3.5). +from behavioural simulation**". The source checked it by oracle conformance. Here that check is a +How binding over primitives, and the What carries the oracle. "An undisclosed algorithm +masquerading as a mechanical projection is the dishonesty the [primitive] exists to prevent". ### 3.6 Quality demands — the non-functional, made checkable > **a quality demand is never prose.** … Admitted into the spec, a quality demand is one of -> exactly **two kinds**, distinguished by *how it is checked*. (PF §3.6) +> exactly **two kinds**, distinguished by *how it is checked*. | Kind | Is | Its How side | |---|---|---| -| **Runtime bound** (`sdlc:RuntimeBound`) | a bound measured against telemetry: latency, throughput, capacity, uptime. It declares its bound and its measured source | the measurement wiring is a contract over `telemetry` facts, anchored to the bound (how.md §4.2, H-9) | +| **Runtime bound** (`sdlc:RuntimeBound`) | a bound measured against telemetry: latency, throughput, capacity, uptime. It declares its bound and its measured source | the measurement wiring is a contract over `telemetry` facts, anchored to the bound (how.md §4.2) | | **Architectural constraint** (`sdlc:ArchitecturalConstraint`) | a constraint on the realisation: residency, security posture, fault-tolerance topology | a contract anchored to it, held at build time (how.md §4.2; `RESID@1`) | > **The test that keeps demands honest.** … *is it checked by measuring production, or by > inspecting the realisation?* … If *neither* can confirm it, it is not a quality demand yet — it -> is prose, and prose is debt. (PF §3.6) +> is prose, and prose is debt. **Demands are located, not listed.** A demand is within the element it scopes: - the product, for product-wide demands such as a residency rule binding every system; - a system; - a flow, a step, a Decider or a Projector. -PF §3.6 said Kind 2 "binds to the **How** (§4)". Here, the How's contract anchors to the demand, -and the What holds only the demand. +The source said the second kind "binds to the **How**". Here, the How's contract anchors to the +demand, and the What holds only the demand. ### 3.7 Subjects and authorization — who may act -*Ruled (Round 1, Q-1 and Q-5).* PF v1.11.0 §3.7 is adopted, with **subject kind** for its -"actor kind" and **subject** for its `acts_as`. Of the three available words, "actor" is canon's, -"principal" is authority's, and "subject" is what OIDC calls the authenticated identity whose -claims these are. The claims are the point. +The source's v1.11.0 section is adopted, with **subject kind** for its "actor kind" and +**subject** for its `acts_as`. Of the three available words, "actor" is canon's, "principal" is +authority's, and "subject" is what OIDC calls the authenticated identity whose claims these are. +The claims are the point. -**Two authorities, never one.** v1.11.0 makes this split, and it fits this repository's rulings +**Two authorities, never one.** The source makes this split, and it fits this repository's rulings exactly: > This section is about the *product's* authorization: who may act **in the product being > specified** (a customer cancelling an order). It is not about authority **over the > specification** — who may accept a decision about the product, sign a version, or ratify an > act. That second authority belongs to whatever governance tooling holds the specification, -> never to the specification's own vocabulary. (PF v1.11.0 §3.7) +> never to the specification's own vocabulary. -Here, the second authority is the genesis grant and the authority profile (`DDD-dec-46`, -`DDD-dec-47`). A subject kind is never a grant. A grant is never a subject kind. A specification's -author does not become a subject of the product. +Here, the second authority is the genesis grant and the authority profile. A subject kind is never +a grant. A grant is never a subject kind. A specification's author does not become a subject of +the product. **Authentication is How.** Which identity provider authenticates a subject, how a session is held, and what a token looks like are realisation. The binding of a subject kind to a provider is declared per deployment. In the How it is a contract over the deployable unit (how.md §4.2). The -What never names a provider. v1.11.0's **provider coverage** check therefore belongs to the How. +What never names a provider. The source's **provider coverage** check therefore belongs to the +How. **Authorization splits by the framework's own test.** @@ -583,12 +608,12 @@ What never names a provider. v1.11.0's **provider coverage** check therefore bel **The subject kind.** - **Nature.** It has exactly one: `human` (acts through a UI step), `process` (through an automated trigger) or `external` (an outside system through an API call). Nature is a closed - vocabulary, "*not* a role" (PF v1.11.0 §3.7). + vocabulary, "*not* a role". - **Claims.** It carries typed claims. A claim may be set-valued, and may draw its values from reference data. - **Role or kind?** "The framework ships **no actor kinds and no roles**." One test decides between a kind and a claim value: "if a surface is offered to it, it is an actor kind; if only a - rule reads it, it is a claim" (PF v1.11.0 §3.7). + rule reads it, it is a claim". - **Delegation** (an external system acting for a human) is not modelled. Until it is, it is an external subject kind whose claims carry the delegating principal. @@ -599,21 +624,25 @@ What never names a provider. v1.11.0's **provider coverage** check therefore bel - **Defaults.** A rule with no keys is a declared "every row". A subject kind with no rule on a scoped View sees nothing: deny by default. - **The fold is unchanged.** The scope is applied at the seam, over the fold's output. "Every key - field is a key of the fold" (PF v1.11.0 §3.7). + field is a key of the fold". - **Cross-row aggregates** are folded keyed by the scoping dimension. - **A disjunctive scope** ("mine, or shared with me") is modelled as a recorded fact and a View keyed on it. +*In Acme Shop:* the subject kinds are Customer and Staff, both within the Ordering domain. The +View `Order summary` is scoped by two rules, "customers see their own orders" and "staff see +every order". + **The checks.** They bind once a What declares at least one subject kind. A What that declares -none has authorization that is "*unstated*, not *absent*" (PF v1.11.0 §3.7). +none has authorization that is "*unstated*, not *absent*". | Check | Twin of | Holds | |---|---|---| -| **Subject coverage** (v1.11.0's actor coverage) | command coverage | every step that offers or surfaces something is offered to at least one human subject kind. Every automated or external trigger acts as one. Every (command, subject kind) pair has a scenario showing acceptance or a reachable rejection | +| **Subject coverage** (the source's actor coverage) | command coverage | every step that offers or surfaces something is offered to at least one human subject kind. Every automated or external trigger acts as one. Every (command, subject kind) pair has a scenario showing acceptance or a reachable rejection | | **Scope coverage** | — | every surfaced View is public, or has a rule for every subject kind its step is offered to. Every claim a key reads belongs to the rule's subject kind. Every compared view field is a key of the fold | | **Claim justification** | state justification | a claim no Decider reads and no scope uses is dead, or the trace of an unmodelled authorization rule | -`what/shapes.ttl` carries all of it (`DDD-dec-113`, E-4): +`what/shapes.ttl` carries all of it: - subject coverage: the step half (`SurfaceCoverageShape`), automated and external triggers (`TriggerSubjectCoverageShape`), and a scenario per (command, subject kind) pair (`PairScenarioCoverageShape`); @@ -630,8 +659,8 @@ malformed element (§7.2). ### 4.1 The What declares its targets -*Ruled (`DDD-dec-57`).* A design system and a content store are targets the What declares, -"exactly as it declares iOS". A system, or the product for every system, declares: +A design system and a content store are targets the What declares, "exactly as it declares iOS". +A system, or the product for every system, declares: - its **platform contexts** and **interaction classes** (§3.2.2); - a **design system** at an edition: an `sdlc:DeclaredTarget` with `targetKind` `design-system` @@ -639,20 +668,20 @@ malformed element (§7.2). - a **content store** and the **locales** it serves: an `sdlc:DeclaredTarget` with `targetKind` `content-store`, its edition, and one `sdlc:locale` per BCP 47 tag. -*Ruled (`DDD-dec-64`, P-4):* one kind, `sdlc:DeclaredTarget`, for both. Its edition reference may -not resolve from this product. That is the protocol's "not reachable", and it is Writ's `explain` -to resolve, not a check this tool requires. +There is one kind, `sdlc:DeclaredTarget`, for both. Its edition reference may not resolve from +this product. That is the protocol's "not reachable", and it is Writ's `explain` to resolve, not a +check the What's own checker requires. The catalogue (components, tokens, strings) is the target's vocabulary edition, in a package with its own genesis, typically a design team's. "Nothing in a catalogue is a What element of the -product that uses it" (`DDD-dec-57`). So `pf:DesignSystem`, `pf:ContentStore`, `pf:Cio`, -`pf:Token` and `pf:ReificationRule` are not carried (Q-3). The How's vocabulary has the target -kinds (`sdlc:DesignSystemTarget`, `sdlc:ContentStoreTarget`, how-vocabulary.md). +product that uses it". So `pf:DesignSystem`, `pf:ContentStore`, `pf:Cio`, `pf:Token` and +`pf:ReificationRule` are not carried. The How's vocabulary has the target kinds +(`sdlc:DesignSystemTarget`, `sdlc:ContentStoreTarget`, how-vocabulary.md). ### 4.2 The obligations -*Ruled (`DDD-dec-45`).* Reification and content resolution enter the What "as obligations, not -content". The framework "ships obligations, never widgets or words". +Reification and content resolution enter the What "as obligations, not content". The framework +"ships obligations, never widgets or words". 1. **Reification exists.** For a declared design-system target, `reify(AIO, context) → CIO` is defined: each interaction in each context of use its system targets resolves to a concrete @@ -665,8 +694,7 @@ content". The framework "ships obligations, never widgets or words". content-store target declares. **Where the content lives.** The content of each rule (which CIO, which words) is a How binding -anchored to the interaction or the content key (`DDD-dec-57`). Coverage of those bindings is -how.md §8 (`DDD-dec-58`): +anchored to the interaction or the content key. Coverage of those bindings is how.md §8: - a pair that should be realised and is not yet is a baseline entry, which shrinks under the ratchet ("declared missing"); - a pair that cannot apply is an exclusion decision with its reason ("declared unreifiable"); @@ -679,87 +707,83 @@ part. ## 5. Authoring scopes — who can change what -*Ruled (`DDD-dec-44`, `DDD-dec-46`, `DDD-dec-43`).* Authoring scopes are "a central part of the -framework, who can change what, and who helds the genesis grant for a given product". They -instantiate the genesis grant over a product. Tools never change the What, and everything -gathered is signed by a human principal. +Authoring scopes are "a central part of the framework, who can change what, and who helds the +genesis grant for a given product". They instantiate the genesis grant over a product. Tools never +change the What, and everything gathered is signed by a human principal. ### 5.1 A scope is a grant over What element kinds -*Ruled (`DDD-dec-64`, P-7).* Force, grants and acceptance are the authority profile's (Q-4). -This section states what a scope ranges over, which is the What's to say. It also states the one -rule on scopes that the profile inherits rather than chooses: the multi-scope rule, below. +Force, grants and acceptance are the authority profile's ([`authority.md`](authority.md)). This +section states what a scope ranges over, which is the What's to say. It also states the one rule +on scopes that the profile inherits rather than chooses: the multi-scope rule, below. -- **The genesis grant** is unscoped within the product (`DDD-dec-46`). It covers every element - kind, everywhere under P. +- **The genesis grant** is unscoped within the product. It covers every element kind, everywhere + under P. - **A scope** is a set of What element kinds (classes of `what/ontology.ttl`), optionally narrowed to the subtree of one element (`sdlc:within*`). A grant delegating from the genesis carries a scope. An acceptance of a What decision is valid only if every element the decision creates, changes or retires is of a kind in the grant's scope, inside its subtree. - **A decision spanning scopes** needs a valid acceptance under each scope, from the same holder - or different holders. It is in force only while all of those acceptances are live (Round 5). - This is Writ's [D2] conjunction for scopes, the same shape as derived acceptance for blends. The - authority profile inherits it and does not choose otherwise. -- **The kind vocabulary is the ontology.** PF §14.2 carried its kinds "as a parallel list pending - expression as direct references into the sections above". Here they are those references: a - scope names `sdlc:UIStep`, `sdlc:Interaction`, `sdlc:ContentKey` and so on. A scope introduces - no ontology of its own. + or different holders. It is in force only while all of those acceptances are live. This is + Writ's conjunction for scopes, the same shape as derived acceptance for blends. The authority + profile inherits it and does not choose otherwise. +- **The kind vocabulary is the ontology.** The source carried its kinds "as a parallel list + pending expression as direct references into the sections above". Here they are those + references: a scope names `sdlc:UIStep`, `sdlc:Interaction`, `sdlc:ContentKey` and so on. A + scope introduces no ontology of its own. - **Derived kinds** are in no scope. "Some kinds are **derived, not authored** — a read model's - state space derives from the projection's shape … no tool is its author" (PF §14.2). Equally, - no grant authorises authoring them. -- **Kind is immutable** (`DDD-dec-63` §3), so a scope's boundary cannot be crossed by - reclassifying an element. + state space derives from the projection's shape … no tool is its author". Equally, no grant + authorises authoring them. +- **Kind is immutable** (a kind change makes new elements, §2.2), so a scope's boundary cannot + be crossed by reclassifying an element. -*Update, 2026-11-02.* The profile carries the multi-scope rule as inherited, and it states how -the kinds a decision touches are recorded at signing ([`authority.md`](authority.md) §3.1, §4.2). -The acme example's `CUR@1` touches kinds in both scopes and is accepted under each (§9). +The profile carries the multi-scope rule as inherited, and it states how the kinds a decision +touches are recorded at signing ([`authority.md`](authority.md) §3.1, §4.2). The acme example's +`CUR@1` touches kinds in both scopes and is accepted under each (authority.md §9). The product owner's What scope and the architect's How scope are two grants over two sets of -kinds of one product. That is Writ's "two grants over two subgraphs of the same log" (Writ product -definition, Draft 2, chapter 2). +kinds of one product. That is Writ's "two grants over two subgraphs of the same log". ### 5.2 Gathering — tools as sources, never as authors -PF §14 made a tool a "bounded co-author" whose in-scope content "is accepted into the What". -*Ruled (`DDD-dec-43`):* that is reversed. A tool is a **gathering source**. Its material is a -proposed What decision, and it enters only when a human holder of a grant whose scope covers it -signs the acceptance. +The source made a tool a "bounded co-author" whose in-scope content "is accepted into the What". +That is reversed. A tool is a **gathering source**. Its material is a proposed What decision, and +it enters only when a human holder of a grant whose scope covers it signs the acceptance. -What survives of §14, rewritten: +What survives of the source's authoring-scope chapter, rewritten: - **The gathering declaration.** Each source declares the kinds it may supply material for, each with a completeness (`sufficient` or `partial`) and a channel (how the meaning is carried). It - also declares an explicit **excluded** list. This is §14.2's `authors` and `excluded`, renamed. - A declaration grants nothing. It only bounds what the source may propose. + also declares an explicit **excluded** list. These are the source's `authors` and `excluded`, + renamed. A declaration grants nothing. It only bounds what the source may propose. - **The enforcement oracle.** "Out-of-scope content is rejected, the basis naming the scope violation — a Decider authored in Figma is rejected *because Figma is not a sanctioned author of - Deciders*, not because the Decider is wrong" (PF §14.3). Here: such material is never even - proposed. + Deciders*, not because the Decider is wrong". Here: such material is never even proposed. - **The gap split.** "`unauthored-within-scope`: the tool *could* author this and didn't" and - "`outside-scope`: no work in this tool can author this — **route** to a sanctioned author" (PF - §14.3). These are kept as findings that route work. + "`outside-scope`: no work in this tool can author this — **route** to a sanctioned author". + These are kept as findings that route work. - **The completeness join.** A What is complete when every required kind is covered. A join across gathering sources and grants reports each required kind as covered (and by whom), - coverable but ungathered, or uncovered (PF §14.4). Coverage now has two halves: a source that - can supply the kind, and a grant holder who can accept it. + coverable but ungathered, or uncovered. Coverage now has two halves: a source that can supply + the kind, and a grant holder who can accept it. -**The symmetry.** "Authoring scopes are the **top** of a symmetry whose bottom is reification" -(PF §14.5). Here the top is grants over kinds, which say who may change what. The bottom is the -How's coverage (how.md §8), which says what is realised where. Both are bidirectional joins over -one authoritative What. +**The symmetry.** "Authoring scopes are the **top** of a symmetry whose bottom is reification". +Here the top is grants over kinds, which say who may change what. The bottom is the How's +coverage (how.md §8), which says what is realised where. Both are bidirectional joins over one +authoritative What. --- ## 6. The behavioural-conformance wire -*Ruled (charter; Round 1, Q-1):* PF §6.3.1 moves with the What, at v1.11.0. It is the What's -because it is how anyone claims that a realisation computes what the What's Deciders and -Projectors say. It is the oracle's interface, not a verification process. This corrects how.md -Appendix B, which had it as "not carried". +The source's conformance wire moves with the What, at v1.11.0. It is the What's because it is how +anyone claims that a realisation computes what the What's Deciders and Projectors say. It is the +oracle's interface, not a verification process. This corrects how.md Appendix B, which had it as +"not carried". > A **conformance runner** is any process that reads a JSON array of requests on stdin and writes > a JSON array of outcomes on stdout, one per request, in order, exiting 0. Payload values are -> drawn from the wire scalar alphabet (§3.3). (PF §6.3.1) +> drawn from the wire scalar alphabet (§3.3). **Decision requests.** There is one per Decider scenario: `{ "given": [EventRef…], "when": CommandRef, "subject"?: SubjectRef }`. The runner folds `given` @@ -767,8 +791,8 @@ into fresh aggregate state, decides `when`, and answers `{ "emit": [EventRef…] `{ "reject": "" }`. If a response carries both keys, `reject` wins. **Subjects.** A `SubjectRef` is `{ "kind": "", "claims": { claim: scalar | -[scalar…], … } }`. It is supplied beside the command, never inside its `with`. v1.11.0's key was -`actor` (Q-5). A set-valued claim is the one array on the wire. A request with no subject is +[scalar…], … } }`. It is supplied beside the command, never inside its `with`. The source's key +was `actor`. A set-valued claim is the one array on the wire. A request with no subject is conformant only for a Decider whose subject alphabet is empty. **Projection requests.** There is one per Projector scenario: `{ "given": [EventRef…], "key"?: { @@ -777,45 +801,46 @@ partition's state. "Scoping is **not** on this wire." **Equality.** It is exact for decisions: the verdict, the invariant, the emitted events in order, and each payload. It is full-state for projections: "an extra field is as non-conformant as a -wrong one" (PF §6.3.1). - -**Names on the wire.** *Ruled (Round 2, `DDD-dec-64` P-1):* "Opaque keys were ruled for identity, -and identity is not a wire contract." Every element kind that appears on the wire carries an -authored **wire name** (`sdlc:wireName`): commands, events, payload fields, invariants in -rejections, subject kinds and their claims. The REST projection and the conformance protocol -use it, "never the key and never the label": -- **Why not the key.** Keys are opaque ULIDs (`DDD-dec-63`), and a payload object keyed by ULIDs - would make the wire unreadable to every runner author. +wrong one". + +**Names on the wire.** "Opaque keys were ruled for identity, and identity is not a wire contract." +Every element kind that appears on the wire carries an authored **wire name** (`sdlc:wireName`): +commands, events, payload fields, invariants in rejections, subject kinds and their claims. The +REST projection and the conformance protocol use it, "never the key and never the label": +- **Why not the key.** Keys are opaque ULIDs (§2.2), and a payload object keyed by ULIDs would + make the wire unreadable to every runner author. - **Why not the label.** Labels change freely by decision, and a rename would silently break every runner. - **What a wire name is.** It is authored, a `dpp/1` token, and stable by default. It is "changed only by a decision that is by definition a breaking change to the wire contract". -- **Where it is unique.** *Ruled (`DDD-dec-64`, R-1):* product-wide for commands, events, - invariants and subject kinds. For a field, it is unique within its owning command, event, - subject kind or view, because the wire names a field only inside its owner. -- **Which kinds carry one.** *Ruled (`DDD-dec-64`, R-2, amending P-1's list):* everything that - appears on the wire. That is commands, events, payload fields, invariants in rejections, subject - kinds and their claims, and view fields, which a projection response names. - -PF §3.2.0 already called the payload "a **public wire contract**" that "must be authored, not +- **Where it is unique.** Product-wide for commands, events, invariants and subject kinds. For a + field, it is unique within its owning command, event, subject kind or view, because the wire + names a field only inside its owner. +- **Which kinds carry one.** Everything that appears on the wire. That is commands, events, + payload fields, invariants in rejections, subject kinds and their claims, and view fields, which + a projection response names. + +The source already called the payload "a **public wire contract**" that "must be authored, not guessed". The wire name is that contract's vocabulary. +*In Acme Shop:* the commands' wire names are `place-order` and `refund-order`, and the events' +are `order-placed` and `order-refunded`. + The four schemas are in [`what/conformance/`](what/conformance/), moved from v1.11.0's `preview/conformance/` with `actor` renamed `subject`. Their `$id`s are under `https://decision-driven-design.dk/ns/sdlc/conformance/1/`. -A runner's answers are ground readings, not stored verdicts (`DDD-dec-52`). Whether a realisation -conforms is computed by the gate from the What's scenarios and the recorded run. +A runner's answers are ground readings, not stored verdicts. Whether a realisation conforms is +computed by the gate from the What's scenarios and the recorded run. --- ## 7. Encoding and conformance -### 7.1 Encoding (PF §9, cut down) +### 7.1 Encoding, cut down -*Ruled (`DDD-dec-51`).* - Everything is one graph. -- Every What element has a stable identity (`DDD-dec-63`). +- Every What element has a stable identity (§2.2). - Derivation edges run between What elements. - RDF and SHACL are the reference encoding, and an equivalent is conformant. - The edges into the retired How (`realizes`, `enforces`) are dropped. @@ -824,7 +849,7 @@ conforms is computed by the gate from the What's scenarios and the recorded run. graph itself carries `sdlc:succeeds` between elements. - The store is Varve. -The edges are in `what/ontology.ttl`, each with its source. Of PF §9's table: +The edges are in `what/ontology.ttl`, each with its source. Of the source's table of edges: - the What links are carried (renamed as `within` absorbs the ownership links); - the How, work-unit, verification and delivery links (`applies`, `realizes`, `enforces`, `realizes_step`, `composes`, `binds`, `renders`, `at_tier`, `versioned_as`, `realises_version`, @@ -832,24 +857,22 @@ The edges are in `what/ontology.ttl`, each with its source. Of PF §9's table: ### 7.2 Conformance — one level -*Ruled (`DDD-dec-51`):* one level, **described and in force**. A product's What conforms at a -stated position when: +One level, **described and in force**. A product's What conforms at a stated position when: 1. **Described.** The What graph conforms to `what/shapes.ttl` at the sdlc edition it names, and - every element is in the identity form (`DDD-dec-63`). It conforms when validation reports no + every element is in the identity form (§2.2). It conforms when validation reports no `sh:Violation`. Warnings are reported with the claim, and never count against it. 2. **In force.** Every element has an accepted decision chain back to the genesis, under the - authority profile (`DDD-dec-47`). The authority profile is therefore part of conformance, and - this half cannot be claimed until it exists (Q-4). *Update, 2026-11-02:* it exists, in - [`authority.md`](authority.md). "In force" is its §4.7, over a positioned log. + authority profile. The authority profile is therefore part of conformance. "In force" is + [`authority.md`](authority.md) §4.7, over a positioned log. 3. **Versioned.** The position is named by a What-version record whose element list and graph hash recompute from the graph. What it does not claim: that any realisation satisfies the What. That is a verdict at a position, computed and never stored. -**The validation regime** (`DDD-dec-113`, E-1). "Conforms to `what/shapes.ttl`" means this, so -that every implementation computes the same results: +**The validation regime.** "Conforms to `what/shapes.ttl`" means this, so that every +implementation computes the same results: - **The data graph** is the What graph merged with the edition's `what/ontology.ttl`, in the default graph. The vocabulary's enumerated individuals (the states, the interaction classes, the AIOs) live in the ontology, so the What graph alone does not validate. @@ -857,7 +880,7 @@ that every implementation computes the same results: graph), with SHACL-SPARQL, and no RDFS or OWL entailment. - **The ontology** is never part of a What graph's hash or of its export (§2.3). -**Violations and warnings** (`DDD-dec-113`, E-2). Each shape has one severity: +**Violations and warnings.** Each shape has one severity: - `sh:Warning` when it can only hold once an element authored later exists, later in phase order or in a later write: a finding about what is not yet modelled. A tool that refuses a write on a failed shape refuses on violations only. @@ -880,20 +903,20 @@ example's warnings, by message and focus node, with the set expected of it. --- -## 8. The move's own choices — `DDD-dec-64`, ruled +## 8. The choices made when the What moved here -P-1 was ruled in Round 2. P-2 to P-7, R-1 and R-2 were ruled in Round 5, all as proposed. P-7's -multi-scope rule and R-2's amendment to P-1's list were added with the ruling. +The move made seven choices of its own. All are decided, as proposed, with two additions made when +they were ruled: the multi-scope rule, and view fields among the kinds that carry a wire name. -| # | Choice | Section | -|---|---|---| -| P-1 | `sdlc:wireName`: the authored name the wire and public interfaces use, distinct from key and label. With R-1 (field names unique within their owner) and R-2 (view fields carry wire names) | §6 | -| P-2 | `sdlc:within` as the single containment edge | §2.2 | -| P-3 | interactions, fields, state annotations, content keys and scenarios are elements | §2.2 | -| P-4 | `sdlc:DeclaredTarget` for design-system and content-store declarations | §4.1 | -| P-5 | §3.5 is titled "Named-algorithm primitives", with no subtitle | §3.5 | -| P-6 | the What-side kinds the move adds where product-cli's `schema/` had none: Domain, System, Journey, Trigger, Decider, Projector, Scenario, NamedAlgorithm, ReferenceData, StateAnnotation, ContentKey, QualityDemand, SubjectKind, ScopeRule, among others (each with its `dct:source`) | `what/ontology.ttl` | -| P-7 | an authoring scope as a set of element kinds, optionally narrowed to a subtree; tools as gathering sources; a decision spanning scopes needs a live acceptance under each | §5 | +| Choice | Section | +|---|---| +| `sdlc:wireName`: the authored name the wire and public interfaces use, distinct from key and label. Field names are unique within their owner, and view fields carry wire names | §6 | +| `sdlc:within` as the single containment edge | §2.2 | +| interactions, fields, state annotations, content keys and scenarios are elements | §2.2 | +| `sdlc:DeclaredTarget` for design-system and content-store declarations | §4.1 | +| §3.5 is titled "Named-algorithm primitives", with no subtitle | §3.5 | +| the What-side kinds the move adds where product-cli's `schema/` had none: Domain, System, Journey, Trigger, Decider, Projector, Scenario, NamedAlgorithm, ReferenceData, StateAnnotation, ContentKey, QualityDemand, SubjectKind, ScopeRule, among others (each with its `dct:source`) | `what/ontology.ttl` | +| an authoring scope as a set of element kinds, optionally narrowed to a subtree; tools as gathering sources; a decision spanning scopes needs a live acceptance under each | §5 | ## Appendix — where the source went @@ -902,21 +925,71 @@ multi-scope rule and R-2's amendment to P-1's list were added with the ruling. | PF §1, §2, §2.1 | not carried. Scope is §1. The authoring order (step 6 of the funnel was the How) is not restated | | PF §2.2 allocation reading | not carried. It was a reading of canon, and canon is consumed by pin | | PF §3 introduction, §3.0, §3.0.1 | §3, §3.0, §3.0.1. Direction and value-anchoring struck | -| PF §3.1 | §3.1. The data-conformance callouts are cut to a pointer (`DDD-dec-44`) | +| PF §3.1 | §3.1. The data-conformance callouts are cut to a pointer | | PF §3.2, §3.2.0 | §3.2, §3.2.0, with v1.11.0's subject edge. The slice-as-work-unit clause is struck | | PF §3.2.1–§3.2.4 | §3.2.1–§3.2.4. Reification rules become the obligation (§4.2) and How bindings | | PF §3.2.5 | §3.2.5, plus declared targets (§4.1) | | PF §3.3, §3.4 | §3.3, §3.4 at v1.11.0. The pure-core contract becomes a pointer to the How | -| PF §3.5 | §3.5, retitled (P-5). Oracle conformance becomes the How's | +| PF §3.5 | §3.5, retitled. Oracle conformance becomes the How's | | PF §3.6 | §3.6. "Binds to the How" becomes "a contract anchors to it" | | PF v1.11.0 §3.7 | §3.7, with subject for actor. Provider coverage goes to the How | -| PF §4–§5, §6 except §6.3.1, §7 | retired (`DDD-dec-42`) | -| PF §6.3.1 | §6, at v1.11.0, with wire names (P-1) | -| PF §8 | dropped (`DDD-dec-42`) | -| PF §9 | §7.1 and `what/ontology.ttl`, cut down (`DDD-dec-51`) | -| PF §10 | §7.2, one level (`DDD-dec-51`) | -| PF §11, §12 | §4: declared targets and obligations. Catalogues are packages (`DDD-dec-57`) | -| PF §13 | not carried: an add-on (`DDD-dec-44`) | +| PF §4–§5, §6 except §6.3.1, §7 | retired | +| PF §6.3.1 | §6, at v1.11.0, with wire names | +| PF §8 | dropped | +| PF §9 | §7.1 and `what/ontology.ttl`, cut down | +| PF §10 | §7.2, one level | +| PF §11, §12 | §4: declared targets and obligations. Catalogues are packages | +| PF §13 | not carried: an add-on | | PF §14 | §5: grants over element kinds, with tools as gathering sources | -| product-cli `schema/` | `what/ontology.ttl` and `what/shapes.ttl`, §3 subset (Q-2). The diff from `spec/schema/` is recorded in the session | -| `examples/checkout/` manifests | not carried. They are instances, and the framework ships none (`DDD-dec-45`) | +| product-cli `schema/` | `what/ontology.ttl` and `what/shapes.ttl`, §3 subset. The diff from `spec/schema/` is recorded in the move's session | +| `examples/checkout/` manifests | not carried. They are instances, and the framework ships none | + +## Not settled yet + +- **Whether an adopter may register AIOs** (§3.2.2) *(open)*. The source allowed it. Under this + ontology a registered AIO would be a vocabulary change in this repository, not a What element. + It is the same question as how.md's open question on adopters registering What kinds. Deciding + it yes would add a registration route for vocabulary; deciding it no would close the base set + at ten. + +## Where this comes from + +**The source.** The Product Framework, github.com/Hafeok/product-framework: v1.10.0 at `c895652`, +and v1.11.0 at `55c9281` for §3.7 and the sections it threads. v1.11.0 was never merged in that +repository. It is adopted here by ruling. Quoted passages are its text, cited below by its section +("PF §3.1"). The move was made by the session at +`meta/sessions/2026-10-28-product-framework-what-move/` and ratified when its pull request (#42) +merged. + +| Section | Rests on | +|---|---| +| §1.1 | `DDD-dec-41`; `DDD-dec-42` (declared ground) | +| §1.2 | How: `DDD-dec-55`…. Delivery, work units, Two Pillars: `DDD-dec-42`; the gate is Writ: `DDD-dec-54`. Data conformance: `DDD-dec-44`. Force: `DDD-dec-46`, `DDD-dec-47`, set aside for its own pull request (move Round 1, Q-4), now `authority.md` (`DDD-dec-85`, `DDD-dec-86`). Catalogues: `DDD-dec-57`. `pf:` ends: move Round 1, Q-3 | +| §1.3 | In order: `DDD-dec-41`, `-42`; `-42`, `-55`; `-43`; `-44`, `-57`; `-45`; `-44`, `-46`; `-49`, `-52`; `-51`; `-63`; move Round 1, Q-1, Q-3, Q-5; `DDD-dec-113` | +| §2.1 | `DDD-dec-42`, `DDD-dec-43`. Anchoring a creating decision: move Round 6, `DDD-dec-63` §8, applying `DDD-dec-55` (How ruling 1) | +| §2.2 | `DDD-dec-63`. Containment: `DDD-dec-64` P-2. What is an element: `DDD-dec-64` P-3; bindings anchor: `DDD-dec-57` | +| §2.3 | `DDD-dec-63` §6; the canonical form: `DDD-dec-73` (Round 3), superseding `DDD-dec-63`. Ontology not hashed: `DDD-dec-113` E-1. Second implementation: successor item M-12 (`DDD-dec-73`). Varve's reproduction: `DDD-dec-113` E-3 | +| §3, §3.0, §3.0.1 | PF §3, §3.0, §3.0.1. Direction struck: `DDD-dec-42`; PF §7.3. Second genesis: `DDD-dec-46`. Value-anchoring was PF §6/§7 | +| §3.1 | PF §3.1, §3.2.0 (datatypes). Every box says what it is: `DDD-dec-113` E-7. Context mapping direction: `DDD-dec-113` E-8. Data conformance: PF §13; `DDD-dec-44` | +| §3.2, §3.2.0 | PF §3.2, §3.2.0. Trigger source and subject: move Round 1, Q-1 and Q-5; PF v1.11.0 §3.2.0. Slices and work units: PF §5 | +| §3.2.1 | PF §3.2.1; offered to: Q-1, Q-5, PF v1.11.0 §3.2.1. Concrete controls: `DDD-dec-57`. The reification rule (PF §4.5) is not the What's: `DDD-dec-45` | +| §3.2.2 | PF §3.2.2. The open point: how.md §6 | +| §3.2.3 | PF §3.2.3. Criteria not re-minted: `DDD-dec-63` §4. Attestations: `DDD-dec-52`; held by the authority profile (move Round 1, Q-4) | +| §3.2.4, §3.2.5 | PF §3.2.4, §3.2.5 | +| §3.3 | PF v1.11.0 §3.3 (signature: Q-1; subject: Q-5); PF §3.3 (scenarios; pure core, PF §4.2) | +| §3.4 | PF §3.4, PF v1.11.0 §3.4 (Q-5). The checks in `shapes.ttl`: `DDD-dec-113` E-4 | +| §3.5 | PF §3.5; title `DDD-dec-64` P-5. Oracle conformance was PF §6.3 | +| §3.6 | PF §3.6; Kind 1 wiring how.md §4.2, H-9 | +| §3.7 | PF v1.11.0 §3.7, adopted by move Round 1, Q-1 and Q-5. Second authority: `DDD-dec-46`, `DDD-dec-47`. The checks in `shapes.ttl`: `DDD-dec-113` E-4 | +| §4.1 | `DDD-dec-57`; `DDD-dec-64` P-4. `pf:` classes: Q-3 | +| §4.2 | `DDD-dec-45`; content as How bindings `DDD-dec-57`; coverage `DDD-dec-58` | +| §5 | `DDD-dec-44`, `DDD-dec-46`, `DDD-dec-43` | +| §5.1 | `DDD-dec-64` P-7; force is the profile's (move Round 1, Q-4); the multi-scope rule: move Round 5; Writ's [D2]; genesis unscoped: `DDD-dec-46`; kind immutable: `DDD-dec-63` §3; PF §14.2. Recorded 2026-11-02: `authority.md` §3.1, §4.2, §9. Writ product definition, Draft 2, chapter 2 | +| §5.2 | `DDD-dec-43`; PF §14, §14.2–§14.5 | +| §6 | The charter; move Round 1, Q-1 (PF §6.3.1 at v1.11.0). `actor` → `subject`: Q-5. Wire names: move Round 2, `DDD-dec-64` P-1; uniqueness: R-1; kinds: R-2. Keys: `DDD-dec-63`. Ground readings: `DDD-dec-52` | +| §7.1 | `DDD-dec-51`; PF §9; identity `DDD-dec-63` | +| §7.2 | `DDD-dec-51`; PF §10; identity `DDD-dec-63`; in force `DDD-dec-47`, set aside until the profile existed (Q-4) and recorded on 2026-11-02 as existing (`authority.md` §4.7). Validation regime: `DDD-dec-113` E-1; violations and warnings: E-2 | +| §8 | `DDD-dec-64`, its table rows in order P-1 to P-7 (P-6: the What-side kinds the move adds); Q-2 (product-cli's `schema/` §3 as the subset); `examples/checkout` not carried: `DDD-dec-45`. P-1 ruled in move Round 2; P-2 to P-7, R-1 and R-2 ruled in Round 5, all as proposed; P-7's multi-scope rule and R-2's amendment to P-1's list added with the ruling | + +Ids in this document are in this table and the `ddd:doc` block, not in its running text. The text +it replaces is `84aa466:applications/sdlc/what.md`. diff --git a/core/decisions/DDD-dec-119.yaml b/core/decisions/DDD-dec-119.yaml new file mode 100644 index 0000000..2dc82db --- /dev/null +++ b/core/decisions/DDD-dec-119.yaml @@ -0,0 +1,62 @@ +format: 1 +id: DDD-dec-119 +kind: decision +statement: | + The merge of PR #41 ratified every part of the How that was "not ruled separately" and stood as proposed until the merge. They are ruled as proposed: the parts listed under "Not ruled separately; stands as proposed until the merge" in DDD-dec-55, -57, -59 and -60, the condition on editions in DDD-dec-61, and every point applications/sdlc/how.md marked [PROPOSED] under its banner "what was not ruled separately stays [PROPOSED] until the merge", including Appendix A's H-3, H-8, H-9, H-11, H-12, H-13 and H-17 and the proposals it kept unlisted. It reaches applications/sdlc/how-vocabulary.md, the How's vocabulary under the same decisions, whose banner says "the rest stands as proposed until the merge". The ruling changes their register only, and no statement. It does not reach the [OPEN] point (whether adopters may register What kinds), any UNVERIFIED reading, or any document outside the How (how.md and how-vocabulary.md). +principal: Emil +made: | + 2026-11-10, in Claude's question dialog of the session meta/sessions/2026-11-09-applications-for-readers-redo/ (issue #71), answering PR #48's ruling request 2; recorded verbatim in that session's rulings.md, Round 2 (its reach over how.md §5.2's term list and §11 ruled in Round 3, 2026-11-11): "The merge ratified them all" (option text: "Every 'not ruled separately' item became ruled when #41 merged; the rewrite drops their [PROPOSED] marks"). Emil's landing of that session's branch is the ratification act +resolution: | + ## The question + + how.md said, from 2026-10-28: "Sections a ruling settled say *Ruled*. What was not ruled + separately stays [PROPOSED] until the merge." PR #41 merged (1d0f40c), although it was titled + "for the record, not for merge", and how.md was not touched again except for dated pointers to + the authority profile (533ac8e). PR #48's rewrite kept every such part marked unsettled and asked + whether the merge had settled them (#48 report.md, ruling request 2). Two of them were already + word for word in a decision's statement: coverage (DDD-dec-58) and the three parts of an import + (DDD-dec-59). + + ## Ruled: the merge ratified them + + Each part below is ruled as it stood proposed at the merge. Locations are how.md on main at + 84aa466. + + | how.md | Part | Decision whose "not ruled separately" list held it | + |---|---|---| + | §4 | The three kinds; no fourth and no split; the idle report; target declarations and exclusions as record types; no-orphans as coverage of code by decisions | DDD-dec-55 | + | §4.3 | A principle is not a kind | DDD-dec-55 | + | §4.2, §9 | Kind-1 measurement wiring held as a contract; deployment-declared facts may gate land and deployment-observed facts do not; a freshness bound per contract | DDD-dec-60 | + | §5, §5.2 | Every How decision stated once, with no language or platform term; shapes derived from a target's edition, never authored, and expressible iff the edition maps every fact term read; interface standards are not targets; platform targets beside languages; which targets the What declares and which How target declarations declare | DDD-dec-57 | + | §5 | The form of a decision's statement and violation description | how.md's banner; reach ruled in Round 3 | + | §7 | The recorded-reading condition on "rests on superseded version"; narrow, never alter | DDD-dec-59 (its statement already ruled the three parts of an import and withdrawal) | + | §8 | Coverage over every binding, as proposed | already ruled by DDD-dec-58's statement; how.md still marked it [PROPOSED] | + | §10 | Generation out of scope, on condition that no edition may be check-only (H-15) | DDD-dec-61 | + | §11 | Conformance: one level, specified and in force | how.md's banner; reach ruled in Round 3 | + | Appendix A | H-3, H-8, H-9, H-11, H-12, H-13, H-17; and "kept as proposed and not listed" | DDD-dec-55, -57, -59, -60 | + + ## Not reached + + - **[OPEN]:** whether adopters may register What kinds (how.md §6 and §10, item 2). + - **UNVERIFIED readings:** the ratchet semantics of a baseline (§8.2), assumed while the + authority profile was unwritten; Claude's reading of DDD-dec-45's consequence (§8.2); and the + readings DDD-dec-55 to -61 record at filing under "UNVERIFIED — Emil review". + - **Documents outside the How.** The ruling is about how.md, how-vocabulary.md and their + decisions. The How vocabulary's IRI question (no IRI under /ns/sdlc is served; UNVERIFIED) + is a reading, and is not reached either. +basedOn: + - DDD-dec-55 + - DDD-dec-57 + - DDD-dec-58 + - DDD-dec-59 + - DDD-dec-60 + - DDD-dec-61 +notes: | + The id is the next free one above DDD-dec-118, checked on every remote branch on 2026-11-10. + The decisions it ratifies parts of are not edited. Each of them still says "stands as proposed + until the merge", which this decision answers. The table above is Claude's inventory of the + parts, checked against how.md at 84aa466. The §5 form and the §11 conformance level are in no + decision's list and are reached only by how.md's banner. Claude read the ruling as reaching + them, and Emil ruled that reading on 2026-11-11: "Yes, it covers them" (option text: "The banner + made them 'not ruled separately' items, which the ruling names; §10 item 2 stays [OPEN]"), + recorded verbatim in meta/sessions/2026-11-09-applications-for-readers-redo/rulings.md, Round 3 (2026-11-11). diff --git a/core/decisions/DDD-dec-120.yaml b/core/decisions/DDD-dec-120.yaml new file mode 100644 index 0000000..d2d926a --- /dev/null +++ b/core/decisions/DDD-dec-120.yaml @@ -0,0 +1,48 @@ +format: 1 +id: DDD-dec-120 +kind: decision +statement: | + The seam table's rows 1 to 8, 10 and 11 in applications/pdlc/pdlc.md §2.1 are ruled as listed: for each, its ground, the act that produces it, the act that reads it, and the check against the act map. This supersedes only the sentence "It is not ruled here" of DDD-dec-114 P-3, and nothing else in DDD-dec-114. Row 9, telemetry of the product in use, was already ruled (Round 16 of the 2026-11-07 record) and is not re-ruled here. Rows 10 and 11, the classification verdicts, were added to this decision in place before it landed (Round 4). +principal: Emil +made: | + 2026-11-11, in Claude's question dialog on claude.ai, answering the redo session's finding F-10: "Rule rows 1–8 now" (option text: "They are checked against the act map by check.py; rule them as listed, and the register line becomes true"), recorded verbatim in meta/sessions/2026-11-09-applications-for-readers-redo/rulings.md, Round 3 (issue #71, PR #73). Rows 10 and 11 added in place before landing, on Emil's answer of 2026-11-11: "Rule them now" (option text: "The redo session adds them to DDD-dec-120 (still unlanded) and #73 gets a new head"), recorded verbatim in the same rulings.md, Round 4. Emil's landing of that branch is the ratification act +resolution: | + ## What is ruled + + The rows as they stand in applications/pdlc/pdlc.md §2.1 at the redo session's head before + this decision (b27407a), and rows 10 and 11 as they stand at 01c6840. Each is checked by applications/pdlc/graph/check.py against the act map + (applications/pdlc/graph/acts.ttl with applications/sdlc/acts/acts.ttl). + + | # | From → To | Ground supplied | Produced by | Read by | Check | + |---|---|---|---|---|---| + | 1 | When → What | A pulled option (a need) | o2a (When) | o1 (dependency "the pulled option") | **Holds** | + | 2 | When → What | A scope-cut proposal | **oS**, propose a scope or assurance cut (When) | o1 (`lc:readsEarlier m:oS`) | **Holds**, now that oS exists. It was a gap: no act produced it. Not an option, because an option is never a What change, and not a What decision, because the When owner proposes and the What owner decides | + | 3 | What → When | Each element's outcome and acceptance | Earlier o1s (What) | o2a (`lc:readsEarlier m:o1`) | **Holds** (fixed when the map was first drawn) | + | 4 | What → When | The ready-for-users verdict | oR (What) | o16 (dependency) | **Holds** | + | 5 | What → How | The What, the product assurance | o1 (What and assurance loci) | o1b (dependency, new demand), and the How owner's implementation-assurance decisions | **Holds** | + | 6 | When → How | A released issue, in order | o2a (the pull and its rank) | o2b (dependency, `lc:forKind lc:NewDemand`) | **Holds, for new demand only.** Owed and own-ground issues cross no When → How seam | + | 7 | How → When | The record: cadence, lead time, change failure rate | The dispatcher's occurrence records, o3 to o13 | o2a (`lc:readsEarlier m:o13`); the forecast | **Holds** | + | 8 | How → What | The change in production, dark, with its verdicts | o13, with o9 and o10's verdicts | oR (dependency) | **Holds** | + | 10 | What → How | A classification verdict: owed | oC (What) | o1b (dependency, `lc:forKind lc:OwedDemand`) | **Holds** | + | 11 | What → When | A classification verdict: new | oC (What) | o2a, through the option the What owner proposes at o0 | **Holds, indirectly.** A defect classified new becomes an option. The When owner reads it as an option, never as a defect | + + ## What is not changed + + - DDD-dec-114 is landed and not edited. P-3's other sentences stand: each owner controls its + own ground; ground crossing a seam is supplied by its producer and read, read-only, by its + receiver; a ground-locus issue declares whose ground it changes, and that owner accepts it. + - Row 2's scope-cut act (oS) and row 9 (telemetry) were ruled before this decision. + - Rows 10 and 11, the classification verdicts owed and new, were Claude's additions in the + 2026-11-07 record (Round 22), made when the three kinds of demand were adopted. They are ruled + here by Round 4 of the redo session, which amended this decision in place before it landed. +basedOn: + - DDD-dec-114 +notes: | + Id: the next free above DDD-dec-119, checked on every remote branch (60) on 2026-11-11 just + before the commit and again just before the push. No branch holds a decision file above 119. + DDD-dec-120 appears on several branches only as a range mention in two 2026-11-08 session + records, which the specification-feasibility bootstrap ruled is not use. The parallel + method-plugin session (claude/confident-goldberg-c0y0ia) holds no decision file above 118. + + Not filed as supersedes: DDD-dec-114. That field marks a whole decision superseded + (validate-core-order.py), and only one sentence of P-3 is. The pattern is DDD-dec-117's. diff --git a/core/decisions/DDD-dec-94.yaml b/core/decisions/DDD-dec-94.yaml new file mode 100644 index 0000000..1541f62 --- /dev/null +++ b/core/decisions/DDD-dec-94.yaml @@ -0,0 +1,68 @@ +format: 1 +id: DDD-dec-94 +kind: decision +statement: | + The doc-format rulings of 2026-10-26 are re-filed on main: only canon carries authority, and canon is both repositories' core/; every other folder exists for a named reader doing a named act; a document outside canon opens with a ddd:doc block (reader, act, pin, basis, status, supersedes) whose schema is spec/doc-format.md; a reformatted document replaces its old text in place and names it in supersedes; local canon in a basis is written ID@status; and, adopting the pilot's amendment, running text says status in words a reader can use and keeps decision, claim and promotion ids out. +principal: Emil +made: | + The rulings re-filed were given by Emil on 2026-10-26 in the doc format session (pre-session rulings 1 and 2, Gate 1 rulings 1, 3 and 4, Gate 2 ruling 1), recorded only on branch claude/doc-format, which shares no history with main. Their re-filing, with the pilot's amendment, was ruled on 2026-11-02 in the applications-for-readers session ("agreed go with your recommendations", recommendation 2), recorded verbatim at meta/sessions/2026-11-02-applications-for-readers/rulings.md on branch claude/applications-for-readers-2026-11-02 (068cb23), the record of PR #48, which was closed without merging. Re-filed on main on 2026-11-10 by the session meta/sessions/2026-11-09-applications-for-readers-redo/ (issue #71), on Emil's ruling of 2026-11-09 to close #48 and have a successor land this decision (recorded verbatim in that session's rulings.md, Round 1). Emil's landing of that session's branch is the ratification act +resolution: | + ## Why this is re-filed + + The 2026-10-26 rulings govern every document outside canon, and they existed only on an + orphaned branch. That branch shares no history with main, so it cannot merge, and its decision + id DDD-dec-39 has since been given to the release-head guard. A ruling that governs documents + but lives where no document can reach it is basis loss in this repository's own sense + (DDD-agent-01). This decision restores the rulings to main without changing them. + + ## The rulings, as given on 2026-10-26 + + | Source | Ruling | + |---|---| + | Pre-session 1 | Only canon carries authority. Every other folder exists for a named reader doing a named act. A document there is ground for that act, and its format follows from what that reader needs. | + | Gate 1, ruling 1 | Canon is upstream core/ and this repository's core/ (reading A). | + | Pre-session 2 | The format lives in spec/doc-format.md, in this repository. A document outside canon opens with a ddd:doc block: reader, act, pin, basis, status. A validator checks it, at warning level first. | + | Gate 1, ruling 3 | A reformatted document replaces its old text in place, and names the old text in a supersedes: : field. | + | Gate 1, ruling 4 | basis may name a held result, held:/. | + | Gate 2, ruling 1 | A local canon entry in basis carries the status it was read at, as ID@status. | + + ## The pilot's amendment, ruled now + + The 2026-10-26 pilot's readers listed decision ids, promotion numbers and "held" markers among + the things they did not understand. The amendment it proposed is adopted: in running text, say + a document's status, and the status of what it rests on, in words the reader can use; keep + claim, term, decision and promotion ids out of the prose. Ids belong in the ddd:doc block and + in the document's basis table. + + ## Not re-filed + + - **The check (W8 to W15).** It was written against the old history's validate-core-order.py. + Porting it to scripts/ is a successor item. Until it lands, a ddd:doc block is a convention, + not a gate. + - **The folder charters (ddd:charter).** Gate 2 ruling 2 accepted them as a whole, but their + readers and acts name the old tree. They are re-proposed folder by folder as each folder is + reformatted, starting with applications/ (DDD-dec-95). + - **Gate 2 rulings 3 and 4** (way-of-working.md §5, CLAUDE.md). Both were to be made at a + Gate 4 that never ran. AGENTS.md has since replaced CLAUDE.md as the instruction file + (DDD-dec-81). Both are carried as successor items, to be re-proposed against the current + tree. +basedOn: + - DDD-agent-01 + - DDD-dec-04 + - DDD-dec-81 +notes: | + The 2026-10-26 session's record, including the pilot evidence, is on branch claude/doc-format + at df9d05b. spec/doc-format.md is ported from that branch with its check section marked not + yet ported; nothing else is copied from it. + + Re-filed on 2026-11-10 from claude/applications-for-readers-2026-11-02 at 068cb23 (PR #48, + closed without merging) by meta/sessions/2026-11-09-applications-for-readers-redo/. The + statement, resolution and basis are #48's text unchanged. Changed, because main made them + wrong after #48 was written: the made line, which cited #48's session record as if it were on + main and named #48's pull request as the ratification act. #48's record is not on main, and + #48 was closed, so the made line now names the branch and commit where the record lives and + this session's landing as the act. Re-checked on main at 84aa466 and still true: DDD-dec-39 is + the release-head guard upstream (pinned at v5.15.2); AGENTS.md replaced CLAUDE.md as the + instruction file (DDD-dec-81); the check (W8 to W15) has not been ported to scripts/; the + folder charters and Gate 2 rulings 3 and 4 have not been re-proposed. The successor items + that "Not re-filed" names are carried by the re-filing session's successor-items.md. diff --git a/core/decisions/DDD-dec-95.yaml b/core/decisions/DDD-dec-95.yaml new file mode 100644 index 0000000..8dd20ce --- /dev/null +++ b/core/decisions/DDD-dec-95.yaml @@ -0,0 +1,68 @@ +format: 1 +id: DDD-dec-95 +kind: decision +statement: | + Documents under applications/ are written for the people who use them: an opening that names the reader, what they can do and how settled the document is, in words; a ddd:doc block; no decision, claim, round or session ids in running text, except where the id is the subject; register in words, with decided unmarked, "(proposed, not yet ruled)" for [PROPOSED], "(open)" for [OPEN] and "(Claude's reading, not yet confirmed by Emil)" for an unconfirmed reading, each also listed under "Not settled yet"; deliberation in the session record; a closing "Where this comes from" table; and no change of content. Every numbered section keeps its number, order and file, because other files cite sections by number, so no document is split, merged or renamed, and reference material stays in its numbered section. Existing ddd:ref and ddd:embed markers stay. Acme Shop stays the example for the What and the How, beside Varve for the method. The scope is every document under applications/, including pdlc/, sdlc/sdlc.md, sdlc/authority.md and sdlc/product-cli/, with apparatus/ next. Whether the format helps is decided by a human first-contact test (successor item A-4), not by model readers. +principal: Emil +made: | + The format was ruled on 2026-11-02 in Round 1 of the applications-for-readers session ("agreed go with your recommendations", recommendations 1, 3, 4 and 5), recorded verbatim at meta/sessions/2026-11-02-applications-for-readers/rulings.md on branch claude/applications-for-readers-2026-11-02 (068cb23), the record of PR #48, which was closed without merging. Emil ruled on 2026-11-09 that a successor redo the rewrite on current applications/, and that the format stays, with a human first-contact test deciding later; and on 2026-11-10 that unsettled points use two phrases. Both are recorded verbatim in meta/sessions/2026-11-09-applications-for-readers-redo/rulings.md, Rounds 1 and 2 (issue #71). Emil's landing of that session's branch is the ratification act +resolution: | + ## The format, as applied + + #48's F1 to F8 (gate1-proposal.md at 068cb23, "The proposed format"), applied as follows. + + - **F1, the opening.** Kept. Who the document is for, what they can do after reading it, and how + settled it is, in words, before the content. + - **F2, a ddd:doc block** under the title (DDD-dec-94, spec/doc-format.md). supersedes names + 84aa466:. + - **F3, ids out of running text.** Kept, with an exception where the id is the subject: a table + mapping departures to decisions, a record name such as GEN@3, a vocabulary term. Register in + words: four registers, each with its own phrase (Round 2), and a "Not settled yet" section. + - **F4, order by the reader's task.** Adapted. Numbered sections keep their order. The opening + says which sections serve which task, and which a practitioner can skip. + - **F5, reference material in its own document.** Not applied. Reference material stays in its + numbered section (below). + - **F6, deliberation in the session record.** Kept. Quoted rulings become plain rules at the same + strength, and the quotes move to "Where this comes from". + - **F7, "Where this comes from".** Kept, keyed by section. + - **F8, no change of content.** Kept. The only register changes are the ones decisions give: + DDD-dec-119 for the How, and stale "not yet ratified" lines corrected where the pull request + their decisions name as the ratification act has merged. Facts found wrong are corrected and + listed (the session's findings.md, F-9, F-13, F-14). + + ## Point-of-use markers + + #48 added a rule that an invisible ddd:ref marker sits at the point of use where a rule rests on + a projected claim. It is not applied in this rewrite. Existing markers stay exactly where they + are. spec/doc-format.md keeps the permission ("may sit"). The validator checks a ddd:ref against + upstream pins only and skips local ids (Gate A finding F-4), so a marker on a local projected + claim warns about nothing. + + ## What differs from #48's version, and why + + | #48's DDD-dec-95 | This version | Why | + |---|---|---| + | what.md and how.md split into practitioner and reference documents; how-vocabulary.md merged into how-reference.md | No split, merge or rename | 157 citations by section number outside the session records, including in what/shapes.ttl and what/ontology.ttl (hashed into a vocabulary edition) and in signed dpp/1 records. A split moves cited sections out of the file they are cited in (findings F-6, F-8) | + | F4 and F5 as written | F4 adapted, F5 not applied | The same anchor constraint | + | Unsettled points as "not settled yet" | Four registers in words | Emil, Round 2: two phrases for [PROPOSED] and [OPEN]. Unconfirmed readings are kept as a third unsettled register, so that no distinction is lost | + | Point-of-use ddd:ref markers for projected claims | Not applied; existing markers kept | Above | + | Scope: what.md, how.md, how-vocabulary.md, how-examples, production-as-ground.md and three READMEs | Every document under applications/ (15), including pdlc/, sdlc.md, authority.md and its vocabulary, product-cli/product-definition.md and test-keys/README.md | Those landed after #48, or (authority.md) waited for #45, which has merged | + | If Gate 3's model-reader test fires against F3, the markers go with it | A human first-contact test decides (A-4), pre-registered before the rewrite was committed | Emil, Round 1: "Keep it, human test decides". #48's model readers hit a ceiling | + | Sequence through Gate 3 | Gate B, then the independent equivalence check, then Emil's review. A-4 is scheduled by Emil | Emil, Round 1 | + + ## The examples + + Acme Shop remains the worked example of the What and the How; Varve the method's (DDD-dec-77). + Writing Varve's What is successor item A-5. The six content gaps #48's readers found are + successor items A-8 to A-12 and A-16, not fixed or marked in the rewrite (Round 2), with A-8 + first. +basedOn: + - DDD-dec-94 + - DDD-dec-119 + - DDD-dec-74 + - DDD-dec-77 +notes: | + Re-filed from claude/applications-for-readers-2026-11-02 at 068cb23 and adapted, on Emil's + ruling that a successor redo the rewrite. The table above lists every difference from #48's file. + The weakest point, which #48 also named: whether the format helps people is not yet shown. A-4 is + the test that decides it. diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/bootstrap.md b/meta/sessions/2026-11-09-applications-for-readers-redo/bootstrap.md new file mode 100644 index 0000000..2ca63d6 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/bootstrap.md @@ -0,0 +1,54 @@ +# Bootstrap — applications/ for readers, redone, 2026-11-09 + +Filled in at arrival and committed with `prompt.md` as the session's first commit. + +| Parameter | Value | +|---|---| +| Invocation | Interactive, gated. Emil's two rulings are verbatim in `prompt.md`, and `rulings.md` records them as Round 1 | +| Principal | Emil (sole ratifier; ratifies by landing the branch) | +| Issue | [#71](https://github.com/mindovermachine-dev/decision-driven-design/issues/71). Every commit of the session carries `Refs #71` | +| Predecessor | PR #48, closed and not merged. Its branch `claude/applications-for-readers-2026-11-02` at `068cb23` is kept as the record and is read here, not merged | +| Precondition | PR #64 (the PDLC and the SDLC) **has landed**: merged 2026-11-09T13:54Z, head `a53d02d` | +| Upstream pin | `graph/upstream.yaml`, unchanged by this session | +| Downstream base | `84aa466` (`84aa4665b4b0392ef4bb08ac042e42ae9fc6d12c`), the head of `main` at arrival (2026-11-10). It is after #64 and after the v0.7.0 release descriptor (#69/#70) | +| Downstream branch | `claude/zealous-ptolemy-3txf8k`, from `main` at `84aa466` | +| Date | The prompt names the session 2026-11-09, and the folder keeps that name. The work starts on 2026-11-10 | + +## Gates + +| Gate | What | Who | +|---|---|---| +| G0 | This charter committed before any other change | Claude | +| A | `DDD-dec-94` filed on `main` from #48's file; `spec/doc-format.md` ported; the validators run | Claude; **stops for Emil** | +| Q | #48's ruling requests 2 to 4 put to Emil; answers recorded verbatim before anything they affect is written | **Emil** | +| B | The rewrite of `applications/` to `spec/doc-format.md`; `DDD-dec-95` filed; the independent equivalence check; A-4 pre-registered | Claude; **stops for Emil** | +| Land | CI green, head reported, land commands given | **Emil** | + +## Decision ids at arrival (prompt step 2) + +Checked on all 59 remote branches after unshallowing, on 2026-11-10. + +- `core/decisions/DDD-dec-94.yaml` and `DDD-dec-95.yaml` exist only on + `claude/applications-for-readers-2026-11-02` (`068cb23`). No branch holds a file for `DDD-dec-96` + to `-99`. `main` holds up to `DDD-dec-93`, then `DDD-dec-100` to `-118`. +- Other text that names the ids is headroom bookkeeping and claims no use. On `main`, this is + `DDD-dec-100` (notes), `DDD-dec-103` (notes), `meta/sessions/2026-11-02-canon-cli/bootstrap.md` + and its `successor-items.md` S-6, and `meta/sessions/2026-11-03-sdlc-edition-1/prompt.md`. A + canon test fixture uses `DDD-dec-99` as a string, in `tools/canon/tests/Canon.Tests/IssueRefsTests.cs`. + Other branches carry copies of the same lines. +- **Stale note, reported and not changed:** S-6 in the canon-cli session left `94` to `99` to the + authority-profile session (`claude/bold-franklin-i7b16g`). That branch uses none of them. The + note is a session record and stays as written. + +This session uses `DDD-dec-94` and `DDD-dec-95`. If another id is needed, it takes the next free +one above `DDD-dec-118`, checked again when it is needed. + +## Scope + +In scope: `core/decisions/DDD-dec-94.yaml` and `-95.yaml`; `spec/doc-format.md`; every document +under `applications/`, for presentation only; this session record; and the session's row in +`meta/sessions/README.md`. + +Out of scope: any claim's statement, status or evidence; any rule in `applications/`, since a +rewrite that changes a rule is reported, not made; hashed vocabulary files (`what/ontology.ttl`, +`what/shapes.ttl`); `apparatus/` (successor A-2); landing. diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/applications-README.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/applications-README.md new file mode 100644 index 0000000..5092df3 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/applications-README.md @@ -0,0 +1,18 @@ +# Equivalence — `applications/README.md` + +Old: `84aa466:applications/README.md`. New: the working tree of this session. The writer's table, +not evidence of equivalence. + +| # | Old: rule, in brief | New: section | Note | +|---|---|---|---| +| 1 | "The framework denominated in a domain. Each application is a projection of the general principle, not a restatement of it." | What an application is | same | +| 2 | pdlc/: the product lifecycle, ruled (Rounds 28 to 30; `DDD-dec-114`); three owners and their holdings; pull system, option pool, three kinds of demand, responsibility per decision | folder table, `pdlc/` row; "Ruled"; ids to "Where this comes from" | same | +| 3 | sdlc/: the agentic/DAG design framework that was the whole of DDD through v3, "now correctly positioned as one projection of the actor-general core" | folder table, `sdlc/` row | same ("now positioned as") | +| 4 | Within the PDLC, the SDLC is the How owner's arrangement and a composite act; every SDLC act's layer path begins PDLC ▸ SDLC | `sdlc/` row | same | +| 5 | sdlc.md `[PROPOSED]`, `DDD-dec-115` | `sdlc/` row: "The SDLC specification (`sdlc.md`) is ruled" | register: `[PROPOSED]` -> ruled, by `DDD-dec-115` S-11 (Round 28; Round 30). Fact corrected: the old mark was wrong (release v0.7.0 F-2) | +| 6 | "The directories sit side by side, and the nesting is a relation in the act map, not a directory layout" | `sdlc/` row | same | +| 7 | organizations/: organisation design as a directory of four claims, `DDD-org-01..04`, all projected | `organizations/` row | same; ids to the table | +| 8 | Conservation of Specification Demand is what Conservation of Determination Demand is called when the actor is building software; that relationship is the structure the framework prescribes for itself | What an application is | same | +| 9 | (new) registers of the What, the How, the authority profile | `sdlc/` row | added: states each register as the decisions give it (conventions §4), and points to `sdlc/README.md` | +| 10 | (new) "ready to try, not ready to use" | after the table | added: `DDD-dec-74` | +| 11 | (new) how these documents are written; what they do not carry | sections of those names | added: the folder format (`DDD-dec-94`, `DDD-dec-95`) and the register phrases (Round 2) | diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/authority-vocabulary.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/authority-vocabulary.md new file mode 100644 index 0000000..3feb4bf --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/authority-vocabulary.md @@ -0,0 +1,15 @@ +# Equivalence — `applications/sdlc/authority-vocabulary.md` + +Old: `84aa466` (79 lines). New: 111 lines. + +| # | Old: rule, in brief | New | Note | +|---|---|---|---| +| 1 | Status: with authority.md (`DDD-dec-85`, `-86`); written 2026-11-02; not yet ratified | Opening, "How settled this is"; closing table | fact corrected: #45 merged | +| 2 | Namespace IRI and prefix, beside the How's and the What's | Namespace | same | +| 3 | UNVERIFIED — Emil review: no IRI under `/ns/sdlc` is served yet (M-10) | Namespace, *(Claude's reading, not yet confirmed by Emil)*; "How settled this is"; closing table | same register, in words; M-10 moved | +| 4 | In records, ruled F-2: one hashed member; never `extensions`; values objects/arrays/strings, `"yes"`, times as strings | In records | same; "Ruled (Round 1, F-2)" moved | +| 5 | The protocol's members (four bullets) | unchanged | same | +| 6 | §1 table, 23 rows | §1 | same, except three source citations moved: `mayDelegate`'s Q-8, `BaselineEntry`'s "how.md D-6" (now "`how.md`'s (decision, element, target)"), the violation description's `DDD-dec-52` | +| 7 | §2 computed terms, five rows | §2 | same | +| 8 | §3 Writ mapping: "As Writ's definition states them (`[D2]`, `[D2.5]`)"; seven rows; waiver row "(Round 1, Q-6)" | §3 | same; labels moved to the closing table | +| 9 | (new) ddd:doc block, opening paragraph, closing table | — | format | diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/authority.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/authority.md new file mode 100644 index 0000000..4fdbf76 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/authority.md @@ -0,0 +1,71 @@ +# Equivalence — `applications/sdlc/authority.md` + +Old: `84aa466:applications/sdlc/authority.md` (682 lines). New: the rewrite (730 lines). The +writer's table, not evidence of equivalence; the independent check is. + +| # | Old: section and rule, in brief | New: section | Note | +|---|---|---|---| +| 1 | Status banner: written 2026-11-02 to Round 1's plan, Appendix A ruled in Round 2, Q-11 and the re-founding in Round 3; "not yet ratified (Emil merges #45)"; session and decision ids | Opening, "How settled this is"; "Where this comes from" | fact corrected: #45 merged 2026-11-02, the ratification act the decisions name. Rounds and ids moved to the closing section | +| 2 | Profile is what `dpp-1.md` §9.4 leaves to adopters; says what makes a decision in force, who may make it so, how authority is founded, delegated, transferred | Opening | same | +| 3 | Register: after Round 3 no UNVERIFIED mark remains and nothing is open | "How settled this is" | same, in words | +| 4 | Section numbers are the ones `DDD-dec-86` cites | "Where this comes from" | moved; all numbers kept | +| 5 | Companions (vocabulary, evaluator, property run, worked example) | Opening, "Companions" | same | +| 6 | Who it binds: Writ implements; product-cli's draft log never claims it; a Context& package is a product under it | Opening | same | +| 7 | (new) Where to start, by task | Opening | added navigation only; no rule | +| 8 | (new) Executed over one hand-built example and generated histories; neither shows another implementation or a real log holds it | "How settled this is" | restates §8.3 and §9's own limits; no new claim | +| 9 | §1.1 all four bullets, "iff", "nothing else confers force" | §1.1 | same | +| 10 | §1.2 table, six rows; record row cited `DDD-dec-62`; attestations "a successor item (Round 1, Q-10)" | §1.2 | same; id and Q-10 moved to closing table. "later work, not this profile" for "a successor item" | +| 11 | §1.3 Ruled F-2 quote: signature-covered fields are top-level dotted members inside the canonical form; `extensions` only for what may change without a new version; nothing authority-bearing may | §1.3, "The rule:" | same words, unquoted; source in closing table | +| 12 | §1.3 four bullets (one member; inside hash and signature, `"yes"`; `extensions` display aids, read by no evaluation; `status` carries no force) | §1.3 | same | +| 13 | §1.4 table: ruling → decision, six rows | §1.4 (subjects); "Where this comes from" §1.4 row (decisions, and their supersessions by `DDD-dec-87`–`90`) | moved. The supersessions are added in the closing table; they are on main (`DDD-dec-87` keeps the definition) | +| 14 | §2.1 genesis definition, verbatim quote (`DDD-dec-46`) | §2.1 | same, quote kept verbatim ("The definition, as ruled:"), id moved | +| 15 | §2.1 a product is the decision space; What and realisation are scopes under one genesis; a package is a product with an empty What and its own genesis; in another product it is provenance, never authority (`DDD-dec-85`) | §2.1 | same | +| 16 | §2.2 "the genesis is founded, not accepted" (Q-1); four bullets: founding record names P (`DDD-dec-63` §1), `basedOn` empty; self-bound `firstKey`, also first key binding (ledger's D7, as it fits); no acceptance; one per product, second refused, `id` names it for life | §2.2 | same; `DDD-dec-63` §1 moved to closing table | +| 17 | §2.3 transfer is a decision, never an edit; steps 1–4, including "closing is not a revocation" (Q-2) and delegation from the genesis decision's `id` | §2.3 | same | +| 18 | §2.4 quoted rule: filed unavailability with a fallback holder who may act and may not transfer | §2.4, "The rule:" | same words | +| 19 | §2.4 five bullets, including A-6 quote "any grant may have a fallback, and a fallback delegates from its primary" | §2.4 | same; A-6 stated as a sentence, source moved | +| 20 | §2.5 quoted rule: loss with no fallback not repairable from inside; new genesis, new product, imports by `basedOn` | §2.5, "The rule:" | same | +| 21 | §2.5 Q-11: key loss is not holder loss; fallback is the pre-authorised party; A-9 genesis reading quoted; "Round 2's 'by transfer' is withdrawn" | §2.5 | same; the withdrawal stated as "the earlier reading, that such a holder gets a key by transfer, is withdrawn" | +| 22 | §2.5 four bullets (vouch; binding; no transfer; no path) | §2.5 | same | +| 23 | §2.6 adopting by founding the log; earlier records carry provenance, no force until landed and accepted; acme's stand-ins | §2.6 | same | +| 24 | §2.6 test fixtures re-founded once (A-5, P-9): four bullets | §2.6 | same; rulings moved | +| 25 | §3.1 scope definition and five bullets incl. derived kinds refused, `sdlc:Journey`, what a scope may name (three lists), grants choose | §3.1 | same | +| 26 | §3.2 Q-8 quote: delegates only if it says so, only a subset; six bullets | §3.2 | same | +| 27 | §3.3 Q-1: live only from grantee's acceptance; never imposed; three bullets | §3.3 | same | +| 28 | §3.4 two bullets | §3.4 | same | +| 29 | §3.5 four bullets incl. "the genesis is never revoked", chain below falls, what stands (G2) | §3.5 | same | +| 30 | §4.1 F-1 quote; six bullets incl. Draft 3's fields, A-10 | §4.1 | same; quote stated as "The rule:" | +| 31 | §4.2 scope at signing (quote), `touches` items, A-11 quote and "ruled as proposed", four sub-bullets, covering, multi-scope rule (quote, kept quoted) | §4.2 | same; "It is ruled as proposed" moved to the closing table (decided is the default) | +| 32 | §4.3 baseline quote; five bullets; entry is `how.md` D-6's triple; Writ `[D2]`, G11 | §4.3 | same; "D-6" moved to closing table, `how.md`'s triple kept | +| 33 | §4.4 waiver quote; five bullets; Q-6 quote "expiry is a header-clock time, and Writ follows"; "iff", "must expire after" | §4.4 | same | +| 34 | §4.5 three bullets (Q-4) | §4.5 | same | +| 35 | §4.6 Q-2 quote; three bullets | §4.6 | same | +| 36 | §4.7 definition 1–3 with "iff"; "Force is local" quote; three bullets | §4.7 | same; the quote became the bold lead sentence, same words | +| 37 | §5.1 machine (four sub-bullets), `attributedTo` refusal, recorded, human, grant as attestation, weakest point | §5.1 | same | +| 38 | §5.2 team not a holder | §5.2 | same | +| 39 | §5.3 bindings (4), first key (3), key-binding acts (4, with A-9 and Q-11), `since` (3), order within a position | §5.3 | same; "ruled, Round 2, A-9" and "Round 3, Q-11" moved | +| 40 | §6.1 header members (six), header hash coverage, Writ `[D2.5]` | §6.1 | same; `[D2.5]` moved, the quote kept | +| 41 | §6.2 header clocks only; `at` never read for force; A-8 refusal and precision rule; `[D2.11]` as Emil states it (four bullets); why a time (quote, `[D2.3]`), Writ amended (Emil's act) | §6.2 | same; Writ's own labels `[D2.11]`, `[D2.3]` kept as the subject | +| 42 | §6.3 three statements; "(charter)" | §6.3 | same; "(charter)" moved | +| 43 | §7 five bullets; `DDD-dec-52` names the field, verdict computed never stored | §7 | same; "the field a decision carries to say what violates it" replaces "the field `DDD-dec-52` names on a decision" | +| 44 | §8.1 four bullets; Writ `[D2.5]` | §8.1 | same | +| 45 | §8.2 table A1–A13, properties verbatim | §8.2 | same; the "Mirrors" column's ruling ids (Q-1, Q-2, Q-3, Q-6, Q-8, `DDD-dec-46`) replaced by the rule's name and section, and listed in the closing table. G-numbers kept | +| 46 | §8.3 evaluator, histories, output, eight mutations, "Not Writ's suite" | §8.3 | same | +| 47 | §9 intro "(Round 1, Q-9)"; "Every key is a throwaway test key" | §9 | fact corrected: the keys are kept for the fixture's life (§9's own bullet, test-keys README, `DDD-dec-92`); "throwaway" contradicted that | +| 48 | §9 table p1–p16 | §9 | same; p16 "(`DDD-dec-113`, E-5)" moved | +| 49 | §9 what `check.py` verifies (six bullets) | §9 | same | +| 50 | §9 what it shows and does not; verdicts' date; keys (P-6 quote and four bullets, session `rulings.md`, P-9) | §9 | same; quote stated as "kept for the fixture's life"; sources moved | +| 51 | Appendix A intro and table A-1 to A-15 | Appendix A | same; the intro restated without decision ids. The row labels and State column are kept: records cite "Appendix A, A-5" | +| 52 | Appendix B intro and twelve rows | Appendix B | same, except: "Why" column ruling ids (Q-1, Q-2, Q-3, P-7) moved to the closing table | +| 53 | Appendix B roles row: "dropped … A role is a name for a scope nobody evaluates" | Appendix B | **added note**: `DDD-dec-117` (2026-11-08) amends this row (roles carried, a role is an evaluated reusable scope, scopes range over decision kinds). The old text did not reflect it. The note states the decided amendment and says the text has not been reworked; reworking §3 to it is that session's successor work, not this rewrite's | + +## Not restated + +None. Every rule of the old text is in the new one. + +## Findings for the parent + +- F-a. The old text's status ("not yet ratified") was stale: #45 merged. +- F-b. "Every key is a throwaway test key" (§9) contradicted the kept-keys ruling. Corrected. +- F-c. `DDD-dec-117` amends Appendix B and widens scopes to decision kinds. Main's text had not + applied it. Flagged in place, not applied (§3.1 is unchanged). diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/how-examples-README.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/how-examples-README.md new file mode 100644 index 0000000..cce1840 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/how-examples-README.md @@ -0,0 +1,34 @@ +# Equivalence — `applications/sdlc/how-examples/README.md` + +Old: `84aa466`. New: this session's working tree. The sections are reordered for a reader who +wants to run the example first: run, cast, decisions, targets, facts, checks; the history last. + +| # | Old: rule or statement, in brief | New: section | Note | +|---|---|---|---| +| 1 | Companion to how.md §12; every record `dpp/1` (token `DDD-dec-62`, superseding `-53`), pinned by the hash law; built by build.py, checked by check.py | opening | same; ids to the table | +| 2 | Version 1 records accepted provisionally (ruling 4); to be "superseded by a version against the real identifiers, never edited"; the What has landed in the identity form (`DDD-dec-63`) | How the records came to be: Superseded against the landed What | same; ruling and decision ids to the table | +| 3 | Version 2 records: `GEN`, `GRANT-how`, both `TGT-*`, all four `IMP-*`, `ACC-1`; and the vendor's `REST`; `REL@3` ships it | same | same | +| 4 | Nothing edited; build.py refuses to build if it would change one | same | same | +| 5 | The landed What is read; `what/acme-shop.ttl` is provisional history, no longer read | same | same | +| 6 | New readings `facts/*.r2.ttl`; `r1` files stay, unread | same | same | +| 7 | `DDD-dec-65` to `-71` supersede `-55` to `-61` on the same terms | same ("The How's decisions were superseded on the same terms"); ids in the table | same | +| 8 | The What itself as decisions: `GRANT-what@1`, `WHAT-found@1`, `ACC-what@1`, `what@1` | same | same | +| 9 | Version 1's pins still hold and are checked, as history. Still a test product; nothing acceptable into a real product | same; How settled this is | same | +| 10 | The provisional-to-landed table | same | same, verbatim; "ruling 1" written "the anchor rule" | +| 11 | Under the authority profile: a positioned log with **16 positions**; 25 records added, none edited | Under the authority profile (2026-11-02): "On 2026-11-02 it had 15 positions, and 25 records were added" | fact corrected: #45 shipped 15 positions; p16 (`SCN@1`) came with sdlc edition 1 on 2026-11-06 (`8a5b4e9`). The old text listed `SCN@1` inside the 2026-11-02 list | +| 12 | The list: `GEN@3` and the vendor's `GEN@2`; grants; re-acceptances with a baseline; `CUR@1` and `what@4`; delegation and revocation; rotation; waiver; review; two refusals | same | same; A-5, P-9 to the table. The old text's missing full stop after "signed" restored | +| 13 | `SCN@1` at p16: creates the scenario for (Place order, Customer), fills four descriptions, no findings under edition 1; `what@5`; `what@3` and `what@4` keep their edition hash | sdlc edition 1 (2026-11-06) | same; "accepted by `ACC-scn-what@1`" added, from `records/acme/ACC-scn-what` | +| 14 | Stand-in records stay as history, at no position, put nothing in force; build.py needs rdflib; refuses to rewrite a landed header; keys kept in `test-keys/`, never used outside; a rebuild reproduces every record; a later session can extend | Under the authority profile, last paragraph | same | +| 15 | The run command; "225 ok or note lines, 1 expected warning, 0 failures. All 64 records (26 of them written on 2026-11-02)" | Run it | fact corrected by a fresh run: 238 ok or note lines, 1 expected warning, 0 failures; 67 of 67 records conformant. 27 records date from 2026-11-02 (25 + `what@3` + vendor `GEN@2`), not 26; three added 2026-11-06 | +| 16 | Rebuilt with `dpp/1` and fresh keys on 2026-10-28; the `decprov/1` set never conformant, at `d11df86`; build.py refuses if the token and `DDD-dec-62` disagree; without rdflib, SKIP, never passed | Run it | same; "the ruled token" for `DDD-dec-62` | +| 17 | The cast table | The cast | same, verbatim | +| 18 | Throwaway keys for v1/v2; since Round 2 of 2026-11-02, keys kept in `test-keys/`; no real key ever used or held by a session (Round 3, ruling 1); `ssh-sig`, namespace `decision-provenance` | The cast | same; round numbers to the table | +| 19 | The three decisions, held once, no target named; check.py checks it; the decisions table | The three decisions, written once | same, verbatim | +| 20 | `REST@2`: a binding at `POST /commands/{wire name}`, the third "specified once" check; supersedes `REST@1`; anchored at the bounded context; reads the wire name, ruled in Round 2 (`DDD-dec-64`, P-1: "REST@2 stands") | same | same; "So Acme Shop imports four How decisions" added, verified against `records/acme/IMP-*` and check.py ("four imports") | +| 21 | `what@3` supersedes `what@2`, which superseded `what@1`; each kept the graph and renamed the edition by the hash of the files as amended before edition 1 was tagged; `what@2`'s pin held to `655db92`; `what@1`'s pin the files at `2c4f276` | What-versions 2 and 3 | same; the old paragraph's repetition merged | +| 22 | `REL@2` supersedes the layer rule with `LAYER@2` (adds `test`); the importer still rests on version 1; check.py shows it; nothing in force changed | The three decisions, written once | same | +| 23 | Two targets each; the two fact-term tables | Two targets each | same, verbatim | +| 24 | The facts, hand-written; manifest; What graph in `what/` provisional too (how.md §1.2); planted-defect table | The facts, and what is hand-written | same, verbatim | +| 25 | Expectations analytic, not evidence; "It shows nothing about whether the How is right" | same; How settled this is | same | +| 26 | `RESID@1` requires both provenance values | same | same | +| 27 | What check.py checks, 1 to 9 | What `check.py` checks | same, verbatim except item 8: "(ruling 1)" removed, "The ruling calls" became "The anchor rule calls" | diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/how-vocabulary.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/how-vocabulary.md new file mode 100644 index 0000000..898a983 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/how-vocabulary.md @@ -0,0 +1,22 @@ +# Equivalence — `applications/sdlc/how-vocabulary.md` + +Old: `84aa466:applications/sdlc/how-vocabulary.md` (113 lines). New: this branch (151 lines). The +writer's table, not evidence of equivalence. Sections 1 to 4 keep their numbers and order. + +| # | Old: section and rule, in brief | New: section | Note | +|---|---|---|---| +| 1 | Status: "ruled in part … not yet ratified … the rest stands as proposed until the merge" | Opening, "How settled this is" | fact corrected (PR #41 merged); register: the rest -> decided, by `DDD-dec-119` (which names this file) | +| 2 | Namespace; Writ ADR 0007; the path reasoning; "`UNVERIFIED — Emil review`: no IRI under `/ns/sdlc` is served or registered yet, and the choice is Emil's" | Namespace; Not settled yet | same register: *(Claude's reading, not yet confirmed by Emil)* | +| 3 | In records: one hashed dotted member; reverse domain; authority fields in `…authority`; violation description in the profile; none of the authority fields; objects, arrays, strings only | In records | same; `DDD-dec-62`, `DDD-dec-52` moved to "Where this comes from" | +| 4 | Three kinds of term; "What terms: provisional, read from PF v1.10.0 §3, owned by the move" | Three kinds of term | fact corrected: the What has moved; "defined by the What, read here (§3)" | +| 5 | §1, every term row | §1 | same; inline "*Ruled* (2026-10-28)", "(ruled 2026-10-28, Round 2)", "(ruling 3)" removed: decided is unmarked, sources in "Where this comes from". `sdlc:Package` quote kept as a quote | +| 6 | §1 baseline entry and waiver rows, dated "2026-11-02" | §1 | date removed from the cross-references | +| 7 | §1 `sdlc:Reading` "demand on Writ (D-3)" | §1 | "(`how.md` §9.4, D-3)": the reference made findable | +| 8 | §2 fact terms and the derived terms; "`check.py` holds the same list" | §2 | same. Not re-verified: `check.py` derives the needed terms from decision text and checks them against each edition's `facts`; it does not hold a literal list | +| 9 | §3 "What terms — provisional, the move's": the list including `sdlc:localId`; "when the move lands they become pinned references" | §3 | fact corrected: defined in `what/ontology.ttl` (checked: Product, Domain, System, Decider, Command, QualityDemand, within, referencesDomain, AIO, context of use, content key, `sdlc:locale`); `sdlc:localId` is not in the ontology and is named as the provisional term `REST@1` read and `REST@2` replaced with `sdlc:wireName`. The PF section numbers moved to "Where this comes from" | +| 10 | §4 heading "— Writ's page is not written; Draft 2 is cited as Emil states it" | §4 | the heading's clause moved to a sentence under it | +| 11 | §4 table, "(ruled 2026-10-28 …)" annotations | §4 | annotations removed; content same | + +## Could not restate + +None. diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/how.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/how.md new file mode 100644 index 0000000..0789d6a --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/how.md @@ -0,0 +1,63 @@ +# Equivalence — `applications/sdlc/how.md` + +Old: `84aa466:applications/sdlc/how.md` (705 lines). New: this branch (754 lines). The writer's +table. It is not evidence of equivalence; the independent check is. + +Section numbers 1 to 13, Appendix A and Appendix B are unchanged, in the same order. + +| # | Old: section and rule, in brief | New: section | Note | +|---|---|---|---| +| 1 | Banner: "ruled in part, 2026-10-28; not yet ratified"; "what was not ruled separately stays `[PROPOSED]` until the merge" | Opening, "How settled this is" | fact corrected (PR #41 merged); register: every "not ruled separately" part `[PROPOSED]` -> decided, by `DDD-dec-119` | +| 2 | Register legend (*Ruled*, `[PROPOSED]`, `[OPEN]`, `UNVERIFIED`) | conventions phrases; "Where this comes from" | removed: replaced by the format's phrases | +| 3 | Companions | Companions | same | +| 4 | §1.1 the not-here table, eight rows | §1.1 | same; ids and old section numbers moved to "Where this comes from" | +| 5 | §1.2 updates of 2026-11-02 and 2026-10-28; four preconditions; ruling 4's three conditions on provisional IRIs; the token history | §1.2, restructured as "preconditions, and how each was discharged" | same content; precondition 3's "stands until the authority profile's PR" was already overtaken by the old text's own 2026-11-02 update. "The text below is left as written" removed: history | +| 6 | §2 thesis quote; verdict "holds with four repairs"; three accepted, one corrected ("unknown" -> open question) | §2 | same | +| 7 | §2 table row 2: the anchor reading, "`UNVERIFIED — Emil review`" | §2 table | register: `UNVERIFIED` -> decided. The old text's own §3 says the reading is ruled as proposed (`DDD-dec-55` ruling 1), and `DDD-dec-55`'s statement states it. The mark was stale | +| 8 | §2 other rows | §2 | same | +| 9 | §2 naming repair: binding; Writ adopts; `writ:realisation` never minted; "expressible"; realisation scope left as ruled | §2 | same; the quoted ruling sentence restated as a plain sentence with the same content | +| 10 | §2 "Writ narrows, the How does not widen"; three kinds onto Writ | §2 | same | +| 11 | §3 anchor rule; the reading quote; points 1–5; the checker warning and its advisory limit; empty-What adoption; Varve | §3 | same. Quote "the checker should warn on that" restated as "the checker warns on that" (point 3 already says the checker warns) | +| 12 | (none) | §3, *In Acme Shop* | new example sentence, checked against `how-examples/README.md` (the landed What puts Deciders and Commands in the Ordering bounded context) and `IMP-pure@2`, `IMP-rest@2` anchors | +| 13 | §4.1 members; SPARQL `SELECT` form; `?anchor`, `?target`; provenance; verdicts never stored | §4.1 | same. Cross-reference "`how-vocabulary.md` §3" corrected to §1, where record shapes are (§3 is the What terms): fact corrected | +| 14 | §4.2 table, "Worked: `PURE@1`, `REST@1`" | §4.2 table | fact corrected: `REST@2` supersedes `REST@1` and is the record the checker evaluates | +| 15 | §4.2 constraint, binding, contract paragraphs; no-orphans; guards 1 and 2 | §4.2 | same; "old §4.3" etc. replaced by "the old How's layout model" etc. | +| 16 | §4.2 contract: "as `RESID@1` anchors to `qd-residency-eu`" | §4.2 | restated: "as `RESID@1` is imported at the residency quality demand" (the import, `IMP-resid@2`, carries that anchor; `RESID@1` itself anchors to the package product) | +| 17 | §4.3 "`[PROPOSED]`: not a kind"; idle report; two record types | §4.3 | register: `[PROPOSED]` -> decided, by `DDD-dec-119` (`DDD-dec-55`'s list) | +| 18 | §4.4 no split, three bullets | §4.4 | same | +| 19 | §5.1 three sorts of target; "targets, not catalogues" (ruled) and four bullets | §5.1 | same | +| 20 | §5.1 "`[PROPOSED]`, not ruled separately: the rest of this section and §5.2" | §5.1, §5.2 | register: `[PROPOSED]` -> decided, by `DDD-dec-119` (`DDD-dec-57`'s list) | +| 21 | §5.1 interface standards; "as `REST@1` names `POST`" | §5.1 | same; `REST@2` (fact corrected) | +| 22 | §5.2 "`[PROPOSED]`" four allowed term sets; never a language term; editions; derived shape; expressible iff; table; where it would fail; purity approximate | §5.2 | register: `[PROPOSED]` -> decided, by `DDD-dec-119`; table row `REST@2` (fact corrected); "(H-14)" -> "(Appendix A)" | +| 23 | §6 package as product with genesis; provenance never authority; contents table; tightening; no What; superseded clause | §6 | same | +| 24 | §6 "`[OPEN]`: whether the old §3.2.2 'an adopter may register AIOs' survives the move" | §6 | same register: *(open)*, listed in "Not settled yet" | +| 25 | §7.1 "*Ruled*: … enter by import"; "`[PROPOSED]`. An import has three parts" | §7.1 | register: `[PROPOSED]` -> decided. The three parts are in `DDD-dec-59`'s statement; narrow-never-alter is in its list, ratified by `DDD-dec-119` | +| 26 | §7.2 "`[PROPOSED]`, the proposal kept, with one condition"; the recorded-reading condition | §7.2 | register: `[PROPOSED]` -> decided, by `DDD-dec-119` (`DDD-dec-59`'s list). "(§6.4)" written "(protocol §6.4)": it is the protocol's section | +| 27 | §7.3 withdrawal (ruled); obliges, does not do, teeth | §7.3 | same | +| 28 | §8.1 "`[PROPOSED]`, the proposal kept": the generalised obligation, three outcomes | §8.1 | register: `[PROPOSED]` -> decided. `DDD-dec-58`'s statement rules it; `DDD-dec-119` also lists it | +| 29 | §8.1 `PURE@1` and `REST@1` show it | §8.1 | `REST@2` (fact corrected) | +| 30 | §8.2 two kinds of gap, ruled as proposed; table | §8.2 | same | +| 31 | §8.2 "A waiver, as the authority profile will define it" | §8.2 | fact corrected: "defines it"; the profile is written (authority.md §4.4, which also says a waiver never covers a coverage gap) | +| 32 | §8.2 "`UNVERIFIED — Emil review`: the ratchet semantics of baseline are assumed here, because the profile is not written" | §8.2; Not settled yet | same register: *(Claude's reading, not yet confirmed by Emil)*. "because the profile is not written" restated as "assumed here before the profile was written". Not-settled entry notes authority.md §4.3 now states baselines | +| 33 | §8.2 `DDD-dec-45`'s consequence "(Claude's reading, not ruled)" | §8.2; Not settled yet | same register | +| 34 | §8.3 the other direction | §8.3 | same | +| 35 | §9.1 table of what Writ must hold | §9.1 | same | +| 36 | §9.2 provenance set and the two added values; the reading table; manifest | §9.2 | same; the quoted "two provenance values, not two inputs" restated plainly | +| 37 | §9.3 gap and open question; freshness bound; open question can block; drift | §9.3 | same | +| 38 | §9.4 D-1 to D-8 | §9.4 | same; heading's "not resolved here" dropped (four of eight are answered). D-3 "still open" -> "still a demand, not yet met" (not a register mark). D-8: fact corrected, marked answered, as §1.2 already said | +| 39 | §10 generation out of scope, ruled; the condition | §10 | the condition: register (`DDD-dec-61` "stands as proposed") -> decided, by `DDD-dec-119` | +| 40 | §11 "`[PROPOSED]`." one level, six conditions; what it does not claim | §11 | register: `[PROPOSED]` -> decided, by `DDD-dec-119` (through how.md's banner; `DDD-dec-119` notes flag that reading) | +| 41 | §12 worked decisions paragraph and table: anchors `acme:product`, `acme:domain-ordering` (×2), `acme:qd-residency-eu`; `REST@1` | §12 | fact corrected: the in-force imports are `IMP-*@2`, anchored at the product node, the Ordering bounded context (×2) and the residency quality demand; `REST@2`. Verdicts re-checked against `check.py` output: LAYER 1+1, PURE TS 1 / C# 0, REST TS 1 / C# 0, RESID AWS 1+1, Azure observed open question | +| 42 | §13 "Not ruled separately … stand as proposed until the merge ratifies them" (four bullets); `[OPEN]` adopter kinds | §13 | register: the four bullets -> decided, by `DDD-dec-119`; restated as ratified. `[OPEN]` kept; the two Claude's readings of §8.2 added to the list (they were marked in the body, not listed) | +| 43 | Appendix A table H-1 to H-17 | Appendix A | same rows; ids in the Decision column kept (the column is the subject) | +| 44 | Appendix A "Not ruled separately: H-3, H-8, H-9, H-11, H-12, H-13 and H-17. They stand as proposed until the merge" | Appendix A, "Ratified by the merge" | register -> decided, by `DDD-dec-119`; also names the rest of H-4, H-15's condition and the kept-unlisted proposals, all in `DDD-dec-119`'s inventory | +| 45 | Appendix B | Appendix B | same; `REST@2` added beside `REST@1` (fact) | + +## Could not restate + +None. + +## Not changed, though questionable + +- §1.1 "Delivery … drift (old §7)" and §9.3 "drift" use the same word for two things (old + delivery drift; declared-versus-observed drift). Kept, as in the old text. diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/organizations-README.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/organizations-README.md new file mode 100644 index 0000000..e54b229 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/organizations-README.md @@ -0,0 +1,16 @@ +# Equivalence — `applications/organizations/README.md` + +Old: `84aa466`. New: this session's working tree. + +| # | Old: rule, in brief | New: section | Note | +|---|---|---|---| +| 1 | A directory, not a repository (`DDD-dec-05`): four claims, no documents of its own yet | opening | same; id to the table | +| 2 | "Promotion to a repository requires core-like documents and an identified external checker — not before." | opening | same ("core-like", "external", "not before" kept; #48 trap F2.10) | +| 3 | The claims exactly as in `core/claims/`, statements and falsifiers only, no new prose | the paragraph before §1; four sections | same. Statements and falsifiers checked byte-exact against the claim files by script | +| 4 | All four projected | How settled this is; each section "Projected" | same | +| 5 | "session-authored (flagged `UNVERIFIED — Emil review` in their claim files)" | How settled this is: "session-authored"; closing note | fact corrected: the claim files carry no such flag; `DDD-dec-40` ratified all four as projected on 2026-10-26. "Session-authored" kept (their notes say it) | +| 6 | They rest on principle-layer claims pinned upstream in `graph/upstream.yaml` | How settled this is; the table | same | +| 7 | Nothing here is canon | How settled this is | same | +| 8 | Headings: "graph discipline predicts organisational outcomes"; "statused Stable Dependency Principle"; "priority as a governed decision"; "cross-domain retrodiction of institutional discipline" | §1 to §4 headings | reworded plainly, no stronger than the claims (#48 trap F2.9); ids moved to the table | +| 9 | "**Falsifier.**" | "**It is wrong if:**", followed by the falsifier verbatim | same; "or" kept in org-03 and org-04 because the text is verbatim (#48 trap F2.1) | +| 10 | (new) "predictions that have not been tested, not findings" | How settled this is | added: what "projected" means for an empirical claim with `evidence: []` | diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/pdlc-README.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/pdlc-README.md new file mode 100644 index 0000000..b22ee70 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/pdlc-README.md @@ -0,0 +1,15 @@ +# Equivalence — `applications/pdlc/README.md` + +Old: `84aa466:applications/pdlc/README.md` (39 lines). The writer's table. + +| # | Old: rule, in brief | New | Note | +|---|---|---|---| +| 1 | The three owners and what each holds | Same list | same; rounds moved to "Where this comes from" | +| 2 | The SDLC is a composite act within the PDLC | same | same; id and rounds moved | +| 3 | Register: ruled (Rounds 28 to 30); construction ruled item by item; forecast settled in Rounds 29 and 30 | "How settled this is" | same in words; "Nothing here has run on a real product yet" added from pdlc.md §0 (third weakness) | +| 4 | Index table, "ruled (Rounds 28 to 30)" and "ruled (Round 28, R30)" | Index table, "decided" | same | +| 5 | The What stays in what.md where `DDD-dec-42` placed it; owned here; read as ground (Round 8) | same | same; ids moved | +| 6 | The SDLC beside, not inside; nesting a relation in the act map. "Whether the directory should one day nest is open (`pdlc.md` §13, O-1)" | "has been decided: it does not (`pdlc.md` §15, O-1)" | **fact corrected.** O-1 is in §15, not §13, and pdlc.md marks it closed (Round 28, R9) | +| 7 | Authority: authority.md §2–3 | same | same | +| 8 | Not Delivery: `DDD-dec-42` O-2 retired it; no releases, versions or timeline as artefacts; ordering and delivery recorded; forecasts computed | same | same; "retired when the What moved here" (`DDD-dec-42` is the What's placement decision); id moved | +| 9 | Run commands | same | same | diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/pdlc.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/pdlc.md new file mode 100644 index 0000000..32759b5 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/pdlc.md @@ -0,0 +1,59 @@ +# Equivalence — `applications/pdlc/pdlc.md` + +Old: `84aa466:applications/pdlc/pdlc.md` (676 lines). New: this session's rewrite. The writer's +table. It is not evidence of equivalence; the independent check is. + +Throughout: round numbers, R-numbers, option labels ("(Recommended)") and decision ids moved from +running prose to "Where this comes from", keyed by section (`removed: history`, grouped). Every +numbered section keeps its number, order and file. The `ddd:ref` block is unchanged. The column +"Ruled by" of §2's table moved to the closing table. + +| # | Old: section and rule, in brief | New: section | Note | +|---|---|---|---| +| 1 | Register banner: ruled (Rounds 28–30); exposition of the decision; prose no listed item covers is exposition; where text and decision disagree, the decision governs | Opening "How settled this is"; "Where this comes from" | same; rounds moved | +| 2 | §0 owners are the projection's; canon names no roles; method step 7 `[PROPOSED]`; placement fails if a decision cannot be split | §0 | same; `[PROPOSED]` → *(proposed, not yet ruled)* | +| 3 | §0 two proposed What elements; until in schema, prose; capability the only thing; classification pin, backstop not guard | §0 | same. "proposed What elements" → "What elements that do not exist yet ... form is decided" (the old §3/§4 say "form ruled, Round 28") | +| 4 | §0 third weakness empirical; record from edition 1 | §0 | same; `DDD-dec-115` → sdlc.md §13 | +| 5 | §1 stance quote (ruled wording) | §1 | same words, unquoted | +| 6 | §1 quality constraints; implementation assurance the How's own; duty; forecast computed; measures DORA keys | §1 | same | +| 7 | §1 Round 29 quote (certainty → best, worst, median; estimate; spread narrows with How performance; probabilistic forecasting) | §1 "The computation" | restated plainly; quote moved to closing table | +| 8 | §1 inputs, flow time definition, Kanban quotes, two differences, not DORA lead time | §1 | same | +| 9 | §1 Monte Carlo ≥1000 trials; percentiles 15/50/85; same method/seed; started issues by flow time; spread; encoded check numbers 5/12/23/18 invented; capacity shared (lower λ); when it changes; landing dark | §1 | same | +| 10 | §1 departure paragraph, with Round 6 quote | §1 | quote restated: "Many have the idea that delivery can affect when ... But it is the How owner's responsibility ..." | +| 11 | §2 scope under genesis grant; several holders; What owner = holder of covering scope; table of owners | §2 | same; "Ruled by" column moved | +| 12 | §2 When owner is go-to-market; How owner understands digital product development (capability, classification pin) | §2 | same | +| 13 | §2 Ground quote (Round 14) and rule | §2 "Ground" | restated: "its own to control, but the seams between them supply some to each" | +| 14 | §2.1 "The prompt asks that every row be..." | §2.1 | stated as the check criterion (extracted from deliberation) | +| 15 | §2.1 "Rows 1 to 8 are Round 14's table, not ruled. Telemetry row ruled. Last two Claude's additions from Round 22" | §2.1; "Not settled yet" | register kept: rows 1–8 not ruled, listed in "Not settled yet". oS and telemetry rows ruled. Last two rows: "Claude's additions", ruled status not asserted either way (as old) | +| 16 | §2.1 table, 11 rows | §2.1 | same; round mentions in cells removed ("since Round 28" → "now that oS exists"; "(fixed in the first session)" → "(fixed when the map was first drawn)") | +| 17 | §2.1 Finding F-2, order o0→o2a→o1→o1b→o2b | §2.1 "The order of o1 and o2a" | same; finding number moved | +| 18 | §2.1 falsifier: ground two owners write; issue thread; toggle | §2.1 | same | +| 19 | §3 Round 18 quote; o1 frames full ground and tolerance; what.md §1.1 quote; table at `1ab1de0` | §3 | quote restated plainly; rest same; "form ruled, Round 28" → "form decided" | +| 20 | §3 the meter | §3 | same | +| 21 | §4 Round 19 quote; assurance a coordinate of the `DDD-frame-01` tuple | §4 | restated; id moved | +| 22 | §4 table | §4 | same; round mentions in cells removed | +| 23 | §4 product assurance decides two things | §4 | same | +| 24 | §4 declaration: located, inherited downward, two levels observed/evidenced; not o9/o10/independence; Round 19 corrects Round 18 | §4 | same; correction stated without round numbers | +| 25 | §4 guard: outcomes read across seams; lowered verification shows; if neither moves, no value, may keep tuning down; withdrawn falsifier, replacement §14.4 | §4 | same | +| 26 | §5 Round 16 quote | §5 | restated plainly | +| 27 | §5 table; method step 10 `[PROPOSED]` | §5 | same; *(proposed, not yet ruled)* | +| 28 | §5 Round 17 quote; form: located, declares, not a quality demand (two kinds quote), How side contract over telemetry (how.md H-9, dec-60 superseded by dec-70), presence checked, its own decision | §5 | quote restated; "how.md's H-9" → "how.md §4.2" (H-9's subject is in §4.2); ids moved | +| 29 | §5 capability pin and guard (Claude's reading, ruled R26) | §5 | same; `term:capability` moved to basis | +| 30 | §6 placement per decision, not role; argument with core/05 §5 quotes; table; three rules; relative importance; answerability per owner | §6 | same | +| 31 | §6 mapping to step 7 (ruled R28; step itself `[PROPOSED]`); five items; "Canon names no owner roles. This mapping is Claude's." | §6 | same; "Claude's, not canon's" | +| 32 | §6 falsifier | §6 | same | +| 33 | §7 four loci; declared on the issue; dispatcher refuses an issue without one; tuple | §7 | same; `DDD-frame-01` moved | +| 34 | §7 table (tools never change the What, `DDD-dec-42` O-5) | §7 | same; id moved | +| 35 | §7 locus and kind; planning not a locus; time is the causal index (`DDD-address-01`); derived and chosen order; task not a locus | §7 | same; id moved | +| 36 | §8 Round 12 quote; Round 22 sharpening | §8 | restated: "A product owner owning the priority is inherently wrong: priority is a When decision" | +| 37 | §8 Scrum Guide quotes; the departure (four points); one person may hold both, acts kept apart; genesis holder reviews; falsifier | §8 | same | +| 38 | §9 Round 22 quotes; kinds adopted; What owner classifies | §9 | restated plainly | +| 39 | §9 two tables; why the backlog struggles; classification verdict and shape; what the When owner sees; guard from both sides; flow diagram; owed fix and `lc:restores`; two falsifiers | §9 | same; "(Round 20's guard applied ...)" → "(the outcome guard of §4, applied ...)" | +| 40 | §10 pull system; o0; Round 11's reading superseded by Round 22 for the How owner | §10 | same, rounds moved ("An earlier reading ... Under the three kinds of demand ...") | +| 41 | §10 outcomes only; exits recorded; shape; metrics; worked pool; Round 26 removed the How option, issue #104; OptionShape refuses non-new; falsifiers | §10 | same; "Round 26 removed it" → "It was removed" | +| 42 | §11 acts, oS, oG, kind-scoped dependencies, o14/o15 not reused | §11 | same | +| 43 | §12 toggles ruled (Round 5; constraint, Round 10); four bullets | §12 | same; an opening sentence states the two rulings in words | +| 44 | §13 composite act; table (`DDD-dec-115` S-6, S-10 → sdlc.md §13, §18); nothing else crosses; seam's price; quote; mechanism, poisonable centre, escape, meter | §13 | same; ids → sections | +| 45 | §14 twelve falsifiers; falsifier 3's ruled test; falsifier 4 replaces the old one | §14 | same; "Ruled (Round 30):" → "The test:" | +| 46 | §15 O-1 to O-9 with closures | §15 | same; closures stated without round labels. O-2 keeps `DDD-org-03` (the id is the subject). O-6 and O-8 marked *(open)*, as their "Closes it" column already said | +| 47 | — | "Not settled yet" (new section) | collects steps 7 and 10, rows 1–8, O-6, O-8; no new content | diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/product-definition.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/product-definition.md new file mode 100644 index 0000000..8cd3eb9 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/product-definition.md @@ -0,0 +1,41 @@ +# Equivalence — `applications/sdlc/product-cli/product-definition.md` + +Old text: `84aa466:applications/sdlc/product-cli/product-definition.md`. New text: same path. Every +chapter number and section heading is kept. The rewrite moves the inline ruling markers +(`[D1.n]` with their dates), decision ids, ADR numbers and item numbers (P-, R-, E-, M-) out of the +running prose into "Where this comes from", keyed by chapter and section. No sentence of the body +changes otherwise, except the rows below. #48 did not rewrite this document (it was not on +#48's base). + +| # | Old: section and rule, in brief | New: section | Note | +|---|---|---|---| +| 1 | Header: "Draft 4, 2026-11-03 (Draft 3 ...; Draft 1, 2026-10-21)" | "How settled this is" (Draft 4, of 2026-11-03); the draft history in "Where this comes from" | moved | +| 2 | Header: written outside-in; chapters 1 to 6 are the product; chapter 7 may change without the product changing | Opening, second paragraph | same | +| 3 | Header: the definition replaces the Rust workspace; it lives here; tool, ADRs, tests in product-cli; carry-over in ch. 8; "it was like that before" is not a reason | Opening, first paragraph | same; `[D1.24]` moved | +| 4 | Header: rulings marked `[D1.n]`; Drafts 2 and 3 add D1.2–D1.15 (ADR-0010–0012, on `dpp/1` 1.0 draft of 2026-10-27); Draft 4 adds D1.16–D1.25 from gate checks A1–A8 against the named commits; D1.24 supersedes D1.23; D1.25 adds step 0; superseded rulings keep their number and the text states the ruling in force | "Where this comes from", "Drafts" paragraph; "How settled this is" | moved; the rule "the text states the ruling in force" kept in both places | +| 5 | Every inline `[D1.n]` marker with its date (D1.1–D1.25, including "amended by" and "superseding" notes) | "Where this comes from", one row per section | moved; each marker's supersession note kept in its row (D1.3 by D1.16; D1.7 and D1.14 superseded; D1.9 by D1.20; D1.4 by D1.18 and D1.21; D1.23 by D1.24; D1.22 amending Draft 3's clause) | +| 6 | Ch. 3 "**Open.** Some kinds are in the vocabulary but have no `domain new` kind ... Either they gain kinds, or the definition names the verb" | Ch. 3 "*(open)*"; "Not settled yet" | same register, in the ruled phrase | +| 7 | Ch. 3 interactions, fields, state annotations, content keys "are elements by `DDD-dec-64` P-3" | "which are elements by the rule \"anything a binding, a baseline, reads, a scope key or a wire request names is an element\"" | same; P-3 quoted verbatim, as a short test, id in the table | +| 8 | Ch. 3 MCP "by elicitation answered by the author (D1.15)" | "(\"Adopting on the fly\")" | same; the cross-reference names the section that states D1.15 | +| 9 | Ch. 4 "Element identity is the ruled form of `DDD-dec-63`" | "the What's ruled identity form (`what.md` §2.2 and §2.3)" | same; id in the table | +| 10 | Ch. 4 "as `DDD-dec-72` rules" (edition pinned by versionIRI and hash) | "as decision-driven-design rules for its editions" | same | +| 11 | Ch. 4 "The one hash law (D1.3)" | "(\"The canonical export\", below)" | same | +| 12 | Ch. 4 regime "ruled in `DDD-dec-113`, E-1 and E-2; `what.md` §7.2"; warning clause "(`DDD-dec-113`, E-2)" | "(`what.md` §7.2)"; clause unchanged | same; ids in the table | +| 13 | Ch. 4 canonical document "under the hash law of `DDD-dec-73`" | "under decision-driven-design's hash law for the What (`what.md` §2.3)" | same | +| 14 | Ch. 4 logic digest and media type "as `DDD-dec-63` §6 rules"; element hash "(`DDD-dec-63` §4, `what.md` §2.3)"; What-version "`DDD-dec-63` §6's record"; logic held by digest "(`DDD-dec-63` §6)" | `what.md` §2.3 in each place | same; `what.md` §2.3 states each of these | +| 15 | Ch. 4 "M-12's second implementation stays Varve's published vectors (`DDD-dec-73`)" | "The conforming second implementation of the canonical form that decision-driven-design is waiting for stays Varve's published vectors" | same; M-12 and the ids in the table | +| 16 | Ch. 5 "W3 and W4 are its warnings (`DDD-dec-113`)" | same without the id | same | +| 17 | Ch. 6 "under the regime of D1.19"; ch. 7 "hash-checked at build (D1.20)" | "(chapter 4, \"Shapes\")" | same | +| 18 | Ch. 7 "(ADR-0005)"; step 0 "(ADR-0002, ADR-0003, ADR-0004)" | "(a product-cli ADR)"; ADR numbers in the table | same | +| 19 | Ch. 7 "`[D1.23]` is superseded by D1.24. It put the rewrite in a new repository." | "**Where it lives.** An earlier decision put the rewrite in a new repository; this one replaced it." | same | +| 20 | Ch. 7 lift: ownership edges become `sdlc:within` "(`DDD-dec-64` P-2)"; blank nodes become elements "(P-3)"; wire names "(`what.md` §6, R-1, R-2)" | "the What's single containment edge"; "by the same rule that makes interactions and fields elements (chapter 3)"; "(`what.md` §6)" | same | +| 21 | — | — | (row withdrawn: a first restatement of P-3 dropped "reads"; replaced by the verbatim quote in row 7) | +| 22 | Ch. 7 behaviour fixture "*Amended 2026-11-06 (decision-driven-design `DDD-dec-113`, E-5):* it was `acme-shop-4.ttl` ... lacks the (Place order, Customer) scenario and the E-7 descriptions" | "It was `acme-shop-4.ttl` and `vectors-4.json` until 2026-11-06 ... lacks the (Place order, Customer) scenario and the descriptions edition 1 asks of every domain, bounded context and subject kind" | same; E-5 and E-7 in the table. E-7 asks a Domain for `sdlc:purpose`, and a Bounded Context and a Subject Kind for `sdlc:definition` | +| 23 | Ch. 7 step 1 "Edition 1 shipped in ... `v0.6.0` (`DDD-dec-113`)" | same without the id | same | +| 24 | Ch. 8 declared targets "(`what.md` §4.1, `DDD-dec-57`)" | "(`what.md` §4.1)" | same | +| 25 | Ch. 8 "through the D1.21 lift" | "through the lift (chapter 7)" | same | +| 26 | Ch. 8 interim rule "of Writ ADR 0008" | "Writ's interim rule for ADRs" | same; ADR 0008 in the table | +| 27 | Ch. 8 subjects "adopted from the unmerged v1.11.0 by ruling, 2026-10-28" | "adopted from the Product Framework's unmerged v1.11.0" | same; the ruling and date in the table | +| 28 | Ch. 8 "The checks this tool needs that `what.md` §3.7 still marks `[OPEN]` are the subject half of W3 and claim justification. They are in edition 1 as warning shapes (`DDD-dec-113`, E-4)" | "The checks this tool needs for subjects, the subject half of W3 and claim justification, are in edition 1 as warning shapes (`what.md` §3.7)" | fact corrected: `what.md` §3.7 has had no `[OPEN]` mark since `8a5b4e9` (edition 1), which says `shapes.ttl` "carries all of it". Recorded in "Where this comes from" | +| 29 | Cross-repository table: "Ruling" column keyed by D1.n; states citing `DDD-dec-113` (E-1, E-2, E-4), `DDD-dec-73`, E-3, M-12, `DDD-dec-63` §6, "withdrawn with D1.7 (D1.16)" | "Needed for" column naming the section; states in words | same states (met, open, to deliver, withdrawn, amended); the ids in the closing table's last row | +| 30 | Every other sentence of chapters 1 to 8 and the table | unchanged | same | diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/production-as-ground.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/production-as-ground.md new file mode 100644 index 0000000..9912f2d --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/production-as-ground.md @@ -0,0 +1,25 @@ +# Equivalence — `applications/sdlc/production-as-ground.md` + +Old text: `84aa466:applications/sdlc/production-as-ground.md`. New text: same path. The body (§1 to +§9) keeps its argument order and its words except for the rows below. #48's rewrite (`068cb23`) +was read as input; its three corrected cross-references were re-checked against the old text and +hold (§8 cited §4, §5 and §6 for points made in §5, §6 and §7). Unlike #48, the three `ddd:ref` +markers stay together and unmoved (conventions §1). + +| # | Old: section and rule, in brief | New: section | Note | +|---|---|---|---| +| 1 | "Location: proposed `applications/sdlc/production-as-ground.md`" | "Where this comes from", last paragraph | fact corrected: the document is at that path; removed: history | +| 2 | An application of the encode/verify split and the closure principle to software delivery, tested against the DORA research programme | Opening, first paragraph, with links | same | +| 3 | **Status: reported, partially. The correspondence with DORA's published findings is real and is checked below, including two places the framework fails to add anything and one place it may be wrong.** | Opening, "How settled this is", bold kept | same, verbatim | +| 4 | Not validated against DORA's underlying data, which is not public; only aggregate findings; a retrodiction check, not a statistical test, presented as such | Opening, "How settled this is" | same, verbatim | +| 5 | "Upstream basis" block: software projection, builds on the principle repo's canon, `core/NN` references pinned in `graph/upstream.yaml` | Opening, last paragraph; `ddd:doc` basis; "Where this comes from" | same; the three `ddd:ref` markers kept in place | +| 6 | §1 "`core/03` holds: digital work with checkable predicates has zero intrinsic floor" | §1 "The framework holds that ..." | same; `core/03`, `DDD-floor-01`, `term:floor` in the closing table | +| 7 | §1 "Per `encode-verify.md`, you cannot amortise an observation of something you do not control" | §1 "By the encode/verify split, ..." | same; link in the opening | +| 8 | §3 "This is `core/10`'s structure at the organisational scale" | §3 "the framework's cost structure at the organisational scale" | same; `core/10` in the closing table | +| 9 | §4.1 "`core/09`'s deployment-distribution caveat" | §4.1 "the framework's deployment-distribution caveat" | same; `core/09`, `DDD-measure-01` (projected) in the closing table | +| 10 | §4.3 caveat: classifying by closure is "`core/03`'s undecidable-in-general problem"; the decision set cannot be cleanly partitioned | §4.3 "undecidable in general, as the framework itself states"; "Not settled yet", third entry | same | +| 11 | §6 the 2024 anomaly is "at least a partial counterexample"; the defence "should not be treated as settled"; "Booked as an open discrepancy" | §6 unchanged; "Not settled yet", first entry, same words | same | +| 12 | §7 "Per `encode-verify.md`, only the first can close it" | §7 "By the encode/verify split, ..." | same | +| 13 | §7 the prediction is offered to the research programme, not settled here; needs response-level data, not public | §7 unchanged; "Not settled yet", second entry | same | +| 14 | §8 cites (§4) for batch size and feedback latency, (§5) for the 2024 anomaly, (§6) for the prediction | §8 cites §5, §6, §7 | fact corrected: off by one; no rule changed | +| 15 | §1 to §9, every other sentence | §1 to §9 | same, unchanged text | diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/sdlc-README.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/sdlc-README.md new file mode 100644 index 0000000..515c27b --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/sdlc-README.md @@ -0,0 +1,28 @@ +# Equivalence — `applications/sdlc/README.md` + +Old: `84aa466`. New: this session's working tree. + +| # | Old: rule, in brief | New: section | Note | +|---|---|---|---| +| 1 | The agentic/DAG design framework constituted the whole of DDD through v3; in v4 it is the engineering projection; CSD is what CDD is called when the actor builds software | opening | same | +| 2 | "Nothing here is deprecated. The reframing is a promotion: what looked like the framework was always one projection of it." | opening | same, verbatim | +| 3 | Upstream basis; three `ddd:ref` markers | opening | same; markers unchanged | +| 4 | The seven-row mapping table, core/ to software | How the general framework reads in software | same, verbatim | +| 5 | The design docs predate `core/`; they remain correct as engineering guidance; foundational justification now lives in `core/`, more generally and carefully | The four v3 design documents | same | +| 6 | The four v3 documents are not in the tree; removed at `219ad6c` under `docs/`; not re-landed; "restoring them is an open decision that has not been taken"; listed as record, not links | The four v3 design documents; Not settled yet | same; register `open` in words: *(open)* | +| 7 | The four descriptions, including the autonomy-levels note (per-role autonomy is the actor model's pinning resolution, `core/04`; ceiling set by closure, `core/03`) | The four v3 design documents, items 1 to 4 | same | +| 8 | what.md: "moved 2026-10-28, not yet ratified"; description; identity form | The documents here, `what.md` row | fact corrected: ratified by the merge of #42 (each decision names the PR's acceptance as the ratification act). Its one `[OPEN]` point stated as *(open)* | +| 9 | how.md: "`[PROPOSED]`, unruled"; description | `how.md` row | register: `[PROPOSED]` -> ruled, by `DDD-dec-55`–`61` (merged in #41) and `DDD-dec-119` (Round 2). The `[OPEN]` adopter-kinds point and the IRI reading kept unsettled | +| 10 | production-as-ground: description (three clauses) | `production-as-ground.md` row | same; register from its own status line ("reported, partially") added | +| 11 | sdlc.md: ruled by Round 28 (`DDD-dec-115`); description | `sdlc.md` row | same; "with the DORA computations over that record" added from `sdlc.md` and `acts/dora/` | +| 12 | (not listed) authority.md, authority-vocabulary.md, authority/, product-cli/, acts/ | The documents here | added: the directive asks for every document in `sdlc/`. authority.md: ruled, ratified by the merge of #45 | +| 13 | The What is owned in the PDLC and read here as ground (`DDD-dec-114`, Round 8); stays where `DDD-dec-42` placed it; the SDLC never writes it | after the table | same; ids to the table | +| 14 | Note: the v3 documents were written before the v4 register ("law" vs "principle"; pre-review immune framing); if restored, reconciliation is the restoring session's work; `core/` wins | The four v3 design documents, last paragraph | same | +| 15 | "Until then, this README and `production-as-ground.md` are what the SDLC projection carries here" | removed; closing note says why | fact corrected: what.md, how.md, authority.md and sdlc.md have landed, so the sentence is false | +| 16 | The reference implementation is product-cli | Reference implementation | same | +| 17 | `core/03`: a decision can be owned by a model **iff** its acceptance predicate closes over digital ground; otherwise an actor selected for competence on open predicates; autonomy bounded by closure | Where the projection sharpens the design | same; "iff" written "if and only if" (#48 trap: its version said "when") | +| 18 | `core/06` prices the orchestration layer: cheap to specify, expensive per run, a bottleneck, "the poisonable centre"; the compound move; cheaper over time | same section | same; "poisonable" kept (#48 trap F3.2) | +| 19 | Verification of third-party and environment ground: not optional, not build-triggered; truth moves on their clock; on a schedule; unreachable is `Unknown`, never a pass | same section | same | +| 20 | product-cli: owns features, ADRs, test criteria, dependencies; builds the derived graph; curated bundles; audits; serves the engineering graph; harness designed against `04-implementation.md` | Reference implementation | same | +| 21 | The Rust tool is the reference until retirement; frozen at `rust-final`; the rewrite implements the What alone, `what.md` and its §6 wire, records decisions as `dpp/1` records that carry no force; defined in `product-cli/product-definition.md`; code, ADRs, tests in product-cli's repository | Reference implementation | same | +| 22 | (new) the `sdlc:` namespace IRI reading | `how.md` and `authority.md` rows; Not settled yet | added: carried from the two vocabularies, which mark it `UNVERIFIED`; stated as *(Claude's reading, not yet confirmed by Emil)* | diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/sdlc.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/sdlc.md new file mode 100644 index 0000000..81efede --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/sdlc.md @@ -0,0 +1,89 @@ +# Equivalence — `applications/sdlc/sdlc.md` + +Old: `84aa466:applications/sdlc/sdlc.md` (762 lines). New: the Gate B rewrite (831 lines). +Every numbered section §0 to §19 kept its number, title and order. No `ddd:ref` marker changed. +These rows are the writer's. They are not evidence of equivalence; the independent check is. + +| # | Old: section and rule, in brief | New: section | Note | +|---|---|---|---| +| 1 | Register banner: ruled (Rounds 28 and 30); two layers (what the decision files; what Round 28 ruled); exposition covered by no item is governed by the decision | Opening "How settled this is"; "Where this comes from", first paragraph | same; rounds moved to the closing section | +| 2 | Where this text and `DDD-dec-115` disagree, the decision governs | Opening; "Where this comes from" | same | +| 3 | The arrangement is the SDLC and has no other name; not Delivery, with the reason | Opening | same; the quotes moved to the table | +| 4 | Scope: a product repository that adopts it; this repository's trunk stays under `DDD-dec-108`–`110`, unchanged | Opening | same; ids moved | +| 5 | Upstream basis pinned at v5.15.2; three `ddd:ref` markers | Opening | same; markers unchanged | +| 6 | §0: the weakest point; two untested assumptions; if either fails, force fails and the ruled shape stays | §0 | same ("ruled" → "decided") | +| 7 | §1: composite act within the PDLC, owned by the How owner | §1 | same; Round 5's quote paraphrased with the same content, quoted in the table | +| 8 | §1: inputs (issue by three entries; the What; product assurance), outputs (production dark; the record; telemetry), no calendar input | §1 | same | +| 9 | §2: axes accepted for now, revisited after first recorded issues; declared before positions are read | §2 | same; O-3 cross-reference added (it is the same item) | +| 10 | §2 table: three axes, values and reasons | §2 | same; "(`DDD-dec-114` P-8)" → "(the PDLC's locus, `../pdlc/pdlc.md` §7)" | +| 11 | §2: occupant not an axis nor in any address (`DDD-ground-06`) | §2 | same; status of the basis stated in words: projected upstream (`graph/upstream.yaml`, `status_at_pin: projected`) | +| 12 | §3: act map as graph data; SHACL regime; one address, one owner, PDLC ▸ SDLC path, occupant lens; acyclic within an issue; the checker command | §3 | same; "the regime of `DDD-dec-113` E-1" → "the same regime as the What" | +| 13 | §3: the stream o1b–o13 | §3 | same, verbatim block | +| 14 | §3: o8 and o14 retired, ids not reused | §3 | same | +| 15 | §3: three causal-index readings (ruled R12) | §3 | same; claim ids moved to the table | +| 16 | §4: the four stores; each step card's Discharges / Store / Cost | §4 | same; "(Round 2)" on o9 and o10's quote removed from prose, content kept ("o10 carries production acceptance" restated) | +| 17 | §5: the issue as seam; plan before allocation; allocation its own act; same addresses for either occupant | §5 | same | +| 18 | §5: whether o10 needs another person; three bullets | §5 | same | +| 19 | §5: implementation assurance sets whether self-acceptance is enough | §5 | same | +| 20 | §5: implementation assurance defined; How owner's; three parts table; independence levels self/independent | §5 | same; Round 19 and R3 moved to the table | +| 21 | §5: a How decision anchored to the What element, or declared on the issue; o9, o11 read it as ground | §5 | same | +| 22 | §5: not product assurance; judged at ready-for-users; the first version's misplacement moved by Round 19 | §5 | same; history kept in one sentence without the round | +| 23 | §5: tune down until outcomes move; Emil's quote | §5 | same; the quote paraphrased ("If neither moves, that is fine: the verification removed was probably not giving any value") and kept verbatim in the table | +| 24 | §5: relation to Varve ADR 0088, three bullets | §5 | same; `DDD-dec-109` → "this repository's own trunk rule" | +| 25 | §5: falsifier | §5 | same | +| 26 | §6: takt's shape with Varve's force; candidate; trailers and gate; approval and landing; precedence (Round 2's "Drop it" governs) | §6 | same; the precedence restated as "an earlier ruling … a later ruling dropped the squash. Both are recorded, and the later governs" | +| 27 | §6: the mechanics 1–6 and the ruleset | §6 | same | +| 28 | §6: what leaves takt (READY_PUSHER, pr-to-ready, on_semver) and why | §6 | same | +| 29 | §6: where Varve's force changes; new and unexercised | §6 | same | +| 30 | §7: main deploys to prod; o10 carries production acceptance; dark behind a toggle | §7 | same | +| 31 | §7: o13, dark by default, toggles.yaml checked at o9; creating and retiring the How owner's; retiring never turns on | §7 | same | +| 32 | §7: turning on is the PDLC's (o16, When owner, refused without verdict; `DDD-dec-114` P-4) | §7 | same; P-4 → `../pdlc/pdlc.md` §12, which states it | +| 33 | §7: state outside the trunk, with the reason | §7 | same | +| 34 | §7: the store is a service the When owner uses, recording traceability; branch-file alternative rejected; Round 30's "not the whole PROV-O" | §7 | same; "ruled differently from the proposal" made explicit in words ("decided otherwise than proposed") | +| 35 | §7: what the service does; four recorded facts; `lc:ToggleOnShape`; who reads; the SDLC never writes on state | §7 | same | +| 36 | §8: the request quote | §8 | same in substance ("All communication happens on the issue, and the issue controls the developer session behind it"); quote verbatim in the table | +| 37 | §8: who may allocate; locus label; kind label; which comments are instructions (three conditions); data; framing; control verbs table | §8 | same; `DDD-dec-109` rule 5 moved to the table | +| 38 | §9: Round 1's ruling with its option text | §9 | same content as plain statement; the verbatim ruling in the table | +| 39 | §9: the port, whole, of ADR 0087 with amendments, read at Varve `81fba3d`; "The whole section is ruled (Round 28, R21)" | §9 | same; R21 moved to the table, and a pointer to §11 added | +| 40 | §9: the map (humans, agents, exempt, delegate changes, holders of Approve) | §9 | same | +| 41 | §9: the three gates, verbatim quotes and regex | §9 | same | +| 42 | §9: the exit to the ledger; identities.json retired | §9 | same | +| 43 | §10: How one layer up; stricter rule (main judges; the base decides); cannot approve itself; `DDD-address-03`'s case | §10 | same; claim status stated in words (local, projected) | +| 44 | §11: "Each is flagged as a departure; D-1 to D-8 ruled (R21), D-9 ruled (R1)" | §11 | same ("All nine are decided"); rounds moved | +| 45 | §11: D-1 to D-9, each departure and reason | §11 | same; in "Why", decision ids and round numbers replaced by what they are (this repository's trunk rule; the PDLC's owners and placement rule, `pdlc.md` §2, §6; "decided with the landing"); D-9's "Tension"/"Proposed:"/"Ruled (R1): as proposed" collapsed to "Decided:" with the proposal's content | +| 46 | §12: Round 1's "Claude Code Action"; sources [GA], [SEC], [USE]; nothing from memory | §12 | same | +| 47 | §12: triggering, who may trigger, comments and injection, pushes and CI, branches, signing, cost | §12 | same; "this is unverified" → "This is not verified" (a fact about the docs, not a register mark) | +| 48 | §13: session records (prompt, bootstrap with its fields, committed by o4, each run records what it read) | §13 | same; `DDD-dec-20`, `DDD-dec-52` moved; `DDD-dec-52`'s content kept as the reason | +| 49 | §13: the occurrence record from edition 1 (Round 2, with option text) | §13 | same, as plain statement | +| 50 | §13: the field table | §13 | same; "`DDD-dec-52`" in the Ground read row → "What the occurrence read" | +| 51 | §13: where stored (R23): orphan branch, ruleset, why the App | §13 | same | +| 52 | §13: the checker over "an illustrative record of one invented issues, #101 (new) and #103 (owed …)" with 10 plants plus one DORA plant | §13 | **fact corrected**: the record holds three invented issues, #101, #103 and #104 (own-ground, charter only) (`acts/example-record.ttl` l. 124–133); `check.py` run confirms 10 plants plus one DORA plant | +| 53 | §13: the two fields from Round 22 | §13 | same | +| 54 | §13: the SDLC's output; forecast from throughput and flow time (ruled, Round 27, Kanban cycle time; P-14); DORA keys; split of capacity | §13 | same; "based on the Kanban cycle time" kept, ids moved | +| 55 | §14: hotspots computed from the record; o5 ↔ o6 (why, three classes with levers, metric); o10 (why, lever, metric); worked numbers | §14 | same | +| 56 | §15: nine falsifiers | §15 | same; the replacement falsifier's history ("Claude's (Round 20), ruled by Round 28 (R20). It replaces Claude's Round 19 falsifier … which Emil withdrew") → "This replaces an earlier falsifier … which was withdrawn"; the round history is in the table | +| 57 | §16: Round 22's ruling with option text; the classifier; kinds defined in pdlc.md §9 | §16 | same, as plain statement | +| 58 | §16: the table; act map scoping; the shape; what the PDLC reads; When sees only cadence; owed fix usually not dark; the guard from both sides | §16 | same | +| 59 | §17: oR is the PDLC's; the SDLC supplies two things; the check; "the H-9 pattern (`DDD-dec-60`, now `DDD-dec-70`)"; gap never "unknown"; in the record; until the schema has observation needs | §17 | same; H-9 described as "the How's pattern for measurement wiring, a contract over `telemetry` facts (`how.md` §4.2)", where how.md states it | +| 60 | §18: Round 20's quote; answerability in core/05 §5's sense; the table of four keys | §18 | same; quote paraphrased, verbatim in the table | +| 61 | §18: production is an input; the reading's shape; the worked values | §18 | same; values re-run by `acts/check.py` and unchanged | +| 62 | §18: the forecast's spread (Round 29) | §18 | same | +| 63 | §18: which occurrences feed each key; flow time a different interval | §18 | same | +| 64 | §19: O-1, O-2, O-3 | §19 | register: unmarked open items → *(open)*; content same | +| 65 | §19: O-4 to O-7 "Ruled (Round 28, Rn)", closed | §19 | same ("Closed."); rounds moved to the table | +| 66 | §19: O-8, with "Proposed, not ruled:" and "Whether a model may occupy it … is open" | §19 | register kept: *(open)* for the item, *(proposed, not yet ruled)* for the proposal, *(open)* for the model question; content same | +| 67 | §19: O-9 | §19 | register kept: *(open)*; content same | +| 68 | (none) | §19 preamble: the O-numbers are this document's own, separate from `pdlc.md` §15's | added from Round 31's "How it governs" (record of fact, no rule) | +| 69 | (none) | "Not settled yet" | added, as the format requires; lists only what §19 and §0/§12 already leave open | + +## Not restated + +None. Every normative sentence is in the new text with the same strength. + +## Register notes + +- R5's "PROV" reading is not `UNVERIFIED` at `84aa466`: Round 30 withdrew Claude's PROV-O reading + and ruled "traceability for the act". The old text already said so, and the new text keeps it as + decided. +- O-8 holds two registers in one item: the proposed act, and the open model-occupancy question. + Both are marked separately. diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/test-keys-README.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/test-keys-README.md new file mode 100644 index 0000000..9b9a5c9 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/test-keys-README.md @@ -0,0 +1,11 @@ +# Equivalence — `applications/sdlc/how-examples/test-keys/README.md` + +Old: `84aa466` (29 lines). New: 46 lines. + +| # | Old: rule, in brief | New | Note | +|---|---|---|---| +| 1 | These are test keys of a declared test holder of `GEN@3` or vendor `GEN@2`; none used outside the fixture; none belongs to a person | unchanged | same | +| 2 | Ruled (Round 2, P-6), quoted: keep for the fixture's life; commit beside it, marked; never used outside; rotated only by a new founding the record states as such | "The rule." | same terms, unquoted; the verbatim quote moved to the closing table | +| 3 | Key table, eight rows | unchanged | same | +| 4 | `build.py` generates a key only when its file is missing; a closed key stays, never signs again; after p13 refused | unchanged | same | +| 5 | Earlier records' throwaway keys discarded; both test products re-founded once (Round 3, P-9); the next founded under kept keys | unchanged | same; "(Round 3, P-9)" moved | diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/what.md b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/what.md new file mode 100644 index 0000000..330bdfc --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/equivalence/what.md @@ -0,0 +1,61 @@ +# Equivalence — `applications/sdlc/what.md` + +Old: `84aa466:applications/sdlc/what.md` (922 lines). New: this branch (995 lines). The writer's +table, per `gate-b-conventions.md` §7. It is not evidence of equivalence; the independent check is. + +**Method.** Every numbered section keeps its number, its order and its file. Every rule's sentence +is kept, with only these edits: decision, round, Q-/P-/R-/E-/H- ids and `PF §` citations removed +from running text and moved to "Where this comes from"; "*Ruled (…)*" lead-ins removed (decided is +the default); "v1.11.0" / "PF §x" as an attribution became "the source" where a sentence needs a +subject. Product Framework quotations are kept verbatim, without their citations; the opening says +that quoted passages are the source's text. Rows below are grouped by section; a row marked +`same` means every normative sentence of that section is word for word, apart from the id and +citation edits above. + +| # | Old: section and rule, in brief | New | Note | +|---|---|---|---| +| 1 | Opening "Status: moved, 2026-10-28; not yet ratified … Emil ratifies by merging" | Opening, "How settled this is": ratified when its pull request merged | `fact corrected`: #42 merged; `DDD-dec-64`'s made line names acceptance of the pull request as the ratification act | +| 2 | Opening: move session, source repository and commits, v1.11.0 adopted by ruling | "Where this comes from", "The source" | `removed: history` from the body; kept in the closing | +| 3 | "Register" paragraph (*Ruled*, `[PROPOSED]`, `[OPEN]`, PF quoting) | Opening "How settled this is" and "How to read it" | Register words per Round 2. No `[PROPOSED]` point exists in the old body; the one `[OPEN]` point stays *(open)* | +| 4 | Companions list | Companions | `same` | +| 5 | — | Opening: reader, act, how to read, the worked example in brief | new framing; every example fact checked against `acme-shop.ttl` (one domain Ordering; systems `shop-api`, `shop-bff`; Customer issues Place order and Refund order; scope rules "customers see their own orders", "staff see every order"; `shop-bff` targets GUI, context `web`) | +| 6 | §1.1 the What; a system is not a coordinate; declared ground over which decisions are made; step 1 reads addresses off the What | §1.1 | `same` ("Read with `DDD-dec-42`" moved to closing) | +| 7 | §1.2 table, seven rows | §1.2 | `same`, ids to closing. Force row: "in their own pull request after this one … *Update, 2026-11-02:* authority.md" became "the authority profile, `authority.md`" (`removed: history`; the profile now exists) | +| 8 | §1.3 table: eleven rulings with their decisions | §1.3, eleven bullets in the same order; decisions in the closing table, in the same order | `same` in substance. "§9 cut down … §10 one level" restated as "Encoding … cut down … conformance to one level" (PF section numbers are source citations) | +| 9 | §2.1 three rules; gathered material enters only when a human principal signs and accepts it "(§8)" | §2.1, pointer "(§5)" | `fact corrected`: old §8 is the move's choices table; signing and acceptance is §5 | +| 10 | §2.1 creating decisions anchor to the narrowest existing covering element; product for a new domain; never its own anchor; "How ruling 1 applied to the What" | §2.1, "the How's anchor rule (how.md §3) applied to the What" | `same`; quoted ruling kept verbatim | +| 11 | §2.2 identity (five bullets), containment, what is an element | §2.2 | `same` | +| 12 | §2.3 record, canonical form, hashes, equalities, no force; ontology never hashed; vectors; pyoxigraph/pyld; second implementation "successor item M-12 (`DDD-dec-73`): Varve's published vectors"; Varve preview.15 reproduction "Recorded" | §2.3 | `same`; "successor item M-12" restated as "still to come", item number in the closing | +| 13 | §3 intro quotes; one or more domains and systems; system references whole domains; `within`, `referencesDomain` | §3 | `same`; one example line added (checked) | +| 14 | §3.0 product concerns; direction not carried; boundary quote; second genesis | §3.0 | `same` | +| 15 | §3.0.1 journey definition, edges, owns nothing, three rules; "the old journey payoff named value-anchoring and blast radius" | §3.0.1 | `same` for rules; the "old payoff named" clause shortened to "Blast radius stays … Value-anchoring went with Delivery" (`removed: history`, the two outcomes kept) | +| 16 | §3.1 contents; structure quote; every box says what it is; mapping direction; strategic patterns are How; field datatypes; reference data quote and test; production data and data conformance not framework | §3.1 | `same`. "PF §3.1's three callouts … describe §13's profile" became "The source's three callouts … describe a data-conformance profile". One example line added (checked: `Order`'s three fields and three invariants) | +| 17 | §3.2 three bullets | §3.2 | `same` | +| 18 | §3.2.0 blocks, patterns, two rules; trigger source and subject; nature admitted per source; payload schemas; slices | §3.2.0 | `same`. "v1.11.0 called this edge `acts_as`" → "The source called this edge `acts_as`". One example line added (checked) | +| 19 | §3.2.1 UI step quote; AIO type split; buildable core; offered to; modelled meaning; intent is debt; the rate stays a What-side signal; reification is not the What's | §3.2.1 | `same` ("(§4.5)" source citation removed from the quoted phrase) | +| 20 | §3.2.2 AIO quote; the ten AIOs; input AIOs; `[OPEN]` adopter-registered AIOs; context of use; interaction class | §3.2.2 | `register: [OPEN] -> *(open)*` (Round 2 wording), listed in "Not settled yet". One example line added (checked) | +| 21 | §3.2.3 WCAG quote; `mustSatisfy`; criteria not re-minted; inherited and added; verification type; attestations: signed record and ground reading, not a stored verdict; held by the profile | §3.2.3 | `same` ("Under this repository's rulings" → "Here") | +| 22 | §3.2.4, §3.2.5 | §3.2.4, §3.2.5 | `same`. One sentence added after the PF Acme quote saying it is the source's illustration, not the worked example (#48 W5 trap) | +| 23 | §3.3 signature; subject is input; six derived-signature rules; logic by digest; four conformance rules incl. subject coverage; wire scalar alphabet; scenarios; pure core is a How binding | §3.3 | `same`. One example line added (checked: Decider `Order` handles both commands, rejects with the three invariants) | +| 24 | §3.4 signature; symmetric; three rules; actor not an input quote; `keyedBy`; state justification "if and only if"; at least one reachable rejection; claim justification; shapes are warnings | §3.4 | `same`; "if and only if" kept | +| 25 | §3.5 title "Named-algorithm primitives", no subtitle; "Floor" is canon's; derivability quote; reference, I/O contract, oracle; exempt; oracle conformance is a How binding; dishonesty quote | §3.5, title unchanged | `same`. One plain-words gloss sentence added as the section's first sentence, as Round 2 (request 3) allows | +| 26 | §3.6 two kinds table; honesty test; located not listed; contract anchors to the demand | §3.6 | `same` ("H-9" moved to closing) | +| 27 | §3.7 subject-kind wording; two authorities; authentication is How; authorization table; subject kind (nature, claims, role or kind, delegation); View scope (five rules); checks bind once one kind declared; checks table; shapes list; warnings | §3.7 | `same`. One example line added (checked: Customer and Staff within Ordering; the two scope rules on `Order summary`) | +| 28 | §4.1 declared targets; one kind `DeclaredTarget`; edition may not resolve; "not a check this tool requires"; catalogues are packages; `pf:` classes not carried | §4.1 | "this tool" → "the What's own checker" (the old "this tool" had no referent outside the move session; #48's fix 13). Otherwise `same` | +| 29 | §4.2 obligations 1–3; content lives in How bindings; debt, boundary, never a waiver; neither holds the other's part | §4.2 | `same` | +| 30 | §5 intro: scopes central, instantiate genesis, tools never change the What, gathered material signed by a human principal | §5 | `same` (quoted ruling kept, typo "helds" included) | +| 31 | §5.1 force is the profile's; genesis unscoped; scope definition; acceptance validity; multi-scope rule "(Round 5)"; Writ's [D2] conjunction; kind vocabulary is the ontology; derived kinds in no scope; kind immutable "(`DDD-dec-63` §3)"; update 2026-11-02 on the profile and `CUR@1` "(§9)"; two grants | §5.1 | `same`. "Writ's [D2] conjunction" → "Writ's conjunction" ([D2] in closing). "Kind is immutable (`DDD-dec-63` §3)" → "(a kind change makes new elements, §2.2)". "(§9)" → "(authority.md §9)": `fact corrected`, what.md has no §9. "*Update, 2026-11-02*" label removed (`removed: history`; content kept) | +| 32 | §5.2 tool is a gathering source; declaration; enforcement oracle; gap split; completeness join; symmetry | §5.2 | `same` ("PF §14" → "the source's authoring-scope chapter") | +| 33 | §6 the wire moves, is the oracle's interface, corrects how.md Appendix B; runner quote; decision requests; subjects beside the command, never inside `with`; projection requests; equality; names on the wire (five bullets); schemas; ground readings | §6 | `same`. One example line added (checked: the four wire names). The A-8 contradiction is not touched (Round 2) | +| 34 | §7.1 seven bullets; edges carried and not carried | §7.1, title "Encoding, cut down" | `same` (title lost "(PF §9" citation) | +| 35 | §7.2 three conditions; "this half cannot be claimed until it exists (Q-4). *Update, 2026-11-02:* it exists … §4.7" | §7.2, "The authority profile is therefore part of conformance. 'In force' is authority.md §4.7" | `fact corrected` / `removed: history`: the profile exists; the condition is unchanged | +| 36 | §7.2 validation regime; violations and warnings; edition 1 warnings list; check.py | §7.2 | `same` | +| 37 | §8 "The move's own choices — `DDD-dec-64`, ruled": P-1 Round 2, P-2–P-7, R-1, R-2 Round 5, as proposed; additions; table P-1..P-7 | §8 "The choices made when the What moved here": seven choices, all decided as proposed, two additions; table without P numbers | `same` in substance; P numbers and rounds to the closing. Title reworded (no ruling names it) | +| 38 | Appendix — where the source went | Appendix | `same` (decision ids and Q-2 removed from cells; in the closing) | +| 39 | — | "Not settled yet" | lists the one *(open)* point | +| 40 | — | "Where this comes from" | every id, round and PF citation removed from the body, keyed by section | + +**Could not restate.** None. + +**Register changes.** `[OPEN]` → *(open)* at §3.2.2 (wording only). Status line "not yet ratified" +→ ratified (fact). No proposed or open point was raised, and no decided point lowered. diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/findings.md b/meta/sessions/2026-11-09-applications-for-readers-redo/findings.md new file mode 100644 index 0000000..e71b931 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/findings.md @@ -0,0 +1,128 @@ +# Findings — applications/ for readers, redone + +## Gate A — the format re-filed + +**F-1. What main made wrong in #48's two files, and what was changed.** `DDD-dec-94`'s `made` +line cited #48's session record as if it were on `main`, and named "the pull request" (#48) as the +ratification act. Both stopped being true when #48 was closed without merging. The line now names +the branch and commit that hold the record (`068cb23`) and this session's landing as the act. A +re-filing note is added to `notes`. `spec/doc-format.md` named #48's session folder as the home +of the check's successor item, and now names this session's A-1. Nothing else in either file +changed. The statement, resolution and basis are #48's text, byte for byte. + +**F-2. Re-checked on `main` at `84aa466`, still true, not changed.** The pin `v5.15.2` +(`graph/upstream.yaml`). `DDD-dec-39` is the release-head guard upstream. `DDD-dec-81` made +`AGENTS.md` the instruction file. The W8 to W15 check is not in `scripts/`. `df9d05b` is reachable +on `claude/doc-format`. The basis (`DDD-agent-01` upstream, `DDD-dec-04`, `DDD-dec-81`) resolves. + +**F-3. A forward reference, by design.** `spec/doc-format.md` cites `DDD-dec-95` (its basis, and +"Folder formats"). At Gate A, `DDD-dec-95` is not filed. It is filed at Gate B on this same +branch, and nothing lands before then. If Gate B were abandoned, these two references would have +to go. + +**F-4. The spec's marker sentence promises more than the check does, for local claims. Reported, +not changed.** "Where a rule rests on a projected claim, an invisible `ddd:ref` marker may sit at +the point of use, so the pin check warns when the claim moves." `validate-core-order.py` (E13/W5 +pass) checks `ddd:ref` against upstream pins only. It skips local ids, so a marker on a local +projected claim (for example `DDD-flow-01`) warns about nothing. This was already true when #48 +wrote the sentence, so it is not something `main` made wrong, and the port keeps the text. + +**F-5. The format folds two registers into one. Put to Emil (Round 2).** The spec's "Status in +running text" marks every unsettled point as *(not settled yet)*. `main`'s `applications/` +distinguishes `[PROPOSED]` (a proposal awaiting a ruling) from `[OPEN]` (no proposal yet). In +the release session's F-2, a register mistake about `sdlc.md` was the defect. If one phrase +covers both registers, Gate B could not state "each document's register as the decisions give +it" without losing a distinction. Nothing in the format forbids two phrases, so this is a question +of how to apply it, not a change to `DDD-dec-94`. + +**F-6. More anchors than the prompt names.** Besides `pdlc.md`'s citations of `what.md` §3.0 +to §4.2, `what/shapes.ttl`, `what/ontology.ttl` (both hashed into a vocabulary edition) and +`how-examples/build.py` cite `what.md` §2, §3.6, §5 and §6. #48's split moved these sections. +Gate B keeps `what.md`'s section numbers for this reason. + +**F-7. Stale headroom note, not changed.** `meta/sessions/2026-11-02-canon-cli/successor-items.md` +S-6 leaves `DDD-dec-94` to `-99` to the authority-profile session, and that session used none of +them (`bootstrap.md`, "Decision ids at arrival"). + +## Gate B — the rewrite + +**F-8. No file is split, and this differs from #48 on purpose.** #48 split `what.md` and +`how.md` into practitioner and reference documents, and merged `how-vocabulary.md` into +`how-reference.md`. Sections of these documents are cited by number 157 times outside the session +records, including in `what/shapes.ttl` and `what/ontology.ttl`, which are hashed into a +vocabulary edition, and in signed `dpp/1` records. A split moves sections out of the file they +are cited in. So every numbered section stays where it is, and each opening says which sections a +practitioner can skip (`gate-b-conventions.md` §1). This is why `DDD-dec-95` drops #48's split, +and adapts F4 (order by task) and F5 (reference material in its own document). + +**F-9. Facts in the old text that were wrong, corrected in the rewrite.** Each is recorded in its +equivalence table. + +- *Not yet ratified*: `what.md` (#42), `how.md` and `how-vocabulary.md` (#41), `authority.md` and + `authority-vocabulary.md` (#45). Each decision names the pull request's acceptance as the + ratification act, and each pull request merged. +- `applications/README.md` called `sdlc.md` `[PROPOSED]` (the release session's F-2), and + `sdlc/README.md` called `how.md` "`[PROPOSED]`, unruled". +- `organizations/README.md` said the claim files flag the claims `UNVERIFIED`. None does, and + `DDD-dec-40` ratified all four as projected. +- `product-definition.md` ch. 8 said `what.md` §3.7 "still marks `[OPEN]`" two checks. Edition 1 + (`8a5b4e9`) removed that mark. +- `sdlc.md` §13 said its illustrative record has two issues. It has three (#101, #103, #104). +- `what.md` cross-references: §2.1 pointed to §8, and the rule is in §5. §5.1 pointed to a §9 that + `what.md` does not have, which is `authority.md` §9. +- `pdlc/README.md` pointed to "§13, O-1, open". O-1 is in §15 and is closed. +- `production-as-ground.md`: "Location: proposed" (it is at that location), and three + cross-references in §8 (#48's finding, verified). +- `authority.md` §9: "every key is a throwaway test key", against the ruling that the test keys + are kept for the fixture's life. +- `how-examples/README.md` counts, from a fresh `check.py` run: 238 ok lines, 67 records, 27 + records dated 2026-11-02, the log's p16; four imports, named. + +**F-10. `pdlc.md` §2.1: kept as not ruled; Emil may want to settle it.** *Settled in Round 3: rows 1 to 8 ruled as listed, by a new decision (F-15).* The document's register +line says Round 28 ruled its tables. §2.1 says seam-table rows 1 to 8 are "not ruled", and +`DDD-dec-114` agrees ("It is not ruled here"). The rewrite follows the decision and lists the rows +under "Not settled yet". The table's last two rows are "Claude's additions", and the old text never +says whether they were ruled. The rewrite asserts neither. + +**F-11. Outside scope: a citation in `applications/pdlc/graph/ontology.ttl`, line 160.** +`lc:decidedAt` cites "pdlc.md §8" (priority is a When decision). The property is used by §10's +option-age metric. The citation may be meant as §10. It is not changed: a graph file is outside +this session's scope. + +**F-12. `DDD-dec-117` names `authority.md`'s Appendix B roles row as amended.** The rewrite adds a +note to that row saying so, and that the profile's text has not been reworked to it. Reworking §3.1 +for roles is the specification-feasibility session's successor work, not this session's. + +**F-13. One register moved outside `DDD-dec-119`, for Emil to check.** `how.md` §2's table row +"each anchored to a What element or to the product" said "only with a reading (ruled, §3)" and +ended with `UNVERIFIED — Emil review`. §3 says the reading was ruled as proposed, and +`DDD-dec-55`'s statement contains it ("It is the loophole only when a narrower element exists and +was not used"). The rewrite drops the stale mark on that basis. If the mark was meant for the +row's other sentence, which reads `DDD-dec-54` ruling 1 as forbidding the loophole, it should come +back as Claude's reading. +**Closed in Round 3 (2026-11-11):** Emil accepted the drop ("Accept"; option text: "DDD-dec-55 +states the narrowest-element anchoring and the product-node reading"). + +**F-14. `how.md`'s other corrections** (from its equivalence table): §12's anchors are the +`IMP-*@2` ones in force (the product node, the Ordering bounded context, the residency quality +demand); `REST@2`, not the superseded `REST@1`, is the one evaluated; §4.1's pointer is to +`how-vocabulary.md` §1; "as the authority profile will define it" became "defines it"; D-8 is +marked answered, as §1.2 says. `how-vocabulary.md` §3: the What terms are in `what/ontology.ttl`, +not provisional, and `REST@2` replaced `sdlc:localId` with `sdlc:wireName`. Its "`check.py` holds +the same list" is loose (`check.py` derives the terms), and is left as written. + +## Round 3 + +**F-15. `DDD-dec-120`: `pdlc.md` §2.1's seam rows 1 to 8, ruled.** Filed on Emil's Round 3 +answer to F-10. It supersedes only `DDD-dec-114` P-3's "It is not ruled here", in its statement. +It does not use the `supersedes:` field, which marks a whole decision superseded. The rows are +copied byte for byte from `pdlc.md` at `b27407a`. `pdlc.md`'s §2.1 sentence, its "Not settled yet" +and its basis table now say the rows are ruled. The register line was already right. +- **Rows 10 and 11** (the classification verdicts, Claude's additions from Round 22 of the + 2026-11-07 record) were first left unreached. Round 4 ruled them, and `DDD-dec-120` was amended + in place before landing to record them row by row. `pdlc.md`'s marker and basis row match. + "Not settled yet" had no entry for them to remove. +- **The id:** the next free above `DDD-dec-119`. No branch holds a decision file above 119. + Mentions of 120 elsewhere are range mentions, already ruled not to be use. +- **The checker path:** Round 3 names `applications/pdlc/check.py`. The checker is + `applications/pdlc/graph/check.py`, and that is the one run. diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/gate-b-conventions.md b/meta/sessions/2026-11-09-applications-for-readers-redo/gate-b-conventions.md new file mode 100644 index 0000000..610861f --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/gate-b-conventions.md @@ -0,0 +1,124 @@ +# Gate B — conventions for the rewrite + +The working rules every Gate B rewrite follows. They apply `spec/doc-format.md` (`DDD-dec-94`) and +Emil's Round 2 answers. They add no rule of their own. #48's conventions +(`gate2-conventions.md` at `068cb23`) are the starting point. Where this file differs, the reason +is given. + +## 1. What does not move (the anchor rule) + +Other files cite these documents by section number, 157 citations outside `meta/sessions/`. They +are in hashed TTL (`what/shapes.ttl`, `what/ontology.ttl`), signed `dpp/1` records under +`how-examples/records/`, decisions, claims, `method/` and the `lc:` graphs. No citation uses a +`#fragment`. So: + +- **Every numbered section keeps its number and stays in its file, in the same order.** A + numbered heading's words may be made plainer, unless a ruling names them. `what.md` §3.5 stays + "Named-algorithm primitives" (`DDD-dec-64` P-5; Round 2). `authority.md`'s numbers are the ones + `DDD-dec-86` cites. +- **No file is split, merged or renamed.** #48 split `what.md` and `how.md` and merged + `how-vocabulary.md` into a reference document. This redo does not. `what.md` §6 and §7 are + cited by `shapes.ttl`'s messages, which are hashed into a vocabulary edition. `ontology.ttl` + names `how-vocabulary.md`. Moving either would break a citation that cannot be updated without + a new edition (A-6). The reference material stays in its numbered section, and the opening says + which sections a practitioner can skip. +- **`ddd:ref` and `ddd:embed` markers stay exactly as they are.** The validator reads them. + +## 2. Shape of every document + +``` +# + +<!-- ddd:doc +reader: ... +act: ... +pin: v5.15.2 +basis: [ids, local claims as ID@status] +status: current | held +supersedes: 84aa466:<path> +--> + +<Who this is for and what they can do after reading it: two to four sentences.> + +**How settled this is.** <In words, from the register table below.> + +<Optionally: which sections to read for which task.> + +<Body: the numbered sections, kept.> + +## Not settled yet (only if the document has any unsettled point) +## Where this comes from (section -> decisions, claims, rounds, sessions; then supersedes) +``` + +## 3. Words + +| Instead of | Write | +|---|---| +| *Ruled (DDD-dec-NN, Round N)* | nothing: decided is the default. The id and round go in "Where this comes from" | +| `[PROPOSED]` | *(proposed, not yet ruled)* at the point, and an entry in "Not settled yet" (Round 2) | +| `[OPEN]` | *(open)* at the point, and an entry in "Not settled yet" (Round 2) | +| `UNVERIFIED — Emil review` | *(Claude's reading, not yet confirmed by Emil)* at the point, and an entry in "Not settled yet". It is a third register and is kept distinct from the other two | +| Claim, term, decision, promotion ids; `[D1.n]`; R-, Q-, P- numbers; round and gate numbers; session paths | nothing in running prose. They go in the `ddd:doc` block and in "Where this comes from", keyed by section. Exception: an id that *is* the subject of the text (e.g. a table listing the decisions a record type carries, a vocabulary term, a record's name like `GEN@3`, a file path the reader runs) stays | +| `PF §3.1` | nothing in the body; the source goes in "Where this comes from" | +| Quoted ruling text | the rule, stated plainly with its strength unchanged. The quote's source goes in "Where this comes from". A short test a reader applies verbatim may stay quoted | + +## 4. Register, as the decisions give it + +| Document | Register at `84aa466` | Source | +|---|---|---| +| `applications/README.md` | Index. It calls `sdlc.md` `[PROPOSED]`: **wrong** (release F-2). `sdlc.md` is ruled | `DDD-dec-115` S-11, Round 28 and 30 | +| `organizations/README.md` | Four claims, `projected`. Its "flagged UNVERIFIED in their claim files" must be re-checked against the claim files (#48 found it stale) | `core/claims/DDD-org-01..04` | +| `pdlc/README.md`, `pdlc/pdlc.md` | Ruled (Rounds 28 to 30), with the marks the text itself keeps (method steps 7 and 10 are `[PROPOSED]` in `method/`; R4/R5 readings as recorded) | `DDD-dec-114` | +| `sdlc/README.md` | Index. It calls `how.md` "`[PROPOSED]`, unruled": **now wrong**. `how.md` is ruled, and Round 2 ratified the rest | `DDD-dec-55`–`61`, `DDD-dec-119` | +| `sdlc/sdlc.md` | Ruled (Rounds 28 and 30), with R5's PROV reading `UNVERIFIED` where the text keeps it | `DDD-dec-115` | +| `sdlc/what.md` | "Moved; not yet ratified (Emil ratifies by merging)" is **stale**: #42 merged. Ruled throughout (`DDD-dec-41`–`64`, later supersessions). One `[OPEN]` point (§3.2.2, adopter-registered AIOs) | `DDD-dec-64` and the decisions it cites | +| `sdlc/how.md`, `how-vocabulary.md` | Ruled. #41 merged, and **Round 2 / `DDD-dec-119`**: every "not ruled separately" and `[PROPOSED]` point is ruled as proposed. Still `[OPEN]`: adopters registering What kinds. Still Claude's reading: the baseline ratchet semantics (§8.2), the `/ns/sdlc` IRI, `DDD-dec-45`'s consequence | `DDD-dec-55`–`61`, `DDD-dec-119` | +| `sdlc/authority.md`, `authority-vocabulary.md` | "Not yet ratified (Emil merges #45)" is **stale**: #45 merged 2026-11-02. Ruled; "no UNVERIFIED mark remains and nothing is open" after Round 3, except the vocabulary's IRI reading | `DDD-dec-85`, `86`, `92`, `93`, and `87`–`91` | +| `sdlc/production-as-ground.md` | "Reported, partially", a retrodiction against published DORA findings; "Location: proposed" is stale (it is at that location) | the claims it cites | +| `sdlc/product-cli/product-definition.md` | Draft 4, rulings `[D1.1]`–`[D1.25]` with dates, edition 1 (`DDD-dec-113`) | `DDD-dec-113`, `-72`, `-73` | +| `sdlc/how-examples/README.md`, `test-keys/README.md` | Descriptions of the worked example; facts re-checked against `check.py`, `build.py` and the records | — | + +## 5. Content does not change + +- Every rule keeps its meaning and its strength: must stays must, may stays may, "if and only if" + stays "if and only if", "or" stays "or". +- A point keeps its register. Nothing proposed or open reads as decided, and nothing decided + reads as unsettled. The only register changes are the ones the decisions give (section 4): the + How's ratified parts (`DDD-dec-119`), and the stale "not yet ratified" lines, which are facts + corrected, not registers raised. +- The six content gaps (A-8 to A-12, A-16) are not fixed and not marked (Round 2). +- A rule stated only inside deliberation is extracted into the body and listed in the + equivalence table. +- Every statement about Acme Shop is checked against `what/examples/acme-shop*.ttl` and + `how-examples/records/` before it is written. + +## 6. The traps: #48's 64 findings, as a checklist + +Each rewrite is checked against these before it is handed on. + +1. **Qualifiers lost or gained**: "if and only if" became "only if"; "or" became "and" in a + falsifier; "one or more" dropped; "monotonically" became "steadily"; "would disagree" became + "may differ"; "poisonable" became "can poison"; "core-like" dropped; "allow" dropped; "may be + removed" became automatic; "declared" dropped. +2. **Register moved**: an opening sentence ("everything here is decided") overrode the marks + below it; a proposed point lost its marker in a reference passage; a decided point was marked + unsettled. +3. **Definitions lost their limits**: a principle defined without the limits canon gives it; + "a test stand-in for the unwritten profile" became "not yet implemented". +4. **The example misdescribed**: customers request refunds, and staff see every order; a change to + an invariant anchors to the invariant; `Cancel order` would anchor to the bounded context; + `shop-bff` targets the web only; "44 elements under the product node". +5. **Things added**: a gloss with no basis; "and nothing records it"; "most organisations". +6. **Statements of fact about status**: what imports what, counts of records, what a checker does. + +## 7. Equivalence tables + +One file per old document, `equivalence/<name>.md`: + +| # | Old: section and rule, in brief | New: section | Note | +|---|---|---|---| + +Notes: `same`; `extracted from deliberation`; `removed: history`; `removed: deliberation`; +`register: <from> -> <to>, by <decision>`; `fact corrected`; `could not restate` (with why). +Every normative sentence gets a row. History and deliberation may be grouped by section. These +tables are the writer's. They are not evidence of equivalence; the independent check is. diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/independent-check.md b/meta/sessions/2026-11-09-applications-for-readers-redo/independent-check.md new file mode 100644 index 0000000..255dcb7 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/independent-check.md @@ -0,0 +1,105 @@ +# Independent equivalence check (prompt step 7) + +Three fresh agents compared each old document (`84aa466`) with its rewrite (`b489627`). None of +them had seen the rewrite being made. Each was given the paths of the old and new text and told to +report differences in meaning, register and falsifiers. They were not given the conventions, the +equivalence tables or this session's findings, and were told not to read this folder. They could +read the decisions, the claims, the pins and the example files to check facts. They found **89 +points: 28, 25 and 36, 13 of them called serious.** Each is listed below with what was done. "Fixed" +means the text was changed. "Kept" means the point was examined and the text left as it is, with +the reason. + +**One mistake in the checks themselves.** The What/How checker read the clone's local `main`, +which is stale, and reported that `DDD-dec-118` was "not on main". `origin/main` (`84aa466`) +holds it. `DDD-dec-119` and `DDD-dec-95` are on this branch, and land with the rewrite they +support. Its "unsupported on main" findings for the How are therefore read as "supported by +`DDD-dec-119`", and each one was still checked against that decision's own limits. + +## The What and the How — 25 points, 5 serious + +| # | Point | Disposition | +|---|---|---| +| how 1, voc 1 | The How and its vocabulary read as ratified, but `DDD-dec-55` to `-61` name ratification "after the identity form lands" | Kept. `DDD-dec-119` rules that the merge ratified them (Round 2) | +| how 2 | Every former `[PROPOSED]` point now reads as decided | Kept, by `DDD-dec-119`'s table. Each row was checked against the table | +| how 3 | **§5.2's term list and §11 read as plainly decided, but `DDD-dec-119` reaches them only through the banner, which it marks as Claude's reading** | **Fixed.** Both are marked *(Claude's reading, not yet confirmed by Emil)* at the point and listed in "Not settled yet", and §5.2's row in the basis table is corrected | +| how 5 | **"Not settled yet" misstated what confirming `DDD-dec-45`'s consequence would do** | **Fixed.** It now says the reading would be in tension with the How's refinement for debt | +| how 4 | The anchor row's `UNVERIFIED` mark was dropped | Kept. `DDD-dec-55`'s statement holds the reading (findings F-13) | +| how 6 | "should warn" became "warns" | Kept. `DDD-dec-55`'s statement and `check.py` both warn | +| how 7, 8, 9 | `REST@1` became `REST@2`; §12's anchors; `RESID@1` imported at the demand | Kept. Facts corrected against the records (F-14), and the checker confirmed each | +| how 10 | Cross-references: three corrected; "(H-9)" became "(Appendix A)" | Kept. The corrections are right, and Appendix A's rows carry their H labels | +| how 11 | §9.4 lost "— not resolved here" | Fixed | +| how 12 | "`DDD-dec-42` stands" was narrowed to the anchor rule | Fixed. It now gives both halves of that decision: anchoring, and change only by decision | +| how 13 | Lost: Product Framework v1.10.0 §3; the risk-3 quote; the charter, and that the document answered it | Fixed, in "Where this comes from" | +| voc 3 | "Locale kinds … defined in its ontology" overstated: locale is a property, not a kind | Fixed | +| voc 4, 5 | `localId` history; D-3 pointer | Kept: both correct | +| what 1 | "Ratified when its pull request merged" | Kept. `DDD-dec-64`'s made line, and #42 merged | +| what 2, 4 | §2.1 to §5; §5.1 to `authority.md` §9 | Kept: corrections (F-9) | +| what 3 | "(PF §3.2.0)" became a pointer to this document's own §3.2.0, which does not list the datatypes | Fixed: "the source's datatype list"; the source stays in the basis table | +| what 5 | The Force row dropped "the genesis grant" | Fixed | +| what 6 | §3.5 gained a plain-words first sentence | Kept. Round 2 allows a gloss in the first sentence | +| what 7 | "this tool" became "the What's own checker" | Kept. The old phrase had no referent, and #48's check settled on the same reading | +| what 8 | §8 lost the P-1 to P-7 labels; Q-2 and `DDD-dec-45` absent | Fixed, in "Where this comes from" | + +## The PDLC, the SDLC and the READMEs — 36 points, 3 serious + +| # | Point | Disposition | +|---|---|---| +| sdlc.md 1 | **§5: "probably not giving any value" weakened the ruling ("properly not giving any value"; `DDD-dec-114`: "gave no value")** | **Fixed:** "was not giving any value" | +| sdlc/README 2, applications/README 2 | **The How shown as plainly ruled, although two parts rest on Claude's reading** | **Fixed.** Both rows now name the unconfirmed readings | +| sdlc/README 3 | **"One reading" for `how.md`, which marks three** | **Fixed.** All three are named, and so is the §5.2/§11 reading | +| applications/README 4 | "`DDD-dec-41` to `-64`" for the What takes in the How's decisions | Fixed: `-41`, `-42`, `-63`, `-64` | +| applications/README 5 | "Called sdlc.md `[PROPOSED]`": the mark sat on the nesting sentence | Kept. The text names what was corrected, and the register was wrong either way (`DDD-dec-114`) | +| applications/README 1, 3 | Nesting unmarked; "ready to try" | Kept. Both are supported (`DDD-dec-114`, `DDD-dec-74`) | +| pdlc/README 1 | "Should one day nest has been decided" overstates R9's "now" | Fixed: "decided for now" | +| pdlc/README 2 | "Moved here" read as `pdlc/` | Fixed: "into `applications/sdlc/`" | +| pdlc.md 1 | A ruled option text called "an earlier reading" | Fixed: "an earlier ruling … a later one corrected it" | +| pdlc.md 2 | That the withdrawn falsifier was Claude's was lost | Fixed | +| pdlc.md 3 | "The What owner classifies" can read as all demand | Kept. The old text said the same ("The classifier: 'What owner'") without a scope, and the table that follows gives the scope | +| pdlc.md 4–6, register list | Quotes made prose; two sentences in "Not settled yet"; sources added; registers | Kept. Same strength. The added sentences say what deciding would change, as the format asks. The sources exist | +| sdlc.md 2–8 | D-9, the example's three issues, the projected claims, O-items, the toggle store | Kept. Each is supported, and the reviewer said so. Round 30's "no open items remain … except the successor work", against O-3's "Emil", predates the rewrite and is not changed | +| sdlc/README 1, 4, 5, 7, 8, 9 | Ratification of `what.md` and `authority.md`; production-as-ground's register; the removed sentence | Kept. Supported. #45 merged on 2026-11-02 (the pull request's record) | +| sdlc/README 6 | Product Framework §3 and §6.3.1 lost | Fixed, in the row | +| organizations 1–3 | Statements and falsifiers byte-identical; the stale UNVERIFIED note; headings | Kept: correct | + +## The authority profile, product-cli, the examples, production — 28 points, 5 serious + +| # | Point | Disposition | +|---|---|---| +| pd 19 | **D1.11 ("no authority, ever") presented as in force, though `DDD-dec-117` superseded it, and the opening said replaced rulings are not stated** | **Fixed.** The opening names the exception; each of the three passages carries a marked note; "Not settled yet" lists it; `DDD-dec-117` is in the basis; the table shows the supersession. The passages are not reworked, which is the specification-feasibility work's (`DDD-dec-117`) | +| auth 2 | **"No point is open" beside an amendment the text is not reworked to; no "Not settled yet"** | **Fixed.** The opening names the amendment, and a "Not settled yet" section lists it, with `DDD-dec-117`'s own unconfirmed reading | +| auth 1, voc 8 | "Ratified when its pull request merged" | Kept. Supported (`DDD-dec-85`, `-86`, `-92`, `-93`; #45 merged) | +| voc 9, 10 | The IRI reading not listed; scope still "a set of ontology classes" | Fixed: "Not settled yet" added to the vocabulary, with both | +| auth 3 | "The earlier reading … is withdrawn" understated a withdrawn ruling | Fixed: "earlier ruling" | +| auth 6 | A11's mirror labelled "the genesis grant's fallback rule", though any grant may have one | Fixed: "the fallback rule" | +| auth 4, 5, 7 | Scope of a table row; "later work"; two added, accurate sentences | Kept | +| keys 12 | The ruling quote made a plain rule | Kept: same strength, quote in the table | +| keys 13 | No reader/settledness opening | Fixed | +| ex 14, 15 | Counts and positions | Kept: verified by `check.py` | +| ex 16 | "The ruled What, How and authority profile" overstates (the How has an open point) | Fixed: "the decided parts of" | +| ex 17 | "So Acme Shop imports four" drew a causal link | Fixed: "So" removed | +| ex 18 | Superseding ids in words | Kept: ids in the table | +| pd 20, 21, 23, 24 | §3.7 correction; the open point; paraphrases; "not yet built" | Kept: supported, and checked verbatim | +| pd 22 | The vectors read as "its second implementation" (M-12) | Fixed: "a further cross-check beside the canonical form's second implementation, not a substitute for it" (`DDD-dec-113` E-3) | +| prod 25, 26, 28 | Evidential status, cross-references, falsifiers | Kept: unchanged or correct | +| prod 27 | `core/10`'s structure became "the framework's **cost** structure", a qualifier added | Fixed: "cost" removed. The citations stay in the table | +| basis | Local claims should be `ID@status` (`DDD-dec-94`) | Checked by script: no local claim in any basis lacks a status. Upstream claims are pinned and written bare, as the spec's own example does | + +## What this says + +- **The failure class #48 named recurred, less often and less severely.** #48's rewrite of 8 + documents produced 64 points. This rewrite of 15 documents produced 89, and 13 were called + serious: + - 6 were register changes that the decisions support (how 1, how 2, voc 1, auth 1, voc 8, voc 9, + the last for a missing "Not settled yet" section). They were kept, or fixed where a section was + missing. + - 3 stated as plainly ruled what rests on a flagged reading (how 3, and the How's rows in both + READMEs). All are fixed. + - 1 lowered a decided point: sdlc.md's "probably". Fixed. + - 2 stated a superseded or amended rule as in force (pd 19, auth 2). Both were already in the old + text, and the rewrite's new opening made them explicit. Both are fixed. + - 1 misstated the stake of an unsettled point (how 5). Fixed. +- **The writers' equivalence tables missed every serious one,** as #48's did. They are not evidence + of equivalence on their own. +- **Two of the serious points come from the anchor rule's other side.** A rewrite that keeps the + text in place keeps its stale passages too. A later decision (`DDD-dec-117`) amends text that no + session reworked. The format now makes that visible ("Not settled yet") instead of hiding it. diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/prereg-a4-human-first-contact.md b/meta/sessions/2026-11-09-applications-for-readers-redo/prereg-a4-human-first-contact.md new file mode 100644 index 0000000..e5e31b1 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/prereg-a4-human-first-contact.md @@ -0,0 +1,164 @@ +# Pre-registration — A-4, the human first-contact test + +Successor item A-4. It is the test that decides whether the reader format stays (Emil, 2026-11-09: +"Keep it, human test decides"; option text: "Apply the format; a human first-contact test +(successor A-4) decides later"). This file was written and committed **before any Gate B rewrite +was committed**. Whoever runs the test records this file's SHA-256 when they start it, and checks +it again in the report. The file is not edited after the test is scheduled. A change is a new +pre-registration that names this one. + +**Not run in this session.** Emil's ruling asks for a human test. Model readers are not a +substitute, and none is used. #48's model-reader test (four agents, 8 of 8 each) hit a ceiling and +could not discriminate. A model reads a long record as easily as a short guide. The format exists +for people. + +## What is tested + +Whether people new to the method use `applications/` better in the reader format than in the +record format it replaced. The two versions carry the same rules, and only the presentation +differs. + +- **Old:** the documents at `84aa466` (`main` before this session). +- **New:** the same documents at the head Emil lands from this session, which `report.md` names. +- **In use:** `applications/sdlc/what.md`, `applications/sdlc/how.md`, `applications/sdlc/sdlc.md` + and `applications/pdlc/pdlc.md`, rendered as HTML (GitHub's rendering is fine), with + `applications/sdlc/what/examples/acme-shop.ttl`. Both groups get the same four documents in the + same rendering, and nothing else from the repository. + +## The readers + +- **Six people at least, eight if possible**, split evenly between old and new at random (a coin + or a shuffled list, recorded). +- **Who:** practitioners of the roles the documents name as readers: developers, architects and + product owners. At least one of each role in each group, where the numbers allow. +- **Excluded:** Emil; anyone who has read any version of `applications/`, PR #48, or this + session; anyone who has worked on the method or its repositories. +- **Recorded for each reader, not used to score:** role, years of practice, and whether they have + used event modelling or decision records before. +- **Consent:** each reader knows the answers are kept, without their name, in the session record. + +## What each reader is given + +The four documents and the `.ttl` file, the three tasks below in writing, and **45 minutes in +all**, timed. No help from the person running the test beyond the written instructions. The time +limit is part of the design. #48's readers had unlimited time, and a careful reader with +unlimited time can find anything in either version. + +### Task 1 — change the What (25 minutes) + +> You are joining the team that owns Acme Shop, a small web shop. Its specification of what the +> software is and does (its "What") is described in the documents, and its full What is the file +> `acme-shop.ttl`. +> +> Acme Shop wants staff to be able to add a free-text note to an existing order. Customers must +> not see the note. +> +> 1. List what you would add to or change in the What, and where each belongs. +> 2. Say how each addition gets into the What: what is written, what it is attached to, and why +> there. +> 3. Say who must sign or approve it, and what they must hold to be allowed to. +> 4. Say when the change is in force. +> 5. List anything in the documents you did not understand or were unsure about. +> +> Answer from the documents only. Say where you are guessing. + +The task avoids the six known content gaps (successor items A-8 to A-12 and A-16). It changes an +existing paid order, adds a field to an existing entity, and creates no new owner in the same +change, so a reader can answer it fully from either version. + +### Task 2 — how settled is it? (10 minutes) + +> For each statement, say whether the documents present it as **decided**, **proposed but not +> yet decided**, **open (no proposal yet)**, or **an interpretation the author has not had +> confirmed**. Give the place you found it. + +| # | Statement | Key (the same in both versions) | +|---|---|---| +| T1 | A What may use named-algorithm primitives | decided (`what.md` §3.5) | +| T2 | An adopter may register new abstract interaction objects (AIOs) | open (`what.md` §3.2.2; `how.md` §6) | +| T3 | The baseline's ratchet semantics, as used for coverage debt | an unconfirmed interpretation (`how.md` §8.2) | +| T4 | Method step 7, which the PDLC's accountability is mapped to | proposed (`pdlc.md`, its mapping to step 7) | +| T5 | An approval of a candidate is given by hand by a holder of Approve for the issue's locus | decided (`sdlc.md`, o10) | +| T6 | Whether adopters may register What kinds | open (`how.md` §10) | + +Before the test runs, the person running it re-checks each key against both versions. If any +key differs between them, that item is dropped and the drop is reported. Items whose register +`DDD-dec-119` changed were left out on purpose. + +### Task 3 — find it (10 minutes) + +> Answer each in one sentence, and give where you found it. +> (a) In the SDLC, what must hold before `main` is moved to a candidate? +> (b) In the PDLC, who orders new demand, and who orders owed work? +> (c) In the What, what is a Decider for? + +## Scoring + +**Scored blind.** A third party removes names and version clues (file names, the `ddd:doc` +block's presence) from the answers and labels them A to H. The scorer is a person who knows the +method (Emil, or someone he names), and does not know which label read which version. A fresh +model agent may score the same blinded answers as a second rater. Its scores are reported only to +show agreement, never used in place of the human's. + +**Task 1, eight criteria, one point each.** K3, K5, K6 and K8 are the hard ones. The old text +puts their answers in a decision-cited passage, an appendix or a numbered reference section. + +| # | Criterion | Hard | +|---|---|---| +| K1 | Adds a field (the note) to the `Order` entity, and a command, or a payload field on one, by which staff add it | | +| K2 | Says the field is not in the customer's view: the `Order summary` view's scope or fields keep it from customers | | +| K3 | Anchors each decision to the narrowest existing element that covers what it creates or changes (`Order` for its new field), not to the new element | **yes** | +| K4 | Says the What is not edited in place: every change is a decision, and a tool only proposes | | +| K5 | Says the signer must hold a grant (an authoring scope) covering these element kinds, delegated from the product's founding (genesis) grant | **yes** | +| K6 | Says nothing is in force until a human holder accepts it, and a new What-version then names the What in force | **yes** | +| K7 | Says the new elements get new identities, and `Order` keeps its own | | +| K8 | Says who may issue the command (staff only), using the What's subject kinds and their rules | **yes** | + +**Task 2:** one point per correct register, out of six (fewer if items are dropped). **Task 3:** +one point per correct answer with a correct location, out of three. **Time:** each reader's +minutes for Task 1 are recorded, and a reader who does not finish within time scores what they +wrote. + +## What counts as the format helping, and as it failing + +Fixed before any reader is recruited. With six to eight readers this is a coarse test. The rules +say what result moves the decision, not what is statistically significant. + +**The format helps** if all three hold: + +1. On the hard criteria (K3, K5, K6, K8), the new group's mean is at least **1 point above** the + old group's mean (out of 4). +2. On Task 2, the new group's mean is **not below** the old group's. Ruling 2 put the register + into words, and this checks that the words did not lose it. +3. **No more than one** new-text reader lists a format device as something they did not + understand. The devices are the plain-words register phrases, the "Not settled yet" section, + the "Where this comes from" table, and the opening "How settled this is". + +**The format fails** if either holds: + +1. On the hard criteria, the new group's mean is **at or below** the old group's mean, **and** on + Task 2 it is at or below the old group's too. +2. **Two or more** new-text readers name the **same** format device as confusing. + +**Otherwise the result is inconclusive.** + +**Reported in every case, but not part of the rule:** the means on all eight criteria and on +Task 3; time used; any old-text reader who names ids, section numbers or register tags as +confusing; and content confusions common to both groups, which go to the successor items, not to +the format. + +## What happens in each case + +- **Helps:** the format stays as ruled (`DDD-dec-94`, `DDD-dec-95`). A-2 (`apparatus/`) may go + ahead, with an independent equivalence check before anything else. +- **Fails, limb 1:** the format has not shown it helps people either. Emil chooses between + (a) restoring the record presentation, where each document's `supersedes` pointer makes that one + revert per document, and (b) #48's named fallback: ids stay out of the prose, with invisible + point-of-use markers in place of the closing table. A-2 waits for that ruling. +- **Fails, limb 2:** the named device is changed or removed in `applications/` before any of it + reaches `apparatus/`, and that device alone is tested again. +- **Inconclusive:** the format stays, since Emil's ruling keeps it until a test decides. He rules + whether to run again with more readers or to accept the format as it stands. + +The result, the blinded answers and the scores go in a session record. The decision that acts +on it cites this file and its SHA-256. diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/prompt.md b/meta/sessions/2026-11-09-applications-for-readers-redo/prompt.md new file mode 100644 index 0000000..5b30a24 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/prompt.md @@ -0,0 +1,30 @@ +# Prompt — applications/ for readers, redone, 2026-11-09 + +The session prompt, verbatim. Per `DDD-dec-20`, this file is committed before any other file +changes, so the session's scope is fixed at arrival. + +--- + +New session: applications/ for readers, redone, 2026-11-09, in mindovermachine-dev/decision-driven-design. It succeeds PR #48 (closed, not merged). Start only once PR #64 (the PDLC and the SDLC) has landed; branch from main and report its head. If #64 has not landed, stop and say so. Open an issue; Refs #N on every commit. Commit prompt.md and bootstrap.md under meta/sessions/2026-11-09-applications-for-readers-redo/ first. +Emil's rulings, verbatim +Claude's question dialog on claude.ai, 2026-11-09. They are also recorded on PR #48 (issuecomment-6736005356): +Q: "What should happen to PR #48 (applications/ for readers, DDD-dec-94/95), now 92 commits behind and colliding with #64?" A: "Close; successor redoes it (Recommended)" (option text: "Land #64 first. Close #48, branch kept as record. A new session lands DDD-dec-94 + spec/doc-format.md, then redoes the rewrite (DDD-dec-95) on current applications/, pdlc/ and sdlc.md, reusing #48's report and check") +Q: "#48 asked whether to keep the reader format given its reader test could not show it helps. Your ruling?" A: "Keep it, human test decides" (option text: "Apply the format; a human first-contact test (successor A-4) decides later") +The second answers #48's ruling request 1. Its requests 2 to 4 are still open: whether merging PR #41 settled the How's unruled parts (DDD-dec-58, -59); the named-algorithm heading against DDD-dec-64 P-5; and the six content gaps every reader found, starting with the example scenario that contradicts the wire rule. +Sources to read before writing anything + +* The #48 branch, claude/applications-for-readers-2026-11-02 at 068cb23, as the record: its session folder meta/sessions/2026-11-02-applications-for-readers/ (prompt, rulings, report.md, independent-check.md, the reader test and its pre-registration), core/decisions/DDD-dec-94.yaml and -95.yaml, spec/doc-format.md. +* main as landed: applications/ in full, including applications/pdlc/ and applications/sdlc/sdlc.md from #64; DDD-dec-113 (sdlc edition 1), -114, -115; the 2026-10-26 doc-format rulings DDD-dec-94 re-files; graph/upstream.yaml. + +The work +Predict before each operation. Stop at every gate. + +1. Record the rulings above verbatim in rulings.md. +2. Check that DDD-dec-94 and -95 are still held only by the #48 branch. Re-check every branch for any other use. Report it if either is held elsewhere. +3. Gate A, the format. File DDD-dec-94 on main from the #48 branch's file, with its content unchanged except: its date, its re-filing note naming this session and #48, and anything main has since made wrong (say what and why). Port spec/doc-format.md the same way. Commit, run the validators, and stop for Emil. +4. Put #48's open ruling requests 2 to 4 to Emil, each with what #48 found and what main says now. Record his answers verbatim before writing anything they affect. +5. Gate B, the rewrite. Redo DDD-dec-95's rewrite against applications/ as it now stands, in the format of spec/doc-format.md. Cover every document, including applications/pdlc/ and applications/sdlc/sdlc.md. Use #48's work as input, not as text to paste: its what.md / what-reference.md and how.md / how-reference.md split, and the 64 differences its independent check found, as a list of traps. Keep every section anchor that other documents cite (pdlc.md cites what.md §3.0 to §4.2): either keep the numbering, or update every citation in the same commit and list them. Nothing proposed may read as decided, and nothing decided may be weakened; that was #48's main failure class. Include the release session's F-2: applications/README.md still calls sdlc.md [PROPOSED], while sdlc.md and DDD-dec-115 say its proposals were ruled in Round 28 of the 2026-11-07 record. Read that round first and state each document's register as the decisions give it. +6. File DDD-dec-95 for the rewrite, adapted to what it now covers. Say what differs from the #48 version and why. +7. Independent equivalence check. Brief a separate agent that has not seen the rewrite being made. Give it the old and new text, not your conclusions, and have it report differences in meaning, register (ruled / [PROPOSED] / [OPEN]) and falsifiers. Fix each difference or record why not. +8. The human first-contact test (Emil's ruling: "human test decides"). Do not run it with model readers as a substitute. Write its pre-registration as successor A-4: who the readers are, what they are given, what counts as the format helping and as it failing, and what happens in each case. Add it to successor-items.md for Emil to schedule. +9. Run the validators. Push, wait for green CI, report the head and the land commands, and stop. Do not land. diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/report.md b/meta/sessions/2026-11-09-applications-for-readers-redo/report.md new file mode 100644 index 0000000..569039b --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/report.md @@ -0,0 +1,98 @@ +# Report — applications/ for readers, redone + +Branch `claude/zealous-ptolemy-3txf8k`, from `main` at `84aa466` (`main` has not moved). Issue #71. +The session stops here for Emil. Nothing is landed. + +## Weakest point first + +**Whether the format helps people is still not shown.** Emil ruled that a human first-contact +test decides it (Round 1). That test is pre-registered as A-4 and not run, because model readers +are not a substitute (`prereg-a4-human-first-contact.md`, committed at `ebf84a5` before any +rewrite, SHA-256 `54344db1d6671aa65d71194b7685b4f9a7f01cc50ff681d00db9112cb715b58e`). It is +Emil's to schedule. + +The second weakest point: **the rewrite again produced the failure class #48 named.** 13 serious +points before the independent check, every one of them fixed or kept with a recorded reason. The +writers' own equivalence tables caught none of them (`independent-check.md`). + +## What landed on the branch + +| Gate | What | Commits | +|---|---|---| +| G0 | `prompt.md`, `bootstrap.md` | `70abfa2` | +| — | Round 1 verbatim | `eb52cda` | +| A | `DDD-dec-94` re-filed from #48's file, with what `main` made wrong; `spec/doc-format.md` ported | `1378851` | +| Q | Round 2 verbatim (Emil's answers to #48's requests 2 to 4, and the register phrases) | `4a4b864` | +| — | `DDD-dec-119`: #41's merge ratified the How's "not ruled separately" parts | `0ea1376`, `6536d9c` | +| B | Conventions; the A-4 pre-registration; 15 documents rewritten, one commit per document group; `DDD-dec-95` and the spec's folder line | `cdae9bf` … `b489627` | +| 7 | The independent check, and its fixes | `f61ca44` | + +## Decisions filed + +- **`DDD-dec-94`**: the 2026-10-26 doc-format rulings re-filed, with #48's text unchanged except + its `made` line and a re-filing note (findings F-1). +- **`DDD-dec-95`**: the reader format as applied. It differs from #48's version in the following + ways, each with its reason in the decision. + - No split, merge or rename: sections are cited by number in hashed and signed files (F-6, F-8). + - F4 adapted and F5 not applied. + - Four registers in words (Round 2). + - No new point-of-use markers. + - Scope: all 15 documents. + - The human test decides. +- **`DDD-dec-119`**: Emil's Round 2 answer on #41. The §5.2 term list and §11's level are reached + only through the document's banner. That reading is Claude's, flagged in the decision and in + `how.md`. + +## Predictions + +| # | Prediction | Outcome | +|---|---|---| +| 1 | #64 has landed | Held: merged 2026-11-09 | +| 2 | `DDD-dec-94`/`-95` held only by #48's branch | Held. No other branch holds `94` to `99` (`bootstrap.md`) | +| 3 | #48's two files need only what `main` made wrong changed | Held. Only the `made` line and one pointer (F-1) | +| 4 | Anchors constrain the split | Held, more than predicted. 157 citations, and the split was dropped (F-8) | +| 5 | The independent check finds points the tables missed | Held: 89 points, 13 serious | +| 6 | CI stays green after every commit | Held at every pushed head | + +## Rulings and questions for Emil + +1. **Confirm or correct `DDD-dec-119`'s reading** that the merge reached `how.md` §5.2's term list + and §11, which only the banner covers. If rejected, both return to proposed. +2. **F-13**: the stale `UNVERIFIED` mark on `how.md` §2's anchor row was dropped, because + `DDD-dec-55`'s statement holds the reading. Say if the mark was meant for the row's other + sentence. +3. **F-10**: `pdlc.md` §2.1's seam rows 1 to 8 are kept as not ruled, as `DDD-dec-114` says, + although the register line says the tables were ruled. +4. **A-4**: schedule the human test. +5. **A-8 first** (Round 2): the example's claim inside `with`, against the wire rule. It needs a + new What-version. + +## Not done, and why + +- **`DDD-dec-117`'s amendments are not worked into `authority.md` §3.1–§3.2 or + `product-definition.md`'s "no authority" passages.** That changes content, which this session does not, + and belongs to the specification-feasibility session's successor work. Each passage is now marked, and listed + under "Not settled yet". +- **`what/ontology.ttl`, `shapes.ttl`** (A-6) and **`pdlc/graph/ontology.ttl` line 160** (F-11): + graph files, not in scope. +- **The `ddd:doc` check** (A-1) is not ported, so the blocks are a convention. + +## To land + +The approval (`DDD-dec-109`) is a comment on a pull request. No pull request is open, since none +was asked for. Either Emil opens one (or asks Claude to) and lands it the usual way: + +``` +approve <head sha> # by hand, on the pull request +canon land <PR> --print +canon land <PR> +canon land <PR> --main # after pipeline (devcontainer) is green on land/pr-<PR> +``` + +or, while `agent review` is not yet required, lands the head without a pull request: + +``` +canon land --commit <head sha> --print +canon land --commit <head sha> +canon land --commit <head sha> --main +``` diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/rulings.md b/meta/sessions/2026-11-09-applications-for-readers-redo/rulings.md new file mode 100644 index 0000000..76a8220 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/rulings.md @@ -0,0 +1,74 @@ +# Rulings — applications/ for readers, redone + +Recorded verbatim, when given. + +## Round 1 — before the session, on PR #48 (2026-11-09) + +Given in Claude's question dialog on claude.ai on 2026-11-09. They are also recorded on PR #48 +(issuecomment-6736005356) and in this session's `prompt.md`. + +> Q: "What should happen to PR #48 (applications/ for readers, DDD-dec-94/95), now 92 commits behind and colliding with #64?" A: "Close; successor redoes it (Recommended)" (option text: "Land #64 first. Close #48, branch kept as record. A new session lands DDD-dec-94 + spec/doc-format.md, then redoes the rewrite (DDD-dec-95) on current applications/, pdlc/ and sdlc.md, reusing #48's report and check") + +> Q: "#48 asked whether to keep the reader format given its reader test could not show it helps. Your ruling?" A: "Keep it, human test decides" (option text: "Apply the format; a human first-contact test (successor A-4) decides later") + +The second answers #48's ruling request 1, which was option (a) of `report.md` §"Rulings +requested". Requests 2 to 4 are still open and go to Emil in Round 2. + +## Round 2 — at Gate A (2026-11-10) + +Claude's question dialog in this session, after Gate A was pushed at `1378851`. Questions as put, +answers as given, with the chosen option's text. + +> Q (Gate A): "Gate A is pushed (claude/zealous-ptolemy-3txf8k, head 1378851, all CI gates green). DDD-dec-94 and spec/doc-format.md are #48's text, changed only where main made them wrong: the made line cited #48's record and PR as if on main. One application question before Gate B (findings F-5): the spec marks every unsettled point *(not settled yet)*, but applications/ distinguishes [PROPOSED] (proposal awaiting a ruling) from [OPEN] (no proposal). How should the rewrite say registers?" A: "Accept; two phrases (Recommended)" (option text: "Gate A accepted. In prose: *(proposed, not yet ruled)* for [PROPOSED] and *(open)* for [OPEN]; the closing table keeps the bracket markers. No change to DDD-dec-94") + +> Q (#48 request 2): "#48 ruling request 2: did merging PR #41 settle the How's unruled parts? how.md on main (untouched since) still says 'What was not ruled separately stays [PROPOSED] until the merge', and #41 merged (1d0f40c). DDD-dec-58 states coverage (debt/boundary/waiver) word for word; DDD-dec-59 states withdrawal and the three parts of an import (landing, import decision, acceptance) word for word, yet how.md §5/§7 mark those [PROPOSED]. Appendix A attributes H-3, H-8, H-9, H-11, H-12, H-13, H-17 to decisions -55/-57/-59/-60 while calling them 'not ruled separately'. Which are settled?" A: "The merge ratified them all" (option text: "Every 'not ruled separately' item became ruled when #41 merged; the rewrite drops their [PROPOSED] marks") + +> Q (#48 request 3): "#48 ruling request 3: DDD-dec-64 P-5 ruled what.md §3.5's title as 'Named-algorithm primitives', no subtitle ('floor' is canon's). main still has that title. #48's rewrite changed it to 'Named algorithms — computation you name instead of deriving'. Which title should the redo use?" A: "Keep the ruled title (Recommended)" (option text: "'Named-algorithm primitives', no subtitle; a plain-words gloss may go in the first sentence of the section, not the heading") + +> Q (#48 request 4): "#48 ruling request 4: six content gaps every reader found, all still true on main: (1) no unpaid order; (2) the example scenario puts the customer_id claim inside the command's `with`, against what.md §6 'supplied beside the command, never inside its with' — in acme-shop.ttl, -4 and -5, all hashed, so a fix needs a new What-version; (3) anchoring a decision that both creates and changes; (4) subject coverage's range; (5) whether a field's creation rides with its owner's; (6) no command carries an order id. How should this session treat them?" A: "Successor items; A-8 first (Recommended)" (option text: "Not fixed or marked in the rewrite (presentation only). Kept as A-8 to A-12 plus (1); A-8, the wire-rule contradiction, scheduled first in its own session with a new What-version") + +### Claude's reading — UNVERIFIED, Emil review + +- **Request 2 reaches the items `how.md` itself lists as "not ruled separately"**: the §10 list + (the three kinds, no fourth and no split, the idle report, the record types; shapes derived from + editions, standards not targets; the recorded-reading condition and narrow-never-alter; Kind-1 + wiring as contracts and `deployment-declared` facts gating `land`), Appendix A's H-3, H-8, H-9, + H-11, H-12, H-13 and H-17, and the passages marked `[PROPOSED]` with "not ruled separately" or + "the proposal kept". It does **not** reach §10's item 2, which is `[OPEN]` (whether adopters may + register What kinds), and it does not reach material in other documents. The ruling is a change + of register, so it is filed as a decision of its own (`DDD-dec-119`) rather than carried only + inside the format decision. +- **Request 4, item (1)** (no unpaid order) has no #48 number, and is added as A-16. + +## Round 3 — after the stop, on PR #73 (2026-11-11) + +Emil's message, verbatim: + +> PR #73 is open on your branch at 86d9042. Record this message verbatim in rulings.md as Round 3, and predict before each operation. These are my answers in Claude's question dialog on claude.ai: +> Q: "DDD-dec-119's reach: does "the merge ratified them all" also cover how.md §5.2's term list and §11's conformance level (covered only by the document's banner)?" A: "Yes, it covers them (Recommended)" (option text: "The banner made them 'not ruled separately' items, which the ruling names; §10 item 2 stays [OPEN]") +> Q: "F-13: accept dropping the UNVERIFIED mark on how.md §2's anchor row, since DDD-dec-55's statement contains that reading?" A: "Accept (Recommended)" (option text: "DDD-dec-55 states the narrowest-element anchoring and the product-node reading") +> Q: "F-10: pdlc.md §2.1's seam rows 1–8 are not ruled (DDD-dec-114 P-3). What now?" A: "Rule rows 1–8 now" (option text: "They are checked against the act map by check.py; rule them as listed, and the register line becomes true") +> +> 1. DDD-dec-119: its reading of the reach is now ruled. Remove its UNVERIFIED mark, and cite this round. +> 2. F-13: closed as you did it. Cite this round. +> 3. F-10: pdlc.md §2.1's seam rows 1 to 8 are ruled as listed. Row 9, telemetry, was already ruled in Round 16 of the 2026-11-07 record. DDD-dec-114 is landed, so do not edit it. File a new decision that supersedes only P-3's sentence "It is not ruled here", and records rows 1 to 8 as ruled, row by row, as they stand in pdlc.md §2.1 at your head. Then make pdlc.md's register line and the rows' markers match. Ids: the plugin session (prompt-4) runs in parallel and may file a decision too. Re-check every branch for ids just before you commit and again just before you push. Take the next free id, and report it. +> 4. Run scripts/ci.py, applications/pdlc/check.py and canon's checks as CI runs them. Push, wait for green CI, and report the new head for my approval on #73. Stop. Do not land. + +## Round 4 — on PR #73 (2026-11-11) + +Emil's message, verbatim: + +> Record this message verbatim in rulings.md as Round 4, and predict before each operation. This is my answer in Claude's question dialog on claude.ai: +> Q: "pdlc.md §2.1 rows 10 and 11 (the classification verdicts) are the redo session's additions. Round 28 ruled R1–R30, and neither those nor DDD-dec-120 reach these rows. Rule them?" A: "Rule them now" (option text: "The redo session adds them to DDD-dec-120 (still unlanded) and #73 gets a new head") +> +> 1. Amend DDD-dec-120 in place, since it has not landed: record rows 10 and 11 as ruled, row by row, as they stand in pdlc.md §2.1 at your head, citing this round. It still supersedes only P-3's sentence "It is not ruled here". +> 2. Remove the rows' "my additions" markers in pdlc.md, and update its "Not settled yet" list and basis table to match. +> 3. Run scripts/ci.py, applications/pdlc/graph/check.py and canon's checks as CI runs them. Push, wait for green validate, and report the new head. Stop. Do not land. +> +> On Agent review: it fails because the runner's .NET SDK moved (NU1004, ILLink 10.0.15 against a lock of 10.0.14), not because of this branch. A separate session pins the SDK. Leave it alone here. I will land #73 with `canon land --commit`. + +### Claude's note on the question's wording + +The question called rows 10 and 11 "the redo session's additions". `pdlc.md` at `84aa466` already +said "The last two rows are Claude's additions, made when the three kinds of demand were adopted", +so they came from the 2026-11-07 session (Round 22), not from this one. The ruling is unaffected. diff --git a/meta/sessions/2026-11-09-applications-for-readers-redo/successor-items.md b/meta/sessions/2026-11-09-applications-for-readers-redo/successor-items.md new file mode 100644 index 0000000..d1d2260 --- /dev/null +++ b/meta/sessions/2026-11-09-applications-for-readers-redo/successor-items.md @@ -0,0 +1,25 @@ +# Successor items — applications/ for readers, redone + +Carried from #48's `successor-items.md` (branch `claude/applications-for-readers-2026-11-02` at +`068cb23`), with the same numbers, so that the record and `DDD-dec-94` stay traceable. The status +column is as re-checked on `main` at `84aa466`. A-4 is re-written at Gate B as the pre-registration +of the human first-contact test (prompt step 8). + +| # | Item | Status | +|---|---|---| +| A-1 | Port the `ddd:doc` check (W8 to W15) from `claude/doc-format` (`df9d05b`) to `scripts/`, as a warning-level gate in `ci.py` | `[OPEN]` (`DDD-dec-94`, "Not re-filed"). Not ported on `main` | +| A-2 | Reformat `apparatus/` to the format, with the independent check run before any reader test | `[OPEN]` (`DDD-dec-95`, next) | +| A-3 | Reformat `applications/sdlc/authority.md` | #45 has merged, and `authority.md` is on `main`. It is in Gate B's scope | +| A-4 | The human first-contact test: the deciding test for the format (Emil, 2026-11-09: "Keep it, human test decides") | `[OPEN]`, **for Emil to schedule**. Pre-registered in `prereg-a4-human-first-contact.md`, committed before any rewrite: six to eight people new to the method, old text (`84aa466`) against new (the landed head), three timed tasks, blind scoring, and the rules for helps, fails and inconclusive, with what follows from each. Not run with model readers | +| A-5 | Write Varve's What, so one example carries the whole method | `[OPEN]` | +| A-6 | Re-point `what/ontology.ttl` (l. 15, 293) and `what/shapes.ttl` (l. 487–500) at the next vocabulary edition: they cite `what.md §6` and `how-vocabulary.md`, and they are hashed into the edition | `[OPEN]`. Still true on `main` | +| A-7 | Re-point the comments in `how-examples/build.py` (`what.md` §2, §3.6, §5, §6) if any section moves | `[OPEN]`. Moot if Gate B keeps `what.md`'s numbering | +| A-8 | The example scenario puts the customer's claim inside the command's `with`, against the wire rule. Fix the example, or the rule | `[OPEN]`; put to Emil in Round 2 | +| A-9 | Anchoring a decision that both creates and changes elements | `[OPEN]`; Round 2 | +| A-10 | Subject coverage: over all subject kinds, or those a Decider serves | `[OPEN]`; Round 2 | +| A-11 | Whether a field's creation rides with its owner's creating decision | `[OPEN]`; Round 2 | +| A-12 | How a command addresses its aggregate (no command carries an order identifier) | `[OPEN]`; Round 2 | +| A-13 | Re-propose the 2026-10-26 Gate 2 rulings 3 and 4 (`way-of-working.md` §5; the agents file, now `AGENTS.md`) against the current tree | `[OPEN]` (`DDD-dec-94`, "Not re-filed") | +| A-14 | Folder charters (`ddd:charter`), re-proposed folder by folder as each is reformatted | `[OPEN]` (`DDD-dec-94`) | +| A-16 | The What has no unpaid order: `Order` is "a placed, paid order" and `Order placed` carries `paid_total`. A change about unpaid orders needs a product decision on payment first | `[OPEN]`; found by all four of #48's readers; Round 2 | +| A-15 | Update the project instructions: the protocol token is dpp/1 | Emil's act; outside the repository | diff --git a/meta/sessions/README.md b/meta/sessions/README.md index 23237c9..1d1c198 100644 --- a/meta/sessions/README.md +++ b/meta/sessions/README.md @@ -53,6 +53,7 @@ session's later work exceeds the committed prompt, the excess is visible as exce | `2026-11-07-sdlc-and-pdlc/` | Interactive, gated — the PDLC founded (`DDD-dec-114`): three owners as scopes under the genesis grant (What, with assurance; When, the business and go-to-market; How, the SDLC), responsibility placed per decision, the option pool and pull, ready for users and the toggle constraint, priority as a When decision; the SDLC filed as an arrangement (`DDD-dec-115`): issue-driven sessions started by a label, takt's `ready/<N>` with Varve's force and no squash, Claude Code Action first, Varve's identity map ported, the occurrence record from edition 1. `applications/pdlc/` and `applications/sdlc/sdlc.md`, `[PROPOSED]`; the `lc:` act map with SHACL shapes and checkers. Fifteen rounds of rulings, verbatim. Workflows not written. Continuation (Rounds 16–22, `prompt-2.md`), amended in place before landing (Round 21): two assurances (product, the What owner's; implementation, the How owner's), evidence in use and observation needs, the What owner's output, three kinds of demand (new through the pool; owed and own-ground direct to the SDLC), the DORA keys as the How owner's answerability, computed over the record. Issue #61 | | `2026-11-08-specification-feasibility/` | Rulings filed, gated — specification feasibility, from a claude.ai conversation (F-1 to F-12): every dependency on ground has a What layer and a How layer, the How decides by three loose-coupling conditions, any granted actor vets a pinned What change and product-cli records the decision (`DDD-dec-116`); vetted ground becomes a ground-sourced bounded context, admitted per system for Deciders, Projectors and Views, with permission the data owner's; product-cli and the framework carry grants and roles, superseding `[D1.11]` (`DDD-dec-117`). Not applied; S-1 to S-8. Issue #62 | | `2026-11-08-demand-flow/` | Rulings filed, gated — map the flow of demand, from the claude.ai conversation's Rounds 23 to 25: a method step after step 1 (`method/01b-map-the-flow-of-demand.md`, `[PROPOSED]`), general, with each process declaring its kinds of demand and the PDLC's new, owed and own-ground as its worked example and starting point; four PDLC-scoped claims in a new area, `DDD-flow-01` to `-04`, projected; `DDD-dec-118`, adding to `DDD-dec-114`; the acme shop's #101, #103 and #104 traced as graph data checked against the act map. Nothing upstream. Round 26 (2026-11-10) closed R-1: sighting separated from entry, only the What owner says whether a defect is a bug. Open: numbering (N-1), promotion (P-1), the two examples (E-1). Issue #67 | +| `2026-11-09-applications-for-readers-redo/` | Interactive, gated — successor to #48 (closed, not merged). `DDD-dec-94` (the 2026-10-26 doc-format rulings) re-filed and `spec/doc-format.md` ported; `DDD-dec-119`, Emil's ruling that #41's merge ratified the How's "not ruled separately" parts; every document under `applications/` (15) rewritten for readers to `DDD-dec-95`, with numbered sections kept in place (cited by hashed and signed files), registers in words, and stale facts corrected (`sdlc.md` ruled, not `[PROPOSED]`: release F-2). Independent check: 89 points, 13 serious, each fixed or kept with a reason. The human first-contact test (A-4) pre-registered, not run. Not landed. Issue #71 | | `2026-11-10-release-v0.7.0/` | Release descriptor, gated. `releases/v0.7.0.yaml` is MINOR under `DDD-dec-82`: step 1b's card was added (`DDD-dec-118`), and no step's register moved (F-1). Format 2, `prerelease: true` for Emil to confirm (F-3). Its `CHANGELOG.md` section is from `canon changelog`, and `canon ratify` fills the ratified head. The prompt calls the PDLC and SDLC specifications `[PROPOSED]`, while the repository says they are ruled (Round 28). The summary follows the repository, and Emil is to settle it (F-2). Not landed and not cut. Issue #69 | | `2026-11-18-act-map-scope-and-pull/` | Interactive, gated — the act map, scope and pull (#80). Carries the two session records of 2026-11-17 and 2026-11-18 from the archive branch at `47cf4cc`, unreworded. Filed (`DDD-dec-122`): the act map with its scope and index of determinables (`DDD-address-06`); a second act map with a second scope or a second declaration of axes (`-07`); a process as a named view, north as the determinable of a pull (`-08`); the pull as a gap between two of four states (`-09`); kinds as ground positions (`-10`); the four states, credited to GitHub user pjarnhus (`-11`). Step 1 starts from scope and pull, a `[PROPOSED]` first part; steps 2 to 10 say what they add to the act map; step 1b reads kinds as positions. Superseding sections, nothing reworded. Three conflicts with canon or earlier rulings caught before filing (K-1 to K-3). Issue #80 | | `2026-11-18-canon-lock-file/` | Interactive, gated — the `agent review` check builds again (#83). NU1004 reproduced: `IsAotCompatible` makes the SDK reference `Microsoft.NET.ILLink.Tasks` at its bundled runtime (10.0.15 in SDK 10.0.404), the lock file holds 10.0.14, and the runner sets `CI`. Corrected: `validate` passes because `CI` is unset in the devcontainer, not because of an older SDK; and agent review builds main's canon, so no pull request can pass it until main builds (D-4). Proposals A (regenerate), B (exact SDK pin), C (pin the ILLink pack); G1 open. Issue #83 | diff --git a/spec/doc-format.md b/spec/doc-format.md new file mode 100644 index 0000000..4f7b01f --- /dev/null +++ b/spec/doc-format.md @@ -0,0 +1,99 @@ +# Document format + +<!-- ddd:doc +reader: people and agents writing or changing a document outside canon in this repository +act: give a document the opener and shape its folder requires +pin: v5.15.2 +basis: [DDD-dec-94, DDD-dec-95, DDD-agent-01] +status: current +supersedes: df9d05b:spec/doc-format.md +--> + +Use this when you write or change a document anywhere outside canon. It says how a document +opens, what it records about its own basis, and how it treats status in its prose. + +**The principle.** Only canon carries authority. Canon is the principle repository's `core/` and +this repository's `core/`. Every other folder exists for a named reader doing a named act. A +document there is ground for that act, and its shape follows from what that reader needs. + +A document outside canon may explain, apply, teach or record canon. It may not be the only place a +result lives. A result that lives only outside canon is **held**, and says so. + +## The opener — `ddd:doc` + +A document opens with an HTML comment block directly under its title. It renders as nothing. + +``` +<!-- ddd:doc +reader: architects, developers and product owners specifying a software product +act: write a product's What, change it, and hand it to the people who build from it +pin: v5.15.2 +basis: [DDD-dec-42, DDD-ground-06, DDD-address-01@projected] +status: current +supersedes: e5a332d:applications/sdlc/what.md +--> +``` + +| Field | Required | Meaning | +|---|---|---| +| `reader` | yes | Who the document is for. A role, not a person, unless the reader is the principal | +| `act` | yes | What they can do after reading it that they could not do before | +| `pin` | yes, unless `historical` | The upstream tag the document was written against | +| `basis` | yes; may be `[]` | What the document rests on: an upstream claim or term id pinned in `graph/upstream.yaml`; a local claim or term with the status it was read at, as `DDD-address-01@projected`; a local decision id; or a held result, `held:<session-dir>/<item-id>` | +| `status` | yes | `draft`, `current`, `held` or `historical` | +| `supersedes` | no | `<commit>:<path>` of the text this document replaced in place | + +| `status` | Means | +|---|---| +| `draft` | Not yet accepted | +| `current` | Accepted, and every basis entry is canon or a decision | +| `held` | Accepted, but rests on at least one result not yet in canon; at least one `held:` entry | +| `historical` | Kept as a record; no live reader acts on it | + +A reformatted document replaces its old text in place. The old text stays reachable through +`supersedes`, so nothing is lost. + +## Status in running text + +Say status in words the reader can use. Keep claim, term, decision and promotion ids out of the +prose; they belong in the `ddd:doc` block and the document's closing basis table. + +- Decided is the default, and goes unmarked. +- Mark an unsettled point where it arises, in words: *(not settled yet)*. List it again, with + what it would change if decided, in a "Not settled yet" section near the end. +- Say how settled the document is as a whole in its opening, for example "decided, and not yet + tried on a real product". + +Where a rule rests on a **projected** claim, an invisible `ddd:ref` marker may sit at the point of +use, so the pin check warns when the claim moves. Decisions get no marker. + +## Folder formats + +A folder may set a narrower format in its `README.md`. The one set so far is `applications/` +(`DDD-dec-95`): every document closes with "Where this comes from"; every numbered section keeps +its number, order and file, because other files cite sections by number, so reference material +stays in its numbered section; unsettled points use one phrase per register; and deliberation +stays in the session record. + +## The check — not yet ported + +The 2026-10-26 session built a warning-level check for these blocks (W8 to W15) against the old +history's validator. It has not been ported to `scripts/`. Until it is, the opener is a convention +that nothing enforces. Porting it is successor item A-1 of +`meta/sessions/2026-11-09-applications-for-readers-redo/`. + +## Where this comes from + +| Section | Rests on | +|---|---| +| The principle | `DDD-dec-94` (2026-10-26 pre-session ruling 1 and Gate 1 ruling 1, re-filed) | +| The opener | `DDD-dec-94` (pre-session ruling 2; Gate 1 rulings 3 and 4; Gate 2 ruling 1) | +| Status in running text | `DDD-dec-94` (the 2026-10-26 pilot's amendment); `DDD-dec-95` (the `ddd:ref` amendment) | +| Folder formats | `DDD-dec-95` | +| The check | `DDD-dec-94`, "Not re-filed" | + +Ported from branch `claude/doc-format` at `df9d05b`, where the original carried the 2026-10-26 +session's full text, including the check. Ported to `main` from PR #48's branch +(`claude/applications-for-readers-2026-11-02` at `068cb23`; #48 was closed without merging) by +`meta/sessions/2026-11-09-applications-for-readers-redo/`. #48's text is kept unchanged except +for one pointer: the check's successor item, which named #48's session folder, is not on `main`.