ADR housekeeping: category prefixes, lifecycle folders, retroactive 0034-0037

Filename + lifecycle:
- ADR rename to ADR-NNNN-<cat>-title.md with 8 3-letter category prefixes
  (dev / mem / lat / prog / algo / par / api / ver). Numbers stay immutable.
- ADR Lifecycle split into 3 folders, documented in CLAUDE.md Part 2:
  docs/adr/ (Accepted), docs/adr-proposed/ (Proposed/Stub/Draft),
  docs/adr-history/ (Superseded/Merged). Status field gains "Draft" for
  retroactive docs pending verification.

Merges (one ADR per topic, no change-history annotations):
- ADR-0017 absorbs ADR-0019 (Cube NOC + per-PE HBM connectivity, 10 D-items)
- ADR-0014 absorbs ADR-0021 (PE pipeline execution model, 8 D-items incl.
  TileToken self-routing and multi-op composite epilogue scope)
- ADR-0023 absorbs docs/ipcq-dma-codesign-hw.md as new "HW Realization
  Notes (Informative)" section (D16-D23 + Open HW Questions). codesign-hw.md
  deleted; ADR-0019/0021 moved to adr-history with one-line stub status

Retroactive documentation (G4 closures, code-verified):
- ADR-0037 forwarding component (TransitComponent: first-flit overhead,
  serial worker, path-based routing, single impl/multiple names)
- ADR-0036 IO_CPU component (target_start_ns global barrier stamping,
  per-cube fan-out, response aggregation)
- ADR-0035 M_CPU & M_CPU.DMA component (3 fan-out paths, DMA Resources,
  target_start_ns passthrough)
- ADR-0034 HBM controller internal design (per-PC state, address-based
  selection, flit-aware per-flit commit, async finalize, command-only
  fallback path)

Content updates:
- ADR-0010 expanded to full CLI surface (run/probe/web), retitled
  "Command Line Interface and Execution Semantics"
- ADR-0007 D2 rewritten to current state; ADR-0015 supersession notes pruned
- ADR-0005 wrapped in Decision header with D1-D5; ADR-0022 metadata
  block replaced with standard Status header
- ADR-0024 trimmed to rank=SIP launcher essentials (D1-D4);
  ADR-0027 cleaned of supersession history
- ADR-0033 D6 cleanup: address-based PC selection moved out of future-work
  (now documented in ADR-0034 D3); related D1/D3 wording realigned
- Cross-references back-filled in 5 ADRs (G3 gaps closed)

Onboarding docs split:
- docs/onboarding/ created
- moved: hw-architecture-overview.md, latency-model.md, di-presentation.md,
  ccl-author-guide{,.en}.md
- references updated in README, ADR-0023{,.en}, src/kernbench/ccl/__init__.py

Source / test / yaml: ADR-NNNN cross-references in docstrings and YAML
comments updated after the merges (ADR-0021->0014 D6, ADR-0019->0017 D8).
No behavior change.

Tooling:
- tools/verify_adr_lang_pairs.py + tests/test_verify_adr_lang_pairs.py
  (ADR EN/KO pair invariant checker)
