Refactor: kebab-case the three snake_case doc filenames

.claude/rules/ascend.md

@@ -1,6 +1,6 @@
 # Ascend Architecture Quick Reference
 
-See [docs/hardware/chip-architecture.md](../../docs/hardware/chip-architecture.md) for the **hardware substrate** (Host CPU / AICPU / AICore tiers, PCIe boundary, cache-coherency entry point) — shared across a2a3 and a5. See [docs/chip-level-arch.md](../../docs/chip-level-arch.md) for the **software three-program model** (host `.so` + AICPU `.so` + AICore `.o`) layered on top: full diagram, API layers, execution flow, handshake protocol. See [docs/hierarchical_level_runtime.md](../../docs/hierarchical_level_runtime.md) for the L0–L6 level model and component composition, and [docs/task-flow.md](../../docs/task-flow.md) for end-to-end task data flow.
+See [docs/hardware/chip-architecture.md](../../docs/hardware/chip-architecture.md) for the **hardware substrate** (Host CPU / AICPU / AICore tiers, PCIe boundary, cache-coherency entry point) — shared across a2a3 and a5. See [docs/chip-level-arch.md](../../docs/chip-level-arch.md) for the **software three-program model** (host `.so` + AICPU `.so` + AICore `.o`) layered on top: full diagram, API layers, execution flow, handshake protocol. See [docs/hierarchical-level-runtime.md](../../docs/hierarchical-level-runtime.md) for the L0–L6 level model and component composition, and [docs/task-flow.md](../../docs/task-flow.md) for end-to-end task data flow.
 
 ## Key Concepts
 

.claude/skills/dfx-analyze/SKILL.md

@@ -9,7 +9,7 @@ simpler already ships end-user analysis CLIs under `simpler_setup.tools` —
 **use them; do not re-invent timing/instrumentation in the runtime.** Canonical
 reference (tool flags, examples, output paths): `simpler_setup/tools/README.md`.
 Per-DFX docs: `docs/dfx/` (`l2-timing.md`, `sched-overhead-model.md`,
-`l2-swimlane-profiling.md`, `scope-stats.md`, `dep_gen.md`, `args-dump.md`).
+`l2-swimlane-profiling.md`, `scope-stats.md`, `dep-gen.md`, `args-dump.md`).
 
 ## Pick the tool by question
 

README.md

@@ -97,7 +97,7 @@ Building **on** simpler? Start at **[docs/user/](docs/user/README.md)** — how-
 | -------- | ----------- |
 | [Capability Survey](docs/capability-survey.md) | Status snapshot: what is shipped, gated, or design-only across topology (L2→L4), CANN launch, and comm engines |
 | [Chip-Level Architecture](docs/chip-level-arch.md) | L2 single-chip: three-program model (host/AICPU/AICore), API layers, handshake protocol |
-| [Hierarchical Level Runtime](docs/hierarchical_level_runtime.md) | L0–L6 level model, component composition (Orchestrator / Scheduler / Worker) |
+| [Hierarchical Level Runtime](docs/hierarchical-level-runtime.md) | L0–L6 level model, component composition (Orchestrator / Scheduler / Worker) |
 | [Task Flow](docs/task-flow.md) | End-to-end data flow: Callable / TaskArgs / CallConfig handles, IWorker interface |
 | [Orchestrator](docs/orchestrator.md) | DAG submission internals: submit flow, TensorMap, Scope, Ring, task state machine |
 | [Scheduler](docs/scheduler.md) | DAG dispatch internals: wiring/ready/completion queues, dispatch loop |

docs/README.md

@@ -8,6 +8,9 @@ New docs belong in one of the groups below, and in a subdirectory when the group
 already has one (`dfx/`, `hardware/`, `troubleshooting/`, `investigations/`).
 Add the row here in the same commit — an unlisted doc is invisible.
 
