docs(guarantees): rewrite as design principles - #192
Merged
Merged
Conversation
Replaces the status-tracking shape with principles, per _plans/048. Each entry is a statement with Why, Rules out, and (only for a deliberate trade-off) Accepts. There are no statuses, enforcement notes, or history, so the file changes only when a principle changes. Gaps between a principle and the code are issues: #184, #185, #186. Ids and labels are unchanged. The no-markfluence.yaml trade-off is now an Accepts under S8 and L4. L5 is reworded to what it always meant: the page keeps its meaning, and the Markdown is a fixed point. The byte-level measurement behind that moves to docs/confluence/storage-format.md. The "how each kind is verified" table is dropped, since it describes test practice rather than a principle. Refs #191
docs/guarantees.md no longer carries a status, so references to Holds and Partial in CLAUDE.md, the README, and three code comments now point at nothing. CLAUDE.md's description of the file also had stale id ranges (S1-S7, L1-L8, C1). Refs #191
Without enforcement notes beside them, several statements read wider than meant: - S1 names its destination: --dest for export and attachment-download, the documentation root otherwise. - S3 is scoped to files written from a page. create's metadata write-back and the append-only action log are not overwrites. - S7 Accepts now covers a pages: entry holding the id, --no-persist leaving no record on disk, and page_status resolved after the page exists. - L2 rules out page metadata from flags in update only, and a cache that changes the published bytes. Its Accepts says the log decides whether a body is sent. Also: - Two test comments cited wording the rewrite removed. - CLAUDE.md said S8 is decided by content; it is decided by the logged version. - The 2026-08-28 symlink measurements move beside the code that relies on them (project.Root.FS, linkindex.Build). Refs #191
The file now holds design principles, so its name should say so. This reverses _plans/048's D6, which kept the old name to avoid breaking references; every live reference is updated here, and plans are history and keep the old name. Refs #191
The ids now name design principles, so comments that said "guarantee L2" say "principle L2". The paragraphs are rewrapped, since the rename left them ragged. Refs #191
docs/guarantees.md is now docs/design-principles.md, and the rewrite removed every plan citation from it, so the bullet was false as well as its link. docs/root-model.md's count was also stale: 5, not 10. Refs #191
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.
Fixes #191. Implements _plans/048.
docs/guarantees.mdbecomesdocs/design-principles.md, titled "Design principles". The rename reverses the plan's D6; every live reference is updated, and plans keep the old name as history. Each entry is a statement with Why, Rules out, and, only for a deliberate trade-off, Accepts. There are no statuses, enforcement notes, or history, so the file changes only when a principle changes. Gaps between a principle and the code are issues (#184, #185, #186). Ids and labels are unchanged.markfluence.yamltrade-off is an Accepts under S8 and L4.docs/confluence/storage-format.md.project.Root.FSandlinkindex.Build.CLAUDE.md, the README, and a few code and test comments stop citing statuses.CLAUDE.md's id ranges were also stale.Commits: the rewrite, the reference updates, fixes from a review pass that found several statements reading wider than intended once their enforcement notes were gone (S1, S3, S7, L2), and the rename.