CLAUDE.md: restructure into Part 1 (general) / Part 2 (project-specific)

- Reorganize rules into reusable general behavior vs kernbench-specific
  foundations + rules
- Add Surfacing Choices, Coding Style (Simplicity First, Surgical Changes),
  Mental Model, Common Failure Modes
- Clarify Phase 1 forbidden vs permitted-for-discussion (pseudocode,
  sketches allowed; final ready-to-apply diffs are Phase 2 only)
- Tighten dead-code handling: mention + options before deletion
- Drop redundant "SPEC.md and ADRs are the final authority" from
  Enforcement Defaults (already in Authority & Scope)

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

CLAUDE.md

@@ -5,27 +5,10 @@ SPEC.md and ADRs are the source of truth.
 
 ---
 
-## Terminology
+# Part 1 — General Behavior
 
-- runtime API:
+> Reusable across repos. Describes *how* Claude Code interacts with the user
-  Host-facing public API used by benchmarks and user code (e.g., tensor deployment, kernel launch).
+> and constructs changes, independent of this project's domain.
-- simulation engine (sim_engine):
-  Discrete-event engine responsible for request injection, scheduling, and completion tracking.
-- components:
-  Device-side nodes modeling hardware behavior (IO_CPU, M_CPU, PE_CPU, routers, engines, etc.).
-
-## Authority & Scope
-
-- SPEC.md defines the architectural contract.
-- ADRs (docs/adr/ADR-*.md) define non-trivial architectural decisions.
-- If a change conflicts with SPEC.md or an ADR:
-  - STOP.
-  - Explain the conflict.
-  - Propose options (keep spec, update ADR, or narrow scope).
-- Do NOT silently change architecture.
-- The repository structure reflects architectural intent; Claude Code MUST respect existing module boundaries and file locations.
-
----
 
 ## Design Questions
 
@@ -37,14 +20,21 @@ SPEC.md and ADRs are the source of truth.
   - ADRs
 - If a design question implies a change, default to Phase 1.
 
----
+## Surfacing Choices
+
+Applies to both design discussions and Phase 1 proposals.
+
+- If multiple valid interpretations of the request exist, present them.
+  Do NOT pick one silently.
+- If a simpler approach exists, say so. Push back when warranted —
+  do NOT just implement the more complex path the user proposed.
+- State required assumptions explicitly. If uncertain, ask before assuming.
 
 ## Change & Test Protocol (Mandatory)
 
 All non-trivial changes MUST follow a two-phase process.
-Design discussion is always allowed; code changes are not.
+Design discussion is always allowed.
-
+Production code changes require Phase 1 approval before Phase 2 applies them.
----
 
 ### Phase 1 — Proposal + Verification
 
@@ -63,20 +53,18 @@ Design discussion is always allowed; code changes are not.
 - Explain why the change is needed.
 - Explain consistency with SPEC.md and relevant ADRs.
 
-1) **Verification Plan**
+2) **Verification Plan**
 
-- SPEC requirement(s) / ADR(s) affected (e.g., R1/R2/R5, ADR-0002).
+- SPEC requirement(s) / ADR(s) affected.
 - Tests that validate the change:
   - existing tests to run, and/or
   - new tests to add.
-- Concrete input cases used by the tests:
+- Concrete input cases used by the tests.
-  - topology (SIP / CUBE / PE layout)
+- Expected observable assertions.
-  - request parameters (src, dst, size_bytes).
+- Expected changes (or no changes) in generated artifacts, if applicable.
-- Expected observable assertions, such as:
+
-  - hop trace contains key waypoints,
+(Project-specific expectations for what these inputs/assertions look like:
-  - latency invariants (e.g., > 0, monotonic increase),
+see Part 2 → *Verification Plan — Project Expectations*.)
-  - deterministic route selection.
-  - **expected changes (or no changes) in generated diagrams**, if applicable.
 
 If the Verification Plan is missing or vague, STOP.
 
@@ -89,7 +77,13 @@ If the Verification Plan is missing or vague, STOP.
 
 - Any production code changes
 - Any SPEC.md or ADR modifications
-- Any production diff output
+- Final, ready-to-apply unified diffs (Phase 2 only)
+
+#### Permitted for design discussion
+
+- Pseudocode, interface sketches, type signatures
+- Small illustrative snippets to clarify a design point
+- "Before / after" excerpts (not full diffs)
 
 #### Phase 1 Output
 
