pyplaykit 1.35.0__tar.gz → 1.37.2__tar.gz

{pyplaykit-1.35.0 → pyplaykit-1.37.2}/CHANGELOG.md

@@ -11,6 +11,103 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.37.2] — 2026-10-11
+
+`test-creation` can now commit generated tests to a feature branch of your sandbox repository and push that branch for you to validate and raise as a pull request; a hands-on playground with sample CSVs ships with the package (`pyplaykit docs test-creation`); scaffolded projects no longer break without pandas. Agents stay **disabled by default**, and branch mode needs `agents.autonomy.max: branch` plus `--autonomy branch`.
+
+### Behaviour changes — check before upgrading
+
+- **Test runs started by agents no longer receive `PYPLAYKIT_SANDBOX_*` variables** (they hold the sandbox push token). *What to do:* nothing, unless a test reads such a variable; rename it.
+- **`agents.scm.sandbox` is a new config block** (empty `repo` by default). Projects that copy `config/config.yaml` by hand can add it from a fresh `pyplaykit init`; without it the defaults apply.
+
+### Added
+
+- **Test creation playground (`pyplaykit docs test-creation`).** A hands-on guide from a fresh `pip install` + `pyplaykit init` project: skeletons without a model, real tests with a model, sandbox feature branches, CSV format, settings and troubleshooting. Seven sample CSVs ship with the package (UI, API with inferred types, database, device, mixed, one row per step, custom column names); `pyplaykit docs <topic> --save-examples [DIR]` copies them (default `test_data/testcases/`, never overwrites).
+- **Sandbox feature branches for `test-creation` (ADR-0019 amendment 1, US-AG12.3.3).** With `--autonomy branch` and `agents.scm.sandbox.repo` set, `pyplaykit agents run test-creation` clones the sandbox repository, creates `feature/test-creation/<csv>-<UTC time>` from `origin/main`, generates the tests against that repository's layout, validates them (`pytest --collect-only`; device tests in sim mode), commits them with the test-case CSV as the engineer, and pushes only the feature branch. It never opens a pull request or touches `main`: the engineer validates and edits the tests and opens the pull request. The push token comes from `PYPLAYKIT_SANDBOX_GIT_TOKEN` (environment or `.env`) and reaches git only as an HTTP header; test runs never receive it. New `agents.scm.sandbox` settings; one `sandbox_branch` audit record per run.
+
+### Fixed
+
+- **Scaffolded data-comparison demos without pandas.** In a project created by `pyplaykit init` on a plain `pip install pyplaykit`, `test_demo_excel.py` broke test collection (`No module named 'pandas'`) and the file-comparison demos failed. They now skip with `pip install "pyplaykit[data-comparison]"`; `init` names the same extra when it skips the demo workbooks. Existing projects: re-run `pyplaykit init` does not replace existing files; copy the new guard from a fresh scaffold or install the extra.
+
+---
+
+## [1.37.1] — 2026-10-11
+
+First release on PyPI of the QE agents Phase 1 work: the v1.37.0 tag was not published because its CI gate failed on three agent unit tests under `CI=true`. 1.37.1 contains everything in [1.37.0] below, plus two new built-in agents, `test-review` and `test-creation`. Agents stay **disabled by default**.
+
+### Added
+
+- **Built-in agent `test-creation` (ADR-0019, US-AG12.3.1-3.2).** Turns test cases from a CSV (id, name, description, objective, steps, expected results; optional type, feature, tags) into PyPlayKit UI, API, database and device tests in the project's `pyplaykit init` layout (`tests/<project>/functional/<type>/<feature>/`), reusing existing page objects and the framework's libraries (`BasePage`, `ApiClient`, `ResponseValidator`, `db_client`, `DbValidationHelper`, `dut`). The host assembles every file; inferred UI locators are marked `UNVERIFIED`; generated code is checked with the test-review rules and fixed by the model up to `fix_attempts`. Output: `test_creation.patch`, `.md` and `.json`; skeletons without a model. Configure under `agents.test_creation`. New read tool `list_files`; `read_source` reports `newline` and `final_newline`.
+- **Built-in agent `test-review` (US-AG17.3.3).** Reviews test code for quality before merge, using only assets the QE team owns: deterministic rules for missing or weak assertions, empty tests, swallowed exceptions, sleeps, hardcoded URLs and credentials, raw selectors in tests, print, skips without a reason, the `tests/functional/<type>/<feature>/` layout, duplicates and parametrize candidates, plus a model review of whether each test checks what it claims. Inputs: a change (`base`/`head`), `paths`, or the whole suite. Outputs `test_review.md` / `test_review.json` and signals (`blocking_issues` counts deterministic high issues only). Configure under `agents.test_review`. Mutation-testing evidence is not included yet.
+- ADR-0018 (accepted): change intelligence without access to product source, planned as EP-AG06 feature 4.
+
+### Fixed
+
+- Agent unit tests clear CI-detection and org-governance environment variables, so they behave the same on GitHub Actions as locally (the cause of the failed v1.37.0 publish).
+
+---
+
+## [1.37.0] — 2026-10-11
+
+QE agents Phase 1 complete (Wave 7, EP-AG05 and EP-AG06): the tool layer and Python stack adapter, and the first built-in agent, `change-intelligence` — impact analysis, a deterministic risk score and a regression plan that `pytest --pyplaykit-select-from` applies in PR pipelines. Also the test-impact map, ADR-0017 (evaluation process), the stdio JSON-RPC spike, a QE agents user guide (`pyplaykit docs agents`), and fixes for pip installs. Agents stay **disabled by default**; selection stays off until `agents.change_intelligence.apply_selection` is set on the base branch.
+
+### Behaviour changes — check before upgrading
+
+These affect only projects that enable agents (`agents.enabled: true`) or write their own agents.
+
+- **The host declares data classes on LLM requests.** In an agent run every LLM request now carries `metadata` plus the classes of the tool results the run has received (and any the agent declared). Before, a request the agent did not label counted as carrying every content class. *What to do:* nothing for most agents; an agent that sends content it did not get through a host tool must declare its classes (`pyplaykit.agents.policy.declare`).
+- **Run artifacts are written to disk.** `ctx.artifacts.put()` in a run started by `pyplaykit agents run` or the session trigger writes to `reports/agents/runs/<run id>/artifacts/`; a run reads back only its own artifacts.
+
+### Fixed
+
+- **pip installs without a `config/` folder:** the pytest plugin fell back to `site-packages/config/`, which does not exist, so every test errored with `FileNotFoundError`. It now uses the defaults bundled in the package (`pyplaykit/config/`), as `pyplaykit init` does.
+- **`pyplaykit docs` on Windows consoles and redirected output:** printing emoji under cp1252 raised `UnicodeEncodeError`; output that cannot be encoded is now replaced instead.
+
+### Added
+
+- **QE agents user guide** (`docs/QE_AGENTS_GUIDE.md`, bundled: `pyplaykit docs agents`): install extras, enabling agents and a model, change-intelligence, the impact map, regression selection in PR pipelines, commands and output files. Verified from a clean `pip install "pyplaykit[agents,mcp]"` outside the repository.
+- **Regression plan and `--pyplaykit-select-from` (US-AG06.3.1, ADR-0012).** `change-intelligence` writes `regression_plan.json`: `must_run` (tests mapped to the change, changed test files, smoke tests), `should_run` (importing test files, co-failing tests, and tests the model adds, which it can only add) and `safe_to_skip`, each with reasons; or `full_suite` with the reasons (infrastructure or config change, shared code, untrusted or old map, low confidence). `pytest --pyplaykit-select-from <plan|latest>` deselects only safe-to-skip tests, only in PR pipelines with `agents.change_intelligence.apply_selection` (off by default) true on the base branch, at the plan's commit. In PR pipelines the impact map comes from `PYPLAYKIT_IMPACT_MAP` or the base branch, and the agent's settings from the base branch (F7). `max_map_age` accepts durations such as `7d`.
+- **Deterministic risk score (US-AG06.2.2).** `change-intelligence` scores every changed file 0-100 from change type, code-area criticality, coverage gap, size, failure history and blast radius, with a tier and each factor's contribution and reason; the overall score is the riskiest file's. Configure under `agents.change_intelligence.risk` (weights, thresholds, `criticality.areas`). New signals: `risk_score`, `risk_tier`, `high_risk_files`.
+- **`ctx.settings`**: an agent reads its own `agents.<agent_name>` block (after org governance, read-only); policy keys such as `llm` or `budgets` are never exposed this way. `get_test_impact_map` for files also returns `total_tests`, `failures` and `history`.
+- **First built-in agent: `change-intelligence`, impact analysis (US-AG06.2.1).** For a commit range it lists each changed file's area, the functions it touches, the tests mapped to them, untested changed code, features, API domains and requirement ids from test docstrings, and asks the model what each change means through a structured-output prompt; without a model the deterministic impact is still returned (`partial`). Writes `impact.json` and `impact.md` run artifacts. Runs at `recommend` at most, and only when `agents.enabled` (off by default). Example: `pyplaykit agents run change-intelligence --input '{"base": "origin/main"}'`.
+- **`ctx.prompt(name, **values)`**: agents load prompts from their own `prompts/` directory; the prompt's SHA-256 is recorded in the run events and the audit log. Projects cannot override agent prompts.
+- **Test-impact map (US-AG06.1.1).** `pyplaykit/agents/impact_map.py` and `pyplaykit agents impact-map build|show` build `reports/agents/impact_map.json` from per-test coverage (`pytest --cov=<source> --cov-context=test`, mapped to functions and classes), static import dependencies (test → page → module) and the failure history (failure counts, tests that fail together); `--incremental` refreshes it from a partial run and marks changed files stale. `get_test_impact_map` reads the new format. New, off by default: `reporting.history` appends each session's failed tests to `reports/observability/history.jsonl`.
+- **Read tools for agents (US-AG05.1.1).** `HostTools` serves the existing MCP tools agents reuse (redacted by the host's fail-closed redactor, so `get_config` and `get_org_policy` never reach an agent unredacted) and new host-internal read tools in `pyplaykit/agents/read_tools.py`: `get_change_set`, `get_test_impact_map`, `get_failure_artifacts`, `read_source` (confined to the project: symlinks resolved, denylist for `.git/`, `.env*`, keys, `config/org/`, the audit log) and `get_stack_profile`. Tool results carry host-assigned data classes. `HostContext.dispatch()` serves `artifact.put`, `artifact.get` and `log.event`. CLI: `pyplaykit agents tools` and `pyplaykit agents tool <name> [--args JSON]`. None of these tools is exposed by `pyplaykit-mcp`.
+- **Target-stack adapters (US-AG05.2.1, ADR-0010).** `pyplaykit/agents/stacks/`: the `StackAdapter` protocol (`detect`, `conventions`, `run`, `validate_change`), support states per capability, and the `python-pytest` adapter. It detects pytest projects from `pytest.ini`, `pyproject.toml`, `tox.ini`, `setup.cfg` or `conftest.py`, reads the repository's conventions (page objects, locator style, fixtures, assertions, file naming, example files), runs `python -m pytest` with the project's own interpreter and normalises JUnit XML (parsed with `defusedxml`) into results that feed `ObservabilityTracker`. Adapters are discovered through the `pyplaykit.stack_adapters` entry-point group; third-party adapters load only when allowlisted (ADR-0016).
+- **Scrubbed environment for every stack execution (threat model F5).** Runs receive operating-system basics, the target test environment's credentials and `agents.execution.env_passthrough` only; provider and SCM credentials are refused even when listed.
+- `defusedxml` added to the `agents` extra.
+- **Execute tools for agents (US-AG05.1.2).** `pyplaykit/agents/host_tools.py`: `HostTools`, the runner's tool backend (wired by `agent_runner`), serves `run_tests` and `run_single_test` through the stack adapter. Only `agents.execution.allowed_envs` can be targeted; output goes to `reports/agents/runs/<run id>/tests/`, and writes elsewhere are reported in git checkouts; the timeout is capped by the run's deadline. `run_single_test` now counts against the test-execution budget. The runner binds a tool backend that has `for_run(request, envelope)` to each run.
+- The `python-pytest` adapter writes `tmp_path` (`--basetemp`) and coverage data (`COVERAGE_FILE`) to the run's output directory and sets `PYTHONDONTWRITEBYTECODE`.
+
+---
+
+## [1.36.0] — 2026-10-11
+
+QE agents governance and safety (Wave 7, EP-AG04): agent policy through org governance, redaction before anything leaves the machine, a tamper-evident audit log, tool tiers with prompt-injection defence, and the enforcement model. Also light and dark themes for the live dashboard, and lock modes for org governance. Agents stay **disabled by default** and no built-in agents ship yet.
+
+### Behaviour changes — check before upgrading
+
+These affect only projects that enable agents (`agents.enabled: true`) or write their own agents.
+
+- **External providers refuse unlabelled requests.** An LLM request that does not declare its data classes (`LLMRequest.metadata["pyplaykit.data_classes"]`, helper `pyplaykit.agents.policy.declare`) counts as carrying source, results, documents and test data, which external providers do not receive by default. *What to do:* declare the classes a request carries, allow them per provider in `agents.llm.egress.<provider>`, or use a provider declared `hosting: self_hosted`. Host-assigned classes for tool results are planned in US-AG05.1.1.
+- **Every LLM request and tool result is redacted** by default, and a request that cannot be redacted safely ends the run `denied`.
+- **Tools are granted by tier.** An agent at `analyze` autonomy no longer gets `execute` tools such as `run_tests`; tools outside the catalogue need `agents.tools.extra`.
+- **Tool calls return `ToolOutput`.** `ctx.tools.call()` returns a `ToolOutput` labelled untrusted; the result is in `.data`.
+- **Runs are audited.** If `reports/agents/audit.jsonl` cannot be written, agent runs are refused.
+- **Agent policy follows org governance.** `agents.*` keys from `config/org/` (and locks) now apply to agent runs; in PR pipelines org policy comes from the base branch or `PYPLAYKIT_ORG_ROOT`.
+
+### Added
+
+- **QE agents: policy through org governance** (`pyplaykit.agents.policy`; WBS US-AG04.1.1, ADR-0013, ADR-0016). The `agents:` section now resolves through config, the `config/projects/<project>.yaml` overlay and org → business unit → project governance with locks. `PolicyEnforcer` checks every LLM attempt in the tier router, fallbacks included: provider and model allowlists (`agents.llm.allowed_providers` / `allowed_models`, glob patterns) and the request's data classes against `agents.llm.egress.<provider>` (external providers get `metadata` only by default, providers declared `hosting: self_hosted` get every class but `media` and `secrets`); requests declare classes in `LLMRequest.metadata["pyplaykit.data_classes"]`, and an undeclared request counts as carrying all content classes. MCP-started runs are capped by `agents.mcp.egress`; `agents.execution.allowed_envs` refuses runs targeting other environments (`pyplaykit agents run --env`, the session's `--pyplaykit-env`); in CI, captured content stays out of the uploaded events file unless the new `agents.ci.artifact_classes` covers it. In PR pipelines org policy comes from `PYPLAYKIT_ORG_ROOT` or `config/org/` on the base branch, never the PR head; in CI a missing org root warns, or blocks agent runs with `agents.governance.required` or `PYPLAYKIT_GOVERNANCE_REQUIRED`. New `pyplaykit agents policy` and MCP tool `pyplaykit_get_agent_policy` / `get-agent-policy` (23 tools).
+- **QE agents: enforcement model** (`pyplaykit.agents.enforcement`; WBS US-AG04.5.1, ADR-0009). Every agent control is registered with exactly one class — host-enforced, out-of-process only, or in-process convention — and the story that delivers it (`pyplaykit agents controls`). An `ast` scan checks in-process agent code for the convention (no provider SDKs, `subprocess` / test runners, git libraries, `httpx` / `requests` / `urllib`, `open` or path file access, `os.environ`, `importlib`, `__import__`, `eval`): `pyplaykit agents scan [PATH…]` exits 1 on findings, and the unit tests run it over the built-in agents, so a breach fails CI. The docs state that in-process is not a sandbox.
+- **QE agents: tool tiers and prompt-injection defence** (`pyplaykit.agents.tools`, `pyplaykit.agents.output`; WBS US-AG04.4.1, threat model TH5, F13). Tools are granted by permission tier (`read`, `execute`, `propose`) according to the effective autonomy (`analyze` → read; `recommend` → read and execute; `propose`+ → all), narrowed by `agents.tools.allowed_tiers`; tools outside the catalogue are refused unless `agents.tools.extra` declares their tier, and refused tools appear as run warnings and in the `run.started` event. Tool results reach the agent redacted (fails closed) and wrapped as `ToolOutput` labelled untrusted, whose `as_prompt()` block cannot be closed by its content; a prompt-injection corpus test shows injected text cannot change the run's tools or autonomy. Model-generated text is encoded per sink (`encode(text, "markdown" | "html" | "mcp" | "terminal")`, `model_generated()`): raw HTML and images stripped, @-mentions neutralised, links only to `agents.output.allowed_link_domains`, terminal control sequences removed; MCP `run_agent` responses and CLI run output use it. Artifacts are limited to allowed content types and sizes (`agents.artifacts`), need plain names, and archives are refused by signature. Behaviour change: an agent calling a tool now receives a `ToolOutput` (its data in `.data`) instead of the raw result.
+- **QE agents: tamper-evident audit log** (`pyplaykit.agents.audit`; WBS US-AG04.3.1, threat model F15, TH32). `reports/agents/audit.jsonl` is append-only and hash-chained: the runner records each run's start (trigger, actor, agent, version, release digest, autonomy, environment, effective-policy hash), every LLM call (model, tokens, cost, redaction count, request SHA-256), every tool call (arguments SHA-256, status), every change proposal (diff SHA-256) and the outcome, with no prompt, argument or diff content. People are recorded by user id (`PYPLAYKIT_USER_ID`, the CI actor, else the login); e-mail-like ids are pseudonymised. A run whose actions cannot be audited is stopped with `policy_denied`. New `pyplaykit agents audit verify|head` (verify exits 1 on a broken chain), `pyplaykit agents decide <proposal> accept|reject` (audit log, run log and telemetry) and `pyplaykit agents prune` (run log, audit log with `agents.retention.audit_days`, response cache; pruning keeps the chain verifiable). The Jenkins and Azure DevOps templates print the audit chain head in the job log and upload the audit log; `python -m pyplaykit.agents.cli` runs the agents CLI without the console script.
+- **QE agents: redaction before anything leaves the machine** (`pyplaykit.agents.redaction`; WBS US-AG04.2.1, ADR-0013). Every LLM request is redacted in the runner before it is sent: known secret values (every `${SECRET:…}` value the process resolved, recorded in the new `utils.secrets.resolved_secret_values()` registry; environment variables on `agents.redaction.env_allowlist`, matching `agents.redaction.env_patterns` or with secret-looking names; credentials in `environments.yaml`), credential and PII patterns (private keys, AWS keys, GitHub and Slack tokens, JWTs, bearer tokens, URL passwords, e-mail, Luhn-checked card numbers, phone numbers, plus `agents.redaction.patterns`) and sensitive `key=value` / JSON fields (TDM masking rules). It fails closed: an error, or a credential still present after masking, refuses the call with `policy_denied`. Redaction counts are recorded on `chat` and run spans (`pyplaykit.redactions`), and captured telemetry content uses the same redactor. `AgentRunner` redacts by default (`redactor=None` only for tests).
+- **Org governance: lock modes.** `policy.locked_keys` entries may be `{key, mode}` with `pin` (the default, as before), `min` (floor), `max` (ceiling) or `raise_only` (lists keep org entries, maps keep and may raise them); numbers, versions, autonomy levels and risk tiers are ordered, and an incomparable value falls back to the org value. Resolution entries record the lock mode and org value.
+- **Live dashboard: light and dark themes.** The dashboard follows the operating system's theme, and a **Light / Dark** button in the header switches it; the choice is remembered in that browser (`localStorage`). Tables scroll inside their section on narrow screens.
+
+---
+
 ## [1.35.0] — 2026-10-11
 
 QE agents observability (Wave 7, EP-AG03): GenAI traces, agent metrics and events, and a run log with reports, usage CLI and MCP tools. Agents stay **disabled by default** and no built-in agents ship yet; existing suites are unaffected. Tracing needs `telemetry.enabled` (the `telemetry` extra for OTLP export); Prometheus export needs the `prometheus` extra.

