Prepare v0.4.0 repository health release

.github/dependabot.yml

@@ -17,6 +17,10 @@ updates:
       time: "09:00"
       timezone: America/Los_Angeles
     open-pull-requests-limit: 5
+    ignore:
+      - dependency-name: mcp
+        update-types:
+          - version-update:semver-major
 
   - package-ecosystem: pip
     directory: /plugins/profile-and-optimize/server/tools/profile_and_optimize_mcp
@@ -26,6 +30,10 @@ updates:
       time: "09:00"
       timezone: America/Los_Angeles
     open-pull-requests-limit: 5
+    ignore:
+      - dependency-name: mcp
+        update-types:
+          - version-update:semver-major
 
   - package-ecosystem: github-actions
     directory: /

.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
       - name: Run public static gates
         run: make check
       - name: Check Python syntax
-        run: python -m compileall -q plugins/profile-and-optimize/server scripts
+        run: python -m compileall -q plugins/profile-and-optimize scripts
       - name: Check repository whitespace
         run: git diff --check 4b825dc642cb6eb9a060e54bf8d69288fbee4904 HEAD
 
@@ -72,6 +72,9 @@ jobs:
         run: make smoke-test
       - name: Run tool tests
         run: make pytest
+      - name: Type-check production Python
+        if: matrix.python-version == '3.12'
+        run: make typecheck
       - name: Run the MCP protocol smoke test
         run: make smoke-mcp-runtime
 

.gitignore

@@ -5,6 +5,8 @@ __pycache__/
 .venv/
 .venv-test/
 *.egg-info/
+build/
+dist/
 .env
 .env.local
 .idea/

.pre-commit-config.yaml

@@ -25,14 +25,25 @@ repos:
     rev: v0.16.3
     hooks:
       - id: ruff
-        args: [--fix, --select, E4,E7,E9,F, --config, plugins/profile-and-optimize/server/pyproject.toml]
-        files: '^plugins/profile-and-optimize/server/(perf_baseline|evidence|slurm|tools/(perf_baseline|evidence|slurm))/'
+        args: [--fix, --config, plugins/profile-and-optimize/server/pyproject.toml]
+        files: '^(plugins/profile-and-optimize/|scripts/).*\.py$'
       - id: ruff-format
         args: [--config, plugins/profile-and-optimize/server/pyproject.toml]
-        files: '^plugins/profile-and-optimize/server/(perf_baseline|evidence|slurm|tools/(perf_baseline|evidence|slurm))/'
+        files: '^(plugins/profile-and-optimize/|scripts/).*\.py$'
 
   - repo: local
     hooks:
+      - id: pyright-production
+        name: pyright (production Python)
+        entry: make typecheck
+        language: system
+        pass_filenames: false
+        files: '(^plugins/profile-and-optimize/(server|hooks|skills)/.*\.py$|^scripts/.*\.py$|^pyrightconfig\.json$)'
+      - id: shellcheck
+        name: shellcheck (tracked shell scripts)
+        entry: bash scripts/check-shell.sh
+        language: system
+        types: [shell]
       - id: check-doc-links-no-network
         name: check-doc-links (no-network)
         entry: bash scripts/check-doc-links.sh --no-network --quiet
@@ -53,7 +64,7 @@ repos:
         files: '(^plugins/profile-and-optimize/skills/|^README\.md$|^CONTRIBUTING\.md$|^REVIEWERS\.md$|^SECURITY\.md$|^Makefile$|^plugins/profile-and-optimize/README\.md$|^plugins/profile-and-optimize/\.claude-plugin/plugin\.json$|^\.claude-plugin/marketplace\.json$)'
       - id: lint-tool-counts
         name: lint-tool-counts (single source of truth for MCP tool / library totals)
-        entry: python3 scripts/lint-tool-counts.py
+        entry: make lint-tool-counts
         language: system
         pass_filenames: false
         files: '(^plugins/profile-and-optimize/server/(mcp_surface\.py|README\.md|AGENTS\.md|docs/|tools/profile_and_optimize_mcp/README\.md)|^README\.md$|^CONTRIBUTING\.md$|^REVIEWERS\.md$|^SECURITY\.md$|^Makefile$|^plugins/profile-and-optimize/README\.md$|^plugins/profile-and-optimize/\.claude-plugin/plugin\.json$)'

AGENTS.md