@@ -100,8 +94,6 @@ If the Verification Plan is missing or vague, STOP.
   - "No Phase 2 needed" OR
   - "Await approval for Phase 2"
 
----
-
 ### Phase 2 — Apply + Verify + Rollback
 
 #### Trigger
@@ -112,10 +104,10 @@ Phase 2 is triggered ONLY by the exact user approval phrase:
 
 #### Phase 2 Rules
 
-- Output **minimal unified diffs only**
+- Keep changes minimal and scoped to the approved Phase 1 proposal.
-- Modify ONLY production files declared in Phase 1
+- Modify only production files declared in Phase 1.
-- Do NOT include explanations, comments, or unchanged code
+- Avoid unrelated edits, cleanup, or formatting churn.
-- Automatically apply the diff to the working tree
+- Automatically apply approved changes to the working tree.
 
 #### Mandatory Verification
 
@@ -126,7 +118,7 @@ Phase 2 is triggered ONLY by the exact user approval phrase:
 If ALL tests PASS:
 
 - Keep the applied changes
-- Ensure generated diagrams (if affected) are consistent
+- Ensure generated artifacts (if affected) are consistent
 - Report success concisely
 
 #### Failure Path (Mandatory)
@@ -143,8 +135,142 @@ If ANY test FAILS:
 
 Tests must NEVER be weakened, removed, or altered to force Phase 2 to pass.
 
+Failing tests may indicate:
+- invalid assumptions,
+- architectural violations,
+- or incomplete modeling.
+
+Do not assume the test is wrong without explicit evidence.
+
+## Allowed Exceptions
+
+(Protocol Still Required)
+
+- comments or docstrings
+- formatting-only changes
+- type annotation changes with no runtime behavior change
+
+In exceptions, Phase 1 MUST explicitly state:
+**"No behavior change; tests unchanged."**
+
+## Coding Style
+
+Applies to all production code changes (Phase 2) and test code (Phase 1).
+The Phase 1/2 protocol decides *whether* and *what* to change;
+this section decides *how* the resulting diff should look.
+
+### Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- Write the minimum code that satisfies the Phase 1 proposal.
+- No abstractions for single-use code.
+- No "flexibility"/"configurability" not declared in Phase 1.
+- No error handling for impossible scenarios.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+### Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+- Touch only files declared in the Phase 1 proposal.
+- Don't "improve" adjacent code, comments, or formatting.
+- Match existing style in the file, even if you'd do it differently.
+- If your changes orphan imports/variables/functions, remove them.
+- If you notice pre-existing dead code, do NOT delete it silently.
+  Mention it, and present options:
+    (a) delete (with approval),
+    (b) keep as-is,
+    (c) refactor to make it reachable / repurposed.
+  Let the user choose before acting.
+- Every changed line must trace to the Phase 1 proposal.
+
+## Enforcement Defaults
+
+General fallbacks. Apply to anything not explicitly covered above.
+
+- If unsure whether a change is non-trivial → treat it as non-trivial.
+- If unsure whether Phase 2 is allowed → STOP and ask.
+
 ---
 
