docs: rebuild the decision surface; the spec follows the ADRs - #65
Open
ExtraToast wants to merge 4 commits into
Open
ExtraToast wants to merge 4 commits into
ExtraToast wants to merge 4 commits into
Conversation
…ed set scripts/lint-adrs.mjs enforces the docs/adr contract: frontmatter schema, required sections, register integrity against docs/adr/README.md, qualified citations (no bare ADR tokens), normative anchors resolving into spec/v1, content shape (no >10-line fences, costed alternatives), and Open-items entries carrying Owner / Settled by / Blocks. Wired as a blocking adr-lint job in ci.yml via pipeline-complete. The six delivery examples (aggregator*, deployer-rbac, reapply-cronjob, renovate.json) move from spec/v1/examples to docs/adr/deferred/examples: delivery is defined separately from the model as of 2026-09-07.
Replaces the 19-ADR set (last carried at 7ea3c4f) with a tiered rebuild: - docs/adr: 8 premises with falsifiable claims + 39 decisions, one separately-reversible decision each, rests-on naming premises only; README.md is the machine-checked register. - Delivery and co-testing are defined separately from the model (owner decision, 2026-09-07): 13 ADRs (0008, 0041-0051, 0058) parked in docs/adr/deferred with their examples. The model's complete interface to future delivery: Release Unit atomicity (0060), Durability Class gating (0015), pinned inputs only (0006/0034). - New: 0060-release-unit — several Services switch as one task; no member's new version receives traffic until every member is healthy. - spec/v1 chapters 00-60 rewritten to carry the normative anchors, the authority table (once, in ch20), pinned ClusterState purity, per-Workload env files, path-unit grants, per-Workload identity, pod hardening and size classes, and the registry-derived coverage table. Examples are model-only: split secret paths per reader set, byte-matched placeholders, releaseUnit on the auth pair, error-code-asserting negative fixture. - review/: the adversarial review, consolidation, spine and rebuild manifest that produced this set (audit trail). scripts/lint-adrs.mjs passes clean across all 47 model ADRs.
Sixteen fixes from a read of all eight chapters against the ADR set and the example files: E_UNBOUND_SECRET_GRANT scoped to delivery:env only; one error code per condition (E_LEDGER_ENTRY_STALE / E_LEDGER_REVIEW_OVERDUE replace the double-booked E_STALE_EXEMPTION; E_SUBTREE_PREFIX_COLLISION replaces the reused E_PATH_COLLISION, which is render-phase and leaves the composition table); E_RELEASE_UNIT_NO_READINESS added and cited from chapter 50; chapter 16's trace and chapter 20's projection now grant the same split path the examples grant (.../postgres/kb); knowledge's healthTimeoutClass corrected to stateful per its own derivation rule; the seven-node estate fact restored in chapter 60 and ADR 0036; two open items repointed at consumers that exist; 'aggregator' removed from chapter 30's render placement; the alias/applier clause reduced to the negation and pointer the delivery split requires.
ExtraToast
added
type: docs
Lint carried an unused statusOk binding and two useless regex escapes, and its README link check did not resolve links into deferred/. .gitignore did not cover .idea/, which showed untracked on every status. Add editor, env, and cache patterns.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replaces the 19-ADR set with a tiered rebuild and rewrites
spec/v1to follow it.What
docs/adr/— 8 premises carrying falsifiable claims (claim: opennames its owner and settling test) + 39 decisions at one-reversible-decision grain;README.mdis the machine-checked register. Old set recoverable: last carried at7ea3c4f,git log --diff-filter=D -- docs/adr.docs/adr/deferred/with their examples. The model's complete interface to future delivery: Release Unit atomicity (0060), Durability Class gating (0015), pinned inputs only (0006/0034).0060-release-unit— several Services switch as one task; no member's new version receives traffic until every member is healthy; one failing member holds the unit on old versions.spec/v1chapters 00–60 rewritten: normative anchors for every ADR pointer, the authority table once (ch20), purity over pinnedClusterState, per-Workload env files and identity, path-unit grants, pod hardening + size classes, registry-derived coverage table.releaseUniton the auth pair, error-code-asserting negative fixture.scripts/lint-adrs.mjs+ blockingadr-lintCI job: frontmatter schema, register integrity, citation + anchor resolution, content shape. Clean across all 47 model ADRs.review/— the six-lens adversarial review, consolidation, spine and rebuild manifest that produced this set (audit trail).Provenance
103-finding adversarial review (
review/CONSOLIDATED.md) → approved spine (review/SPINE.md) → authored perreview/REBUILD-MANIFEST.md→ per-domain adversarial verification (quotes checked against sources) → cross-set seam verification (16 fixes in the final commit).