docs(skill): place PTOAS venv inside the checkout

.agents/skills/ptoas-development/SKILL.md

@@ -17,7 +17,7 @@ build tree. Its runtime commands use this contract:
 ```bash
 export PTO_SOURCE_DIR=<workspace>/PTOAS
 export LLVM_BUILD_DIR=<workspace>/llvm-project/build-shared
-export VENV_DIR=<workspace>/.venv
+export VENV_DIR="$PTO_SOURCE_DIR/.venv"
 export PYTHON_BIN="$VENV_DIR/bin/python"
 export PTOAS_BIN="$VENV_DIR/bin/ptoas"
 export PTO_BUILD_DIR="$PTO_SOURCE_DIR/build"
@@ -26,6 +26,10 @@ export PTO_BUILD_DIR="$PTO_SOURCE_DIR/build"
 `<workspace>` is a placeholder, not a literal directory or shell syntax. Probe
 the current checkout or source its generated `env.sh` to obtain the real paths.
 
+The isolated venv lives inside the checkout at `$PTO_SOURCE_DIR/.venv` — not in
+the parent directory — so the workspace stays self-contained and a global
+`python`, `ptoas`, or conda environment is never used.
+
 For an isolated feature worktree created by `ptoas-workspace-manager`, source
 its generated `env.sh`. It is authoritative: it selects the worktree's venv,
 build tree, LLVM build, and optional CANN environment. Do not substitute a
@@ -45,9 +49,6 @@ else
   : "${PTO_BUILD_DIR:=$PTO_SOURCE_DIR/build}"
   if [[ -z "${PYTHON_BIN:-}" && -x "$PTO_SOURCE_DIR/.venv/bin/python" ]]; then
     PYTHON_BIN="$PTO_SOURCE_DIR/.venv/bin/python"
-  elif [[ -z "${PYTHON_BIN:-}" && -x "$(dirname "$PTO_SOURCE_DIR")/.venv/bin/python" ]]; then
-    # This is the standard layout in the repository README.
-    PYTHON_BIN="$(dirname "$PTO_SOURCE_DIR")/.venv/bin/python"
   fi
   if [[ -n "${PYTHON_BIN:-}" ]]; then
     VENV_DIR="$(dirname "$(dirname "$PYTHON_BIN")")"
@@ -99,16 +100,15 @@ adding a global shell setting by default.
 ## Initialize or repair PTOAS
 
 Use this path after resolving a compatible LLVM build and the Python intended
-for the workspace. For a normal checkout, create it at the workspace root
-(`$PTO_SOURCE_DIR/../.venv`), as in the repository README; manager-owned
-worktrees already have one.
+for the workspace. For a normal checkout, create it inside the checkout at
+`$PTO_SOURCE_DIR/.venv`; manager-owned worktrees already have one there.
 
 ```bash
 test -d "$LLVM_BUILD_DIR/lib/cmake/llvm"
 test -d "$LLVM_BUILD_DIR/lib/cmake/mlir"
 
 if [[ -z "${PYTHON_BIN:-}" ]]; then
-  VENV_DIR="$(dirname "$PTO_SOURCE_DIR")/.venv"
+  VENV_DIR="$PTO_SOURCE_DIR/.venv"
   python3 -m venv "$VENV_DIR"
   PYTHON_BIN="$VENV_DIR/bin/python"
 fi

README.md

@@ -60,9 +60,15 @@ export PTO_SOURCE_DIR=$WORKSPACE_DIR/PTOAS
 # 创建工作目录
 mkdir -p $WORKSPACE_DIR
 
+# 先拉取 PTOAS 源码：venv 将创建在 PTOAS 工作区内（$PTO_SOURCE_DIR/.venv），
+# 保持工作区自包含，所以需要先有 $PTO_SOURCE_DIR 目录。
+cd $WORKSPACE_DIR
+git clone https://github.com/hw-native-sys/PTOAS.git PTOAS
+cd $PTO_SOURCE_DIR
+
 # 推荐使用独立虚拟环境。后续 LLVM 和 PTOAS 构建必须使用同一个 Python。
