Add: paged attention unroll scene test with 4D input shapes

.claude/lib/github/README.md

@@ -8,10 +8,10 @@ Reusable procedures for GitHub PR workflows.
 | --------- | ----------- | ------- |
 | [setup](setup.md) | Authenticate and detect repository context | All |
 | [lookup-pr](lookup-pr.md) | Find PR by number, branch, or list all | All |
-| [detect-permission](detect-permission.md) | Check push access to PR | address-pr-comments |
-| [commit-and-push](commit-and-push.md) | Squash commits, rebase, and push | github-pr, address-pr-comments |
-| [fetch-comments](fetch-comments.md) | Get unresolved PR review comments | address-pr-comments |
-| [reply-and-resolve](reply-and-resolve.md) | Reply to and resolve review threads | address-pr-comments |
+| [detect-permission](detect-permission.md) | Check push access to PR | fix-pr |
+| [commit-and-push](commit-and-push.md) | Squash commits, rebase, and push | github-pr, fix-pr |
+| [fetch-comments](fetch-comments.md) | Get unresolved PR review comments | fix-pr |
+| [reply-and-resolve](reply-and-resolve.md) | Reply to and resolve review threads | fix-pr |
 | [branch-naming](branch-naming.md) | Generate branch name from commit | github-pr |
 | [common-issues](common-issues.md) | Troubleshooting reference | All |
 
@@ -21,9 +21,9 @@ After running `detect-context`, these variables are available:
 
 | Variable | Description | Example (owner) | Example (fork) |
 | -------- | ----------- | --------------- | -------------- |
-| `REPO_OWNER` | Origin repo owner | `ChaoWao` | `contributor` |
+| `REPO_OWNER` | Origin repo owner | `hw-native-sys` | `contributor` |
 | `REPO_NAME` | Origin repo name | `simpler` | `simpler` |
-| `PR_REPO_OWNER` | PR target owner | `ChaoWao` | `ChaoWao` |
+| `PR_REPO_OWNER` | PR target owner | `hw-native-sys` | `hw-native-sys` |
 | `PR_REPO_NAME` | PR target name | `simpler` | `simpler` |
 | `DEFAULT_BRANCH` | Base branch name | `main` | `main` |
 | `BASE_REF` | Full base ref | `origin/main` | `upstream/main` |

.claude/lib/github/common-issues.md

@@ -49,7 +49,7 @@ Do NOT use `-f`/`-F` flags to pass GraphQL `$variables`. Bash mangles `$` signs
 
 ```bash
 # BAD — $owner/$repo/$number clash with bash
-gh api graphql -f owner="ChaoWao" -f repo="simpler" -F number=276 \
+gh api graphql -f owner="hw-native-sys" -f repo="simpler" -F number=276 \
   -f query='query($owner: String!, $repo: String!, $number: Int!) { ... }'
 
 # GOOD — inline values, no variables

.claude/lib/github/detect-permission.md

@@ -1,6 +1,6 @@
 # Detect Permission
 
-Used by `address-pr-comments` when working on someone else's PR. Determines push access and overrides `PUSH_REMOTE` if needed.
+Used by `fix-pr` when working on someone else's PR. Determines push access and overrides `PUSH_REMOTE` if needed.
 
 ## Fetch PR Metadata
 
@@ -62,4 +62,4 @@ esac
 
 ## Cleanup After Push
 
-Do NOT remove the fork remote — it is reused by upstream tracking for auto-detection in `/github-pr` and `/address-pr-comments`.
+Do NOT remove the fork remote — it is reused by upstream tracking for auto-detection in `/github-pr` and `/fix-pr`.

.claude/lib/github/fetch-comments.md

@@ -33,7 +33,7 @@ query {
 }'
 ```
 
-Replace `OWNER`, `REPO`, `NUMBER` with actual values (e.g., `"ChaoWao"`, `"simpler"`, `276`).
+Replace `OWNER`, `REPO`, `NUMBER` with actual values (e.g., `"hw-native-sys"`, `"simpler"`, `276`).
 
 Use `--jq` to filter unresolved threads:
 