{pyplaykit-1.35.0 → pyplaykit-1.37.2}/CLAUDE.md

@@ -13,6 +13,7 @@ For QE engineers adding functional tests, see:
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** - Comprehensive contributor guide
 - **[docs/QE_VISUAL_GUIDE.md](docs/QE_VISUAL_GUIDE.md)** - Visual guide with diagrams
 - **[docs/TEST_ORGANIZATION.md](docs/TEST_ORGANIZATION.md)** - Enterprise-scale test organization
+- **[docs/QE_AGENTS_GUIDE.md](docs/QE_AGENTS_GUIDE.md)** - QE agents user guide (also `pyplaykit docs agents` after pip install)
 
 Quick answer: Add UI tests to `tests/functional/ui/<feature>/`, API tests to `tests/functional/api/<domain>/`, database tests to `tests/functional/database/<category>/`, and integration tests to `tests/integration/`.
 
@@ -102,9 +103,10 @@ Available pytest CLI options (registered in `conftest.py`):
 - `--pyplaykit-dut-mode` — Device automation mode: sim (twins, default), emu (not yet available), hil (real hardware); or PYPLAYKIT_DUT_MODE
 - `--pyplaykit-bench` — Device bench whose DUTs are in scope (config/devices.yaml benches); or PYPLAYKIT_BENCH
 - `--pyplaykit-dut` — DUT for tests that do not select one with `requires_dut`; or PYPLAYKIT_DUT
