mirror of
https://github.com/razzant/ouroboros.git
synced 2026-10-03 04:07:04 +00:00
35b8151819
The books were one physical file each: ARCHITECTURE 2,386 lines and DEVELOPMENT 3,886, with 13 and 14 `##` sections. `reference_books.py` had shipped the chaptered reader — membership, authored introductions, exact physical source views — with the migration still at zero, so every reader took the legacy monolith branch and the validator had no production caller. Each `##` section is now one chapter file under `docs/architecture/` or `docs/development/`. The only new bytes per chapter are its prologue: the old section title at H1 (numbering text kept, so every `ARCHITECTURE "8. Git Branching, CI, and Build"` cross-reference still reads) and one authored introductory paragraph saying what the chapter owns and why it exists. Everything after that prologue is the old section body byte for byte, with `###`/`####` levels untouched — so the residue rules keep reading the exact subsection headings they exempt, and no section title was renamed. The move is therefore INVERTIBLE, and `tests/test_reference_book_migration.py` inverts it: drop each chapter's H1 line and its one introduction, re-prefix `## `, concatenate in membership order, and require the recorded SHA-256 of the old body — plus, whenever the base commit is reachable, byte equality with `git show <base>:<path>`. `docs/reference-books-migration.md` is the operator transfer table: every row a verbatim move, with its line range at the base, its destination and an empty rename column. It lives directly under `docs/`, so it is reviewable without becoming a book member. `_preamble` now takes the FIRST paragraph under the H1 instead of demanding the only one before the first H2. Most sections open with prose at the level they already had, so the old rule could only be satisfied by promoting `###` to `##` or inventing a sub-heading — either of which would rewrite what this migration relocates verbatim. A source whose H1 is followed straight by a subsection still has no introduction and is still refused, which is the property that keeps an overview from quoting body prose as authored orientation. `.gitattributes` pins `docs/**/*.md` to LF: chapter line ranges, byte spans and SHA-256s are physical facts that a Windows checkout must not rewrite, and `full-test` runs on windows-latest for every PR. The two ARCHITECTURE-derived generated inventories are regenerated, because a chaptered section now carries its physical provenance note. Co-authored-by: Ouroboros <311266734+ouroboros-agent@users.noreply.github.com>
1.7 KiB
1.7 KiB
DEVELOPMENT.md — Development Principles & Module Guide
This is Ouroboros's engineering handbook: imperative rules for changing the body, grouped by change class, each naming the surface that enforces it — a test, a gate, a CI lane — or stating honestly that none does. The first chapter fixes this book's authority beside the constitution, the architecture map, the design semantics and the reviewer checklists; the rest are the rules themselves, from naming and size discipline through the governance-artifact contract, the commit protocol, the per-change-class rules, and the build and CI topology. Read the chapter for the class of change in hand: this book is not a changelog, and a change replaces the description of the node it touched.
Chapters
- Role and authority
- Naming and boundaries
- Module Size & Complexity
- Core Governance Artifacts
- Review & Commit Protocol
- Rules by change class
- Managed Update Rule
- Mutation Attribution Rule
- Process Custody Rule
- Platform Abstraction Rule
- Design System
- MCP Client Integration
- Gateway Boundary Pattern
- Build & CI