@@ -43,9 +43,11 @@ gh api graphql -f query='...' \
 ```
 
 **Limits:**
+
 - `reviewThreads(first: 100)`: Fetches up to 100 threads.
 - `comments(first: 50)`: Fetches up to 50 comments per thread.
 
 Output: JSON array of unresolved threads. Each thread has:
+
 - `id` — GraphQL node ID (for resolving via mutation)
 - `comments.nodes[].databaseId` — REST API ID (for replying)

.claude/lib/github/setup.md

@@ -17,7 +17,7 @@ Detects repository role, remotes, and current state. Sets standard variables use
 ### Canonical Repo
 
 ```bash
-UPSTREAM_OWNER="ChaoWao"
+UPSTREAM_OWNER="hw-native-sys"
 UPSTREAM_NAME="simpler"
 UPSTREAM_REPO="$UPSTREAM_OWNER/$UPSTREAM_NAME"
 DEFAULT_BRANCH="main"
@@ -90,7 +90,7 @@ fi
 | `ROLE` | `"owner"` | `"fork"` |
 | `BASE_REF` | `upstream/main` | `upstream/main` |
 | `PUSH_REMOTE` | `origin` | `origin` |
-| `PR_REPO_OWNER` | `ChaoWao` | `ChaoWao` |
+| `PR_REPO_OWNER` | `hw-native-sys` | `hw-native-sys` |
 | `PR_REPO_NAME` | `simpler` | `simpler` |
 | `PR_HEAD_PREFIX` | `""` | `"myuser:"` |
 | `DEFAULT_BRANCH` | `main` | `main` |

.claude/rules/architecture.md

@@ -1,25 +1,36 @@
 # Architecture Quick Reference
 