+- `--pyplaykit-select-from` — Apply a change-intelligence regression plan (`regression_plan.json` or `latest`): deselect only tests it marks safe to skip, in PR pipelines with `agents.change_intelligence.apply_selection` on the base branch; or PYPLAYKIT_SELECT_FROM
 - `--pyplaykit-agents` — After the session, run the agents in `agents.triggers.on_session_finish` (local only; skipped in CI; requires `agents.enabled`)
 
-QE agents CLI: `pyplaykit agents [--config DIR] [--json] list | show <agent> | run <agent> [--input JSON|FILE] [--stack S] [--autonomy LEVEL] [--project P] | usage [--by agent|model|project|day] [--days N]` (disabled by default — `agents.enabled: false` in `config/config.yaml`; `run` exits 0 only on success; see docs/QE_AGENTS_DESIGN.md).
+QE agents CLI: `pyplaykit agents [--config DIR] [--json] list | show <agent> | run <agent> [--input JSON|FILE] [--stack S] [--autonomy LEVEL] [--project P] | usage [--by agent|model|project|day] [--days N] | policy [--project P] [--business-unit B] | audit verify|head | decide <proposal> accept|reject --agent A | prune | controls | scan [PATH...] | impact-map build|show [--coverage FILE] [--incremental] | tools | tool <name> [--args JSON] [--env E]` (`run` also takes `--env E`) (disabled by default — `agents.enabled: false` in `config/config.yaml`; `run` exits 0 only on success; see docs/QE_AGENTS_DESIGN.md).
 
 Device bench CLI: `pyplaykit devices [--config DIR] [--env ENV] [--bench B] [--mode M] list | show <dut> | check | scenarios | report | catalog [--json] | release <dut> | editor [--serve]` (`check` exits 1 when a DUT is not ready; `--json` output matches the MCP device tools; `editor` edits devices.yaml through forms in a self-contained HTML page, `--serve` saves it directly).
 - `pyplaykit devices list|release <dut>` — Device bench inventory (capabilities, leases, quarantine)
