.. meta::
   :description: TELES --- Terminally Eliminating Log Errors Systematically. A compiler for fixing RST formatting errors and performing controlled identifier migrations in LLogs.
   :keywords: TELES, compiler, llog, RST errors, formatting, log errors, systematic, matheology, identifier migration, renaming
   :author: Yah, Yas, everyone, LLoL as Laurence Loewe of Laodicea, ClaudeOp46Max, Anthropic, and The Spirit of Boolean Truth

.. _compiler-teles:


***********************************************************************
TELES --- Terminally Eliminating Log Errors Systematically
***********************************************************************

TELES is a compiler for fixing RST formatting errors in LLogs (session logs)
without compromising any conceptual integrity of the log content. Unlike
PROMY (which purifies reasoning) and SISYF (which assembles views), TELES
operates only on the *form* of logs, never on the *substance*.

**Safety Profile**: Read-write with respect to RST formatting and
controlled identifier migrations *only*. The meaning of formal objects
(axioms, theorems, etc.) is untouchable --- only their surface-level
identifiers may change, and only under the strict conditions defined below.


The TELES Contract
====================

Standard Operations (formatting fixes)
-----------------------------------------

TELES is allowed to fix:

- Heading underline/overline length mismatches
- Inconsistent heading hierarchy (e.g., skipping levels)
- Indentation errors in directives and code blocks
- Broken cross-references (typos in ``:doc:`` / ``:ref:`` targets)
- Malformed ``.. meta::`` blocks (blank lines inside directives)
- Missing blank lines before/after directives
- Trailing whitespace and line-ending inconsistencies

Extended Operations (mechanical identifier migrations)
---------------------------------------------------------

TELES is additionally allowed to perform **mechanical identifier-format
migrations** where the identity of the formal object is preserved (synonym,
not rename). This extension covers operations such as:

- Migrating axiom/theorem text references from one naming convention to
  another (e.g., ``ax15`` → ``ax15``) where both forms denote the
  same formal object
- Removing or replacing characters that cause parsing problems in web
  contexts (e.g., ``ax11b`` → ``A11b``)
- Updating cross-reference labels to match a new naming architecture

**Conditions for extended operations** (ALL must hold):

1. **Identity preservation**: The formal object (axiom, theorem, equation)
   MUST remain the same. The old identifier MUST survive as a suffix,
   alias, or documented synonym. No information loss.
2. **Mechanical consistency**: The substitution MUST be expressible as a
   deterministic find-and-replace (possibly with word-boundary or context
   constraints). No judgment calls about meaning.
3. **Complete mapping table**: A dated mapping table listing every
   old→new substitution MUST be produced and stored permanently.
4. **Manual checking**: The researcher in charge MUST review the results
   for false positives, especially for short identifiers (ax1--ax9) that
   could match non-axiom text.
5. **Minimal scope**: Only change what the migration requires. Do not
   "improve" surrounding text, fix nearby formatting, or make editorial
   changes while performing the migration.
6. **Documentation**: A dated migration note MUST be appended to every
   modified file (see reporting format below).

**This extension should be used sparingly.** Identifier migrations are
disruptive and error-prone. They are justified only when the current
identifiers cause concrete problems (parsing failures, ambiguity,
systematic confusion) that outweigh the cost of the migration.

For full rationale and procedures, see :doc:`renaming-policy`.


TELES is NEVER allowed to
----------------------------

- Change the **meaning** of any text (wording, phrasing, argument structure)
- Modify the **substance** of axioms, theorems, proofs, or equations
  (the mathematical content, not the label)
- Delete, reorder, or merge content sections
- Add new content (except error-report and migration-report admonition boxes)
- Change file names or directory structure
- Perform identifier migrations that do NOT preserve identity (true renames
  where the old name is lost)


Reporting Format
==================

**After every standard TELES run**, append:

.. code-block:: rst

   .. admonition:: TELES error report (YYYY-MM-DD)

      Repaired N formatting errors:

      - Line X: heading underline extended from 40 to 72 chars
      - Line Y: added missing blank line before directive
      - ...

**After every extended TELES run** (identifier migration), append:

.. code-block:: rst

   .. admonition:: TELES migration report (YYYY-MM-DD)

      Mechanical identifier migration applied to this file.
      All axiom/theorem text references migrated from short form
      (e.g., ax15) to compound form (e.g., ax15).
      Both forms refer to the same formal object. The old form
      survives as the suffix. See <link to mapping table> for
      the complete mapping.


Using the RST Linter Before TELES
====================================

Before running TELES, use the installed RST linter to identify errors:

.. code-block:: bash

   make lint

This runs ``rstcheck --config scripts/rstcheck.cfg --recursive source/``
and catches many structural RST errors in seconds. The linter output helps
TELES focus on real errors rather than false positives.

For build-level warnings:

.. code-block:: bash

   make html 2>&1 | grep WARNING

TELES should address warnings that are RST-formatting-related, not
content-related (e.g., unreferenced citations are content issues, not
formatting issues).


TELES Prompt Template (Standard)
===================================

When running TELES on a specific file for formatting fixes:

.. code-block:: text

   You are TELES (Terminally Eliminating Log Errors Systematically).

   Your task is to fix RST formatting errors in the following LLog file.
   You must NOT change any content, meaning, wording, axioms, theorems,
   symbol definitions, or equations. You may ONLY fix formatting:
   heading underlines, indentation, blank lines, directive syntax, etc.

   After fixing, append a dated TELES error report admonition at the end
   of the file documenting exactly what you changed and why.

   File to process: <path>

   Known warnings from `make html` for this file:
   <paste warnings here>

   Known errors from `make lint` for this file:
   <paste lint output here>


Status
========

:Created: 2026m04d03
:Status: Designed, not yet tested
:Contract extended: 2026m04d03 (mechanical identifier migrations)

TELES has been designed but not yet run on any files. The first test run
should be coordinated with LLoL.

For the first planned extended operation (axiom/theorem compound naming),
see: :ref:`hell-ll-other-b15-teles-renaming-prompt`.


.. toctree::
   :maxdepth: 1
   :caption: TELES Documentation

   teles-start-prompt
   teles-stop-prompt
   renaming-policy


.. Future TELES session logs will be stored at hell/ll/teles/b/<N>/
   following the same lettered-numbering convention as other compiler logs.