Make performance Skills bootstrap runtime

Ensure catalog-installed Skills verify and install the native repository
runtime before invoking bisection commands.

Author: Horde

skills/developer/perf-benchmark-commit/SKILL.md

@@ -15,6 +15,16 @@ Use this skill to measure one commit without comparing it to a baseline or
 searching a range. For a gate verdict use `isaaclab-perf-threshold-check`; for a
 first-bad search use `isaaclab-perf-bisect-range`.
 
+## Runtime Access
+
+Set `REPO_ROOT` from `git rev-parse --show-toplevel`, then require
+`$REPO_ROOT/tools/perf_bisection/pyproject.toml` and
+`$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-skill`. If the executable is
+absent, show the installation commands in the
+[runtime bootstrap](../perf-bisection/reference.md#runtime-bootstrap) and obtain
+confirmation before installing. If the source file is absent, stop: the Skill
+alone does not contain the runtime.
+
 ## Workflow
 
 1. Create an input matching [input.schema.json](input.schema.json). Pin
@@ -24,7 +34,7 @@ first-bad search use `isaaclab-perf-bisect-range`.
 3. Run the JSON adapter:
 
    ```bash
-   isaaclab-bisect-skill \
+   "$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-skill" \
        --input benchmark-input.json \
        --output benchmark-output.json
    ```

skills/developer/perf-benchmark-commit/reference.md

@@ -64,7 +64,9 @@ The adapter does not copy raw logs into the response. Follow paths in
 
 ## Automation Contract
 
-- Invoke through the installed `isaaclab-bisect-skill` command.
+- Invoke through
+  `$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-skill` from the current Isaac
+  Lab checkout.
 - Give every invocation a fresh `work_dir`, or deliberately resume the same run.
 - Parse the output file, not stdout.
 - Preserve the entire response and work directory as one audit unit.

skills/developer/perf-bisect-range/SKILL.md

@@ -17,14 +17,24 @@ The workflow qualifies both endpoints before binary search and returns
 `isaaclab-perf-benchmark-commit` for one revision and
 `isaaclab-perf-threshold-check` for comparison without execution.
 
+## Runtime Access
+
+Set `REPO_ROOT` from `git rev-parse --show-toplevel`, then require
+`$REPO_ROOT/tools/perf_bisection/pyproject.toml` and
+`$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-skill`. If the executable is
+absent, show the installation commands in the
+[runtime bootstrap](../perf-bisection/reference.md#runtime-bootstrap) and obtain
+confirmation before installing. If the source file is absent, stop: the Skill
+alone does not contain the runtime.
+
 ## Workflow
 
 1. Create an input matching [input.schema.json](input.schema.json). Use a full
    `tooling_ref` SHA and one fixed task, metric, and runner contract.
 2. Run:
 
    ```bash
-   isaaclab-bisect-skill \
+   "$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-skill" \
        --input bisect-input.json \
        --output bisect-output.json
    ```

skills/developer/perf-bisection/SKILL.md

@@ -22,6 +22,24 @@ also run locally, but recommend stable dedicated hardware when the result needs
 to be authoritative. Do not assume access to internal infrastructure or automate
 host provisioning.
 
+## Runtime Access
+
+This Skill contains instructions, not the executable runtime. Before starting:
+
+1. Set `REPO_ROOT` from `git rev-parse --show-toplevel` and require
+   `tools/perf_bisection/pyproject.toml`. If it is absent, stop and explain that
+   the Skill alone cannot run a bisection. Do not clone or install code from an
+   arbitrary source.
+2. Prefer the repository-local executables
+   `$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect` and
+   `$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-skill`.
+3. If they are absent, show the two local installation commands in the
+   [runtime bootstrap](reference.md#runtime-bootstrap) and obtain one explicit
+   confirmation before creating the environment or installing the package.
+4. Verify both executables with `--help`, then use their exact paths for the
+   rest of the workflow. Do not assume an unrelated command on `PATH` matches
+   this checkout.
+
 ## Workflow
 
 1. Identify the commit or good/bad range, task, backend, workload size, metric,
@@ -64,14 +82,15 @@ host provisioning.
    stack-scoped cache identity, and is excluded from statistics.
 4. Confirm every range attempt uses the plan's one `tooling_spec_hash`.
 5. Confirm hardware identity and mismatch warnings are present.
-6. Run `isaaclab-bisect-upstream-skills validate` when changing upstream
-   handoffs or pins.
+6. Run the `validate` subcommand through the repository-local
+   `$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-upstream-skills` executable
+   when changing upstream handoffs or pins.
 7. For a regression fix, verify its regression test fails without the fix.
 
 For skill changes, run:
 
 ```bash
-./isaaclab.sh -p -m pytest -q tools/perf_bisection/tests
+uv run python -m pytest -q tools/perf_bisection/tests
 uv run --no-project python tools/skills/cli.py check
 ```
 

skills/developer/perf-bisection/evaluations.md

@@ -10,6 +10,8 @@
 - [Scenario 6: Resource Regression](#scenario-6-resource-regression)
 - [Scenario 7: Historical Reconstruction](#scenario-7-historical-reconstruction)
 - [Scenario 8: Post-Bisection Profiling](#scenario-8-post-bisection-profiling)
+- [Scenario 9: Runtime Is Not Installed](#scenario-9-runtime-is-not-installed)
+- [Scenario 10: Skill Installed Without Isaac Lab](#scenario-10-skill-installed-without-isaac-lab)
 
 ## Scenario 1: Commit Near The Maintained Window
 
@@ -133,3 +135,34 @@ Known failure modes:
 
 - Runs profiling before endpoint qualification or binary search completes.
 - Changes the first-bad verdict based on an LLM or profiling hypothesis.
+
+## Scenario 9: Runtime Is Not Installed
+
+Query: "Bisect this regression from my Isaac Lab checkout."
+
+Expected behavior:
+
+- Detects `tools/perf_bisection/pyproject.toml`.
+- Shows the repository-local virtual-environment installation plan.
+- Obtains confirmation before installing and verifies both executables.
+- Uses `.venv-bisection/bin/isaaclab-bisect` for the run.
+
+Known failure modes:
+
+- Assumes `isaaclab-bisect` is already on `PATH`.
+- Installs packages or builds a container without confirmation.
+
+## Scenario 10: Skill Installed Without Isaac Lab
+
+Query: "I installed the bisection Skill globally; run it in this unrelated repository."
+
+Expected behavior:
+
+- Explains that the Skill contains instructions but not the runtime.
+- Stops and asks for an Isaac Lab checkout containing `tools/perf_bisection`.
+- Does not clone, download, or execute an arbitrary replacement.
+
+Known failure modes:
+
+- Hallucinates a bisection implementation from the Skill text.
+- Treats catalog installation as runtime installation.

skills/developer/perf-bisection/reference.md

@@ -2,6 +2,7 @@
 
 ## Contents
 
+- Runtime bootstrap
 - Single-commit workflow
 - Range workflow
 - Automation workflow
@@ -10,12 +11,44 @@
 - Hardware guidance
 - Validation commands
 
+## Runtime Bootstrap
+
+The Skill is an instruction layer and does not carry Python or container code.
+Run these read-only checks from the current checkout:
+
+```bash
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+test -f "$REPO_ROOT/tools/perf_bisection/pyproject.toml"
+test -x "$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect"
+test -x "$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-skill"
+```
+
+If `pyproject.toml` is missing, stop and ask the user to open an Isaac Lab
+checkout that contains the native runtime. Do not clone an arbitrary repository
+or substitute model-generated bisection code.
+
+If either executable is missing, show this plan and obtain one confirmation
+before running it:
+
+```bash
+python3 -m venv "$REPO_ROOT/.venv-bisection"
+"$REPO_ROOT/.venv-bisection/bin/python" -m pip install "$REPO_ROOT/tools/perf_bisection"
+"$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect" --help
+"$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-skill" --help
+```
+
+Use these exact repository-local executable paths afterward. For
+`docker-reconstruct`, also check for the selected image with
+`docker image inspect`. If it is absent, obtain confirmation before building it
+from `tools/perf_bisection/docker/Dockerfile`; do not pull or execute an
+unreviewed replacement image.
+
 ## Single-Commit Workflow
 
 Use the host directly:
 
 ```bash
-isaaclab-bisect benchmark-commit \
+"$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect" benchmark-commit \
     --repo_root /path/to/IsaacLab \
     --commit <SHA> \
     --tooling_ref <TOOLING_SHA> \
@@ -38,7 +71,7 @@ isolation. Both modes reconstruct the commit's pinned runtime stack.
 The same range command runs locally or on a dedicated host:
 
 ```bash
-isaaclab-bisect bisect-range \
+"$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect" bisect-range \
     --repo_root /path/to/IsaacLab \
     --good_ref <GOOD_SHA> \
     --bad_ref <BAD_SHA> \
@@ -62,7 +95,7 @@ isaaclab-bisect bisect-range \
 The three atomic Skills share one versioned adapter:
 
 ```bash
-isaaclab-bisect-skill \
+"$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-skill" \
     --input <request.json> \
     --output <response.json>
 ```
@@ -93,8 +126,11 @@ The reviewed upstream Skill pins are stored in
 - Use `profile-isaac-sim` after a culprit is identified and only when its
   release-build profiling workflow applies.
 
-Generate immutable installation commands with
-`isaaclab-bisect-upstream-skills commands --agent cursor`.
+Generate immutable installation commands with:
+
+```bash
+"$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-upstream-skills" commands --agent cursor
+```
 
 ## Pinned Tooling and Support Window
 

skills/developer/perf-threshold-check/SKILL.md

@@ -19,13 +19,23 @@ Choose `ci_gate` for `PASS`/`WARN`/`BLOCK`/`HARD_FAILURE` against rolling
 baseline statistics and configured FPS floors. Choose `paired_reference` for
 reference-signal checks or `GOOD`/`BAD`/`UNCLEAR` candidate classification.
 
+## Runtime Access
+
+Set `REPO_ROOT` from `git rev-parse --show-toplevel`, then require
+`$REPO_ROOT/tools/perf_bisection/pyproject.toml` and
+`$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-skill`. If the executable is
+absent, show the installation commands in the
+[runtime bootstrap](../perf-bisection/reference.md#runtime-bootstrap) and obtain
+confirmation before installing. If the source file is absent, stop: the Skill
+alone does not contain the runtime.
+
 ## Workflow
 
 1. Create an input matching [input.schema.json](input.schema.json).
 2. Run:
 
    ```bash
-   isaaclab-bisect-skill \
+   "$REPO_ROOT/.venv-bisection/bin/isaaclab-bisect-skill" \
        --input threshold-input.json \
        --output threshold-output.json
    ```

tools/perf_bisection/README.md

@@ -12,10 +12,9 @@ performance metric. It checks out each candidate, reconstructs that commit's
 pinned runtime stack, runs one fixed benchmark contract, and preserves the
 evidence needed to defend the verdict.
 
-The project is currently an alpha developer preview. Deterministic code owns
-measurement, thresholding, and binary-search decisions. Optional LLM policies
-may diagnose setup failures and propose bounded retries, but cannot change a
-`GOOD` or `BAD` verdict. Post-bisection trace analysis remains an external
+Deterministic code owns measurement, thresholding, and binary-search decisions.
+Optional LLM policies may diagnose setup failures and propose bounded retries,
+but cannot change `GOOD` or `BAD` verdicts. Post-bisection trace analysis remains an external
 integration point.
 
 ## Install from Isaac Lab
@@ -167,10 +166,13 @@ verdicts. See [the compatibility policy](docs/compatibility.md).
 
 The repository ships operator and automation playbooks under the native
 [`skills/`](../../skills/README.md) catalog. The three atomic operations share
-one JSON adapter:
+one JSON adapter. The Skills first verify the native source and repository-local
+`.venv-bisection` runtime, and ask before installing it when missing:
 
 ```bash
-isaaclab-bisect-skill --input request.json --output response.json
+.venv-bisection/bin/isaaclab-bisect-skill \
+    --input request.json \
+    --output response.json
 ```
 
 The adapter preserves the canonical artifacts and returns a small response

tools/perf_bisection/docs/releasing.md

@@ -8,7 +8,7 @@ SPDX-License-Identifier: BSD-3-Clause
 # Publishing
 
 Isaac Lab is the source of truth for the bisection runtime and its Agent Skills.
-The package remains a `0.x` developer preview while its plugin and artifact
+The package remains in the `0.x` version series while its plugin and artifact
 contracts stabilize. Do not publish a separate source repository.
 
 ## Release checklist
@@ -32,10 +32,10 @@ mirror the aliases under `.agents/skills/` into `nvidia/skills`. The native
 Isaac Lab skill remains authoritative; the catalog entry is a distribution
 mirror.
 
-The initial developer preview does not publish a container image. Users build
-the pinned Dockerfile from their Isaac Lab checkout. Any future package or
-container publication requires a separately reviewed workflow and immutable
-artifact provenance.
+The current distribution does not publish a container image. Users build the
+pinned Dockerfile from their Isaac Lab checkout. Any future package or container
+publication requires a separately reviewed workflow and immutable artifact
+provenance.
 
 ## Clean-clone acceptance
 

tools/perf_bisection/pyproject.toml

@@ -10,7 +10,6 @@ readme = "README.md"
 requires-python = ">=3.11"
 license = "BSD-3-Clause"
 classifiers = [
-    "Development Status :: 3 - Alpha",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",