DD-b12: Compiled Output Location — The Hybrid Landing Page Strategy#

Status: Adopted for testing purposes (2026-03-25)

Drafted by: Claude Opus 4.6 (MMv1 — machine-made, pending human review)

The Problem#

The matheology compiler produces audience-specific views (expert, producer, easy, math, machine) from PoR source files. Where should these compiled pages live?

Three options were considered:

Option A — Separate ``compiled/`` folder:

matheology/compiled/axioms/easy.rst
matheology/compiled/axioms/expert.rst

Option B — Directly into existing model folders:

matheology/pet/axioms/easy.rst
matheology/jub/axioms/easy.rst

Option C — Human landing pages with compiled depth views beneath:

matheology/axioms/index.rst       (human-crafted, never overwritten)
matheology/axioms/easy/           (compiled, deletable, regenerable)
matheology/axioms/expert/         (compiled)

The Decision: Option C#

Option C was adopted. The reasoning:

  1. URLs that mean something forever. balospe.com/matheology/axioms/easy/ is self-explanatory to any reader. balospe.com/matheology/compiled/axioms/easy/ leaks an implementation detail (“compiled”) into every link anyone shares. That word means nothing to a reader — it is plumbing.

  2. The landing page solves the discovery problem. A newcomer arrives at /matheology/axioms/ and sees a human-written page explaining what the axioms are, who they are for, and which depth to start with. This page requires editorial judgment that no compiler can provide. It is the most valuable page in the system.

  3. Clean regeneration boundary. The landing page (index.rst) is human-crafted and never touched by the compiler. The depth subdirectories (easy/, expert/) are entirely generated — they can be deleted and regenerated without risk. Option B mixes source and output in the same folder, making safe regeneration impossible.

  4. Contributors think in models; readers think in topics. The pet/ and jub/ folders serve contributors (organized by model, because that is how content is authored). The top-level axioms/ and theorems/ folders serve readers (organized by what they want to learn, at their level). The compiler is the bridge between these two views of the same content.

  5. Option A’s disadvantage compounds. Every external link, every citation, every bookmark would contain /compiled/. If the system reorganizes, every link breaks. With Option C, the entry points (/axioms/, /theorems/) are permanent — only the depth views underneath are generated and can evolve.

Input Data vs. Compiled Output#

Both source data and compiled output live under source/matheology/. This makes the boundary between what the compiler may touch and what it must never touch a matter of life and death for the project’s data.

Input data — NEVER touched by the cross-model compiler:

source/matheology/
  pet/              ← PoR source: Pet model axioms, elements
  jub/              ← PoR source: Jub model axioms, theorems, quest
  hell/             ← Findings register: cons, pros, evidence
  compiler/         ← The compiler itself (spec, guides, decisions)
  symbols/          ← Symbol definitions
  prior-art/        ← Prior art and references
  vv/               ← Version archive (append-only llogs, prompts)

Every file in these folders is authored content — the raw material from which everything else is derived. It was written by humans or by agents under human direction, reviewed, committed, and in many cases declared append-only. No compilation operation may modify, overwrite, move, or delete any file in these folders.

If the input data is lost, no amount of recompilation can recover it. The compiled output, by contrast, can always be regenerated from the input.

Compiled output — written by the compiler, safe to regenerate:

source/matheology/
  axioms/
    easy/           ← compiled (regenerable)
    expert/         ← compiled (regenerable)
    producer/       ← compiled (regenerable)
    math/           ← compiled (regenerable)
    machine/        ← compiled (regenerable)
  theorems/
    easy/           ← compiled (regenerable)
    expert/         ← compiled (regenerable)
    ...

These depth subdirectories are entirely generated. They can be deleted in full and rebuilt from source. The index.rst at each topic level (axioms/index.rst, theorems/index.rst) is human-crafted and is NOT compiled output — see Rule 1 below.

The boundary in one sentence: model folders (pet/, jub/, hell/) are input; topic folders (axioms/, theorems/) contain both a protected human-crafted landing page and regenerable compiled depth views. The compiler reads from models and writes only into the depth subdirectories beneath topic landing pages — never the landing pages themselves.

Two Kinds of Compiler, Two Safety Profiles#

The system will eventually support two fundamentally different compilation operations. They have opposite safety profiles and must not be confused.

1. Cross-model compiler (this document’s subject).

Reads PoR source across all models. Produces audience-depth views that combine, extract, and reformat content for different readers. All model folders are strictly read-only input. This compiler never modifies source data.