-python3 -m venv "$WORKSPACE_DIR/.venv"
-source "$WORKSPACE_DIR/.venv/bin/activate"
+python3 -m venv "$PTO_SOURCE_DIR/.venv"
+source "$PTO_SOURCE_DIR/.venv/bin/activate"
 export PYTHON_BIN="$(command -v python3)"
 
 ```
@@ -118,12 +124,10 @@ ninja -C $LLVM_BUILD_DIR
 
 ### 3.3 第二步：构建 PTOAS (Out-of-Tree)
 
-下载 PTOAS 源码并基于刚刚编译好的 LLVM 19 进行构建。
+PTOAS 源码已在 3.0 拉取，基于刚刚编译好的 LLVM 19 进行构建。
 
 ```bash
-# 1. 下载 PTOAS 源码
-cd $WORKSPACE_DIR
-git clone https://github.com/hw-native-sys/PTOAS.git PTOAS
+# 1. 进入 PTOAS 源码目录（3.0 已 clone）
 cd $PTO_SOURCE_DIR
 
 # 2. 安装到当前 Python 环境，并保留可增量构建的 build tree
@@ -197,7 +201,7 @@ Python 环境。editable 安装会将选定 LLVM 构建目录记录为 native ex
 
 ```bash
 # 先重新导出 WORKSPACE_DIR、LLVM_BUILD_DIR 等 3.0 中的路径变量
-source "$WORKSPACE_DIR/.venv/bin/activate"
+source "$PTO_SOURCE_DIR/.venv/bin/activate"
 export PYTHON_BIN="$(command -v python3)"
 
 command -v ptoas

README_en.md

@@ -59,9 +59,16 @@ export PTO_SOURCE_DIR=$WORKSPACE_DIR/PTOAS
 # Create the workspace directory
 mkdir -p $WORKSPACE_DIR
 
+# Clone PTOAS first: the venv lives inside the PTOAS checkout
+# ($PTO_SOURCE_DIR/.venv) to keep the workspace self-contained, so
+# $PTO_SOURCE_DIR must exist before creating it.
+cd $WORKSPACE_DIR
+git clone https://github.com/hw-native-sys/PTOAS.git PTOAS
+cd $PTO_SOURCE_DIR
+
 # Use an isolated environment. LLVM and PTOAS must use the same Python.
-python3 -m venv "$WORKSPACE_DIR/.venv"
-source "$WORKSPACE_DIR/.venv/bin/activate"
+python3 -m venv "$PTO_SOURCE_DIR/.venv"
+source "$PTO_SOURCE_DIR/.venv/bin/activate"
 export PYTHON_BIN="$(command -v python3)"
 ```
 
@@ -112,12 +119,11 @@ ninja -C $LLVM_BUILD_DIR
 
 ### 3.3 Step 2: Build PTOAS (Out-of-Tree)
 
-Clone the PTOAS source and build against the LLVM 19 you just compiled.
+PTOAS was already cloned in section 3.0; build it against the LLVM 19 you
+just compiled.
 
 ```bash
-# 1. Clone PTOAS
-cd $WORKSPACE_DIR
-git clone https://github.com/hw-native-sys/PTOAS.git PTOAS
+# 1. Enter the PTOAS source directory (cloned in section 3.0)
 cd $PTO_SOURCE_DIR
 
 # 2. Install into the current Python environment while keeping a persistent,
@@ -189,7 +195,7 @@ directory to the runtime library search path:
 
 ```bash
 # Re-export WORKSPACE_DIR, LLVM_BUILD_DIR, and the other paths from section 3.0.
-source "$WORKSPACE_DIR/.venv/bin/activate"
+source "$PTO_SOURCE_DIR/.venv/bin/activate"
 export PYTHON_BIN="$(command -v python3)"
 export LD_LIBRARY_PATH="$LLVM_BUILD_DIR/lib:${LD_LIBRARY_PATH:-}"