# Claude Code Instructions (Repo)

This repository uses Claude Code with strict architectural and verification rules.
SPEC.md and ADRs are the source of truth.

---

## 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.).

## 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

- Design / architecture questions are ALWAYS allowed.
- Design questions MUST NOT modify:
  - production code
  - test code
  - SPEC.md
  - ADRs
- If a design question implies a change, default to Phase 1.

---

## Change & Test Protocol (Mandatory)

All non-trivial changes MUST follow a two-phase process.
Design discussion is always allowed; code changes are not.

---

### Phase 1 — Proposal + Verification

(No Production Code Changes)

#### Purpose

- Decide *what* to change and *how it will be validated*
- Establish verification coverage BEFORE touching production code

#### Phase 1 MUST include

1) **Design Proposal**

- Explain the design change.
- Explain why the change is needed.
- Explain consistency with SPEC.md and relevant ADRs.

1) **Verification Plan**

- SPEC requirement(s) / ADR(s) affected (e.g., R1/R2/R5, ADR-0002).
- Tests that validate the change:
  - existing tests to run, and/or
  - new tests to add.
- Concrete input cases used by the tests:
  - topology (SIP / CUBE / PE layout)
  - request parameters (src, dst, size_bytes).
- Expected observable assertions, such as:
  - hop trace contains key waypoints,
  - latency invariants (e.g., > 0, monotonic increase),
  - deterministic route selection.
  - **expected changes (or no changes) in generated diagrams**, if applicable.

If the Verification Plan is missing or vague, STOP.

#### Allowed in Phase 1

- Creating or modifying **test code only**
- Running tests and reporting results

#### Forbidden in Phase 1

- Any production code changes
- Any SPEC.md or ADR modifications
- Any production diff output

#### Phase 1 Output

- Proposal + Verification Plan
- Tests added/modified (if any)
- Test execution results (PASS / FAIL)
- Clear recommendation:
  - "No Phase 2 needed" OR
  - "Await approval for Phase 2"

---

### Phase 2 — Apply + Verify + Rollback

#### Trigger

Phase 2 is triggered ONLY by the exact user approval phrase:

**"ok"**

#### Phase 2 Rules

- Output **minimal unified diffs only**
- Modify ONLY production files declared in Phase 1
- Do NOT include explanations, comments, or unchanged code
- Automatically apply the diff to the working tree

#### Mandatory Verification

- Run the tests defined in the Phase 1 Verification Plan

#### Success Path

If ALL tests PASS:

- Keep the applied changes
- Ensure generated diagrams (if affected) are consistent
- Report success concisely

#### Failure Path (Mandatory)

If ANY test FAILS:

- Immediately rollback ALL Phase 2 changes
- Do NOT keep partial changes
- Report:
  - failing test names
  - error messages / assertions
  - brief hypothesis of the root cause
- Return to Phase 1 state

Tests must NEVER be weakened, removed, or altered to force Phase 2 to pass.

---

## What Counts as "Non-Trivial"

(Protocol Required)

Any of the following:

- routing policy or ordering changes
- topology builder changes (nodes, links, parameters)
- address decoding / PhysAddr behavior
- latency composition rules
- changes affecting determinism or connectivity
- changes touching two or more production files

---

## 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."**

---

## CLI Semantics

- `kernbench run --device <id>` runs the benchmark on a single device.
- Omitting `--device` runs the benchmark on all devices discovered in the topology (logically parallel).
- Device enumeration is handled by the CLI only; benchmarks MUST remain single-device.

## Derived Artifacts (Clarification)

- Generated diagrams under `docs/diagrams/` are **derived artifacts**, not production code.
- Creating or updating files in `docs/diagrams/`:
  - does NOT count as a production code change,
  - does NOT require Phase 2 approval,
  - MUST be consistent with SPEC.md and ADRs.

## Enforcement Defaults

- 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).