Direction of data flow:

pet/axioms.rst  ──┐
                  ├──→  axioms/easy/   (compiled)
jub/axioms.rst  ──┘    axioms/expert/ (compiled)

Safety: read-only with respect to all source data. If something goes wrong, delete the depth subdirectories and recompile.

2. Intra-model reasoning compiler (future, not yet built).

Works within a single model, using HELL evidence (cons, pros, findings) to determine whether theorems, axioms, or other elements need updating in light of new evidence. This compiler does modify source data — it is the mechanism by which the model evolves.

Direction of data flow:

hell/con/b/38/ ──→ jub/theorems.rst  (source modified)
hell/pro/b/38/ ──┘

Safety: read-write with respect to model source data. This operation is inherently dangerous and requires a completely different set of safeguards (version control, human review gates, append-only audit trails). It is a future design discussion, not part of this DD.

Why the distinction matters: a user who says “clear the slate and recompile everything” must trigger only the cross-model compiler. The intra-model reasoning compiler should never be invoked by a blanket regeneration command. These are separate operations with separate triggers, separate permissions, and separate recovery strategies.

Note

The intra-model reasoning compiler deserves its own DD when its design begins. The safety rules here apply only to the cross-model compiler described in this document.

Implementation Rules#

Rule 1 — The compiler never overwrites ``index.rst`` files. Landing pages are human-crafted. The compiler writes only into depth-specific subdirectories or files (easy/, expert/, producer/, math/, machine/).

Rule 2 — Compiled depth subdirectories are deletable. Any depth subdirectory (easy/, expert/, etc.) can be removed and regenerated from source without data loss. The topic folder itself (axioms/, theorems/) must NOT be deleted wholesale, because it contains the protected index.rst landing page.

Rule 3 — The compiler never writes to model folders. The directories pet/, jub/, hell/, compiler/, symbols/, prior-art/, and vv/ are read-only input to the cross-model compiler. No compilation operation may create, modify, or delete files in these directories.

Rule 4 — The directory structure mirrors the content structure, not the source structure. Compiled output is organized by topic (axioms, theorems, findings) and depth (easy, expert), not by model (pet, jub). Cross-model views (all-ax5-easy) live alongside single-model views.

Rule 5 — Landing pages link downward to compiled views. Each index.rst links to the available depth views beneath it, giving the reader a choice of audience level.

Rule 6 — Protected files carry a ``.. compiler:protected`` comment. Any RST file whose first non-blank comment begins with .. compiler:protected must not be overwritten, modified, or regenerated by the cross-model compiler. Before writing to any file that already exists, the compiler checks for this token. If present, the file is skipped and the compiler logs a notice (e.g., SKIP [protected]: axioms/index.rst). This comment is an RST comment — invisible in rendered HTML — so human readers never see it. The canonical form is:

.. compiler:protected
   DD-b12: This file is human-crafted. The cross-model compiler
   must never overwrite, modify, or regenerate this file.

The DD-b12: reference is recommended but optional; the token compiler:protected alone is sufficient for the compiler to recognize the file as protected.

Resulting Directory Layout#

source/matheology/
  pet/                        (INPUT --- PoR source, never touched)
    axioms.rst
  jub/                        (INPUT --- PoR source, never touched)
    axioms.rst
    theorems.rst
  hell/                       (INPUT --- findings, never touched)
    con/
    pro/
  axioms/                     (MIXED --- protected landing + compiled views)
    index.rst                 (PROTECTED --- human-crafted landing page)
    easy/                     (compiled, regenerable)
    expert/                   (compiled, regenerable)
    producer/                 (compiled, regenerable)
  theorems/                   (MIXED --- protected landing + compiled views)
    index.rst                 (PROTECTED --- human-crafted landing page)
    easy/                     (compiled, regenerable)
    expert/                   (compiled, regenerable)
  compiler/                   (the compiler itself --- not input or output)
    ww/                       (skill spec, architecture doc, stubs)
    aha/                      (user guides)
    dd/                       (design discussions)
    ee/                       (experimental evidence)

What Changed#

The skill specification (SISYF — Skill Specification) previously defaulted to source/matheology/compiled/ as the output path. This DD changes the default to source/matheology/ with topic-level subdirectories. The AHA compile guide (AHA: SISYF User Guide) should document the boundary between what the compiler touches and what it does not, with a link back to this DD for the reasoning.