@@ -8,7 +8,8 @@ Client-specific files may point here, but shared policy belongs in this file.
 ```bash
 make demo     # print the tool and skill surface, no GPU needed
 make help     # list operator targets
-make all      # run smoke checks, doc links, skill lint, and pytest
+make quality  # run Ruff, Pyright, and ShellCheck
+make all      # run quality checks, docs, skill lint, MCP smoke, and pytest
 ```
 
 The repository layout, client setup, and methodology live in
@@ -119,8 +120,9 @@ source revisions, or delivery methods.
 
 ## Working in this repository
 
-- Run `make all` before committing. Use `make -j4 all` to run independent
-  targets in parallel.
+- Run `make all` before committing. It includes Python lint and formatting,
+  production type checks, shell lint, repository gates, MCP smoke, and pytest.
+  Use `make -j4 all` to run independent targets in parallel.
 - Skill, tool, and library counts are canonical in
   [`plugins/profile-and-optimize/server/mcp_surface.py`](plugins/profile-and-optimize/server/mcp_surface.py).
   Never hardcode a replacement count without updating and running the count

CHANGELOG.md

@@ -3,6 +3,34 @@
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-08-16
+
+### Added
+- Added repository-wide Ruff, Pyright, and ShellCheck gates to `make all`,
+  pre-commit, and CI.
+- Added an upgrade guide, a Claude Code MCP health check, and a Codex MCP
+  registration check.
+
+### Security
+- Kept Artificial Analysis API keys out of subprocess arguments, command
+  receipts, standard output, standard error, CLI JSON, and MCP responses.
+- Rejected custom AIPerf commands that embed `--api-key` before they can run or
+  create evidence artifacts.
+
+### Changed
+- Required an explicit `--client` in the direct MCP installer and client
+  configuration helper. The installer no longer writes Cursor configuration
+  when the caller omits a client.
+- Updated the pinned Artificial Analysis dependency closure and held the MCP
+  runtime below version 2 pending a deliberate compatibility migration.
+
+### Fixed
+- Corrected production type contracts across the server, hooks, skills, and
+  repository scripts.
+- Fixed a variable-shadowing bug that could corrupt K-suffixed benchmark cell
+  identifiers when variant metadata was present.
+- Documented the search-tool fallback when `rg` is not installed.
+
 ## [0.3.1] - 2026-08-16
 
 ### Security

CLAUDE.md

@@ -9,3 +9,10 @@ in that adapter. Keep shared project policy in `AGENTS.md`.
 
 The shared value bar is that every promoted result must be
 adversarially-confirmed to add value.
+
+## Health Stack
+
+- typecheck: make typecheck
+- lint: make lint
+- test: make pytest
+- shell: make lint-shell

CONTRIBUTING.md

