feat(mcp,vscode): clarify repository health and triage focus semantics

- add compact MCP interpretation fields for health_scope, focus, and new_by_source_kind across summary, production triage, and changed-scope projections
- make the VS Code extension explain repository-wide health, production focus, outside-focus debt, and new-finding source-kind attribution more clearly without widening the review flow
- bump the preview VS Code extension to 0.2.2 and record the UX clarification pass in its changelog

Author: orenlab

CHANGELOG.md

@@ -9,6 +9,10 @@
   report metadata, MCP summary/triage projections, and the HTML Executive Summary subtitle.
 - Clarify MCP interpretation with compact `health_scope`, `focus`, and `new_by_source_kind` fields in summary/triage
   projections.
+- Make baseline mismatch handling more explicit in MCP and the VS Code client by surfacing baseline/runtime python tags
+  and whether comparison is proceeding without a valid baseline.
+- Make the Codex plugin prefer workspace-local launchers before `PATH`, with Poetry environment fallback for
+  python-tag-safe MCP startup.
 - Refresh branch metadata and client docs for the `2.0.0b5` line.
 - Update the README repository health badge to `87 (B)`.
 

README.md

@@ -163,7 +163,8 @@ repos:
 Optional read-only MCP server for AI agents and IDE clients.
 21 tools + 10 resources — never mutates source, baselines, or repo state.
 Compact summary and triage payloads make scope explicit: repository-wide health,
-current focus, and new-finding source-kind attribution.
+current focus, new-finding source-kind attribution, and when comparison is
+proceeding without a valid baseline.
 
 ```bash
 uv tool install --pre "codeclone[mcp]"       # or: uv pip install --pre "codeclone[mcp]"

codeclone/mcp_service.py

@@ -1670,6 +1670,7 @@ def get_production_triage(
             "run_id": self._short_run_id(record.run_id),
             "focus": _FOCUS_PRODUCTION,
             "health_scope": _HEALTH_SCOPE_REPOSITORY,
+            "baseline": dict(self._as_mapping(summary.get("baseline"))),
             "health": dict(self._summary_health_payload(summary)),
             "cache": dict(self._as_mapping(summary.get("cache"))),
             "findings": {
@@ -3283,6 +3284,7 @@ def _changed_analysis_payload(
             "run_id": self._short_run_id(record.run_id),
             "focus": _FOCUS_CHANGED_PATHS,
             "health_scope": _HEALTH_SCOPE_REPOSITORY,
+            "baseline": dict(self._summary_baseline_payload(record.summary)),
             "changed_files": len(record.changed_paths),
             "health": health_payload,
             "analysis_profile": self._summary_analysis_profile_payload(record.summary),
@@ -3959,6 +3961,7 @@ def _build_run_summary_payload(
             "root": str(root_path),
             "analysis_mode": request.analysis_mode,
             "codeclone_version": meta.get("codeclone_version", __version__),
+            "python_tag": str(meta.get("python_tag", "")),
             "report_schema_version": report_document.get(
                 "report_schema_version",
                 REPORT_SCHEMA_VERSION,
@@ -3971,6 +3974,7 @@ def _build_run_summary_payload(
                 "loaded": bool(meta_baseline.get("loaded", baseline_state.loaded)),
                 "status": str(meta_baseline.get("status", baseline_state.status.value)),
                 "trusted_for_diff": baseline_state.trusted_for_diff,
+                "python_tag": meta_baseline.get("python_tag"),
             },
             "metrics_baseline": {
                 "path": meta_metrics_baseline.get(
@@ -4096,11 +4100,21 @@ def _summary_trusted_state_payload(
         key: str,
     ) -> dict[str, object]:
         baseline = self._as_mapping(summary.get(key))
-        return {
+        trusted = bool(baseline.get("trusted_for_diff", False))
+        payload: dict[str, object] = {
             "loaded": bool(baseline.get("loaded", False)),
             "status": str(baseline.get("status", "")),
-            "trusted": bool(baseline.get("trusted_for_diff", False)),
+            "trusted": trusted,
         }
+        if key == "baseline":
+            payload["compared_without_valid_baseline"] = not trusted
+            baseline_python_tag = baseline.get("python_tag")
+            runtime_python_tag = summary.get("python_tag")
+            if isinstance(baseline_python_tag, str) and baseline_python_tag.strip():
+                payload["baseline_python_tag"] = baseline_python_tag
+            if isinstance(runtime_python_tag, str) and runtime_python_tag.strip():
+                payload["runtime_python_tag"] = runtime_python_tag
+        return payload
 
     def _summary_cache_payload(
         self,

docs/book/20-mcp-interface.md

@@ -59,6 +59,9 @@ Current server characteristics:
     - `health_scope` explains what the health score covers
     - `focus` explains the active summary/triage lens
     - `baseline`, `metrics_baseline`, `cache`
+    - untrusted baseline comparisons stay compact but explicit through
+      `baseline.compared_without_valid_baseline`,
+      `baseline.baseline_python_tag`, and `baseline.runtime_python_tag`
     - `cache.freshness` classifies summary cache reuse as `fresh`, `mixed`,
       or `reused`
     - flattened `inventory` (`files`, `lines`, `functions`, `classes`)
@@ -67,9 +70,10 @@ Current server characteristics:
     - flattened `diff` (`new_clones`, `health_delta`)
     - `warnings`, `failures`
     - `analyze_changed_paths` is intentionally more compact than `get_run_summary`:
-      it returns `changed_files`, `focus`, `health_scope`, `health`,
-      `health_delta`, `verdict`, `new_findings`, `new_by_source_kind`,
-      `resolved_findings`, and an empty `changed_findings` placeholder, while
+      it returns `changed_files`, compact `baseline`, `focus`, `health_scope`,
+      `health`, `health_delta`, `verdict`, `new_findings`,
+      `new_by_source_kind`, `resolved_findings`, and an empty
+      `changed_findings` placeholder, while
       detailed changed payload stays in
       `get_report_section(section="changed")`
 - workflow guidance:

docs/book/21-vscode-extension.md

@@ -123,7 +123,7 @@ The extension runs as a workspace extension and requires:
 - CodeClone `2.0.0b4` or newer
 
 In `auto` mode, launcher resolution prefers the current workspace virtualenv
-before `PATH`.
+before `PATH`. Runtime and version-mismatch messages identify that resolved launcher source.
 
 For this reason:
 

docs/book/23-codex-plugin.md

@@ -46,6 +46,7 @@ The plugin currently provides:
 The plugin surface is additive:
 
 - `.mcp.json` contributes a local stdio MCP server definition
+- that launcher prefers a workspace `.venv`, then a Poetry env, then `PATH`
 - the skill contributes workflow guidance and starter prompts
 - `README.md` documents local usage and boundaries inside the repository tree
 - Codex remains free to use direct `mcp add` config alongside or instead of the
@@ -65,7 +66,8 @@ The plugin does not rewrite user config or install CodeClone automatically.
 - **Repo-local clarity**: the plugin is meant to travel with the repository as
   a native Codex surface.
 - **Launcher honesty**: the plugin assumes `codeclone-mcp` is already
-  installable or configured in the local environment.
+  installable in the current workspace or reachable on `PATH`, and prefers the
+  workspace environment when one is present.
 
 ## Relationship to other interfaces
 

docs/codex-plugin.md

@@ -8,16 +8,24 @@ Repo-local discovery via `.agents/plugins/marketplace.json`.
 | File                         | Purpose                                            |
 |------------------------------|----------------------------------------------------|
 | `.codex-plugin/plugin.json`  | Plugin metadata, prompts, instructions             |
-| `.mcp.json`                  | Local `codeclone-mcp --transport stdio` definition |
+| `.mcp.json`                  | Workspace-first MCP launcher definition            |
 | `skills/codeclone-review/`   | Conservative-first full review skill               |
 | `skills/codeclone-hotspots/` | Quick hotspot discovery skill                      |
 | `assets/`                    | Plugin branding                                    |
 
 ## Install
 
 ```bash
