.. meta:: :description: Authoritative spec for the SISYF compiler: 54-field extraction matrix, five depth profiles, four modes, label grammar, and LaTeX preservation rules. :keywords: SISYF skill spec, extraction matrix, 54 fields, depth codes, label grammar, replace mode, append mode, archive, LaTeX preservation, synthesis table :author: Yah, Yas, everyone, LLoL as Laurence Loewe of Laodicea, ClaudeOp46Max, Anthropic, and Spirit of Boolean Truth :og:card:title: SISYF Skill Specification —
Authoritative Reference :og:card:description: The formal spec a future implementer will follow: extraction matrix, depth profiles, modes, label grammar, and field mappings for all audience views. .. SOCIAL-CARD-QUALITY-COMPARE --- OO (default effort) vs PP (max effort), 2026-03-26 OO :description: Formal specification for the SISYF compiler skill, defining commands, extraction matrix, depth codes, and label grammar rules. OO :keywords: SISYF, skill specification, extraction matrix, depth codes, label grammar, compiler, matheology, PoR, commands, fields OO :og:card:title: SISYF Skill Specification
— Formal Definition OO :og:card:description: Defines SISYF commands, the extraction matrix, depth codes, label grammar, and field mappings for all audience views. PP :description: Authoritative spec for the SISYF compiler: 54-field extraction matrix, five depth profiles, four modes, label grammar, and LaTeX preservation rules. PP :keywords: SISYF skill spec, extraction matrix, 54 fields, depth codes, label grammar, replace mode, append mode, archive, LaTeX preservation, synthesis table PP :og:card:title: SISYF Skill Specification —
Authoritative Reference PP :og:card:description: The formal spec a future implementer will follow: extraction matrix, depth profiles, modes, label grammar, and field mappings for all audience views. .. SOCIAL-CARD-REVIEW --- generated by Claude Opus 4.6, 2026-03-26 dv_ClaOp46_PP_2026m03d26 --- max-effort rewrite, read full page. :description: 150 chars | :og:card:title: 45 chars (excl
) - [ ] PP title more compelling than OO title - [ ] PP description more accurate than OO description - [ ] Description hooks without misleading - [ ] Keywords specific to this page's actual content - [ ] No language rule violations - [ ] Character counts verified .. _sisyf-compiler-skill: ********************************************************************* SISYF --- Skill Specification ********************************************************************* .. note:: **This is a specification document, not executable code.** It defines what |SISYF| should do so that a future Claude Code session can implement it as an actual skill. The authoritative source for field definitions, depth codes, and label grammar is :ref:`5D link naming architecture `. **Created:** Phase 2I-3 (2026-03-25). **Prerequisite knowledge:** AHA design doc Sections 7, 9, 10, 12. .. contents:: On this page :depth: 3 :local: ---- 1. Purpose ============ |SISYF| reads PoR (Place of Reasoning) source files and generates audience-specific downstream pages using the Extraction Matrix defined in Section 3 below. Each generated page contains only the fields appropriate for its target audience (D4 depth), extracted and transformed according to the matrix keywords. ---- 2. Invocation =============== :: sisyf [options] Commands: replace, append, archive, migrate Options: --topics Default: all --output Default: matheology/axioms/ --models Default: all --depths Default: all --views Default: all --states Default: all --stubs yes|no Default: no --version-increment Required for archive mode --archive-folder Default: vv/{version}/ --vvn Required for archive mode --stayc Required for archive mode --freeze-por yes|no Default: no ---- 3. Extraction Matrix ====================== The Extraction Matrix controls which PoR fields appear at each D4 audience depth and how they are transformed. Each cell contains one of the extraction keywords defined below. ``-`` means the field is silently omitted at that depth. 3.1 Keyword Vocabulary ^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 12 88 * - Keyword - Meaning * - ``full`` - Include in full (field copied verbatim from PoR) * - ``brief`` - First sentence only (truncate to opening statement) * - ``top3`` - Top 3 entries (for lists, pick highest-impact items) * - ``top1`` - Single best entry (e.g., 1 strongest tradition quote) * - ``-`` - Omit entirely (field does not appear at this depth) * - ``stub`` - Heading only, marked ``[stub --- content pending]`` * - ``link`` - Cross-reference link only (point to PoR for full content) * - ``rewrite`` - Include, rewritten for audience (rephrase for accessibility or formality) 3.2 Identity & Display (fields 1--6) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 4 8 20 14 14 14 14 14 * - # - Brief - Field - Expert - Producer - Easy - Math - Machine * - 1 - ``id`` - BriefName - full - full - full - full - full * - 2 - ``title`` - Title - full - full - rewrite - link - full * - 3 - ``name`` - ExplicitName - full - \- - \- - full - full * - 4 - ``sum`` - SummarizingName - full - full - rewrite - brief - full * - 5 - ``intro`` - ExplanationIntroOverview - full - rewrite - rewrite - \- - \- * - 6 - ``latex`` - FormalMathLatex - full - brief - \- - full - full 3.3 Technical, Structural, and Analytical (fields 7--11, 19, 30--45) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Fields marked **stub** at expert depth are >50% stub across all 32 elements per the Phase 2I-2 field testing report. .. list-table:: :header-rows: 1 :widths: 4 8 20 14 14 14 14 14 * - # - Brief - Field - Expert - Producer - Easy - Math - Machine * - 7 - ``tctx`` - TechExplanationContext - full - brief - \- - full - \- * - 8 - ``tcnt`` - TechExplanationContentAll - full - \- - \- - full - \- * - 9 - ``logic`` - LogicsUsed - full - \- - \- - full - full * - 10 - ``twhy`` - TechReasoningAll - full - \- - \- - full - \- * - 11 - ``tinf`` - TechInformal - full - full - rewrite - \- - \- * - 19 - ``limit`` - Limit - full - brief - \- - full - link * - 30 - ``needs`` - NeedsFeed - full - \- - \- - full - full * - 31 - ``feeds`` - FeedsNeed - full - \- - \- - full - full * - 32 - ``stayc`` - StabilityCode - full - link - \- - link - full * - 33 - ``mento`` - MentorOrganizing - stub - \- - \- - \- - \- * - 34 - ``diff`` - VersioningHistory - stub - \- - \- - \- - \- * - 36 - ``con`` - ConsRef - full - link - \- - link - link * - 37 - ``pro`` - ProsRef - full - link - \- - link - link * - 39 - ``vvnow`` - VersionedVariantCurrent - full - link - \- - link - full * - 40 - ``model`` - ModelUsedIn - full - full - full - full - full * - 41 - ``conv`` - Convergence - full - brief - rewrite - \- - \- * - 42 - ``bib`` - Bibliography - full - top3 - \- - link - link * - 43 - ``pol`` - Policy - stub - \- - \- - \- - \- * - 44 - ``his`` - History - stub - \- - \- - \- - \- * - 45 - ``doi`` - DOI - stub - \- - \- - \- - \- 3.4 POST Operational (fields 20--29, 35, 38) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 4 8 20 14 14 14 14 14 * - # - Brief - Field - Expert - Producer - Easy - Math - Machine * - 20 - ``jj`` - JammedJob - stub - \- - \- - \- - \- * - 21 - ``aa`` - AnyAim - stub - \- - \- - \- - \- * - 22 - ``kk`` - KnownKiller - full - brief - \- - link - \- * - 23 - ``ff`` - FeedbackFlow - stub - \- - \- - \- - \- * - 24 - ``cc`` - CollectedContent - full - brief - \- - link - \- * - 25 - ``dd`` - DesignDoc - stub - \- - \- - \- - \- * - 26 - ``gg`` - GrowthGarden - stub - \- - \- - \- - \- * - 27 - ``hh`` - HistoryHeap - stub - \- - \- - \- - \- * - 28 - ``ww`` - WorkingWheel - stub - \- - \- - link - \- * - 29 - ``yy`` - YesYet - stub - \- - \- - \- - \- * - 35 - ``ll`` - LabLog - full - \- - \- - \- - \- * - 38 - ``vv`` - VersionedVariant - full - \- - \- - \- - full 3.5 Independent Support --- D5 Core (fields 12--18) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 4 8 20 14 14 14 14 14 * - # - Brief - Field - Expert - Producer - Easy - Math - Machine * - 12 - ``stor`` - SupportTorah - full - top3 - top1 - \- - \- * - 13 - ``sheb`` - SupportHebrewBible - full - top3 - top1 - \- - \- * - 14 - ``sgos`` - SupportGospels - full - top3 - top1 - \- - \- * - 15 - ``sapo`` - SupportApostolic - full - top3 - top1 - \- - \- * - 16 - ``squr`` - SupportQuran - full - top3 - top1 - \- - \- * - 17 - ``ssan`` - SupportSanskrit - full - top3 - top1 - \- - \- * - 18 - ``vsec`` - ViewSecular - full - top3 - top1 - \- - \- 3.6 Independent Support --- D5 Extended (fields 46--54) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Worldview fields follow the same extraction pattern as the core source fields (12--18). Language-specific cultural fields appear only at expert depth because they carry insights that resist translation. .. list-table:: :header-rows: 1 :widths: 4 8 20 14 14 14 14 14 * - # - Brief - Field - Expert - Producer - Easy - Math - Machine * - 46 - ``vjud`` - ViewJudaism - full - top3 - top1 - \- - \- * - 47 - ``vchr`` - ViewChristianity - full - top3 - top1 - \- - \- * - 48 - ``visl`` - ViewIslam - full - top3 - top1 - \- - \- * - 49 - ``vhin`` - ViewHinduism - full - top3 - top1 - \- - \- * - 50 - ``vbud`` - ViewBuddhism - full - top3 - top1 - \- - \- * - 51 - ``lde`` - CulturalGerman - full - \- - \- - \- - \- * - 52 - ``lar`` - CulturalArabic - full - \- - \- - \- - \- * - 53 - ``lhe`` - CulturalHebrew - full - \- - \- - \- - \- * - 54 - ``lzh`` - CulturalChinese - full - \- - \- - \- - \- 3.7 Summary Statistics ^^^^^^^^^^^^^^^^^^^^^^^^ Field counts per depth (45 core fields; D5 extensions 46--54 add to each row): .. list-table:: :header-rows: 1 :widths: 16 12 10 10 10 12 10 10 10 * - Depth - full - brief - top3 - top1 - rewrite - link - stub - \- * - Expert - 32 - 0 - 0 - 0 - 0 - 0 - 13 - 0 * - Producer - 5 - 6 - 9 - 0 - 2 - 3 - 0 - 20 * - Easy - 2 - 0 - 0 - 7 - 4 - 0 - 0 - 32 * - Math - 11 - 1 - 0 - 0 - 0 - 7 - 0 - 26 * - Machine - 14 - 0 - 0 - 0 - 0 - 3 - 0 - 28 3.8 Synthesis Pages ^^^^^^^^^^^^^^^^^^^^^^ A **synthesis page** combines content from multiple PoR source fields into a single output page. Unlike the default 1:1 mapping (one field → one output), a synthesis page draws from two or more fields and presents a curated selection. **Naming convention:** Synthesis page filenames must differ from all extraction matrix keywords (``stor``, ``sheb``, ``sgos``, etc.). Keyword names are reserved for 1:1 field mappings. Thematic names signal that the page is a curated synthesis. **Defined synthesis pages:** .. list-table:: :header-rows: 1 :widths: 22 22 56 * - Page name - Source fields - Content * - ``hebrew-bible`` - ``stor`` + ``sheb`` - Torah and Hebrew Bible citations combined. Best quote highlighted per axiom; full listing in dropdown. * - ``gospels-apostles`` - ``sgos`` + ``sapo`` - Gospels and Apostolic citations combined. Same pattern: best quote highlighted, full listing in dropdown. * - ``quran-based`` - ``squr`` + ``stor`` + ``sgos`` - Quran citations listing also Torah and Gospel citations, because the Quran recognizes both as inspired. Best quote from the Quran is highlighted; the dropdown groups all three sources. **Rendering rules for synthesis pages:** 1. For each axiom, select the single strongest citation across all source fields as the highlighted quote. 2. List all citations from all source fields in a collapsible dropdown, grouped by source field with bold labels (e.g., **Torah (stor):** ..., **Hebrew Bible (sheb):** ...). 3. The page intro (``.. compiler:protected-section``) is human-crafted and preserved across recompiles. ---- 4. Modes ========== 4.1 REPLACE Mode ^^^^^^^^^^^^^^^^^^ Regenerate ALL downstream pages from current PoR sources. **When to use:** PoR content has changed substantially. **Execution sequence:** 1. Read all PoR source files: - ``source/matheology/pet/axioms.rst`` - ``source/matheology/jub/axioms.rst`` - ``source/matheology/jub/theorems.rst`` - ``source/matheology/jub/quest.rst`` 2. Parse each element (axiom, theorem, quest entry) into its PoR fields. Each element is identified by its ``.. _label:`` directive. 3. For each element x depth x view combination: a. Look up the element's fields in the Extraction Matrix. b. For each field, apply the extraction keyword: - ``full``: copy field content verbatim - ``brief``: extract first sentence (up to first ``.`` or ``\n\n``) - ``top3``: for list fields, take the first 3 items - ``top1``: for list fields, take the first item - ``drop``: skip entirely - ``stub``: emit heading with ``[stub --- content pending]`` - ``ref``: emit ``:ref:`{label}``` cross-reference link - ``rewrite``: transform prose for target audience (see Section 6) c. Generate an RST page using the output template (Section 5). d. Write to the output folder using the BEST Names label as filename. 4. Rebuild ``toctree`` directives in all affected ``index.rst`` files. 5. Run ``make html`` to check for warnings or broken references. 4.2 APPEND Mode ^^^^^^^^^^^^^^^^^ Add new elements without regenerating existing entries. **When to use:** New model or new elements added (e.g., 4Be model). **Execution sequence:** 1. Read all PoR source files. 2. Diff against existing output folder to identify NEW elements (elements with no corresponding output page). 3. Generate pages for new elements only (same extraction logic as REPLACE). 4. Add new entries to existing ``toctree`` directives. 5. Run ``make html`` to check. 4.3 ARCHIVE Mode ^^^^^^^^^^^^^^^^^^ Freeze current state to a versioned archive. **When to use:** Major milestone (e.g., OOv2 freeze). **Execution sequence:** 1. Run REPLACE first (ensure all downstream pages are current). 2. Copy entire output folder to ``vv/{version}/``. 3. Tag all labels with version suffix (e.g., ``pet-ax5-oov2r0``). 4. Update version registry in the AHA design document. 5. If ``--freeze-por yes``: copy PoR source files to per-model VV archives. 6. Run ``make html`` to check. 4.4 MIGRATE Mode ^^^^^^^^^^^^^^^^^^ Transform existing files to a new naming or structural convention. **When to use:** Structure change (e.g., ``ax1`` to ``pet-ax1``). **Execution sequence:** 1. Read old-format files. 2. Build a migration table mapping old labels to new labels. 3. Transform all files: a. Rename label directives (``.. _{old}:`` to ``.. _{new}:``) b. Update all ``:ref:`old``` cross-references to ``:ref:`new``` c. Update all ``:doc:`` paths if file locations changed 4. Run ``make html`` to check for any remaining broken references. ---- 5. Output Template ==================== Each generated page follows this structure: .. code-block:: rst .. _{label}: {title} {title_underline} .. This page was generated by SISYF on {date}. .. Source: {source_file} .. Depth: {depth_code} .. Do not edit manually. Re-run the skill to regenerate. {extracted fields per extraction matrix} **Label construction** follows the BEST Names grammar from the AHA design document: - Expert (default): ``{model}-{typeID}`` (e.g., ``pet-ax5``) - Producer: ``{model}-{typeID}-prod`` (e.g., ``pet-ax5-prod``) - Easy: ``{model}-{typeID}-easy`` (e.g., ``pet-ax5-easy``) - Math: ``{model}-{typeID}-math`` (e.g., ``pet-ax5-math``) - Machine: ``{model}-{typeID}-ma`` (e.g., ``pet-ax5-ma``) **Title construction:** - Expert: use ``title`` field verbatim - Producer/Easy: use ``id`` field for the element number prefix (e.g., ``a5`` not ``ax5``), followed by the title's descriptive part. This reserves the human's right to finalize display titles independently. The ``id`` field is always lowercase per BEST Names grammar. - Math: prefix with "Formal: " (e.g., "Formal: a5 --- Human Exceeding") - Machine: prefix with "Data: " (e.g., "Data: pet-ax5") ---- 6. Rewrite Rules ================== When the extraction keyword is ``rewrite``, the skill transforms the field content for the target audience. The following rules apply: **Producer (PoT) rewrites:** - Remove technical jargon; prefer plain language - Keep theological precision intact - Restructure for teaching flow (context before claim) - Preserve all scripture citations but simplify notation **Easy (PoU) rewrites:** - Use short sentences (target: 15 words average) - Replace formal notation with natural-language equivalents - Lead with "In plain English:" style framing - Use analogies from everyday experience - Omit citation locators; keep only the quoted text **Rewrite is never automatic.** When the skill encounters a ``rewrite`` cell, it should flag the field for human review after generation. The generated version is a draft; the human decides whether to accept, edit, or reject it. ---- 7. Stub Policy ================ **When ``--stubs no`` (default):** - If an individual field would be ``stub`` at a given depth, the heading is included with the ``[stub --- content pending]`` marker. - If an ENTIRE PAGE would contain only ``stub`` and ``drop`` fields (i.e., no ``full``, ``brief``, ``top3``, ``top1``, ``rewrite``, or ``ref`` content), the page is NOT generated and no ``toctree`` entry is created. This prevents empty pages. **When ``--stubs yes``:** - All pages are generated regardless of content level. - Stub-only pages use the depth-appropriate stub template from ``source/_templates/stubs/matheology-{depth}.rst``. - Stub pages are marked with a visible banner: ``.. warning:: This page is a stub. Content pending.`` ---- 8. User Decisions Reference ============================== The 13 user decisions from AHA Section 12.2, mapped to CLI options: .. list-table:: :header-rows: 1 :widths: 4 28 20 20 28 * - # - Decision - CLI option - Default - Notes * - 1 - Mode - ``[mode]`` (positional) - (required) - replace, append, archive, migrate * - 2 - Output folder - ``--output`` - ``matheology/`` - Override for non-standard locations * - 3 - Models to include - ``--models`` - all - Comma-separated: ``pet,jub`` or ``all`` * - 4 - Audience-depths - ``--depths`` - all - Comma-separated: ``expert,prod,easy,math,ma`` * - 5 - Worldviews - ``--views`` - all - Which v-codes and s-codes to generate * - 6 - D2 chain types - ``--states`` - all - Which D2 type IDs to generate pages for * - 7 - Stub folder - (hardcoded) - ``_templates/stubs/`` - Pre-defined stub templates for depths * - 8 - Generate stubs? - ``--stubs`` - no - If no, omit pages that would be entirely stubs * - 9 - Version increment - ``--version-increment`` - (required for archive) - ``v`` (incompatible), ``r`` (features), ``p`` (bugfix) * - 10 - Archive folder - ``--archive-folder`` - ``vv/{version}/`` - Override for non-standard location * - 11 - VVN - ``--vvn`` - (required for archive) - e.g., ``hv_LLoL_OOv2r0p0_2026m03d22`` * - 12 - StayVS maturity - ``--stayc`` - (required for archive) - StayC code for the compilation * - 13 - Freeze PoR? - ``--freeze-por`` - no - Copy PoR sources to per-model VV archives ---- 9. Implementation Notes ========================= 9.1 Pre-Write Protection Check ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Before writing to any file that already exists on disk, the compiler must check whether the file begins with the ``.. compiler:protected`` comment token. If the token is present, the compiler must: 1. Skip the file (do not write, modify, or delete it). 2. Log a notice: ``SKIP [protected]: {path}`` 3. Continue to the next file without error. This check applies to all modes (replace, append, archive, migrate). It is the machine-enforceable form of :ref:`DD-b12 Rule 6 `. The token is an RST comment and is invisible in rendered HTML. .. code-block:: python :caption: Pseudocode if target_path.exists(): first_line = target_path.read_text().lstrip().split('\n')[0] if first_line.startswith('.. compiler:protected'): log(f'SKIP [protected]: {target_path}') return # do not write 9.2 Protected Sections Within Compiled Pages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some compiled pages contain human-crafted sections that must survive regeneration (e.g., a hand-edited intro on an otherwise compiled page). These sections are marked with start/end comment tokens: .. code-block:: rst .. compiler:protected-section start Human-crafted intro. The compiler preserves this section verbatim during regeneration. [human-crafted content here] .. compiler:protected-section end When the compiler regenerates a page that contains these markers, it must: 1. Extract the content between ``start`` and ``end`` markers. 2. Regenerate the rest of the page normally. 3. Re-insert the preserved content at the same position. If no markers are found, the entire page is regenerated. This is distinct from ``.. compiler:protected`` (Section 9.1), which protects an entire file. Protected sections protect a region within an otherwise compiled file. 9.3 PoR Field Parsing ^^^^^^^^^^^^^^^^^^^^^^^ The current PoR format (as seen in ``pet/axioms.rst`` and ``jub/axioms.rst``) uses a semi-structured RST format: - Each element starts with ``.. _{label}:`` - Title is the next heading (underlined with ``^^^`` or ``===``) - ``sum`` is the first italic line after the title - ``intro`` follows "In plain English:" - ``latex`` is inside ``.. math::`` blocks - ``tctx`` follows "Explanation:" - Source fields follow "Scriptural and philosophical support:" as a bullet list, keyed by tradition name in bold The parser must extract these fields by pattern matching against the current RST structure. If the structure changes, the parser must be updated. 9.3.1 LaTeX Math Block Preservation '''''''''''''''''''''''''''''''''''''' When extracting and emitting ``latex`` fields (``.. math::`` blocks), the compiler must preserve the **exact whitespace and LaTeX formatting** from the PoR source, including: - ``\\`` (LaTeX line-break markers) - ``&`` (alignment markers, used with ``\\`` for multi-line alignment) - ``\bigl``, ``\bigr``, ``\Bigl``, ``\Bigr`` (bracket sizing) - Indentation within the math block RST's ``.. math::`` directive ignores RST-level line breaks. Multiple RST lines within a math block are concatenated into a single LaTeX expression unless the source contains explicit ``\\`` markers. If the compiler strips or fails to copy these markers, multi-line formulas collapse into a single overflowing line in the rendered output. **Rule:** Copy the entire content of each ``.. math::`` block character-for-character from the PoR source. Do not reflow, rewrap, or normalize whitespace within math blocks. 9.4 Cross-Reference Integrity ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ After any compilation run, all ``:ref:`` links in generated pages must resolve. The skill should: 1. Collect all labels defined in generated pages 2. Collect all ``:ref:`` targets used in generated pages 3. Check that every target either exists in generated pages or in the source PoR files 4. Report any orphaned references as warnings 9.5 Toctree Management ^^^^^^^^^^^^^^^^^^^^^^^^^ Generated pages must be added to ``toctree`` directives in the appropriate ``index.rst`` files. The skill should: 1. Read the existing ``index.rst`` 2. Add new entries in alphabetical order within the appropriate section 3. Never remove existing manually-created entries 4. Mark auto-generated toctree sections with a comment: ``.. Auto-generated by SISYF. Do not edit below.``