:orphan: .. include:: /_templates/include-file/page-prefix.rst **************************************************************************************************** Design Proposal: The Floor Model for HELL --- Jubilee Transitions as Era Separation **************************************************************************************************** | **Bug c103 --- Design Document MMv1** | **VVN:** ``dv_ClaOp46Max_v1_2026m04d16`` | Back to :doc:`index` .. contents:: Contents :depth: 2 :local: ---- 1. Problem Statement ====================== The HELL archive accumulates structural debt with each reorganization. Broken links, stale annotations, and compounding cross-references make the archive increasingly unnavigable for newcomers while remaining transparent to insiders. The two-layer policy (update living documents, annotate frozen records) handles individual restructurings but degrades over multiple cycles. The public website needs a clean, translatable, navigable surface for beginners, producers, and experts. The audit trail needs to remain complete and accessible for deep scrutiny. These two needs conflict: the same archive cannot simultaneously be newcomer-friendly and forensically complete. ---- 2. Design Principle: Floors, Not Zones ========================================= **The key insight:** The navigable public surface is not a separate zone (HEAVEN) floating above the audit trail (HELL). It is the **top floor of HELL** --- a compacted, clean stratum built on top of sealed historical strata below. The metaphor is geological or archaeological: - **Each era** of the project's development is a **stratum** --- a layer of files, links, discussions, drafts, and decisions that were produced during that era. - **A jubilee transition** is the act of **pouring a floor** on top of a stratum. The floor compacts the stratum below: it seals the historical record, summarizes what the stratum contains, and provides a clean surface for the next era to build on. - **Newcomers walk on the current floor.** They see the latest papers, the clean navigation, the translatable content. They do not fall through the floor into historical strata unless they choose to. - **Auditors drill through floors.** Each floor has clearly marked access points (hatches) that lead to the stratum below. The access points carry warnings: "You are entering Era N. Links may be stale. Organizational structure reflects the state at time of writing." - **The floor IS the jubilee.** Pouring a new floor is the periodic structural reset. Everything below the floor is preserved but sealed. Everything above is clean and current. ---- 3. Architecture ================= 3.1 Stratum structure ----------------------- Each era produces a stratum containing: - **Papers** (formal papers, introductions, companion papers) - **Reviews** (adversarial reviews, rechecks) - **Prompts** (writing prompts, review prompts, revision prompts) - **LLogs** (session logs, discussion logs, infrastructure logs) - **Artifacts** (scripts, data files, intermediate outputs) Currently, all of these live in HELL (``hell/mm/``, ``hell/ll/``, ``hell/bug/``, etc.) with no era separation. The first era's files are interleaved with the current era's files. 3.2 The floor (HEAVEN releases) ---------------------------------- A floor is a set of files that: 1. **Contains the HEAVEN release of each public-facing document.** For each paper, the floor holds exactly one file: the clean, current-best version. Not the MMv1, not the MMv2, not the full revision history --- just the current best, with all annotations, intermediate-version references, and stale cross-references removed. 2. **Links only to other floor-level documents.** Every ``:doc:`` reference within a HEAVEN release resolves to another HEAVEN release on the same floor. No links into the strata below, with one narrow exception: **stable HELL citations** where a specific llog finding, bug report, or review serves as irreplaceable primary evidence. Such citations use stable references (e.g., ``[Balospe-N-m]_``) and are clearly marked as links into the development archive. 3. **Contains an era summary.** A document that describes what happened in the stratum below: what papers were produced, what was reviewed, what major decisions were made. This summary IS the compaction --- it reduces the full stratum to a navigable overview. 4. **Contains clearly marked hatches to the stratum below.** Each hatch is a link with a warning: "You are entering the Era N development archive. Expect historical paths, append-only logs, and organizational structures that differ from the current floor." 5. **Is translatable.** The floor contains only content that benefits from translation. The strata below remain in their original language (English). 3.3 HELL variants (annotated versions in the stratum) ------------------------------------------------------- Each paper that has a HEAVEN release on the floor also has a **HELL variant** in the stratum below. The HELL variant contains: - **The same core content** as the HEAVEN release. - **All annotation layers:** Links to earlier versions (MMv1, MMv2, etc.), renamed-path cross-references from prior restructurings, reviewer-by-reviewer annotations, intermediate draft references, deeper llog pointers. - **Full revision history context:** What changed between versions, why, and which review findings drove the changes. The HELL variant is the "debug build" of the paper. It is useful only for experts who are drilling through strata to understand the development process. It is not translated. It is not maintained for newcomer navigability. Its links may be stale, annotated, or historical --- the two-layer policy applies here. **The relationship:** - HEAVEN release = the clean release build. Self-contained on the floor. All links resolve within the floor (plus stable HELL citations where primary evidence demands it). Translatable. - HELL variant = the annotated debug build. Lives in the stratum. Contains all cross-references, annotations, and version history. English only. Expert use only. Both are derived from the same source content. The HEAVEN release is produced by *removing* annotation layers from the HELL variant, not by writing a separate document. The HELL variant is always the more complete version; the HEAVEN release is always the more navigable version. 3.4 The hatch (HELL gate) ---------------------------- Each hatch (entry point from the floor into a lower stratum) provides: - **A one-paragraph summary** of what the stratum contains - **A pointer to the HELL variant** of each paper (the annotated version with full cross-references --- the natural entry point for experts who want to go deeper) - **A warning** about navigational challenges (stale links, historical organization, large volume) - **An orientation guide** (where to start, what to read first, what to skip unless doing deep audit) - **The era boundary date** (when the floor was poured --- the jubilee transition date) ---- 4. Jubilee Transition Procedure ================================== When a jubilee transition is triggered (see Section 5 for triggers), the procedure is: **Step 1: Freeze the current stratum.** All files in the current working state become the sealed stratum of the completed era. No further edits to these files (beyond TELES-scope syntax fixes with dated admonitions). **Step 2: Write the era summary.** A document that compacts the stratum: what papers were produced, what reviews were done, what major decisions were made, what structural changes occurred. This summary replaces the need to navigate the full stratum for most readers. **Step 3: Pour the floor.** Create the new navigable surface: - Copy the latest-best version of each public-facing document to the floor level (or create stable references to them). - Check all links resolve within the floor. - Create hatches to the sealed stratum below. - Mark the floor with the jubilee transition date. **Step 4: Begin the new era.** New work builds on the floor. New files are created in the new era's working space. The stratum below is sealed. ---- 5. Triggers for Jubilee Transitions ====================================== A jubilee transition should be triggered when: 1. **The Matheo papers are complete for public review.** This is the first natural jubilee point for this project. The papers are the primary public-facing content. Completing them defines the end of Era 1 (development) and the beginning of Era 2 (public engagement). 2. **A major structural reorganization is needed.** If the directory structure must change in ways that break more than a threshold number of references (e.g., >20), it is cheaper to pour a new floor than to update all references incrementally. 3. **The annotation burden on frozen records exceeds a threshold.** If frozen documents in the current stratum have accumulated more than two layers of path-change admonitions, the stratum is overdue for sealing. 4. **Translation is initiated.** The decision to translate content into other languages naturally defines a floor: what gets translated is the floor; what remains untranslated is the stratum below. ---- 6. What This Means for Current Work ======================================= **Now (Era 1, pre-jubilee):** - Keep writing papers. Do not restructure for its own sake. - When restructuring is necessary (like the b15 split), fix live links (Groups 1--2) immediately. Leave frozen records as-is. - Use this design document as the plan for the eventual jubilee. - Track structural debt informally (note when broken references accumulate, when newcomer confusion is observed). **When papers are done (jubilee transition):** - Execute the jubilee procedure (Section 4). - The floor becomes the public website's primary navigation layer. - The sealed stratum becomes "HELL's kitchen" --- accessible via hatches, clearly marked as development archive. **After the jubilee (Era 2):** - New work builds on the floor. - The floor is maintained as a clean, translatable, navigable surface. - When Era 2's own structural debt accumulates to threshold, pour another floor. ---- 7. Open Questions =================== 1. **Floor implementation:** Should the floor be physically separate files (copies of the latest versions) or a virtual layer (an index page that links to the latest versions in their current locations)? Physical copies are simpler but create duplication. Virtual layers are DRY but depend on the underlying files not moving. 2. **Hatch granularity:** One hatch per paper? One hatch per HELL topic area (``study/``, ``forge/``, ``infra/``, ``other/``)? One hatch per era? The right granularity depends on what auditors actually need. 3. **Translation scope:** Which floor documents get translated first? The paper introductions are the obvious candidates. The formal papers may need domain-specific translation that machine translation handles poorly. 4. **Era numbering:** Should eras be numbered (Era 1, Era 2) or dated (Era 2026m04)? Numbered is simpler; dated is more informative. 5. **Retroactive floor for pre-b15 content:** The content produced before the b15 restructuring (2026m04d14) is already mixed into the current state. Should the first jubilee retroactively define Era 0 (everything before 2026m04d14) and Era 1 (2026m04d14 to paper completion)? Or is one era sufficient for the entire pre-publication period? ---- 8. Relationship to Jubilee System Theory ========================================== This design proposal is itself an instance of the pattern it documents. The Floor Model applies the Jubilee System's structural reset at project scale. The theoretical predictions (compounding debt, information inequality, need for periodic clean breaks) guided the design. The design, if successful, provides empirical evidence that the predictions hold at micro scale. This circular relationship (theory predicts pattern; pattern informs design; design tests theory) is the ZION cycle applied to infrastructure: seed (observe the pattern) |rarr| feed (formalize the prediction) |rarr| grow (design the solution) |rarr| reap (test whether it works) |rarr| and cycle again.