Retire the PTO brand names, and hold the line with a hook

.claude/rules/codestyle.md

@@ -127,28 +127,39 @@
     "PTO Runtime2", and a bare "Runtime2" are not names of anything** — the
     `2` never denoted a version any reader can identify.
 
-    **The retirement is complete** (snapshot 2026-08-24: 6.6k occurrences across
-    367 files on 2026-07-26 → 0 that this repo reads). Nothing here reads a
-    `PTO2` name any more: the last of them were the `PTO2_RING_*` ring-sizing
-    environment variables, retired in favour of per-task
-    `CallConfig.runtime_env`. What is left in the tree is this rule's own
-    examples, the warning that fires if a caller still exports a retired ring
-    variable, prose recording that these names are gone, and
-    `PTO2_MANUAL_MAX_SEQ` — a pypto-lib knob two example READMEs document and
-    this repo never reads. **So a new `PTO2` match is a defect** — there is no
-    backlog to work through. Find the surface with:
+    **No `PTO2` identifier is left.** The last of them were the `PTO2_RING_*`
+    ring-sizing environment variables, retired in favour of per-task
+    `CallConfig.runtime_env`; `git grep -Io -E "PTO2|pto2_"` now finds only this
+    rule's own examples, the warning that fires if a caller still exports a
+    retired ring variable, prose recording that these names are gone, and
+    `PTO2_MANUAL_MAX_SEQ` — a pypto-lib knob two example READMEs document and this
+    repo never reads. **So a new `PTO2` match is a defect.**
+
+    **The brand spellings are held by a hook, not by a count.**
+    `tests/lint/check_retired_names.py` fails pre-commit on any new
+    `PTO Runtime`, `PTO Runtime2`, or bare `Runtime2`. That hook exists because
+    this paragraph once asserted the whole surface was empty while the rule's own
+    grep found 38 banners across 36 files: the assertion had been measured with
+    `PTO2|pto2_`, which cannot see a brand name with a space in it. Do not put a
+    number here again — put it in the hook.
+
+    Find the surface with the rule's own pattern, which is wider than the hook's
+    on purpose (it also reaches the tiers below):
 
     ```bash
     grep -rIn -E "PTO Runtime2?|PTO2|pto2_|pto_runtime2" --include=* . | grep -v '^\./\.git/'
     ```
 
-    Each match falls in exactly one tier, and the tier decides what you owe:
+    Each match falls in exactly one tier, and the tier decides what you owe. Note
+    that **the first two tiers share the `pto_*` namespace and have opposite
+    risk** — that is the trap this table exists to spell out:
 
     | Tier | What | Policy |
     | ---- | ---- | ------ |
-    | **A — prose** | Brand mentions in docs, headings, skill descriptions, issue templates, and code comments (`# PTO Runtime2 Profiling Levels`, "the PTO Runtime consists of…") | **Fix on sight, unconditionally.** No compile risk, no contract. Say `simpler`, or name the actual component ("the AICPU orchestrator", "the `tensormap_and_ringbuffer` runtime") when that is what the sentence means. |
+    | **A1 — brand prose** | The brand itself in docs, headings, skill descriptions, issue templates, and code comments (`# PTO Runtime2 Profiling Levels`, "the PTO Runtime consists of…") | **Fix on sight, unconditionally**, and the hook will make you. No compile risk, no contract, and no Tier-C name can hide in a file banner. Say `simpler`, or name the actual component ("the AICPU orchestrator", "the `tensormap_and_ringbuffer` runtime"). Follow the banner style already in the tree: `orchestrator_core/orchestrator.cpp` opens `* host_build_graph orchestrator implementation`. |
+    | **A2 — comments naming a `pto_*` that does not exist** | e.g. `pto_submit_task` (the entry is `rt_submit_task`), `pto_runtime2_init` (the work is `SchedulerState::init_data_from_layout`) | **Fix on sight**, but this is a [`doc-consistency.md`](doc-consistency.md) §3 defect, not a naming preference: a reader who greps the name finds nothing. Confirm the symbol is absent before renaming it — `git grep -w <name>` returning only comments is the test. |
     | **B — internal identifiers** | `PTO2Foo` types, `pto2_*` functions, internal `PTO2_*` macros and enumerators, `pto_*.h` / `pto_runtime2*.cpp` file names | Rename **only when you are already modifying that code**, per rule 9, and finish the identifier you started (below). |