-uv tool install --pre "codeclone[mcp]"    # or: uv pip install --pre "codeclone[mcp]"
-codeclone-mcp --help                # verify
+uv venv
+uv pip install --python .venv/bin/python "codeclone[mcp]>=2.0.0b4"
+.venv/bin/codeclone-mcp --help
+```
+
+Global fallback:
+
+```bash
+uv tool install "codeclone[mcp]>=2.0.0b4"
+codeclone-mcp --help
 ```
 
 Manual MCP registration without the plugin:
@@ -36,7 +44,7 @@ gets a local MCP definition and two skills. Does not mutate
 
 - if you already registered `codeclone-mcp` manually, keep only one setup path
   to avoid duplicate MCP surfaces
-- the bundled `.mcp.json` assumes `codeclone-mcp` resolves on `PATH`
+- the bundled `.mcp.json` prefers `.venv`, then a Poetry env, then `PATH`
 
 For the underlying interface contract, see:
 

docs/mcp.md

@@ -121,6 +121,8 @@ run-scoped URI templates.
 - Summary and triage projections keep interpretation compact: `health_scope`
   explains what the health score covers, `focus` explains the active view, and
   `new_by_source_kind` attributes new findings without widening the payload.
+- When baseline comparison is untrusted, summary and triage also expose
+  `baseline.compared_without_valid_baseline` plus baseline/runtime python tags.
 - Run IDs are 8-char hex handles; finding IDs are short prefixed forms.
   Both accept the full canonical form as input.
 - `metrics_detail(family="overloaded_modules")` exposes the report-only

docs/vscode-extension.md

@@ -30,7 +30,7 @@ The extension needs a local `codeclone-mcp` launcher.
 Minimum supported CodeClone version: `2.0.0b4`.
 
 In `auto` mode, it checks the current workspace virtualenv before falling back
-to `PATH`.
+to `PATH`. Runtime and version-mismatch messages identify that resolved launcher source.
 
 Recommended install for the preview extension:
 

extensions/claude-desktop-codeclone/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "codeclone",
   "display_name": "CodeClone",
-  "version": "2.0.0-b4.0",
+  "version": "2.0.0-b5.0",
   "description": "Baseline-aware structural review for Claude Desktop through a local CodeClone MCP launcher.",
   "long_description": "CodeClone for Claude Desktop wraps the local codeclone-mcp launcher as an MCP bundle. It keeps Claude on the same canonical MCP surface used by the CLI, HTML report, VS Code extension, and Codex plugin — read-only, baseline-aware, local stdio only.",
   "author": {