@@ -264,7 +266,7 @@ Defined in `pytest.ini`:
 
 **Wave 4 (In Progress):** Self-healing locators with fallback chains and DOM retries (complete), distribution packaging baseline (complete), semantic versioning governance (pending)
 
-**Wave 5 (Complete):** MCP server for AI interoperability — 22 tools across 5 categories (package discovery, project introspection, project state, device automation, QE agents), all also exposed as CLI subcommands. All are read-only except `check_bench_readiness` (connects DUTs, runs health probes). See `docs/MCP_SERVER_DESIGN.md`.
+**Wave 5 (Complete):** MCP server for AI interoperability — 23 tools across 5 categories (package discovery, project introspection, project state, device automation, QE agents), all also exposed as CLI subcommands. All are read-only except `check_bench_readiness` (connects DUTs, runs health probes). See `docs/MCP_SERVER_DESIGN.md`.
 
 **Wave 6 (Complete):** Enterprise readiness gap closure — expanded DB assertions (assert_date_range/aggregate/schema_match), ApiClient OAuth2/multipart/cookie extensions, WCAG accessibility testing, mobile device emulation, Jenkins/Azure DevOps CI templates, Quality Gate Engine (PASS/WARN/BLOCK verdicts)
 
@@ -318,6 +320,7 @@ Every tool is available in two ways: as an **MCP tool** (for AI assistants) and
 | `pyplaykit_check_bench_readiness` | `check-bench-readiness [--bench] [--mode] [--dut]` | Device Automation | Connect each DUT, run health probes, disconnect (exit 1 when not ready) |
 | `pyplaykit_run_agent` | `run-agent <agent> [--input JSON] [--autonomy analyze\|recommend]` | QE Agents | Run a QE agent at analyze/recommend only (requires `agents.enabled`) |
 | `pyplaykit_list_agents` | `list-agents` | QE Agents | Discovered agents, whether config lets each run, refused agents |
