TELES Renaming Policy — Mechanical Identifier Migrations#

This document defines when, why, and how TELES may perform mechanical identifier migrations — operations that change the surface form of formal object references (axiom labels, theorem numbers, etc.) while preserving their identity.

Why This Extension Exists #

Identifier renaming is not rare. In any long-lived project, naming conventions evolve as understanding deepens, scope expands, and new audiences arrive. The original TELES contract forbade all changes to formal content, including identifiers. This was too restrictive: it forced a choice between (a) living with problematic identifiers forever, or (b) creating a separate migration authority for each renaming, multiplying bureaucracy.

The extended TELES contract allows controlled identifier migrations under strict conditions, recognizing that changing A15 to ax15 does not change what Axiom 15 says — it changes how we refer to it.

When to Use TELES for Renaming #

Use TELES renaming when ALL of these hold:

The formal objects are unchanged — same axioms, same theorems, same content. Only the labels change.
The old identifier is preserved as a suffix, alias, or documented synonym. No information is lost.
The migration is mechanical — a deterministic substitution, not an editorial judgment call.
The migration solves a concrete problem (parsing failures, ambiguity, systematic confusion, convention alignment).
The researcher in charge has reviewed and approved the scope.

Do NOT use TELES renaming when:

The migration changes what an axiom/theorem means (true rename, not synonym)
The old identifier would be lost or made unsearchable
The migration requires editorial judgment about which references to change
The migration is purely cosmetic with no concrete benefit

Cons and Pros of Mechanical Identifier Migrations #

Pro: Why Renaming Can Be ZION #

Consistency reduces errors. When all references use the same format, typos and mismatches are easier to detect.
Self-documenting names reduce lookup cost. A compound like ax15 tells the reader both the temporary status (ax) and the legacy mapping (ax15) without consulting a table.
Parsing safety. Characters like ' (apostrophe) in identifiers cause real problems in grep, URLs, databases, and cross-referencing tools. Removing them prevents silent failures.
Explicit temporariness. Lowercase ax signals “this number will change at finalization” — preventing readers from citing a temporary number as if it were permanent.
One migration now prevents N migrations later. If the convention changes piecemeal over many sessions, each session pays a partial migration cost, and the codebase accumulates mixed conventions. One thorough migration is cheaper in total.

Con: Why Renaming Can Be BABL #

Blast radius. A rename touching thousands of references across hundreds of files can introduce errors faster than it fixes them. Every substitution is a potential false positive.
LLog immutability tension. LLogs are append-only audit trails. Changing identifiers in them — even mechanically — means the llog no longer matches what was actually said during the session. The migration report documents this, but the tension remains.
Readability cost. Compound names like ax15 are harder to read than ax15 in running text. Dense passages with many axiom references become noticeably uglier.
Double migration risk. If the final numbering comes sooner than expected, the compound names will need updating again. Each migration has a nonzero error rate.
Short identifiers (ax1–ax9) have high false-positive risk. These patterns are common in non-axiom contexts (list items, headings, hexadecimal values, abbreviations).

EDEN verdict: Grey Edge. The migration is defensible but not risk-free. The cons are manageable with careful execution (context-aware regex, manual review, batch-and-test). The pros are genuine but only pay off if the codebase is actively cited (which it will be, via papers a1–a7).

Procedures for a TELES Renaming Session #

Pre-flight #

Define the mapping table. Every old→new substitution must be listed explicitly. No wildcards, no “and similar.”
Identify the scope. Which files are affected? Separate into:
- Active content (axioms.rst, theorems.rst, etc.) — highest priority
- Historical llogs — mechanical consistency, reviewed post-hoc
- Generated/inventory pages (socialcards) — mechanical, low risk
- Static files (HTML, PDF) — may need separate handling
Identify false-positive risks. For each substitution pattern, list contexts where the pattern might match non-target text. Design regex to exclude those contexts.
Build baseline. Run make html and record the warning count.

Execution #

Process in batches (e.g., by axiom range: ax10–ax25 first, then ax1–ax9 with extra care). Build and test after each batch.

Use word-boundary-aware regex. Example:

# Safe for A10+ (distinctive, low false-positive risk)
sed -i '' 's/\bA15\b/ax15/g' <files>

# For ax1-ax9, use context-aware matching
# (preceded by "Axiom ", "axiom ", ".", or start of RST reference)

