Decide how the decision register is renumbered and rewritten #362

Activity

1. ExtraToast

   added

   type: docsDocumentation-only change.Documentation-only change.

   area: deployhomelab-deploy, deploy-v2, manifests, and rollout flow.homelab-deploy, deploy-v2, manifests, and rollout flow.

   wayfinder:grillingWayfinder ticket resolved by conversation (HITL)Wayfinder ticket resolved by conversation (HITL)

   on Oct 12, 2026
2. ExtraToast

   added a parent issue on Oct 12, 2026

   • Map: re-establish deploy-kit's goals, rewrite its spec, and order the work until the estate is handed over #341
3. ExtraToast

   added

   status: in-progressActively being worked.Actively being worked.

   on Oct 12, 2026
4. ExtraToast

   self-assigned this

   on Oct 12, 2026
5. ExtraToast commented on Oct 12, 2026

   

   ExtraToast

   on Oct 12, 2026

   ContributorAuthor

   More actions

   Resolution

   Settled with the maintainer on 2026-10-12. The content was fixed by Decide what is cut, merged or deferred from the spec and the register; this ticket fixes the mechanics. Facts read first: the numbers 0001 to 0098 are contiguous today across both registers; npm run lint:adrs checks uniqueness only, within one register root; npm run lint:links reads tracked *.md only, so the ADR paths cited in code comments are held by nothing (scripts/lint-codes.ts still cites docs/adr/architecture/0118, a number from before the 2026-09-29 rebuild).

   Numbering

   • A number is retired for good. A folded or deleted record's number is never taken again, and the gap stays. The next record takes the highest number ever used plus one, which is 0099 today. Rejected: reuse (a stale citation would land on an unrelated decision) and a second full renumbering (it breaks every link, comment and issue mention again).
   • In a fold, the lowest number survives and the file is renamed to the merged title, so the slug says what the record now decides. The one fixed exception is 0041, which folds into 0092 because 0092 is the decision that absorbs it. The survivors are therefore 0032 (absorbs 0044), 0047 (absorbs 0051 and 0083) and 0028 (absorbs 0029). Rejected: keeping the old file name (the slug would mislead) and fresh numbers for merged records (burns numbers and breaks the links to the survivors too).
   • The register shows every gap. docs/adr/README.md gains one "Retired numbers" table: the number, its old title, and where it went (folded into a linked record, or deleted with emf/ or with the ledgers). No stub file is kept: that would be a record kept for the record, which the register forbids.
   • lint:adrs enforces it. It refuses a file that takes a listed number, and it refuses a gap below the highest number that the table does not explain. Both refusals carry a negative fixture.
   • The 14 emf numbers (0070 to 0082, and 0098) and 0068 retire when emf/ is deleted, and are the first rows of the table.

   0068

   Two earlier resolutions disagreed: the sunset ticket said 0068 is rewritten in place to describe one implementation, the cut ticket said it leaves with emf/. It is deleted with emf/. Its title, premise and settling test are all about two implementations, so a rewrite would keep only the number. The one clause that outlives it (an oracle file is reviewed by hand and never written by CI) moves into 0088, which already holds the same shape of rule for the schemas and their corpus. docs/architecture.md#the-parity-contract goes with it. The body of Delete the coursework implementation at its sunset is updated to say so.

   Order

   The register is reshaped across these pull requests, in this order:

   1. The emf/ deletion removes the 14 emf records and 0068, moves the oracle clause into 0088, and repoints by hand the root's citations of those records (among them the comments in src/read/env.ts and src/model/json-schema.ts).
   2. The move-only pull request, as Decide the chapter layout of the rewritten spec settled. It touches no record's prose, only normative: pointers and links.
   3. One register pull request, right after it and before the first chapter rewrite. It carries the three folds that change no meaning (0041 into 0092, 0029 into 0028, 0051 and 0083 into 0047), the numbering rule and the Retired numbers table in the README (seeded with every number retired so far), both new checks with their ledger rows and fixtures, the adr skill's numbering step, and the stale 0118 citation. Its proof is lint:adrs and lint:links. Rejected: folding inside the move-only pull request (it would stop being move-only) and folding each record with its chapter (the register would stay half-reshaped for the whole rewrite, and early chapters would cite records that later vanish).
   4. Chapter 00's rewrite pull request rewrites the premise of 0001 (purpose and audience, and the scale test binding the whole repository) together with the goals and non-goals in 00-overview.md#the-estate, the section it points at. This pull request goes first among the chapter rewrites, so every later chapter rests on the restated premise. The rewrite plan must keep that order.
   5. Chapter 15's rewrite pull request rewrites 0097: the three span-clusters open items and the fixed facts from Decide where the rewritten spec states one cluster or one tenant as an instance, with the Estate glossary entry and the retirement of "Cluster Target". The per-cluster env overlay itself is still removed in the contract pull request.
   6. The 1.0.0 contract pull request carries every register change that changes meaning: 0007 rewritten for the lockstep, 0044 folded into 0032, 0038 deleted with the ledgers, and 0024 losing unmanaged surfaces. 0044 and 0038 join the Retired numbers table there.

   Each surviving proposed record is still rewritten and accepted with its chapter, as the cut ticket decided.

   Citations

   • In tracked Markdown (the spec, CONTEXT.md, other records, rests-on lists): repointed to the survivor in the pull request that folds or deletes the record. lint:links and lint:adrs already fail otherwise.
   • In code comments: lint:links is extended to resolve docs/adr/... and spec/v1/... paths in tracked .ts comments, with a ledger row and a failing fixture. It lands in the register pull request, so no later fold can leave a dead citation in code. Rejected: repointing by hand with no rule (the 0118 comment shows that rots) and dropping ADR paths from code.
   • In issues and pull requests: no sweep. Closed issues are history. Of the open ones, only the emf/ deletion issue and the Estate-root OCL issue link a record that goes, and both close with emf/. The Retired numbers table is how an old link is followed by hand. Permalinks to a commit were rejected: they show a record as it was, not as it now reads.

   Where the rule is recorded

   In docs/adr/README.md, beside the citation rule, and in docs/architecture-rules.md as the two new rows. No new ADR: the register's own contract already lives in its README, and the rule is cheap to reverse.

   Consequences for other tickets

   • Delete the coursework implementation at its sunset now deletes 0068 instead of rewriting it; its body is updated.
   • The rewrite plan (/to-spec) takes the six-step order above as an input, with chapter 00 first among the chapter rewrites.
   • No new ticket and no new fog.
6. ExtraToast

   closed this as completedon Oct 12, 2026
7. ExtraToast

   removed

   status: in-progressActively being worked.Actively being worked.

   on Oct 12, 2026
8. ExtraToast

   added a commit that references this issue on Nov 5, 2026

   chore: retire the model-driven implementation at its sunset (#856)

   ...

   90640d4