-See [docs/architecture.md](../../docs/architecture.md) for the full diagram, API layers, execution flow, and handshake protocol.
+See [docs/chip-level-arch.md](../../docs/chip-level-arch.md) for the full diagram, API layers, execution flow, and handshake protocol. See [docs/distributed_level_runtime.md](../../docs/distributed_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 data flow through the hierarchical runtime.
 
 ## Key Concepts
 
 - **Three programs**: Host `.so`, AICPU `.so`, AICore `.o` — compiled independently, linked at runtime
 - **Three runtimes** under `src/{arch}/runtime/`: `host_build_graph`, `aicpu_build_graph`, `tensormap_and_ringbuffer`
 - **Two platform backends** under `src/{arch}/platform/`: `onboard/` (hardware), `sim/` (simulation)
 
+## Python Package Layout
+
+| Package | Source | What's in wheel | Use for |
+| ------- | ------ | --------------- | ------- |
+| `simpler` | `python/simpler/` | `task_interface`, `worker`, `env_manager` only | Stable user API at runtime |
+| `simpler_setup` | `simpler_setup/` | All files + `_assets/{src,build/lib}` | Test framework, compilers, path resolution |
+| `_task_interface` | `python/bindings/` | nanobind `.so` at wheel root | Internal nanobind module |
+
+The 4 files `kernel_compiler.py`, `runtime_compiler.py`, `toolchain.py`, `elf_parser.py` exist in **both** `python/simpler/` and `simpler_setup/` during transition. The `simpler_setup/` copies are authoritative; the `python/simpler/` copies are excluded from wheel via `pyproject.toml::wheel.exclude`. New code must `import` from `simpler_setup.*`, not `simpler.*`, for these four.
+
 ## Build System Lookup
 
 | What | Where |
 | ---- | ----- |
 | Runtime selection | `kernel_config.py` → `RUNTIME_CONFIG.runtime` |
 | Per-runtime build config | `src/{arch}/runtime/{runtime}/build_config.py` |
-| Runtime build orchestration | `examples/scripts/runtime_builder.py` → `runtime_compiler.py` → cmake |
+| Runtime build orchestration | `simpler_setup/runtime_builder.py` → `simpler_setup/runtime_compiler.py` → cmake |
 | Pre-build all runtimes | `examples/scripts/build_runtimes.py` (invoked by `pip install .`) |
-| Platform/runtime discovery | `examples/scripts/platform_info.py` |
-| Kernel compilation | `python/kernel_compiler.py` (one `.cpp` per `func_id`) |
+| Platform/runtime discovery | `simpler_setup/platform_info.py` |
+| Kernel compilation | `simpler_setup/kernel_compiler.py` (one `.cpp` per `func_id`) |
 | Python bindings | `python/bindings/` (nanobind extension for ChipWorker, task types) |
-| Pre-built binary lookup | `build/lib/{arch}/{variant}/{runtime}/` |
+| Path resolution (wheel vs source tree) | `simpler_setup/environment.py::PROJECT_ROOT` |
+| Pre-built binary lookup | `build/lib/{arch}/{variant}/{runtime}/` (source tree) or `simpler_setup/_assets/build/lib/...` (wheel) |
 | Persistent cmake cache | `build/cache/{arch}/{variant}/{runtime}/` |
 
 ## Example / Test Layout

.claude/rules/venv-isolation.md

@@ -27,9 +27,15 @@ Multiple AI agents may work on this repo concurrently (parallel sessions, worktr
 3. **Install the project**:
 
    ```bash
-   pip install .
+   # Production / CI install
+   pip install --no-build-isolation .
+
+   # Editable install for development (auto-rebuilds C++ on import)
+   pip install --no-build-isolation -e .
    ```
 
+   `--no-build-isolation` is required because scikit-build-core consumes the venv's already-installed `scikit-build-core`, `nanobind`, and `cmake` directly. Without the flag, pip spins up a temporary isolated build env that doesn't see them, slowing the install and risking version drift.
+
 4. **Run tests / examples** inside the activated venv.
 
 ### Worktree Scenario
@@ -42,7 +48,7 @@ When working in a git worktree (`.claude/worktrees/` or any other worktree path)
 # First time in a directory (or worktree)
 python3 -m venv --system-site-packages .venv
 source .venv/bin/activate
-pip install .
+pip install --no-build-isolation .            # or: -e . for editable
 
 # Subsequent runs — just activate
 source .venv/bin/activate
@@ -53,3 +59,4 @@ source .venv/bin/activate
 - Run `pip install .` without an activated local venv
 - Share a single venv across multiple worktrees
 - Use `--user` installs as a substitute for venv isolation
+- Drop `--no-build-isolation` — scikit-build-core needs the venv's `nanobind`/`cmake` directly

.claude/skills/checkout-pr/SKILL.md

@@ -62,11 +62,10 @@ Run [checkout-fork-branch](../../lib/github/checkout-fork-branch.md) with `PUSH_
 
 Print summary:
 
-```
-Checked out PR #$PR_NUMBER ($PR_AUTHOR)
+```text
   Remote: $FORK_REMOTE -> git@github.com:$HEAD_REPO_OWNER/$HEAD_REPO_NAME.git
   Branch: $LOCAL_BRANCH -> $FORK_REMOTE/$HEAD_BRANCH
   Push:   PUSH_REMOTE=$FORK_REMOTE  BRANCH_NAME=$LOCAL_BRANCH:$HEAD_BRANCH
 ```
 
-Remind user that `/github-pr` and `/address-pr-comments` will pick up the correct push target automatically (via upstream tracking).
+Remind user that `/github-pr` and `/fix-pr` will pick up the correct push target automatically (via upstream tracking).

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: false
 contact_links:
   - name: General Questions & Discussions
-    url: https://github.com/ChaoWao/simpler/discussions
+    url: https://github.com/hw-native-sys/simpler/discussions
     about: For questions, ideas, or general discussion, please use GitHub Discussions

.github/workflows/ci.yml

@@ -240,10 +240,15 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Build nanobind extension
-        run: pip install .
+        run: |
+          python3 -m venv --system-site-packages .venv
+          source .venv/bin/activate
+          pip install --upgrade pip
+          pip install .
 
       - name: Run hardware unit tests (a2a3)
         run: |
+          source .venv/bin/activate
           export PATH="$HOME/.local/bin:$PATH"
           source ${ASCEND_HOME_PATH}/bin/setenv.bash && pytest tests -m requires_hardware --platform a2a3 -v
 
@@ -257,15 +262,21 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Build nanobind extension
-        run: pip install .
+        run: |
+          python3 -m venv --system-site-packages .venv
+          source .venv/bin/activate
+          pip install --upgrade pip
+          pip install .
 
       - name: Run on-device examples (a2a3)
         run: |
+          source .venv/bin/activate
           export PATH="$HOME/.local/bin:$PATH"
           source ${ASCEND_HOME_PATH}/bin/setenv.bash && python ci.py -p a2a3 -d ${DEVICE_RANGE} -c d96c8784 -t 600 --clone-protocol https
 
       - name: Run pytest scene tests (a2a3)
         run: |
+          source .venv/bin/activate
           export PATH="$HOME/.local/bin:$PATH"
           source ${ASCEND_HOME_PATH}/bin/setenv.bash && pytest examples tests/st --platform a2a3 --device ${DEVICE_RANGE} -v
 

CMakeLists.txt

@@ -36,3 +36,11 @@ add_custom_target(build_runtimes ALL
         --cache-dir ${CMAKE_SOURCE_DIR}/build/cache
     COMMENT "Building runtime binaries (incremental)..."
 )
+
+if(SKBUILD_MODE)
+    install(DIRECTORY ${CMAKE_SOURCE_DIR}/src/
+            DESTINATION simpler_setup/_assets/src)
+    install(DIRECTORY ${CMAKE_SOURCE_DIR}/build/lib/
+            DESTINATION simpler_setup/_assets/build/lib
+            OPTIONAL)
+endif()

README.md

@@ -68,16 +68,22 @@ export ASCEND_HOME_PATH=/usr/local/Ascend/ascend-toolkit/latest
 
 | Document | Description |
 | -------- | ----------- |
-| [Architecture](docs/architecture.md) | Three-program model, API layers, execution flow, handshake protocol |
+| [Chip-Level Architecture](docs/chip-level-arch.md) | L2 single-chip: three-program model (host/AICPU/AICore), API layers, handshake protocol |
+| [Distributed Level Runtime](docs/distributed_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 |
+| [Worker Manager](docs/worker-manager.md) | Worker pool, WorkerThread, THREAD/PROCESS modes, fork + mailbox mechanics |
 | [Getting Started](docs/getting-started.md) | Setup, prerequisites, build process, configuration |
 | [Developer Guide](docs/developer-guide.md) | Directory structure, role ownership, conventions |
 | [Testing Guide](docs/testing.md) | CI pipeline, test types, writing new tests |
-| **Per-arch (a2a3):** | |
-| [Runtimes](src/a2a3/docs/runtimes.md) | Runtime comparison and links to per-runtime docs |
-| [Platform](src/a2a3/docs/platform.md) | onboard vs sim, hardware requirements |
-| **Per-arch (a5):** | |
-| [Runtimes](src/a5/docs/runtimes.md) | Runtime comparison and links to per-runtime docs |
-| [Platform](src/a5/docs/platform.md) | onboard vs sim, hardware requirements |
+
+### Per-arch docs
+
+| Document | a2a3 arch | a5 arch |
+| -------- | --------- | ------- |
+| Runtimes | [a2a3/docs/runtimes.md](src/a2a3/docs/runtimes.md) | [a5/docs/runtimes.md](src/a5/docs/runtimes.md) |
+| Platform | [a2a3/docs/platform.md](src/a2a3/docs/platform.md) | [a5/docs/platform.md](src/a5/docs/platform.md) |
 
 ## License
 

ci.py

@@ -299,8 +299,9 @@ def compile_task(
 ) -> CompiledTask:
     """Compile orchestration + kernels for a single task, return CompiledTask."""
     from runtime_builder import RuntimeBuilder  # noqa: PLC0415
-    from simpler.elf_parser import extract_text_section  # noqa: PLC0415
-    from simpler.kernel_compiler import KernelCompiler  # noqa: PLC0415
+
+    from simpler_setup.elf_parser import extract_text_section  # noqa: PLC0415
+    from simpler_setup.kernel_compiler import KernelCompiler  # noqa: PLC0415
 
     # Load kernel_config and golden
     kc = _load_module(spec.kernels_dir / "kernel_config.py", f"kc_{id(spec)}")

docs/architecture.md → docs/chip-level-arch.md

@@ -1,4 +1,11 @@
-# Architecture
+# Chip-Level Architecture (L2)
+
+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 [distributed_level_runtime.md](distributed_level_runtime.md). For how task
+data (Callable / TaskArgs / CallConfig) flows through all levels, see
+[task-flow.md](task-flow.md).
 
 ## Three-Program Model
 
@@ -135,7 +142,7 @@ worker.finalize()
 ### Python Type Naming Convention
 
 Layer 3 Python types use a **level-prefixed naming convention** that mirrors the
-level model (see [Distributed Level Runtime](distributed_level_runtime.md)):
+level model (see [distributed_level_runtime.md](distributed_level_runtime.md)):
 
 | Concept | L2 (Chip) type | L3+ (Distributed) type | Unified factory |
 | ------- | -------------- | ---------------------- | --------------- |