- .claude/commands/report.md tracked (/report slash command)
- .gitignore: allow .claude/commands/*.md while keeping settings files ignored

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/kernbench/components/builtin/hbm_ctrl.py

@@ -15,7 +15,7 @@ if TYPE_CHECKING:
 
 
 class HbmCtrlComponent(ComponentBase):
-    """HBM controller with per-pseudo-channel (PC) striping (ADR-0019 D1, ADR-0033).
+    """HBM controller with per-pseudo-channel (PC) striping (ADR-0017 D4, ADR-0033).
 
     Stateless per-PC ``available_at`` array; each incoming transaction is
     split into ``ceil(nbytes / burst_bytes)`` chunks distributed round-robin

src/kernbench/components/builtin/m_cpu.py

@@ -267,8 +267,9 @@ class MCpuComponent(ComponentBase):
     def _resolve_dma_destinations(self, request: Any, target_pe: int | str) -> list[str]:
         """Return list of HBM destination node_ids for DMA fan-out.
 
-        With single hbm_ctrl per cube (ADR-0019), always returns one node.
-        PA-based resolution still used for cross-cube routing.
+        The PA-based resolver maps each address to one per-PE
+        ``hbm_ctrl.pe{X}`` (ADR-0017 D9), so this method returns exactly
+        one node. Cross-cube routing uses the same resolution.
         """
         cube_prefix = self.node.id.rsplit(".", 1)[0]  # e.g. "sip0.cube0"
 

src/kernbench/components/builtin/pe_dma.py

@@ -17,9 +17,11 @@ if TYPE_CHECKING:
 class PeDmaComponent(PeEngineBase):
     """PE_DMA: dual-channel DMA engine with READ and WRITE resources.
 
-    Each channel has capacity=1 (ADR-0014 D4):
+    Compute channels (vc_compute) have capacity=1 each (ADR-0014 D4):
       - DMA_READ and DMA_WRITE may execute concurrently.
       - Multiple READs cannot overlap; multiple WRITEs cannot overlap.
+    The orthogonal vc_comm channel for IPCQ traffic is defined in
+    ADR-0023 D8.
 
     Handles two message types:
       - Transaction: external fabric messages (PeDmaMsg probes, M_CPU DMA)

src/kernbench/components/builtin/pe_fetch_store.py

@@ -1,4 +1,4 @@
-"""PE_FETCH_STORE: TCM ↔ Register File transfer unit (ADR-0021 D5).
+"""PE_FETCH_STORE: TCM ↔ Register File transfer unit (ADR-0014 D1).
 
 Handles both fetch (TCM → register) and store (register → TCM).
 BW serialization is delegated to PE_TCM via port communication.
@@ -18,7 +18,7 @@ if TYPE_CHECKING:
 
 
 class PeFetchStoreComponent(PeEngineBase):
-    """PE_FETCH_STORE: TCM ↔ Register File (ADR-0021 D5).
+    """PE_FETCH_STORE: TCM ↔ Register File (ADR-0014 D1).
 
     Receives TileTokens via pipeline self-routing.
     Sends TcmRequest to PE_TCM for BW-based latency.

src/kernbench/components/builtin/pe_gemm.py

@@ -1,4 +1,4 @@
-"""PE_GEMM: matrix multiplication engine (ADR-0021 D6).
+"""PE_GEMM: matrix multiplication engine (ADR-0014 D1).
 
 Handles both legacy PeInternalTxn (GemmCmd) and pipeline TileToken.
 In pipeline mode, receives token after fetch stage, computes MAC, chains to next.
@@ -32,7 +32,7 @@ _DTYPE_BITS: dict[str, int] = {
 
 
 class PeGemmComponent(PeEngineBase):
-    """PE_GEMM: MAC array (ADR-0021 D6).
+    """PE_GEMM: MAC array (ADR-0014 D1).
 
     In pipeline mode: pure compute — register data already fetched.
     In legacy mode: handles PeInternalTxn(GemmCmd) with shared accel_slot.

src/kernbench/components/builtin/pe_math.py

@@ -1,4 +1,4 @@
-"""PE_MATH: element-wise / reduction computation engine (ADR-0021 D6).
+"""PE_MATH: element-wise / reduction computation engine (ADR-0014 D1).
 
 Handles both legacy PeInternalTxn (MathCmd) and pipeline TileToken.
 In pipeline mode, receives token after fetch stage, computes SIMD, chains to next.
@@ -24,7 +24,7 @@ if TYPE_CHECKING:
 
 
 class PeMathComponent(PeEngineBase):
-    """PE_MATH: SIMD/Vector unit (ADR-0021 D6).
+    """PE_MATH: SIMD/Vector unit (ADR-0014 D1).
 
     In pipeline mode: pure compute — register data already fetched.
     In legacy mode: handles PeInternalTxn(MathCmd) with shared accel_slot.

src/kernbench/components/builtin/pe_scheduler.py

@@ -1,10 +1,10 @@
-"""PE_SCHEDULER: plan generation + tile dispatch (ADR-0021 D2).
+"""PE_SCHEDULER: plan generation + tile dispatch (ADR-0014 D6).
 
 Receives PeInternalTxn from PE_CPU, routes to engines:
   - Simple commands (DmaReadCmd, GemmCmd, etc.) → direct dispatch to engine
   - CompositeCmd → generate TilePlan, feed tiles via _feed_loop
 
-Composite pipeline uses token self-routing (ADR-0021 D4):
+Composite pipeline uses token self-routing (ADR-0014 D6):
   Scheduler only does initial dispatch + completion tracking.
   Tiles chain through components based on their plan's stage sequence.
 """
@@ -24,7 +24,7 @@ if TYPE_CHECKING:
 
 
 class PeSchedulerComponent(ComponentBase):
-    """PE_SCHEDULER: sole dispatcher inside a PE (ADR-0014 D1, ADR-0021 D2).
+    """PE_SCHEDULER: sole dispatcher inside a PE (ADR-0014 D1, D6).
 
     Simple commands are forwarded to the appropriate engine.
     CompositeCmd creates a TilePlan and feeds tiles into the pipeline.
@@ -104,7 +104,7 @@ class PeSchedulerComponent(ComponentBase):
     def _dispatch_composite(
         self, env: simpy.Environment, pe_txn: Any, cmd: Any,
     ) -> Generator:
-        """Generate plan and enqueue to feeder. Non-blocking (ADR-0021 D4)."""
+        """Generate plan and enqueue to feeder. Non-blocking (ADR-0014 D6)."""
         from kernbench.components.builtin.pe_types import PipelineContext
 
         plan = self._generate_plan(cmd)
@@ -121,7 +121,7 @@ class PeSchedulerComponent(ComponentBase):
         yield self._pending_feeds.put((plan, ctx))
 
     def _feed_loop(self, env: simpy.Environment) -> Generator:
-        """Single feeder process: FIFO command ordering (ADR-0021 D2).
+        """Single feeder process: FIFO command ordering (ADR-0014 D6).
 
         No tile feed interleaving between commands.
         Queue full → only this process blocks.

src/kernbench/components/builtin/pe_tcm.py

@@ -1,4 +1,4 @@
-"""PE_TCM: tightly-coupled memory with BW-based access serialization (ADR-0021).
+"""PE_TCM: tightly-coupled memory with BW-based access serialization (ADR-0014 D1).
 
 Models scratchpad memory inside the PE. Handles both legacy Transaction forwarding
 and TcmRequest from PE_FETCH_STORE for BW-serialized read/write access.
@@ -32,7 +32,7 @@ class TcmRequest:
 
 
 class PeTcmComponent(ComponentBase):
-    """PE_TCM: BW-serialized scratchpad memory (ADR-0021 D1).
+    """PE_TCM: BW-serialized scratchpad memory (ADR-0014 D1).
 
     Dual-channel: read and write can proceed in parallel,
     but concurrent reads serialize, concurrent writes serialize.

src/kernbench/components/builtin/pe_types.py

@@ -1,4 +1,4 @@
-"""PE pipeline types for ADR-0021: TileToken, TilePlan, Stage, PipelineContext.
+"""PE pipeline types for ADR-0014 D6: TileToken, TilePlan, Stage, PipelineContext.
 
 These types are used by the PE_SCHEDULER and all PE engine components
 for tile-based pipeline execution with self-routing.
@@ -84,7 +84,7 @@ class PipelineContext:
 
 @dataclass
 class TileToken:
-    """Self-routing tile token passed between PE components (ADR-0021 D9).
+    """Self-routing tile token passed between PE components (ADR-0014 D6).
 
     Single-owner: only one component holds this token at any time.
     params is a cache of plan.stages[stage_idx].params (canonical source).

src/kernbench/components/builtin/tiling.py

@@ -1,4 +1,4 @@
-"""Tile plan generators for PE pipeline (ADR-0021).
+"""Tile plan generators for PE pipeline (ADR-0014 D6).
 
 Generates TilePlan with stage sequences for GEMM and Math operations.
 Ported from pe_accel tiling.py with stage-based plan structure.

src/kernbench/components/legacy/__init__.py

@@ -1,2 +1,2 @@
 # Legacy component backups — not actively used.
-# Kept for reference during ADR-0021 migration.
+# Kept for reference during the PE pipeline refactor (ADR-0014).

src/kernbench/components/legacy/builtin/m_cpu.py

@@ -264,8 +264,9 @@ class MCpuComponent(ComponentBase):
     def _resolve_dma_destinations(self, request: Any, target_pe: int | str) -> list[str]:
         """Return list of HBM destination node_ids for DMA fan-out.
 
-        With single hbm_ctrl per cube (ADR-0019), always returns one node.
-        PA-based resolution still used for cross-cube routing.
+        The PA-based resolver maps each address to one per-PE
+        ``hbm_ctrl.pe{X}`` (ADR-0017 D9), so this method returns exactly
+        one node. Cross-cube routing uses the same resolution.
         """
         cube_prefix = self.node.id.rsplit(".", 1)[0]  # e.g. "sip0.cube0"