+# Part 2 — Project-Specific (kernbench)
+
+> Specific to this repo's domain (SIP/CUBE/PE topology, runtime API, sim_engine).
+> Replace this entire Part when adapting the framework to another repo.
+>
+> Contains **foundations** (Authority & Scope → Terminology → Mental Model →
+> Common Failure Modes) followed by **rules** (Non-Trivial, Verification Plan,
+> CLI, Derived Artifacts, runtime API / sim_engine Boundaries).
+
+## Authority & Scope
+
+- SPEC.md defines the architectural contract.
+- ADRs (docs/adr/ADR-*.md) define non-trivial architectural decisions.
+- If a change conflicts with SPEC.md or an ADR:
+  - STOP.
+  - Explain the conflict.
+  - Propose options (keep spec, update ADR, or narrow scope).
+- Do NOT silently change architecture.
+- The repository structure reflects architectural intent; Claude Code MUST respect existing module boundaries and file locations.
+
+## Terminology
+
+- runtime API:
+  Host-facing public API used by benchmarks and user code (e.g., tensor deployment, kernel launch).
+- simulation engine (sim_engine):
+  Discrete-event engine responsible for request injection, scheduling, and completion tracking.
+- components:
+  Device-side nodes modeling hardware behavior (IO_CPU, M_CPU, PE_CPU, routers, engines, etc.).
+
+## Mental Model
+
+The simulator is layered along **request flow**:
+
+  runtime API           (host-facing: tensor ops, kernel launch;
+                         topology-agnostic, no routing — ADR-0007)
+       ↓
+  sim_engine            (schedules events, routes requests,
+                         tracks completion via correlation IDs)
+       ↓
+  components            (device-side nodes: IO_CPU, M_CPU, PE_CPU,
+                         routers, engines — model HW behavior
+                         including interconnect)
+
+Configuration & decisions (orthogonal to request flow):
+- **topology**  — compiled at config time (ADR-0006); defines which
+  components exist and how they connect. Authoritative graph for sim_engine.
+- **policy** (routing / address / placement) — consulted by sim_engine
+  during request handling.
+
+Invariant: all latency arises from **explicit scheduled events on modeled
+components and links** (SPEC §0.1, R8). No implicit waits, no magic delays.
+
+Stay within layer boundaries; do not collapse or bypass for convenience.
+
+## Common Failure Modes
+
+Anti-patterns that violate the Mental Model or Golden Invariants (SPEC §0.1).
+If your change does any of these, STOP and reconsider.
+
+- **runtime topology mutation** — topology is compiled at config time; do not
+  add/remove nodes or edges during simulation (ADR-0006).
+- **nondeterministic iteration order** — never iterate sets, unordered dicts,
+  or anything else with implementation-defined order on the critical path.
+  Determinism is required (SPEC §0.1).
+- **routing policy inside runtime API** — runtime API is topology-agnostic;
+  routing/fan-out belongs in policy + sim_engine (ADR-0007).
+- **latency modeled outside sim_engine scheduling** — every delay must come
+  from an explicit scheduled event on a modeled component or link
+  (SPEC §0.1, R8). No magic sleeps, no hardcoded constants smuggled in.
+- **hidden cross-layer coupling** — do not skip layer interfaces.
+  e.g., runtime API must not call into components directly, bypassing sim_engine.
+- **silent ADR/SPEC reinterpretation** — surface conflicts; do not paper over them.
+  See *Authority & Scope* above.
+- **weakening tests to make Phase 2 pass** — fix the code, not the test.
+  See *Part 1 → Phase 2 → Failure Path*.
+
 ## What Counts as "Non-Trivial"
 
 (Protocol Required)
@@ -158,20 +284,19 @@ Any of the following:
 - changes affecting determinism or connectivity
 - changes touching two or more production files
 
----
+## Verification Plan — Project Expectations
 
-## Allowed Exceptions
+Concrete forms that Part 1's *Verification Plan* MUST take in this repo:
 
-(Protocol Still Required)
+- SPEC requirement(s) / ADR(s) affected (e.g., R1/R2/R5, ADR-0002).
-
+- Concrete input cases:
-- comments or docstrings
+  - topology (SIP / CUBE / PE layout)
-- formatting-only changes
+  - request parameters (src, dst, size_bytes).
-- type annotation changes with no runtime behavior change
+- Expected observable assertions, such as:
-
+  - hop trace contains key waypoints,
-In exceptions, Phase 1 MUST explicitly state:
+  - latency invariants (e.g., > 0, monotonic increase),
-**"No behavior change; tests unchanged."**
+  - deterministic route selection.
-
+  - **expected changes (or no changes) in generated diagrams**, if applicable.
----
 
 ## CLI Semantics
 
@@ -187,10 +312,7 @@ In exceptions, Phase 1 MUST explicitly state:
   - does NOT require Phase 2 approval,
   - MUST be consistent with SPEC.md and ADRs.
 
-## Enforcement Defaults
+## runtime API / sim_engine Boundaries
 
-- If unsure whether a change is non-trivial → treat it as non-trivial.
-- If unsure whether Phase 2 is allowed → STOP and ask.
-- SPEC.md and ADRs are the final authority.
 - runtime API MUST NOT hardcode topology/routing or internal hop sequences.
 - sim_engine MUST remain independent of runtime API semantics (no tensor/kernel policy logic).