+| `pyplaykit_get_agent_policy` | `get-agent-policy [--project] [--business-unit]` | QE Agents | Effective agent policy after org governance: source, locks, egress per provider |
 | `pyplaykit_get_agent_usage` | `get-agent-usage [--days N] [--by agent\|model\|project\|day]` | QE Agents | Runs, tokens and cost from `reports/agents/runs.jsonl` |
 
 ### CLI usage examples

{pyplaykit-1.35.0/pyplaykit.egg-info → pyplaykit-1.37.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyplaykit
-Version: 1.35.0
+Version: 1.37.2
 Summary: Enterprise Python + Playwright automation framework
 Author-email: Shan Konduru <shankonduru@gmail.com>
 License: MIT
@@ -61,6 +61,7 @@ Provides-Extra: mcp
 Requires-Dist: mcp<2,>=1.2; extra == "mcp"
 Provides-Extra: agents
 Requires-Dist: jsonschema>=4.0; extra == "agents"
+Requires-Dist: defusedxml>=0.7; extra == "agents"
 Provides-Extra: agents-anthropic
 Requires-Dist: anthropic<2,>=1.0; extra == "agents-anthropic"
 Provides-Extra: agents-openai
@@ -193,7 +194,7 @@ PyPlayKit is a **multi-project enterprise test automation framework** built with
 - 🔍 **Self-Healing**: Locator recovery with fallback chains
 - 🔭 **Observable**: Comprehensive metrics and reporting
 - 📟 **Device & Embedded Automation**: Test IoT / embedded / PLC / CAN / BLE / Android devices against digital twins or real hardware ⭐ **NEW**
-- 🤖 **AI-ready**: MCP server with 22 tools, each also a `pyplaykit-mcp` CLI subcommand
+- 🤖 **AI-ready**: MCP server with 23 tools, each also a `pyplaykit-mcp` CLI subcommand
 
 ---
 
@@ -1018,6 +1019,10 @@ Each project config includes:
 **Wave 7** 🚧 In progress — QE agents (change intelligence, coverage and test design, test creation, execution intelligence): see [design](docs/QE_AGENTS_DESIGN.md), [plan](docs/QE_AGENTS_PLAN.html) and ADRs 0006–0016 in [docs/adr/](docs/adr/README.md).
 - Done so far (Phase 1, disabled by default): versioned agent contract and JSON Schemas, agent discovery with digest pinning, the runner (limits, effective autonomy, typed results), the `agents:` config block, `pyplaykit agents list | show | run`, `--pyplaykit-agents` (local only) and the MCP `run_agent` tool.
 - GenAI spans for agent runs, LLM and tool calls (OpenTelemetry GenAI conventions), content capture off by default; `agent.*` events and `pyplaykit_agent_*` Prometheus metrics (tokens, cost, latency, tool calls, budget breaches, proposals); `reports/agents/runs.jsonl` and `usage_summary.json`, agent sections in the persona reports, a dashboard panel, `pyplaykit agents usage` and the MCP `list_agents` / `get_agent_usage` tools
+- v1.37.0: Phase 1 complete — tool layer and Python stack adapter, the test-impact map, and the first built-in agent `change-intelligence` (impact, risk score, regression plan applied with `--pyplaykit-select-from` in PR pipelines); user guide: `pyplaykit docs agents`
+- v1.37.1: first PyPI release of Phase 1 (v1.37.0 was not published), plus built-in agents `test-review` (test code quality) and `test-creation` (UI, API, database and device tests from test-case CSVs)
+- v1.37.2: `test-creation` commits to a feature branch of your sandbox repository and pushes it (never a pull request); hands-on playground with sample CSVs (`pyplaykit docs test-creation --save-examples`); scaffold demos skip without pandas
+- v1.36.0: agent governance and safety — policy through org governance, redaction, audit log, tool tiers, enforcement model
 - v1.35.0: agent observability — GenAI traces, `agent.*` events and `pyplaykit_agent_*` metrics, run log and reports
 - v1.34.0: LLM layer — provider-neutral requests, Anthropic / OpenAI-compatible / Ollama adapters, fake and record/replay clients, model tiers with fallback and retries, budgets, cost and a response cache. No built-in agents ship yet.
 

{pyplaykit-1.35.0 → pyplaykit-1.37.2}/README.md

@@ -19,7 +19,7 @@ PyPlayKit is a **multi-project enterprise test automation framework** built with
 - 🔍 **Self-Healing**: Locator recovery with fallback chains
 - 🔭 **Observable**: Comprehensive metrics and reporting
 - 📟 **Device & Embedded Automation**: Test IoT / embedded / PLC / CAN / BLE / Android devices against digital twins or real hardware ⭐ **NEW**
-- 🤖 **AI-ready**: MCP server with 22 tools, each also a `pyplaykit-mcp` CLI subcommand
+- 🤖 **AI-ready**: MCP server with 23 tools, each also a `pyplaykit-mcp` CLI subcommand
 
 ---
 
@@ -844,6 +844,10 @@ Each project config includes:
 **Wave 7** 🚧 In progress — QE agents (change intelligence, coverage and test design, test creation, execution intelligence): see [design](docs/QE_AGENTS_DESIGN.md), [plan](docs/QE_AGENTS_PLAN.html) and ADRs 0006–0016 in [docs/adr/](docs/adr/README.md).
 - Done so far (Phase 1, disabled by default): versioned agent contract and JSON Schemas, agent discovery with digest pinning, the runner (limits, effective autonomy, typed results), the `agents:` config block, `pyplaykit agents list | show | run`, `--pyplaykit-agents` (local only) and the MCP `run_agent` tool.
 - GenAI spans for agent runs, LLM and tool calls (OpenTelemetry GenAI conventions), content capture off by default; `agent.*` events and `pyplaykit_agent_*` Prometheus metrics (tokens, cost, latency, tool calls, budget breaches, proposals); `reports/agents/runs.jsonl` and `usage_summary.json`, agent sections in the persona reports, a dashboard panel, `pyplaykit agents usage` and the MCP `list_agents` / `get_agent_usage` tools
+- v1.37.0: Phase 1 complete — tool layer and Python stack adapter, the test-impact map, and the first built-in agent `change-intelligence` (impact, risk score, regression plan applied with `--pyplaykit-select-from` in PR pipelines); user guide: `pyplaykit docs agents`
+- v1.37.1: first PyPI release of Phase 1 (v1.37.0 was not published), plus built-in agents `test-review` (test code quality) and `test-creation` (UI, API, database and device tests from test-case CSVs)
+- v1.37.2: `test-creation` commits to a feature branch of your sandbox repository and pushes it (never a pull request); hands-on playground with sample CSVs (`pyplaykit docs test-creation --save-examples`); scaffold demos skip without pandas
+- v1.36.0: agent governance and safety — policy through org governance, redaction, audit log, tool tiers, enforcement model
 - v1.35.0: agent observability — GenAI traces, `agent.*` events and `pyplaykit_agent_*` metrics, run log and reports
 - v1.34.0: LLM layer — provider-neutral requests, Anthropic / OpenAI-compatible / Ollama adapters, fake and record/replay clients, model tiers with fallback and retries, budgets, cost and a response cache. No built-in agents ship yet.
 

{pyplaykit-1.35.0 → pyplaykit-1.37.2}/config/config.yaml

@@ -30,6 +30,10 @@ reporting:
   engineering_report_path: "reports/observability/engineering_report.json"
   qa_report_path: "reports/observability/qa_functional_report.json"
   leadership_report_path: "reports/observability/leadership_kpi_summary.json"
+  history:                              # per-session failure history; the test-impact map reads it
+    enabled: false                      #   for co-failure (US-AG06.1.1); enable in the CI full-suite job
+    path: "reports/observability/history.jsonl"
+    max_records: 500
 
 quality:
   automation_coverage_target: 100
@@ -302,9 +306,19 @@ agents:
   execution:
     allowed_envs: [dev, qa]
     timeout_s: 900
+    env_passthrough: []                 # extra non-secret variables stack runs receive (globs); provider
+                                        #   and SCM credentials are refused even if listed (F5)
   scm:
     protected_branches: [main, master, "release/*"]
     allow_pr: false
+    sandbox:                            # test-creation with --autonomy branch (and autonomy.max: branch)
+      repo: ""                          # repository for feature branches (URL or path); "" = this repository
+      base: main                        # branches start from origin/<base>; never pushed to
+      branch_prefix: feature/test-creation
+      push: true                        # push the feature branch only; never a pull request
+      token_env: PYPLAYKIT_SANDBOX_GIT_TOKEN  # token variable (environment, else .env); sent as a header only
+      writable: [tests, pages, test_data]
+      workspace: reports/agents/sandbox # clone and worktrees
   telemetry:                            # GenAI spans need telemetry.enabled (and otlp_endpoint for OTLP)
     capture_content: false              # prompts, completions, tool arguments/results; redacted
     otlp_classes: [metadata]            # data classes the OTLP endpoint may receive; captured content
@@ -317,12 +331,46 @@ agents:
   governance:
     required: false
   mcp:
-    egress: [metadata]
+    egress: [metadata]                  # data classes a run started from an MCP client may send
+  redaction:                            # applied to every LLM request; fails closed (US-AG04.2.1)
+    env_allowlist: []                   # environment variables whose values are always masked
+    env_patterns: ["PYPLAYKIT_TEST_*"]  # ... and names matching these (plus secret-looking names)
+    patterns: []                        # extra [{name, regex}] to mask
+    pii: true                           # e-mail addresses, card numbers, phone numbers
+  tools:                                # tool permission tiers (US-AG04.4.1)
+    allowed_tiers: null                 # e.g. [read, execute]; null: what the autonomy level grants
+    extra: {}                           # tools the catalogue does not know: {name: read | execute | propose}
+  artifacts:                            # what agents may store (threat model F13); archives are never stored
+    max_bytes: 5242880
+    max_total_bytes: 52428800
+    allowed_types: null                 # null: json, text, markdown, csv, xml/junit, diff, png, jpeg
+  output:
+    allowed_link_domains: []            # links in model-generated text kept only to these domains
+  ci:
+    artifact_classes: [metadata]        # data classes CI artifact uploads may hold (F21); captured content
+                                        #   stays out of the uploaded events file unless they cover it
   change_intelligence:
-    min_confidence: null                # set from the Phase 2 baseline (ADR-0012)
-    max_map_age: null
+    min_confidence: null                # 0-1; below it the plan is the full suite; set from the Phase 2 baseline (ADR-0012)
+    max_map_age: null                   # seconds or a duration ("36h", "7d"); an older map means the full suite
     shadow_sample_rate: null
-    apply_selection: false
+    apply_selection: false              # kill switch: --pyplaykit-select-from deselects only when true (read from
+                                        #   the base branch in PR pipelines; PR pipelines only)
+    risk:                               # deterministic risk score (US-AG06.2.2); weights are normalised
+      weights: {change_type: 0.30, criticality: 0.20, coverage_gap: 0.20, size: 0.10, failure_history: 0.10, blast_radius: 0.10}
+      thresholds: {medium: 0.35, high: 0.65}
+      size_saturation_lines: 200
+      criticality:
+        default: medium                 # low | medium | high | critical
+        areas: []                       # [{paths: ["core/**", "utils/auth*"], level: high}], first match wins
+  test_review:                         # test-review agent (US-AG17.3.3)
+    rules: {}                         # severity per rule: high | medium | low | off, e.g. {print: off, missing-marker: low}
+    max_files: 40
+    allowed_url_hosts: []             # hosts allowed in test code, e.g. [localhost]
+  test_creation:                       # test-creation agent (ADR-0019)
+    max_test_cases: 25
+    batch_size: 5                     # test cases per model request
+    fix_attempts: 2                   # problems sent back to the model before a skeleton is kept
+    columns: {}                       # explicit CSV headers, e.g. {id: "TC No", steps: "Procedure"}
   evals:
     export: null
   reports:

{pyplaykit-1.35.0 → pyplaykit-1.37.2}/docs/CLI_REFERENCE.md

@@ -165,8 +165,10 @@ pyplaykit observability-report --open
 Serve the **live execution dashboard** — a zero-dependency, self-contained web
 page that visualizes a test run in real time (or a finished run's `live.jsonl`).
 The page shows collected/run counts, pass/fail/skip totals, current pass rate,
-elapsed time, a per-worker (xdist) breakdown, and a scrolling recent-test log,
-auto-refreshing every second.
+elapsed time, a per-worker (xdist) breakdown, a scrolling recent-test log and, once
+QE agents have run, agent usage, auto-refreshing every second. It follows the operating
+system's light or dark theme; the **Light / Dark** button in the header switches it, and the
+choice is remembered in that browser.
 
 ```bash
 # Serve the default reports/dashboard/live.jsonl on http://127.0.0.1:7474
@@ -202,13 +204,32 @@ pyplaykit agents list                          # discovered agents, and refused
 pyplaykit agents show change-intelligence      # manifest, launch, digest, autonomy ceiling, may it run
 pyplaykit agents run change-intelligence --input '{"base": "main", "head": "HEAD"}' --autonomy recommend
 pyplaykit agents usage --by model --days 7     # runs, tokens and cost from reports/agents/runs.jsonl
+pyplaykit agents policy --project checkout     # effective policy: governance source, locks, egress per provider
+pyplaykit agents audit verify                  # check the hash-chained audit log (exit 1 when broken)
+pyplaykit agents audit head                    # print the chain head (CI job logs, threat model F15)
+pyplaykit agents decide cp_12 accept --agent test-creation --run-id agr_…   # record a reviewer's decision
+pyplaykit agents prune                         # apply agents.retention.* to run log, audit log, response cache
+pyplaykit agents controls                      # every control: host-enforced, out-of-process only, or convention
+pyplaykit agents scan path/to/agent/           # in-process convention scan (exit 1 on findings; default: built-ins)
+pyplaykit agents impact-map build --coverage .coverage   # test-impact map from pytest --cov-context=test
+pyplaykit agents impact-map build --incremental --coverage part.cov   # refresh with a partial run
+pyplaykit agents impact-map show                         # summary of reports/agents/impact_map.json
+pyplaykit agents tools                         # host-internal tools agents can be granted: tier, data classes
+pyplaykit agents tool read_source --args '{"path": "pages/login_page.py", "end": 40}'
+                                               # call a host tool as an agent would (redacted, labelled)
 pyplaykit agents --json list                   # machine-readable output (any subcommand)
 ```
 
 **Options:** `--config DIR` (default `config`), `--json`; for `run`: `--input` (JSON object or path to a JSON
 file), `--stack`, `--autonomy` (`analyze` … `pr`; the effective level is the most restrictive of the agent's
-ceiling, `agents.autonomy.max` and this request), `--project`; for `usage`: `--by` (`agent`, `model`,
-`project`, `day`; default `agent`), `--days` (default 30). Every run is recorded in `reports/agents/runs.jsonl`
+ceiling, `agents.autonomy.max` and this request), `--project`, `--env` (the environment the run's tests
+target; refused unless it is in `agents.execution.allowed_envs`); for `policy`: `--project`, `--business-unit`;
+for `impact-map`: `build|show`, `--coverage FILE` (coverage data with per-test contexts), `--history FILE` (default: `reporting.history.path` when the file exists), `--base REF` (default: `HEAD`), `--incremental`, `--output PATH`, `--share-threshold` (default 0.5); for `tool`: `<name> [--args JSON|FILE] [--env E]` (exit 1 when the result has `status: error` or policy refuses the call; no `agents.enabled` needed: it is for people inspecting what agents see); for `audit`: `verify` or `head`, `--path`; for `decide`: `<proposal> accept|reject --agent A [--run-id R] [--by USER]`
+(the reviewer defaults to the current user id: `PYPLAYKIT_USER_ID`, the CI actor, else the login; e-mail
+addresses are pseudonymised); for `usage`: `--by` (`agent`, `model`,
+`project`, `day`; default `agent`), `--days` (default 30). Every run is also written to the hash-chained audit log `reports/agents/audit.jsonl` (run start with
+actor and policy hash, LLM and tool calls as hashes, proposals, outcome, decisions; no prompt or argument
+content), pruned after `agents.retention.audit_days` by `pyplaykit agents prune`. Every run is recorded in `reports/agents/runs.jsonl`
 (input hashed, outcome, usage per model, provenance) and summarised in `reports/agents/usage_summary.json`;
 lines older than `agents.retention.runs_days` (default 90) are pruned.
 
@@ -439,6 +460,18 @@ config lets each run), and agents refused at discovery with the reason. Mirrors
 pyplaykit-mcp list-agents
 ```
 
+##### `get-agent-policy`
+
+The effective QE agent policy after org → business unit → project governance: where it came from (in PR
+pipelines the base branch or `PYPLAYKIT_ORG_ROOT`), governance status (`ok` / `warn` / `block`), locks with
+their mode, governed `agents.*` keys, and enforcement as an MCP-started run gets it (allowed providers, models
+and environments, egress per provider, autonomy ceiling). Mirrors `pyplaykit_get_agent_policy`; `error` (exit
+1) when agent runs are blocked or the policy is invalid.
+
+```bash
+pyplaykit-mcp get-agent-policy --project checkout --business-unit payments
+```
+
 ##### `get-agent-usage`
 
 Runs, outcomes, tokens and cost from `reports/agents/runs.jsonl`: the full usage summary, or one grouping.
@@ -626,6 +659,22 @@ pytest --pyplaykit-orchestration
 
 ---
 
+### `--pyplaykit-select-from`
+
+Apply a change-intelligence regression plan (`regression_plan.json`, or `latest` for the newest one under
+`reports/agents/runs/`; also `PYPLAYKIT_SELECT_FROM`). Only the tests the plan marks safe to skip are
+deselected, and only when the plan is in selection mode, this is a PR pipeline,
+`agents.change_intelligence.apply_selection` is true on the base branch, and the checkout is the commit the
+plan was made for. Otherwise the full suite runs and one line says why. Smoke tests, tests in changed test
+files and tests the plan does not list always run.
+
+```bash
+pyplaykit agents run change-intelligence --input '{"base": "origin/main"}'
+pytest --pyplaykit-select-from latest
+```
+
+---
+
 ### `--pyplaykit-project`
 
 Active project name override. Loads `config/projects/<name>.yaml`. Overrides auto-detection.

{pyplaykit-1.35.0 → pyplaykit-1.37.2}/docs/KT/01_ARCHITECTURE.md

@@ -44,7 +44,7 @@ projects.
 | Dashboard | `utils/dashboard.py` | Live execution dashboard (real-time HTTP UI + JSONL event stream) |
 | Governance | `utils/org_governance.py` | Org → BU → project policy inheritance with locked-key enforcement |
 | Package/CLI | `pyplaykit/` | Public API exports, `pyplaykit` CLI, pytest plugin entry point |
-| MCP Server | `mcp_server/` | 22 MCP tools (incl. 6 device automation tools and the QE agent `run_agent`, `list_agents` and `get_agent_usage` tools) + CLI subcommands for AI interoperability |
+| MCP Server | `mcp_server/` | 23 MCP tools (incl. 6 device automation tools and the QE agent `run_agent`, `list_agents`, `get_agent_usage` and `get_agent_policy` tools) + CLI subcommands for AI interoperability |
 
 The layering rule is enforced by convention: tests never contain raw selectors, page
 objects never contain environment URLs, utilities stay stateless and generic.

{pyplaykit-1.35.0 → pyplaykit-1.37.2}/docs/MCP_SERVER_DESIGN.md

@@ -91,6 +91,19 @@ CLI equivalents: `pyplaykit-mcp get-device-framework | list-devices [--env] [--b
 
 ---
 
+### Agent-facing tools are host-internal
+
+The QE agent host serves agents more tools than this server exposes (design §2, threat model F6):
+`get_change_set`, `get_test_impact_map`, `get_failure_artifacts`, `read_source`,
+`get_stack_profile`, `run_tests` and `run_single_test`. They are **not** registered by
+`pyplaykit-mcp`, so a connected assistant cannot read source or run tests outside agent policy;
+a unit test checks the server's tool list. When an agent reuses a tool from this catalogue
+(`get_config`, `get_org_policy`, …) the host calls it for the project root and passes the result
+through its fail-closed redactor before the agent sees it. People can call any host tool as an
+agent would with `pyplaykit agents tool <name> [--args JSON]`.
+
+---
+
 ### Module Registry
 
 The following core modules are registered for `get_module_api` / `search_methods` discovery in addition to utility modules. Core modules (prefixed `core.`) are scanned because they contain framework-facing APIs useful to QE engineers and AI assistants.

{pyplaykit-1.35.0 → pyplaykit-1.37.2}/docs/MULTI_PROJECT_STRUCTURE.md

@@ -673,6 +673,35 @@ quality_gate:
       warn: 0.95
 ```
 
+#### Lock modes
+
+A lock can also bound a value instead of pinning it. Write the entry as a mapping with a
+`mode`:
+
+```yaml
+policy:
+  locked_keys:
+    - quality_gate.enabled                                 # pin (same as {key: ..., mode: pin})
+    - {key: agents.autonomy.max, mode: max}                # ceiling: lower layers may only lower it
+    - {key: agents.budgets.per_run_usd, mode: max}
+    - {key: agents.min_contract_version, mode: min}        # floor: lower layers may only raise it
+    - {key: agents.retention.audit_days, mode: min}
+    - {key: agents.risk_overrides, mode: raise_only}       # maps: add entries or raise values
+    - {key: agents.denied, mode: raise_only}               # lists: keep every org entry, add more
+```
+
+| Mode | Lower layers may |
+|---|---|
+| `pin` | not change the value |
+| `min` | raise the value, never lower it |
+| `max` | lower the value, never raise it |
+| `raise_only` | add list entries; add map entries or raise their values; raise a scalar |
+
+Numbers, versions (`1.1`, `2.0.3`), autonomy levels (`analyze` < `recommend` < `propose` <
+`branch` < `pr`) and risk tiers (`low` < `medium` < `high`) are ordered. A value that cannot be
+compared with the org value is replaced by the org value and logged, so a lock never loosens by
+mistake. `pyplaykit-mcp get-org-policy` shows each lock's mode and the org value.
+
 `projects/checkout.yaml` — belongs to the platform BU and sets its own block
 threshold; an attempt to set `quality_gate.enabled: false` here would be
 ignored (the org value wins) and logged:

{pyplaykit-1.35.0 → pyplaykit-1.37.2}/docs/OBSERVABILITY.md

@@ -332,3 +332,9 @@ acceptance rate) and **leadership** (spend this month against `agents.budgets.pe
 spend by agent, success rate, time saved from `agents.reports.minutes_saved`). The live dashboard
 shows agent usage from `usage_summary.json`; `pyplaykit agents usage` and the MCP
 `get_agent_usage` tool read the same data.
+
+**Failure history.** With `reporting.history.enabled: true` (off by default) every pytest session
+appends one line to `reporting.history.path` (default `reports/observability/history.jsonl`): time,
+commit, test count and the failed node ids, keeping the last `max_records` (default 500) sessions.
+The test-impact map reads it for failure counts and tests that fail together
+(`pyplaykit agents impact-map build`); enable it in the CI job that runs the full suite.