@@ -15,10 +15,11 @@ bash plugins/profile-and-optimize/server/install.sh --with-dev
 make all
 ```
 
-The development install includes the official Agent Skills validator, test
-tools, and every dependency required by the default test suite. `make all`
-runs the client-neutral checks. Use `make -j4 all` to run independent targets
-in parallel.
+The development install includes the official Agent Skills validator, Ruff,
+Pyright, ShellCheck, test tools, and every dependency required by the default
+test suite. `make quality` runs the language checks. `make all` adds docs,
+skill validation, the MCP smoke test, and pytest. Use `make -j4 all` to run
+independent targets in parallel.
 
 Claude Code packaging has a separate optional check:
 

Makefile

@@ -10,19 +10,25 @@ SERVER_DIR := $(PLUGIN_DIR)/server
 SCRIPTS_DIR := scripts
 SERVER_PY := $(SERVER_DIR)/.venv/bin/python
 PYTHON ?= $(if $(wildcard $(SERVER_PY)),$(SERVER_PY),python3)
+RUFF ?= $(if $(wildcard $(SERVER_DIR)/.venv/bin/ruff),$(SERVER_DIR)/.venv/bin/ruff,ruff)
+CURRENT_VERSION := $(strip $(shell cat VERSION 2>/dev/null))
 
 # Default VERSION for `make release-notes`. Override on the command line:
-#   make release-notes VERSION=v0.3.1
+#   make release-notes VERSION=v$(CURRENT_VERSION)
 VERSION ?=
 
-.PHONY: help demo check validate validate-agent-skills validate-claude-plugin validate-claude-plugin-uncached validate-uncached smoke-test smoke-mcp-runtime check-doc-links workload-proof-check lint-skill-mcp-args lint-skill-counts lint-tool-counts lint-versions check-version-transition test-release-gates pytest pytest-mcp pytest-xdist all freshness bootstrap print-mcp-snippet doctor install-mcp install-skills install-into-codex install-into-cursor refresh-symlinks release release-notes mcp-surface clean-pycache
+.PHONY: help demo check quality lint typecheck lint-shell validate validate-agent-skills validate-claude-plugin validate-claude-plugin-uncached validate-uncached smoke-test smoke-mcp-runtime check-doc-links workload-proof-check lint-skill-mcp-args lint-skill-counts lint-tool-counts lint-versions check-version-transition test-release-gates pytest pytest-mcp pytest-xdist all freshness bootstrap print-mcp-snippet doctor install-mcp install-skills install-into-codex install-into-cursor refresh-symlinks release release-notes mcp-surface clean-pycache
 
 help:
 	@printf 'profile-and-optimize operator commands\n\n'
 	@printf 'Common targets:\n'
 	@printf '  make demo                     List all skills and a sample of the MCP surface. No GPU required\n'
 	@printf '  make check                    Run the public static gates, including Agent Skills and all Markdown links\n'
 	@printf '  make all                      Run the full client-neutral local test suite. Use `make -j4 all` for parallel execution\n'
+	@printf '  make quality                  Run Ruff, Pyright, and ShellCheck\n'
+	@printf '  make lint                     Check Python lint and formatting with Ruff\n'
+	@printf '  make typecheck                Type-check production Python with Pyright\n'
+	@printf '  make lint-shell               Check every tracked shell script with ShellCheck\n'
 	@printf '  make validate-agent-skills    Validate every skill with the official Agent Skills reference validator\n'
 	@printf '  make validate-claude-plugin   Run the optional Claude Code package validator\n'
 	@printf '  make smoke-test               Validate skills, canonical counts, versions, and MCP argument references\n'
@@ -50,11 +56,11 @@ help:
 	@printf '  make bootstrap               Set up the best-effort Cursor adapter from a clone\n'
 	@printf '  make print-mcp-snippet       Print a Cursor MCP config block without writing it\n'
 	@printf '  make doctor                  Diagnose a Cursor MCP entry. Read-only unless FIX=1\n'
-	@printf '  make release-notes VERSION=v0.3.1   Extract the CHANGELOG section for v0.3.1\n'
+	@printf '  make release-notes VERSION=v%s   Extract the CHANGELOG section for the current release\n' '$(CURRENT_VERSION)'
 	@printf '  make clean-pycache           Remove __pycache__ + *.pyc under server/\n'
 	@printf '\n'
 	@printf 'Variables (override on command line):\n'
-	@printf '  VERSION                      Version tag for release-notes (e.g. v0.3.1)\n'
+	@printf '  VERSION                      Version tag for release-notes (e.g. v%s)\n' '$(CURRENT_VERSION)'
 
 validate: validate-agent-skills
 
@@ -85,16 +91,41 @@ smoke-test: validate-agent-skills
 	@$(PYTHON) $(SCRIPTS_DIR)/lint-tool-counts.py
 	@echo '--- version-header lint ---'
 	@$(PYTHON) $(SCRIPTS_DIR)/lint-versions.py
+	@$(PYTHON) $(SCRIPTS_DIR)/extract-release-notes.py "v$(CURRENT_VERSION)" CHANGELOG.md >/dev/null
 	@echo '--- skill MCP argument lint ---'
 	@$(PYTHON) $(SCRIPTS_DIR)/lint-skill-mcp-args.py
 
-check: smoke-test
+check: smoke-test lint lint-shell
 	@$(PYTHON) scripts/check-version-transition.py
 	@$(PYTHON) scripts/test_release_gates.py
 	@$(PYTHON) scripts/check_docs.py
 	@$(PYTHON) scripts/check_workload_proof_packets.py --self-test --require-workflow-handoff
 	@bash scripts/check-doc-links.sh --no-network --quiet
 
+quality: lint typecheck lint-shell
+	@echo '[ok] Python and shell quality checks passed'
+
+lint:
+	@if ! command -v "$(RUFF)" >/dev/null 2>&1 && [ ! -x "$(RUFF)" ]; then \
+		echo '[FAIL] Ruff is not installed. Run: bash $(SERVER_DIR)/install.sh --with-dev'; \
+		exit 2; \
+	fi
+	@$(RUFF) check --config $(SERVER_DIR)/pyproject.toml $(PLUGIN_DIR) $(SCRIPTS_DIR)
+	@$(RUFF) format --check --config $(SERVER_DIR)/pyproject.toml $(PLUGIN_DIR) $(SCRIPTS_DIR)
+
+typecheck:
+	@if [ -x "$(SERVER_DIR)/.venv/bin/pyright" ]; then \
+		$(SERVER_DIR)/.venv/bin/pyright --project pyrightconfig.json; \
+	elif command -v pyright >/dev/null 2>&1; then \
+		pyright --project pyrightconfig.json; \
+	else \
+		echo '[FAIL] Pyright is not installed. Run: bash $(SERVER_DIR)/install.sh --with-dev'; \
+		exit 2; \
+	fi
+
+lint-shell:
+	@bash $(SCRIPTS_DIR)/check-shell.sh
+
 demo:
 	@printf '== gpu-perf-tune: 32 Agent Skills ==\n'
 	@find $(PLUGIN_DIR)/skills -mindepth 1 -maxdepth 1 -type d -exec basename {} \; | sort | sed 's/^/  /'
@@ -186,7 +217,7 @@ freshness:
 # These targets are independent and can run in parallel with `make -j4 all`.
 # The static check includes offline Markdown links. Scheduled CI checks live
 # external URLs so local validation does not depend on network availability.
-all: check smoke-mcp-runtime pytest
+all: check typecheck smoke-mcp-runtime pytest
 	@echo '[ok] all client-neutral checks passed'
 
 lint-skill-mcp-args:

README.md

@@ -87,9 +87,12 @@ From a clone of this repository:
 ```bash
 make install-skills CLIENT=codex
 make install-mcp CLIENT=codex