-    | **C — external contracts** | `runtime_env` knobs, `extern "C"` symbols in `runtime_c_api.h`, on-wire / serialized names | **Exempt until a migration ships.** Renaming these breaks callers in other repos. Ask the user before touching one; land it only with a compatibility alias or a coordinated cross-repo change. |
+    | **C — external contracts** | `runtime_env` knobs, `extern "C"` symbols in `runtime_c_api.h`, on-wire / serialized names, and **every live `pto_cpu_sim_*` / `pto_sim_*` hook** | **Exempt until a migration ships.** Renaming these breaks callers in other repos. The sim hooks are the worst case and the reason A2 above demands a grep first: `cpu_sim_context.cpp` exports them for "pto-isa via `dlsym(RTLD_DEFAULT)`" and `device_runner_base.cpp` fetches `pto_sim_register_hooks` by `dlsym`, so a rename produces **no compile error** — just a hook that is never found at run time. Ask the user before touching one; land it only with a compatibility alias or a coordinated cross-repo change. |
 
     An environment variable is the worst case in Tier C and the reason it
     exists: an unrecognised name is *ignored*, so the rename fails silently
@@ -172,9 +183,11 @@
       tensormap_and_ringbuffer}/` trees are near-duplicates, so a Tier-B
       rename in one of them must land in its siblings in the same commit.
       Verify with the grep above returning zero hits for that identifier.
-    - **The count only goes down.** Introducing a new `PTO2`/`PTO Runtime`
-      spelling anywhere — including by copying an existing `pto_*.h` to a
-      new arch — is a defect, not neutral. Rule 9 makes this unconditional.
+    - **The count only goes down**, and for the brand spellings
+      `tests/lint/check_retired_names.py` enforces it. Introducing a new
+      `PTO2`/`PTO Runtime` spelling anywhere — including by copying an existing
+      `pto_*.h` to a new arch — is a defect, not neutral. Rule 9 makes this
+      unconditional.
     - **Check the target name against three things, not one.** The bare name
       may be taken by the host orchestrator under `src/common/hierarchical/`
       (`TensorMap`, `ReadyQueue`, `TaskState`, `HeapRing`, `MAX_SCOPE_DEPTH`

.pre-commit-config.yaml

@@ -32,6 +32,13 @@ repos:
           language_version: python3
           files: ^(examples|tests/st)/(.*/)?test_[^/]*\.py$
 
+        - id: check-retired-names
+          name: check-retired-names
+          entry: python tests/lint/check_retired_names.py
+          language: python
+          language_version: python3
+          exclude: ^3rdparty/|vendor/
+
     - repo: https://github.com/pre-commit/pre-commit-hooks
       rev: v4.6.0
       hooks:

examples/a2a3/tensormap_and_ringbuffer/paged_attention_ringbuffer/README.md

@@ -29,9 +29,9 @@ referenced, the golden check fails or the orchestrator wedges.
 
 Two things this example is the reference for:
 
-- **Per-case ring sizing through `config.runtime_env`**, not the process-global
-  now-retired `PTO2_RING_*` environment variables. The rings are sized per task, so one
-  suite can mix a stress case with normally-sized ones.
+- **Per-case ring sizing through `config.runtime_env`.** The rings are sized per
+  task rather than per process, so one suite can mix a stress case with
+  normally-sized ones.
 - **Non-power-of-2 sizes are accepted.** 4 MiB is chosen to keep the stress
   intent compact, not because the runtime requires a round number.
 

examples/a2a3/tensormap_and_ringbuffer/paged_attention_ringbuffer/test_paged_attention_ringbuffer.py

@@ -10,7 +10,7 @@
 """Paged attention with small ring buffer sizes — stress test for ring rotation/reclamation.
 
 Drives per-case ring sizing through ``config.runtime_env`` (ring_task_window /
-ring_heap / ring_dep_pool) rather than the process-global PTO2_RING_* env it replaced, plus
+ring_heap / ring_dep_pool), which is per task rather than per process, plus
 INOUT tensors, bfloat16, and AIC+AIV mixed execution.
 """
 

examples/a5/tensormap_and_ringbuffer/paged_attention_ringbuffer/README.md

@@ -29,9 +29,9 @@ referenced, the golden check fails or the orchestrator wedges.
 
 Two things this example is the reference for:
 
-- **Per-case ring sizing through `config.runtime_env`**, not the process-global
-  now-retired `PTO2_RING_*` environment variables. The rings are sized per task, so one
-  suite can mix a stress case with normally-sized ones.
+- **Per-case ring sizing through `config.runtime_env`.** The rings are sized per
+  task rather than per process, so one suite can mix a stress case with
+  normally-sized ones.
 - **Non-power-of-2 sizes are accepted.** 4 MiB is chosen to keep the stress
   intent compact, not because the runtime requires a round number.
 

examples/a5/tensormap_and_ringbuffer/paged_attention_ringbuffer/test_paged_attention_ringbuffer.py

@@ -10,7 +10,7 @@
 """Paged attention with small ring buffer sizes — stress test for ring rotation/reclamation.
 
 Drives per-case ring sizing through ``config.runtime_env`` (ring_task_window /
-ring_heap / ring_dep_pool) rather than the process-global PTO2_RING_* env it replaced, plus
+ring_heap / ring_dep_pool), which is per task rather than per process, plus
 INOUT tensors, bfloat16, and AIC+AIV mixed execution.
 """
 

examples/workers/l3/per_task_runtime_env/README.md

@@ -7,9 +7,9 @@ each need a different ring footprint.
 
 ## What it shows
 
-Before this knob, every L2 dispatched from one L3 shared the process-wide
-process-wide `PTO2_RING_*` env, since retired, and could not be sized independently. Now each
-`submit_next_level` gets its own `CallConfig`:
+Before this knob, every L2 dispatched from one L3 shared one process-wide ring
+sizing and could not be sized independently. Now each `submit_next_level` gets
+its own `CallConfig`:
 
 Each spec sets `ring_task_window` / `ring_heap` / `ring_dep_pool` to a scalar
 (broadcast to every ring) or a 4-entry list (per-ring). `_l2_config` preserves

examples/workers/l3/per_task_runtime_env/main.py

@@ -14,7 +14,7 @@
 several heterogeneous L2 tasks in one launch, and each L2 needs a different
 ring footprint (a heavy task wants a big heap / wide window; a light one is
 fine with the default). Before this knob, all L2 tasks in one L3 launch shared
-the process-wide ``PTO2_RING_*`` env, since retired, and could not be sized independently.
+one process-wide ring sizing and could not be sized independently.
 
 The demo dispatches three L2 tasks: two use the scalar form (one ring value
 broadcast to every ring), and a third passes 4-entry lists for

src/a2a3/platform/onboard/host/runtime_c_api.cpp

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime C API — a2a3 arch-specific entries
+ * simpler host-runtime C API — a2a3 arch-specific entries
  *
  * The shared c_api glue (simpler_init / simpler_register_callable / simpler_run /
  * device_*_ctx / etc.) lives in

src/a2a3/platform/sim/host/runtime_c_api.cpp

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime C API — a2a3 sim arch-specific entries.
+ * simpler host-runtime C API — a2a3 sim arch-specific entries.
  *
  * The shared c_api glue (simpler_init / simpler_register_callable / simpler_run /
  * device_*_ctx / etc.) lives in `src/common/platform/sim/host/c_api_shared.cpp`

src/a2a3/runtime/host_build_graph/runtime/runtime_types.h

@@ -10,9 +10,9 @@
  */
 
 /**
- * PTO Runtime2 - Core Type Definitions
+ * host_build_graph core type definitions
  *
- * This header defines all fundamental types used by the PTO Runtime2 system:
+ * This header defines all fundamental types used by the host_build_graph runtime:
  * - Configuration constants
  * - Worker types and task states
  * - simpler::hbg::Tensor regions and task parameters

src/a2a3/runtime/host_build_graph/runtime/scheduler/scheduler.cpp

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime2 - Scheduler Implementation
+ * host_build_graph scheduler implementation
  *
  * Implements scheduler state management, ready queues, and task lifecycle.
  *

src/a2a3/runtime/host_build_graph/runtime/scheduler/scheduler.h

@@ -10,7 +10,7 @@
  */
 
 /**
- * PTO Runtime2 - Scheduler Interface
+ * host_build_graph scheduler interface
  *
  * The Scheduler is responsible for:
  * 1. Maintaining per-resource-shape ready queues

src/a2a3/runtime/host_build_graph/runtime/shared/shared_memory.cpp

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime2 - Shared Memory Implementation
+ * host_build_graph shared-memory implementation
  *
  * Implements shared memory allocation, initialization, and management
  * for Orchestrator-Scheduler communication.

src/a2a3/runtime/host_build_graph/runtime/shared/tensormap.cpp

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime2 - TensorMap Implementation
+ * host_build_graph TensorMap implementation
  *
  * Implements TensorMap with a fixed-capacity entry pool. Task completion does
  * not invalidate entries; dependency computation explicitly removes only

src/a2a3/runtime/host_build_graph/runtime/tensormap.h

@@ -10,11 +10,11 @@
  */
 
 /**
- * PTO Runtime2 - TensorMap Interface
+ * host_build_graph TensorMap interface
  *
  * TensorMap provides producer lookup for dependency discovery:
  * - Maps simpler::hbg::Tensor -> producer task ID
- * - Used by pto_submit_task() to find dependencies
+ * - Used by rt_submit_task() to find dependencies
  *
  * host_build_graph runs its orchestrator on the host, so this map is host-only
  * state: it owns its four arrays outright rather than addressing them as offsets

src/a2a3/runtime/host_build_graph/runtime/types.h

@@ -13,7 +13,7 @@
  *
  * Standalone header defining orchestration-specific types for:
  * - TaskOutputTensors: Return value from submit containing materialized output ChipTensors
- * - Arg: Aggregated argument container for pto_submit_task API
+ * - Arg: Aggregated argument container for rt_submit_task API
  *
  * simpler::hbg::Tensor descriptor types (simpler::hbg::Tensor, PTOBufferHandle, TensorCreateInfo) are
  * defined in tensor.h.
@@ -137,7 +137,7 @@ class TaskOutputTensors {
 using TaskSubmitResult = TaskOutputTensors;
 
 // =============================================================================
-// Argument Types (for pto_submit_task API)
+// Argument Types (for rt_submit_task API)
 // =============================================================================
 
 // TensorArgType is defined in tensor.h (included via task_args.h above)
@@ -182,7 +182,7 @@ class TensorRef {
 };
 
 /**
- * Aggregated argument container for pto_submit_task
+ * Aggregated argument container for rt_submit_task
  *
  * Inherits storage from TaskArgsTpl<TensorRef, uint64_t, MAX_TENSOR_ARGS, MAX_SCALAR_ARGS, TensorArgType>.
  * Each tensor slot stores a TensorRef union (simpler::hbg::Tensor* or TensorCreateInfo)

src/a2a3/runtime/tensormap_and_ringbuffer/runtime/orchestrator.cpp

@@ -10,7 +10,7 @@
  */
 
 /**
- * PTO Runtime2 - Orchestrator Implementation
+ * tensormap_and_ringbuffer orchestrator implementation
  *
  * Implements orchestrator state management, scope handling, and task submission.
  *

src/a2a3/runtime/tensormap_and_ringbuffer/runtime/orchestrator.h

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime2 - Orchestrator Interface
+ * tensormap_and_ringbuffer orchestrator interface
  *
  * The Orchestrator is responsible for:
  * 1. Executing the orchestration function (Turing-complete control flow)

src/a2a3/runtime/tensormap_and_ringbuffer/runtime/ring_buffer.cpp

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime2 - Ring Buffer Implementation
+ * tensormap_and_ringbuffer ring buffer implementation
  *
  * Implements DepListPool ring buffer for zero-overhead dependency management.
  * TaskAllocator methods are defined inline in ring_buffer.h.

src/a2a3/runtime/tensormap_and_ringbuffer/runtime/ring_buffer.h

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime2 - Ring Buffer Data Structures
+ * tensormap_and_ringbuffer ring buffer data structures
  *
  * Implements ring buffer designs for zero-overhead memory management:
  *

src/a2a3/runtime/tensormap_and_ringbuffer/runtime/scheduler/scheduler.cpp

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime2 - Scheduler Implementation
+ * tensormap_and_ringbuffer scheduler implementation
  *
  * Implements scheduler state management, ready queues, and task lifecycle.
  *

src/a2a3/runtime/tensormap_and_ringbuffer/runtime/scheduler/scheduler.h

@@ -10,7 +10,7 @@
  */
 
 /**
- * PTO Runtime2 - Scheduler Interface
+ * tensormap_and_ringbuffer scheduler interface
  *
  * The Scheduler is responsible for:
  * 1. Maintaining per-resource-shape ready queues

src/a2a3/runtime/tensormap_and_ringbuffer/runtime/shared/shared_memory.cpp

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime2 - Shared Memory Implementation
+ * tensormap_and_ringbuffer shared-memory implementation
  *
  * Implements shared memory allocation, initialization, and management
  * for Orchestrator-Scheduler communication.

src/a2a3/runtime/tensormap_and_ringbuffer/runtime/shared/tensormap.cpp

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime2 - TensorMap Implementation
+ * tensormap_and_ringbuffer TensorMap implementation
  *
  * Implements TensorMap with ring buffer pool, lazy invalidation,
  * and chain truncation optimization.

src/a2a3/runtime/tensormap_and_ringbuffer/runtime/shared_memory.h

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime2 - Shared Memory Layout
+ * tensormap_and_ringbuffer shared-memory layout
  *
  * Defines the shared memory structure for Orchestrator-Scheduler communication.
  *

src/a2a3/runtime/tensormap_and_ringbuffer/runtime/tensormap.h

@@ -10,11 +10,11 @@
  */
 
 /**
- * PTO Runtime2 - TensorMap Interface
+ * tensormap_and_ringbuffer TensorMap interface
  *
  * TensorMap provides producer lookup for dependency discovery:
  * - Maps simpler::tmr::Tensor -> producer task ID
- * - Used by pto_submit_task() to find dependencies
+ * - Used by rt_submit_task() to find dependencies
  *
  * Key design features:
  * 1. Ring buffer pool for entries (no malloc/free)

src/a2a3/runtime/tensormap_and_ringbuffer/runtime/types.h

@@ -13,7 +13,7 @@
  *
  * Standalone header defining orchestration-specific types for:
  * - TaskOutputTensors: Return value from submit containing materialized output ChipTensors
- * - Arg: Aggregated argument container for pto_submit_task API
+ * - Arg: Aggregated argument container for rt_submit_task API
  *
  * simpler::tmr::Tensor descriptor types (simpler::tmr::Tensor, PTOBufferHandle, TensorCreateInfo) are
  * defined in tensor.h.
@@ -170,7 +170,7 @@ class TaskOutputTensors {
 };
 
 // =============================================================================
-// Argument Types (for pto_submit_task API)
+// Argument Types (for rt_submit_task API)
 // =============================================================================
 
 // TensorArgType is defined in tensor.h (included via task_args.h above)
@@ -215,7 +215,7 @@ class TensorRef {
 };
 
 /**
- * Aggregated argument container for pto_submit_task
+ * Aggregated argument container for rt_submit_task
  *
  * Inherits storage from TaskArgsTpl<TensorRef, uint64_t, MAX_TENSOR_ARGS, MAX_SCALAR_ARGS, TensorArgType>.
  * Each tensor slot stores a TensorRef union (simpler::tmr::Tensor* or TensorCreateInfo)

src/a5/platform/onboard/host/runtime_c_api.cpp

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime C API — a5 arch-specific entries
+ * simpler host-runtime C API — a5 arch-specific entries
  *
  * The shared c_api glue (simpler_init / simpler_register_callable / simpler_run /
  * device_*_ctx / etc.) lives in

src/a5/platform/sim/host/runtime_c_api.cpp

@@ -9,7 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 /**
- * PTO Runtime C API — a5 sim arch-specific entries.
+ * simpler host-runtime C API — a5 sim arch-specific entries.
  *
  * The shared c_api glue (simpler_init / simpler_register_callable / simpler_run /
  * device_*_ctx / etc.) lives in `src/common/platform/sim/host/c_api_shared.cpp`