+**File names are kebab-case** (`chip-level-arch.md`), including when the doc is
+named after a code identifier that uses underscores.
+
 ## Start here
 
 Two audiences use this tree. If you are **building on** simpler — writing
@@ -29,7 +32,7 @@ changing simpler's own internals.
 | Document | What it covers |
 | -------- | -------------- |
 | [Chip-Level Architecture (L2)](chip-level-arch.md) | Three-program model (host / AICPU / AICore), API layers, handshake |
-| [Hierarchical Level Runtime](hierarchical_level_runtime.md) | The L0–L6 level model and component composition |
+| [Hierarchical Level Runtime](hierarchical-level-runtime.md) | The L0–L6 level model and component composition |
 | [Task Flow](task-flow.md) | Callable / TaskArgs / CallConfig pass-through, `IWorker` |
 | [Orchestrator](orchestrator.md) | DAG submission: TensorMap, Scope, Ring, task state machine |
 | [Scheduler](scheduler.md) | DAG dispatch: wiring / ready / completion queues, dispatch loop |
@@ -83,7 +86,7 @@ changing simpler's own internals.
 | [CI Pipeline](ci.md) | Jobs, gating, and what each pipeline stage covers |
 | [Python Packaging](python-packaging.md) | Wheel layout, `simpler` vs `simpler_setup`, asset packaging |
 | [Compiler Sanitizers](sanitizers.md) | ASAN / UBSan / TSAN builds |
-| [Sim Multi-Device Isolation](sim_multi_device_isolation.md) | How the simulator isolates concurrent virtual devices |
+| [Sim Multi-Device Isolation](sim-multi-device-isolation.md) | How the simulator isolates concurrent virtual devices |
 
 ## When something is broken
 

docs/aicore-kernel-programming.md

@@ -5,7 +5,7 @@ How to write an AICore kernel for the `tensormap_and_ringbuffer` runtime
 the things that break silently when ported from native CANN code.
 
 For the broader picture see