+codex mcp get profile_and_optimize
 ```
 
-Restart Codex after installation. Codex discovers the linked skills under
+The registration check should report `enabled: true`. Run
+`make smoke-mcp-runtime` for a live server handshake, then restart Codex after
+installation. Codex discovers the linked skills under
 `~/.agents/skills`. Use `/skills`, invoke a skill with `$skill-name`, or
 describe the task and let Codex select one. The MCP configuration is shared by
 Codex CLI, the IDE extension, and the desktop app. See the official Codex
@@ -107,11 +110,14 @@ claude plugin install --scope user \
 # Install the bundled MCP server inside the current plugin cache entry.
 # Add --full when you need the PDF report dependencies.
 bash "$(ls -dt ~/.claude/plugins/cache/profile-and-optimize-plugins/profile-and-optimize/*/server/install.sh | head -1)"
+
+claude mcp get plugin:profile-and-optimize:profile_and_optimize
 ```
 
-Restart Claude Code. Invoke a skill such as `/inference-perf-bench`, or describe
-the task and let Claude Code select a matching skill. The plugin installs its
-provenance hook, but the hook remains inactive until
+The health check should report `Status: ✔ Connected`. Restart Claude Code.
+Invoke a skill such as `/inference-perf-bench`, or describe the task and let
+Claude Code select a matching skill. The plugin installs its provenance hook,
+but the hook remains inactive until
 `PROVENANCE_COMMIT_GATE=ask` or `PROVENANCE_COMMIT_GATE=deny` is present in the
 Claude hook environment. Install `jq` on `PATH` before enabling either mode.
 
@@ -127,6 +133,12 @@ make install-skills CLIENT=cursor
 make install-mcp CLIENT=cursor
 ```
 
+## Upgrading
+
+Read [`docs/UPGRADING.md`](docs/UPGRADING.md) before changing release lines. It
+lists the client refresh commands and required installer, AI tuning, MLPerf
+rules, and MCP acknowledgement changes.
+
 ## Value bar
 
 Every benchmark result, optimization claim, and generated report starts as a

SECURITY.md

@@ -7,8 +7,8 @@ Security fixes land on `main` while the next release is in development.
 | Version | Status |
 | --- | --- |
 | `main` | Supported development branch |
-| `0.3.x` | Supported release line |
-| `0.2.x` and earlier | Unsupported |
+| `0.4.x` | Supported release line |
+| `0.3.x` and earlier | Unsupported |
 
 The latest published release may not contain fixes that have landed on `main`.
 Check the [release history](https://github.com/cfregly/gpu-perf-tune/releases) before deploying.

VERSION

@@ -1 +1 @@
-0.3.1
+0.4.0