Clean up review findings: remove dead clarification code, fix stale version, honest max_turns docs

.gitignore

@@ -69,3 +69,6 @@ site/
 .squad/sessions/
 # Squad: SubSquad activation file (local to this machine)
 .squad-workstream
+
+# pytest-skill-engineering test scratch (some server tests create a cwd dir)
+.pytest-execution-servers/

CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+### Changed
+
+- **Docs now match the shipped behaviour of `max_turns`** — corrected `CopilotEval` docstrings that claimed the runner "enforces turn limits externally". The runner enforces `timeout_s` as the hard wall-clock limit; `max_turns` is advisory for the top-level session (not hard-enforced mid-run) and is used only to cap subagent turns.
+- **`pyproject.toml` version corrected** — bumped from a stale `0.5.7` to track the real release line, and moved the Trove classifier from `Development Status :: 3 - Alpha` to `4 - Beta`.
+
+### Removed
+
+- **Dead clarification-detection code** — `execution/clarification.py` (`check_clarification`) had zero callers anywhere in the codebase and was never wired into the Copilot execution path, yet the feature was advertised in the README. Removed the unused module and the corresponding README claims to keep docs honest (per the project's no-dead-code policy).
+
+### Fixed
+
+- **`.pytest-execution-servers/` scratch directory** — some server tests created this directory in the repo root; it is now git-ignored.
+
+## [0.6.13] - 2026-07-13
+
 ### Added
 
 - **Agent Skills spec compliance** — Full support for `agentskills.io` compatibility metadata, `allowed-tools`, `scripts`, and `assets` fields in `SKILL.md`

README.md

@@ -34,7 +34,7 @@ pytest-skill-engineering validates the **full skill engineering stack** that shi
 - **MCP Prompt Templates** — Do server-side templates produce the right behavior?
 - **CLI Tools** — Can Copilot use command-line interfaces effectively?
 
-Plus **A/B testing**, **multi-turn sessions**, **clarification detection**, and **AI-powered reports** that tell you exactly what to fix.
+Plus **A/B testing**, **multi-turn sessions**, and **AI-powered reports** that tell you exactly what to fix.
 
 ## How It Works
 
@@ -115,7 +115,6 @@ You can also use Azure OpenAI or other providers if you prefer — see [Configur
 - **A/B Testing** — Compare instructions, skills, custom agent versions, or tool configurations
 - **Eval Leaderboard** — Auto-ranked by pass rate and cost
 - **Multi-Turn Sessions** — Test conversations that build on context
-- **Clarification Detection** — Catch agents that ask questions instead of acting
 - **LLM Assertions** — Semantic checks with `llm_assert`, multi-dimension scoring with `llm_score`, image evaluation with `llm_assert_image`
 - **AI-Powered Reports** — Actionable feedback on tool descriptions, prompts, and costs
 - **Cost Tracking** — Copilot premium request tracking + USD estimation via `pricing.toml`

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytest-skill-engineering"
-version = "0.5.7"
+version = "0.6.14"
 description = "The testing framework for skill engineering. Test tool descriptions, prompt templates, agent skills, and custom agents with real LLMs. AI analyzes results and tells you what to fix."
 readme = "README.md"
 license = { text = "MIT" }
@@ -14,7 +14,7 @@ authors = [
 ]
 keywords = ["pytest", "ai", "llm", "mcp", "testing", "agents", "skill-engineering", "skills", "custom-agents"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Framework :: Pytest",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",

src/pytest_skill_engineering/copilot/eval.py

@@ -68,8 +68,10 @@ class CopilotEval:
     ``build_session_config()`` maps them to the SDK's actual
     ``system_message`` TypedDict.
 
-    The SDK's ``SessionConfig`` has no ``maxTurns`` field — turn limits
-    are enforced externally by the runner via ``timeout_s``.
+    The SDK's ``SessionConfig`` has no ``maxTurns`` field. The runner
+    enforces a hard wall-clock limit via ``timeout_s``; ``max_turns`` is
+    advisory for the top-level session (it is *not* hard-enforced mid-run)
+    and is used when configuring subagent turn caps.
 
     Example:
         # Minimal
@@ -111,7 +113,9 @@ class CopilotEval:
     allowed_tools: list[str] | None = None  # Allowlist (None = all)
     excluded_tools: list[str] | None = None  # Blocklist
 
-    # Limits — enforced by the runner, NOT part of SDK SessionConfig
+    # Limits — the runner enforces timeout_s (hard wall-clock limit).
+    # max_turns is advisory for the top-level session (not hard-enforced
+    # mid-run) and is used to cap subagent turns.
     max_turns: int = 25
     timeout_s: float = 300.0
 
@@ -168,8 +172,9 @@ def build_session_config(self) -> dict[str, Any]:
             skill_directories → skill_directories
             disabled_skills → disabled_skills
 
-        Note: ``max_turns`` is NOT part of ``SessionConfig`` — the runner
-        enforces turn limits externally.
+        Note: ``max_turns`` is NOT part of ``SessionConfig``. The runner
+        enforces ``timeout_s`` as the hard limit; ``max_turns`` is advisory
+        (not hard-enforced mid-run) and used only to cap subagent turns.
         """
         config: dict[str, Any] = {}
 

src/pytest_skill_engineering/copilot/judge.py

@@ -1,8 +1,7 @@
 """Shared Copilot SDK judge utility for LLM-as-judge evaluations.
 
 Provides a common interface for calling the Copilot SDK with judge prompts
-and parsing responses. Used by llm_assert, llm_score, clarification detection,
-and insights generation.
+and parsing responses. Used by llm_assert, llm_score, and insights generation.
 """
 
 from __future__ import annotations