Append migration report to every modified file.
Manual review of ax1–ax9 changes — check every substitution in context.

Post-flight #

Build and test. Warning count must not increase.
Store the mapping table permanently at a stable location (linked from the TELES documentation).
Record the session as an llog in hell/ll/teles/b/<N>/.
Update the Root Table (BEST Names) with all synonym mappings.

Reference: First TELES Renaming (Planned)#

The first planned use of the TELES renaming extension is the axiom/theorem compound naming migration:

ax1 → ax1 through ax25 → ax25
ax11b → ax11b (apostrophe elimination)
th1 → th1 through th11 → th11
Papers and external citations use the brief form: ax15, th8

The execution prompt for this migration is stored at: TELES Axiom/Theorem Compound Naming — Execution Prompt

Future agents writing TELES renaming prompts should reference that prompt as a model for scope, structure, and safeguards.

Amendment 2026m08d03 — Path-Segment Migrations (PROBATIONARY)#

Warning

This is a PROBATIONARY feature of TELES. It may be revoked.

There is virtually no experience with sweeping mechanical changes of this kind in this project, and no settled practice for how to track them. The relaxation below was adopted once, for one concrete job, because the alternative was demonstrably worse — not because it has been tested over time. It must be watched carefully. If it starts being invoked often, or invoked to avoid recording decisions that deserve a per-file record, it should be revoked and the per-file rule restored. Frequency of use is itself the warning sign: a rule that makes bulk edits cheap will attract bulk edits.

What this covers #

A path-segment migration changes the spelling of a directory or path component while preserving the identity of everything it contains. It is the same species as an identifier migration (all five “when to use” conditions above apply unchanged) but the surface being changed is a URL path, not a formal label.

The first such migration was executed on 2026m08d03: seven directory names that had drifted from the site convention — POST codes are Double Caps in PROSE, lowercase in PATHS — were aligned. See LLog — Path-case drift on the deploy server, and a consistent guard against silent link death for the full diagnosis, and the sweep llog beside it for the complete file manifest.

The probationary relaxation #

Procedure step Execution 3 above requires: “Append migration report to every modified file.” For a path-segment migration touching hundreds of files this is counter-productive — ~300 admonition boxes would bury the content they annotate, and the reader of any single file learns nothing useful from “a directory above this one was renamed.”

Therefore, for path-segment migrations only, and probationarily:

ONE sweep llog carrying a complete manifest of every file touched, with per-file substitution counts, replaces the per-file migration reports.

The transparency requirement (\(h^* = h_0\)) is not weakened by this — it is relocated. Nothing is hidden; the full record exists, is auditable, and is more useful in one place than scattered across 300 files. What changes is only where the record lives.

Conditions that must ALL hold #

The change is purely a path/reference spelling. No prose, no formal content, no meaning.
Old URLs are redirected, not revoked (StayVS). A published path that disappears without a redirect is a revocation, and this clause does not license it.
The sweep llog carries a complete manifest — every file, every substitution count. Not a summary, not “and similar.”
A machine check confirms the end state. For path migrations this is make check-paths (see AHA/linting.md); it must exit clean and be re-run with --strict-hell, with no finding naming a path the sweep touched. A plain clean run is not sufficient: findings inside HELL do not fail by default, so the exemption meant to protect frozen history will happily hide breakage the sweep just caused. This is not a theoretical risk — it happened during the 2026m08d03 sweep itself (12 stale toctree entries in hell/mm/b/14/index.rst, reported but not failing).
A full build (make html) is run and its new warnings inspected. check-paths does not parse RST; it cannot see everything Sphinx sees.
The researcher in charge approved the scope in advance.

If any condition fails, fall back to the per-file rule.

Prose is not touched #

A path-segment migration lowercases paths only. The Double Caps prose forms — FF, DD, AA, JoLi, CyLi, OOv1, POST, HELL — stay capitalised everywhere they appear as names. The 2026m08d03 sweep is the reference case: 200 path substitutions were made while 1466 prose occurrences of OOv2 and 577 of OOv2r0p0 were left untouched. A migration that cannot demonstrate that separation has not met condition 1.

This policy was created on 2026m04d03 during the HELL Stability Review and FLAMES Restructuring session. Amended 2026m08d03 with the probationary path-segment clause.