docs: the decisions behind the convention, and where they live #4

Merged

administrator merged 1 commit from docs/the-decisions-behind-v3 into main

2026-10-27 20:37:15 +00:00

seeds-agent commented

2026-10-27 20:26:46 +00:00

Collaborator

CONVENTION.md says what the rule is. Nothing here said why it is that one, what it replaced, or what the alternative would have cost — and four repositories consume this convention, read by people who were not in the conversation that produced it.

The usual outcome of re-deriving a settled argument is reaching the other answer. That happened twice in two days on a neighbouring repository, over the same question, because the reasoning lived in a thread instead of a file.

What this adds

decisions/2026-10-27-scaleway-assessment.md — the seeds-infra return on v2.1.0 and the synthesis of both returns:

the 29 decisions E1 to E29, with the final grammar;
the four home-node-infra decisions they replace (D6→E13 org mandatory, D10→E9 the VMID widens, P21→E14 boundary and permission set are not substitutes, D11→E17 naming an Organization);
the four crossing points between the two returns, resolved;
the point-by-point answer to R1–R8;
the Organization layer decided 2026-10-27 — shr was answering two questions at once, E28 tenancy, E29 lab, E27 organization_axis, E26 grandfathered, and the five Organizations with what cannot be merged;
section 8: what E13 and E5 cost, measured against the existing estate rather than estimated — 8 blocks classified replace, and 13 prevent_destroy sites where a rename is refused at plan time, not warned about.

Why a file and not a thread

It carries its negative results with their date, which no other file here can hold. "A Container Registry namespace has no cross-project ACL, measured 2026-10-13" shapes a whole Project layout and is never contradicted by a test, because nothing exercises it again. A positive claim is refuted by the first apply; a negative one just sits there being believed. The date is what tells a later reader the question is re-openable.

What is deliberately not here

The v3.0.0 specification. An implementation plan is overtaken by the change it describes, and a plan kept after its PR has landed is a document that disagrees with the code. What it decided is in the assessment; what it builds will be in CONVENTION.md and the registry. Its diffs were also written against the French v2.1.0 and no longer apply to any file in this repository — which makes the point concrete rather than theoretical.

Corrections made to the document

Two dates: it was dated 2026-10-28 in two places, which is tomorrow. A decision cannot be dated after the day it was recorded.

For the other session

The home-node-infra return belongs beside this one, under its own date, so the two can be read against each other rather than through one of them. decisions/README.md says so, and says what else belongs here — and what does not.

Verification

make check green. Swept with the guard from #3 (make english): zero findings in decisions/ — no accented letter, no French word, no secret and no account or project identifier.

Independent of #3, but both touch README.md in different tables, ~30 lines apart.

🤖 Generated with Claude Code

`CONVENTION.md` says what the rule is. Nothing here said **why it is that one**, what it replaced, or what the alternative would have cost — and four repositories consume this convention, read by people who were not in the conversation that produced it. The usual outcome of re-deriving a settled argument is reaching the other answer. That happened twice in two days on a neighbouring repository, over the same question, because the reasoning lived in a thread instead of a file. ## What this adds **`decisions/2026-10-27-scaleway-assessment.md`** — the `seeds-infra` return on v2.1.0 and the synthesis of both returns: - the **29 decisions E1 to E29**, with the final grammar; - the **four `home-node-infra` decisions they replace** (D6→E13 `org` mandatory, D10→E9 the VMID widens, P21→E14 boundary and permission set are not substitutes, D11→E17 naming an Organization); - the **four crossing points** between the two returns, resolved; - the point-by-point answer to **R1–R8**; - the **Organization layer** decided 2026-10-27 — `shr` was answering two questions at once, E28 tenancy, E29 `lab`, E27 `organization_axis`, E26 `grandfathered`, and the five Organizations with what cannot be merged; - section 8: **what E13 and E5 cost, measured** against the existing estate rather than estimated — 8 blocks classified `replace`, and 13 `prevent_destroy` sites where a rename is *refused at plan time*, not warned about. ## Why a file and not a thread It carries its **negative results with their date**, which no other file here can hold. *"A Container Registry namespace has no cross-project ACL, measured 2026-10-13"* shapes a whole Project layout and is never contradicted by a test, because nothing exercises it again. A positive claim is refuted by the first apply; a negative one just sits there being believed. The date is what tells a later reader the question is re-openable. ## What is deliberately *not* here **The v3.0.0 specification.** An implementation plan is overtaken by the change it describes, and a plan kept after its PR has landed is a document that disagrees with the code. What it decided is in the assessment; what it builds will be in `CONVENTION.md` and the registry. Its diffs were also written against the **French** v2.1.0 and no longer apply to any file in this repository — which makes the point concrete rather than theoretical. ## Corrections made to the document Two dates: it was dated **2026-10-28** in two places, which is tomorrow. A decision cannot be dated after the day it was recorded. ## For the other session The `home-node-infra` return belongs beside this one, under its own date, so the two can be read against each other rather than through one of them. `decisions/README.md` says so, and says what else belongs here — and what does not. ## Verification `make check` green. Swept with the guard from #3 (`make english`): **zero findings in `decisions/`** — no accented letter, no French word, no secret and no account or project identifier. > Independent of #3, but both touch `README.md` in different tables, ~30 lines apart. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

seeds-agent added 1 commit

2026-10-27 20:26:46 +00:00

docs: the decisions behind the convention, and where they live

ci / check (pull_request) Has been cancelled

Details

2989b92dc7

CONVENTION.md says what the rule is. Nothing in this repository said why it is that
one, what it replaced, or what the alternative would have cost - and four
repositories consume this convention, read by people who were not in the
conversation that produced it.

The usual outcome of re-deriving a settled argument is reaching the other answer.
That happened twice in two days on a neighbouring repository, over the same
question, because the reasoning was in a thread rather than in a file.

WHAT IS HERE. The `seeds-infra` return on v2.1.0 and the synthesis of both returns:
the 29 decisions E1 to E29, the four `home-node-infra` decisions they replace, the
four crossing points between the two returns, and - section 8 - what E13 and E5 cost
measured against the existing estate rather than estimated.

IT CARRIES ITS NEGATIVE RESULTS WITH THEIR DATE, which is the part no other file in
this repository can hold. "A Container Registry namespace has no cross-project ACL,
measured 2026-10-13" shapes a whole Project layout and is never contradicted by a
test, because nothing exercises it again. A positive claim is refuted by the first
apply; a negative one just sits there being believed. The date is what tells a later
reader that the question is re-openable.

WHAT IS DELIBERATELY NOT HERE. The v3.0.0 specification. An implementation plan is
overtaken by the change it describes, and a plan kept after its PR has landed is a
document that disagrees with the code. What it decided is in the assessment; what it
builds will be in CONVENTION.md and the registry. Its diffs were also written
against the FRENCH v2.1.0 and no longer apply to any file here, which makes the
point concrete.

TWO DATES CORRECTED in the document itself: it was dated 2026-10-28 in two places,
which is tomorrow. A decision cannot be dated after the day it was recorded.

The other session's return belongs beside this one, under its own date, so the two
can be read against each other rather than through one of them. decisions/README.md
says so, and says what else belongs here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>