-[hierarchical_level_runtime.md](hierarchical_level_runtime.md) (where
+[hierarchical-level-runtime.md](hierarchical-level-runtime.md) (where
 kernels sit in the L0–L6 layering),
 [task-flow.md](task-flow.md) (end-to-end task data flow), and
 [chip-level-arch.md](chip-level-arch.md) (Host / AICPU / AICore tiers).

docs/capability-survey.md

@@ -10,7 +10,7 @@ rather than restating them:
 - Hardware substrate → [hardware/chip-architecture.md](hardware/chip-architecture.md),
   [hardware/mmio-performance.md](hardware/mmio-performance.md),
   [hardware/cache-coherency.md](hardware/cache-coherency.md)
-- Level model → [hierarchical_level_runtime.md](hierarchical_level_runtime.md)
+- Level model → [hierarchical-level-runtime.md](hierarchical-level-runtime.md)
 - Three-program model → [chip-level-arch.md](chip-level-arch.md)
 - AICPU launch mechanics → [aicpu-kernel-launch-mechanisms.md](aicpu-kernel-launch-mechanisms.md)
 - Comm domains / overlays → [comm-domain.md](comm-domain.md), [a5-sdma-overlay.md](a5-sdma-overlay.md)
@@ -33,7 +33,7 @@ be re-checked directly.
 ## Topology: L2 (host / AICPU / AICore) → L4 (host → remote host)
 
 The 7-level model (L6 Cluster … L0 Core) is declared in
-[hierarchical_level_runtime.md](hierarchical_level_runtime.md). Its own status
+[hierarchical-level-runtime.md](hierarchical-level-runtime.md). Its own status
 table is accurate: L3 implemented; L4 local implemented, remote simulation only;
 L5/L6 untested.
 

docs/chip-level-arch.md

@@ -3,7 +3,7 @@
 This document describes the **single-chip (L2) architecture** — how a host
 program, AICPU kernel, and AICore kernel cooperate on one Ascend NPU chip. For
 the multi-chip hierarchy (L3+: Orchestrator / Scheduler / Worker composition)
-see [hierarchical_level_runtime.md](hierarchical_level_runtime.md). For how task
+see [hierarchical-level-runtime.md](hierarchical-level-runtime.md). For how task
 data (Callable / TaskArgs / CallConfig) flows through all levels, see
 [task-flow.md](task-flow.md).
 
@@ -150,7 +150,7 @@ worker.finalize()
 ### Python Type Naming Convention
 
 Layer 3 Python types use a **level-prefixed naming convention** that mirrors the
-level model (see [hierarchical_level_runtime.md](hierarchical_level_runtime.md)):
+level model (see [hierarchical-level-runtime.md](hierarchical-level-runtime.md)):
 
 | Concept | L2 (Chip) type | L3+ (Distributed) type | Unified factory |
 | ------- | -------------- | ---------------------- | --------------- |

docs/comm-domain.md

@@ -7,7 +7,7 @@ function** via `orch.allocate_domain(...)` — there is no init-time / static
 declaration path.
 
 For where the Orchestrator sits among the engine components see
-[hierarchical_level_runtime.md](hierarchical_level_runtime.md); for the DAG
+[hierarchical-level-runtime.md](hierarchical-level-runtime.md); for the DAG
 submission internals see [orchestrator.md](orchestrator.md).
 
 ---

docs/dfx/README.md

@@ -39,7 +39,7 @@ Analysis CLIs that consume these outputs are documented in
 | Document | What it covers |
 | -------- | -------------- |
 | [Args Dump](args-dump.md) | Per-task argument capture, and replaying a task from it |
-| [dep_gen](dep_gen.md) | Complete per-submit dependency graph, tensor-annotated |
+| [dep_gen](dep-gen.md) | Complete per-submit dependency graph, tensor-annotated |
 | [Scope Stats](scope-stats.md) | Per-scope resource-usage peaks (ring fill, dep pool) |
 
 ## Related, outside this directory

docs/dfx/args-dump.md

@@ -996,5 +996,5 @@ their unset fallback and keep the `#897` distributed-skew trade-off.
   AICore program boundaries this feature spans.
 - [task-flow.md](../task-flow.md) — where AICPU dispatch and
   completion sit in the per-task state machine.
-- [hierarchical_level_runtime.md](../hierarchical_level_runtime.md)
+- [hierarchical-level-runtime.md](../hierarchical-level-runtime.md)
   — how L2 (this feature) relates to L3+ composition.

docs/dfx/l2-swimlane-profiling.md

@@ -43,7 +43,7 @@ available.
   in the swimlane record itself (the device hot path stays clean —
   see PR #863). Instead, `swimlane_converter` joins
   `l2_swimlane_records.json` with `deps.json` from
-  [`dep_gen`](dep_gen.md) at post-process time; see
+  [`dep_gen`](dep-gen.md) at post-process time; see
   [§3.5](#35-dependency-arrows-from-dep_gen).
 - **AICPU scheduler phases** — per-iteration breakdown into six
   mutually time-exclusive **outer** phases (`complete` / `async_poll`
@@ -427,7 +427,7 @@ Two artifacts, one join:
 
 | File | Producer | What it carries |
 | ---- | -------- | --------------- |
-| `deps.json` | `--enable-dep-gen` (a [`dep_gen`](dep_gen.md) run) | The static task graph for one topology / case |
+| `deps.json` | `--enable-dep-gen` (a [`dep_gen`](dep-gen.md) run) | The static task graph for one topology / case |
 | `l2_swimlane_records.json` | `--enable-l2-swimlane` | Per-task / per-phase timing for one run |
 | `merged_swimlane.json` | `swimlane_converter` | Perfetto trace = timing joined to the graph |
 

docs/dfx/profiling-framework.md

@@ -15,7 +15,7 @@ transport deviations that the collectors themselves still carry.
 The per-collector pages
 ([pmu-profiling.md](pmu-profiling.md),
 [l2-swimlane-profiling.md](l2-swimlane-profiling.md),
-[dep_gen.md](dep_gen.md),
+[dep-gen.md](dep-gen.md),
 [args-dump.md](args-dump.md),
 [scope-stats.md](scope-stats.md))
 describe the data each subsystem collects and how it enables it on-device.
@@ -463,7 +463,7 @@ Existing collectors are the canonical examples:
 - [`PmuCollector`](../../src/a2a3/platform/include/host/pmu_collector.h)
   — single kind, per-core instances. See [pmu-profiling.md](pmu-profiling.md).
 - [`DepGenCollector`](../../src/common/platform/include/host/dep_gen_collector.h)
-  — single kind, one instance. See [dep_gen.md](dep_gen.md).
+  — single kind, one instance. See [dep-gen.md](dep-gen.md).
 - [`ArgsDumpCollector`](../../src/common/platform/include/host/args_dump_collector.h)
   — single kind, per-AICPU-thread instances. See [args-dump.md](args-dump.md).
 - [`ScopeStatsCollector`](../../src/common/platform/include/host/scope_stats_collector.h)

docs/l3-l2-message-queue.md

@@ -9,7 +9,7 @@ and L3 dequeues those outputs. The queue is built on top of the lower-level
 L3-L2 orchestration communication primitives described in
 [l3-l2-orch-comm.md](l3-l2-orch-comm.md). For where L3 and L2 sit in
 the runtime stack, see
-[hierarchical_level_runtime.md](hierarchical_level_runtime.md).
+[hierarchical-level-runtime.md](hierarchical-level-runtime.md).
 
 ## 1. API
 

docs/l3-l2-orch-comm.md

@@ -11,7 +11,7 @@ The intended use case is in-flight interaction: L3 can write input payload,
 publish a data-ready counter, wait for L2/AICore completion, and read output
 payload without ending the L2 orchestration task. For where L3 and L2 sit in
 the runtime stack, see
-[hierarchical_level_runtime.md](hierarchical_level_runtime.md). For dynamic
+[hierarchical-level-runtime.md](hierarchical-level-runtime.md). For dynamic
 cross-rank communication domains, see [comm-domain.md](comm-domain.md).
 
 ## 1. API

docs/orchestrator.md

@@ -12,7 +12,7 @@ that turn a sequence of `submit_*` calls into a scheduled DAG: `Ring`,
 `TensorMap`, and `Scope`.
 
 For the high-level role of the Orchestrator among the three engine components,
-see [hierarchical_level_runtime.md](hierarchical_level_runtime.md). For what
+see [hierarchical-level-runtime.md](hierarchical-level-runtime.md). For what
 flows through `submit`, see [task-flow.md](task-flow.md).
 
 ---
@@ -745,7 +745,7 @@ instead of stalling forever. Default timeout: 10 s.
 
 ## 10. Related
 
-- [hierarchical_level_runtime.md](hierarchical_level_runtime.md) — how
+- [hierarchical-level-runtime.md](hierarchical-level-runtime.md) — how
   Orchestrator fits alongside Scheduler and Worker
 - [scheduler.md](scheduler.md) — READY dispatch and completion-time dependency
   release

docs/remote-l3-worker-design/pr-split-and-audit-artifacts.md

@@ -79,7 +79,7 @@ been created by this audit.
 | R12 `PYTHON_SERIALIZED` remote callables reject unless serialized support is explicitly negotiated | `remote-l3-worker-design.md` §§Scope, Worker Identity and Callable Routing; `protocol.md` §CONTROL Payload; `implementation-plan.md` step 6 | required explicit unsupported behavior | `_prepare_register_callable` rejects `CallableKind.PYTHON_SERIALIZED` before install | `test_remote_register_rejects_python_serialized_without_negotiation` | Phase 3 added missing coverage | PR 6 |
 | R13 `CHIP_CALLABLE` is valid only for `INNER_L3_WORKER`; inline blobs are supported by sim, staged blobs reject unless negotiated | `protocol.md` §CONTROL Payload; `implementation-plan.md` step 6; `implementation-record.md` §Completed Items | required in this PR cut plus required explicit unsupported behavior for staged blobs | `_prepare_inner_chip_callable`; dispatcher rejects chip target; staged blob reject | inner chip manifest install, dispatcher reject test, `test_remote_inner_chip_callable_rejects_staged_blob_without_negotiation` | Phase 3 added missing staged-blob coverage | PR 5 / PR 6 |
 | R14 Bootstrap manifest installs dispatcher and inner registries before `HELLO READY`; unsupported negotiated manifest extensions reject rather than partially install | `remote-l3-worker-design.md` §Remote Worker Session; `protocol.md` §CONTROL Payload; `implementation-plan.md` steps 6-7 | required in this PR cut | `remote_l3_session.run_session`, `_install_manifest_inner_registry`, daemon manifest validation | manifest inner Python/chip install tests; remote sim roundtrip tests | None found | PR 6 |
-| R15 Fork ordering preserves prestart before command/health transport threads; `HELLO READY` is a scheduling barrier | `remote-l3-worker-design.md` §Fork-Safe Remote Process Model; `protocol.md` §HELLO Payload; `hierarchical_level_runtime.md` §Process Model | required in this PR cut | daemon writes manifest, session prestarts `inner_worker`, then binds command/health and sends HELLO READY; parent `add_remote_l3_socket` waits for READY | remote unreachable daemon test; remote sim roundtrip/prep tests | None found | PR 6 |
+| R15 Fork ordering preserves prestart before command/health transport threads; `HELLO READY` is a scheduling barrier | `remote-l3-worker-design.md` §Fork-Safe Remote Process Model; `protocol.md` §HELLO Payload; `hierarchical-level-runtime.md` §Process Model | required in this PR cut | daemon writes manifest, session prestarts `inner_worker`, then binds command/health and sends HELLO READY; parent `add_remote_l3_socket` waits for READY | remote unreachable daemon test; remote sim roundtrip/prep tests | None found | PR 6 |
 | R16 Remote frame protocol uses versioned canonical little-endian encoding and never memcpy's C++ POD structs | `remote-l3-worker-design.md` §Protocol; `protocol.md` §§Frames, Wire Encoding; `implementation-plan.md` step 5 | required in this PR cut | `remote_wire.cpp` explicit put/get helpers; Python `_Reader`; local mailbox remains same-binary POD IPC only | `FrameRoundTripValidatesHeader`, Python decode tests | Found and fixed `CallConfigWire.enable_scope_stats` drift in Phase 3 | PR 3 |
 | R17 Frame codec rejects bad magic/version/type/flags, oversized/truncated payloads, unknown enums, non-zero reserved fields, and malformed counts | `protocol.md` §§Frames, Wire Encoding, Bounds and Fuzz Tests; `implementation-plan.md` step 5 | required in this PR cut | C++ and Python decode validation for headers, counts, enums, reserved fields, payload sizes | remote wire bad header/truncation/reserved tests; Python materialization/decode tests | No blocking drift found | PR 3 |
 | R18 TASK payload carries digest, `CallConfigWire`, and `RemoteTaskArgsWire`; tensor wire `data` must be zero; `HOST_INLINE` must be descriptor-backed and bounds-checked | `protocol.md` §§TASK Payload, RemoteTensorDesc, Bounds and Fuzz Tests; `buffers-and-transports.md` §TaskArgs Sidecar Contract | required in this PR cut | `encode_task_payload`, `decode_task_payload`, `RemoteL3Endpoint::build_task_payload`, Python `_materialize_task_args` | non-zero tensor data rejection, HOST_INLINE descriptor bounds, host-inline materialization/roundtrip | Phase 3 fixed and tested missing `enable_scope_stats` field | PR 3 / PR 5 |
@@ -106,7 +106,7 @@ been created by this audit.
 
 | File or hunk | Owner PR | Reason | Depends on | Tests |
 | ------------ | -------- | ------ | ---------- | ----- |
-| `docs/remote-l3-worker-design.md`, `docs/remote-l3-worker-design/*`, related docs (`worker-manager.md`, `scheduler.md`, `orchestrator.md`, `task-flow.md`, `hierarchical_level_runtime.md`) | PR 1 | Establish design, protocol, buffer lifecycle, rollout, and audit artifacts | None | docs/pre-commit checks |
+| `docs/remote-l3-worker-design.md`, `docs/remote-l3-worker-design/*`, related docs (`worker-manager.md`, `scheduler.md`, `orchestrator.md`, `task-flow.md`, `hierarchical-level-runtime.md`) | PR 1 | Establish design, protocol, buffer lifecycle, rollout, and audit artifacts | None | docs/pre-commit checks |
 | `python/simpler/callable_identity.py`, callable descriptor/hashid portions of `python/simpler/worker.py`, callable-handle portions of tests | PR 2 | Make callable identity reviewable before remote endpoint behavior | PR 1 docs | callable identity Python UT |
 | `src/common/hierarchical/remote_wire.*`, `python/simpler/remote_l3_protocol.py`, remote-wire-focused tests | PR 3 | Stable cross-host protocol and codec validation | PR 1 docs; PR 2 enum/identity definitions | C++ `test_remote_wire`; Python protocol decode tests |
 | Scheduler and slot-state hunks in `src/common/hierarchical/types.*`, `orchestrator.*`, `scheduler.*`, `worker_manager.*` | PR 4 | Endpoint eligibility, outcomes, sidecars, dependency keys, failure poisoning | PR 2 identity; PR 3 types/protocol where referenced | C++ `test_orchestrator`, `test_scheduler` |

docs/remote-l3-worker-design/pr-split-and-audit-plan.md

@@ -45,7 +45,7 @@ Inputs:
   - `docs/scheduler.md`
   - `docs/worker-manager.md`
   - `docs/task-flow.md`
-  - `docs/hierarchical_level_runtime.md`
+  - `docs/hierarchical-level-runtime.md`
 
 Use PR-head documents, not stale local notes. Drop empty CI retrigger commits
 during the split. Fixup formatting and CI stabilization commits into the

docs/scheduler.md

@@ -187,7 +187,7 @@ The scheduling invariants are:
 
 ## 8. Related documents
 
-- [hierarchical_level_runtime.md](hierarchical_level_runtime.md)
+- [hierarchical-level-runtime.md](hierarchical-level-runtime.md)
 - [orchestrator.md](orchestrator.md)
 - [worker-manager.md](worker-manager.md)
 - [task-flow.md](task-flow.md)

docs/task-flow.md

@@ -22,7 +22,7 @@ scheduled), see:
 - [orchestrator.md](orchestrator.md) — submit flow, Ring, TensorMap, Scope
 - [scheduler.md](scheduler.md) — dispatch loop, queues, completion handling
 - [worker-manager.md](worker-manager.md) — WorkerThread, mailbox IPC mechanics
-- [hierarchical_level_runtime.md](hierarchical_level_runtime.md) — level model
+- [hierarchical-level-runtime.md](hierarchical-level-runtime.md) — level model
   and how components compose
 
 ---
@@ -612,7 +612,7 @@ lives in the mailbox blob bytes on the child side — view doesn't care.
 
 ## Related
 
-- [hierarchical_level_runtime.md](hierarchical_level_runtime.md) — L0–L6 level
+- [hierarchical-level-runtime.md](hierarchical-level-runtime.md) — L0–L6 level
   model, three-component composition
 - [orchestrator.md](orchestrator.md) — how `submit_*` actually builds the DAG
 - [scheduler.md](scheduler.md) — how dispatched slots get worker threads