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

@@ -7,6 +7,8 @@
 - Bump canonical report schema to `2.4` for `meta.analysis_profile`.
 - Surface the effective runtime analysis profile (`min_loc`, `min_stmt`, block, and segment thresholds) in canonical
   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.
 - Refresh branch metadata and client docs for the `2.0.0b5` line.
 - Update the README repository health badge to `87 (B)`.
 

README.md

@@ -162,6 +162,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.
 
 ```bash
 uv tool install --pre "codeclone[mcp]"       # or: uv pip install --pre "codeclone[mcp]"

codeclone/mcp_service.py

@@ -157,9 +157,15 @@
     "changed",
     "integrity",
 ]
+HealthScope = Literal["repository"]
+SummaryFocus = Literal["repository", "production", "changed_paths"]
 
 _LEGACY_CACHE_PATH = Path("~/.cache/codeclone/cache.json").expanduser()
 _REPORT_DUMMY_PATH = Path(".cache/codeclone/report.json")
+_HEALTH_SCOPE_REPOSITORY: Final[HealthScope] = "repository"
+_FOCUS_REPOSITORY: Final[SummaryFocus] = "repository"
+_FOCUS_PRODUCTION: Final[SummaryFocus] = "production"
+_FOCUS_CHANGED_PATHS: Final[SummaryFocus] = "changed_paths"
 _MCP_CONFIG_KEYS = frozenset(
     {
         "min_loc",
@@ -1662,11 +1668,20 @@ def get_production_triage(
         ]
         payload: dict[str, object] = {
             "run_id": self._short_run_id(record.run_id),
+            "focus": _FOCUS_PRODUCTION,
+            "health_scope": _HEALTH_SCOPE_REPOSITORY,
             "health": dict(self._summary_health_payload(summary)),
             "cache": dict(self._as_mapping(summary.get("cache"))),
             "findings": {
                 "total": len(findings),
                 "by_source_kind": findings_breakdown,
+                "new_by_source_kind": dict(
+                    self._as_mapping(
+                        self._as_mapping(summary.get("findings")).get(
+                            "new_by_source_kind"
+                        )
+                    )
+                ),
                 "outside_focus": len(findings)
                 - findings_breakdown[SOURCE_KIND_PRODUCTION],
             },
@@ -3228,13 +3243,19 @@ def _build_changed_projection(
         known_count = sum(
             1 for item in items if str(item.get("novelty", "")) == "known"
         )
+        new_by_source_kind = self._source_kind_breakdown(
+            item.get("source_kind")
+            for item in items
+            if str(item.get("novelty", "")) == "new"
+        )
         health_delta = self._summary_health_delta(record.summary)
         return {
             "run_id": self._short_run_id(record.run_id),
             "changed_paths": list(record.changed_paths),
             "total": len(items),
             "new": new_count,
             "known": known_count,
+            "new_by_source_kind": new_by_source_kind,
             "items": items,
             "health": dict(self._summary_health_payload(record.summary)),
             "health_delta": health_delta,
@@ -3260,6 +3281,8 @@ def _changed_analysis_payload(
         )
         return {
             "run_id": self._short_run_id(record.run_id),
+            "focus": _FOCUS_CHANGED_PATHS,
+            "health_scope": _HEALTH_SCOPE_REPOSITORY,
             "changed_files": len(record.changed_paths),
             "health": health_payload,
             "analysis_profile": self._summary_analysis_profile_payload(record.summary),
@@ -3270,6 +3293,9 @@ def _changed_analysis_payload(
             ),
             "verdict": str(changed_projection.get("verdict", "stable")),
             "new_findings": _as_int(changed_projection.get("new", 0), 0),
+            "new_by_source_kind": dict(
+                self._as_mapping(changed_projection.get("new_by_source_kind"))
+            ),
             "resolved_findings": 0,
             "changed_findings": [],
         }
@@ -4003,6 +4029,8 @@ def _summary_payload(
             and not summary.get("baseline")
         ):
             return {
+                "focus": _FOCUS_REPOSITORY,
+                "health_scope": _HEALTH_SCOPE_REPOSITORY,
                 "inventory": self._summary_inventory_payload(inventory),
                 "health": self._summary_health_payload(summary),
             }
@@ -4011,6 +4039,8 @@ def _summary_payload(
         )
         payload: dict[str, object] = {
             "run_id": self._short_run_id(resolved_run_id) if resolved_run_id else "",
+            "focus": _FOCUS_REPOSITORY,
+            "health_scope": _HEALTH_SCOPE_REPOSITORY,
             "version": str(summary.get("codeclone_version", __version__)),
             "schema": str(summary.get("report_schema_version", REPORT_SCHEMA_VERSION)),
             "mode": str(summary.get("analysis_mode", "")),
@@ -4149,6 +4179,7 @@ def _summary_findings_payload(
                 "known": 0,
                 "by_family": {},
                 "production": 0,
+                "new_by_source_kind": self._source_kind_breakdown(()),
             }
         findings = self._base_findings(record)
         by_family: dict[str, int] = {
@@ -4160,6 +4191,11 @@ def _summary_findings_payload(
         new_count = 0
         known_count = 0
         production_count = 0
+        new_by_source_kind = self._source_kind_breakdown(
+            self._finding_source_kind(finding)
+            for finding in findings
+            if str(finding.get("novelty", "")).strip() == "new"
+        )
         for finding in findings:
             family = str(finding.get("family", "")).strip()
             family_key = "clones" if family == FAMILY_CLONE else family
@@ -4177,6 +4213,7 @@ def _summary_findings_payload(
             "known": known_count,
             "by_family": {key: value for key, value in by_family.items() if value > 0},
             "production": production_count,
+            "new_by_source_kind": new_by_source_kind,
         }
 
     def _summary_diff_payload(

docs/book/01-architecture-map.md

@@ -68,6 +68,9 @@ Refs:
 - The same rule applies to summary cache convenience fields such as
   `freshness` and to production-first triage projections built from
   canonical hotlists/suggestions.
+- The same rule also applies to compact interpretation hints such as
+  `health_scope`, `focus`, and `new_by_source_kind`: they clarify projection
+  meaning without introducing a second report truth.
 - MCP finding lists may also expose short run/finding ids and slimmer relative
   location projections, while keeping `get_finding(detail_level="full")` as the
   richer per-finding inspection path.

docs/book/14-compatibility-and-versioning.md

@@ -56,7 +56,8 @@ Version bump rules:
   short MCP ids, slim summary locations, or omitting `priority_factors`
   outside `detail_level="full"`.
 - Additive MCP-only convenience fields/projections such as
-  `cache.freshness` or production-first triage also do not change
+  `cache.freshness`, production-first triage, `health_scope`, `focus`, or
+  `new_by_source_kind` also do not change
   `report_schema_version` when they are derived from unchanged canonical report
   and summary data.
 - The same rule applies to bounded MCP semantic guidance such as

docs/book/20-mcp-interface.md

@@ -56,17 +56,21 @@ Current server characteristics:
       `refresh` is rejected in MCP because the server is read-only.
 - summary payload:
     - `run_id`, `version`, `schema`, `mode`, compact `analysis_profile`
+    - `health_scope` explains what the health score covers
+    - `focus` explains the active summary/triage lens
     - `baseline`, `metrics_baseline`, `cache`
     - `cache.freshness` classifies summary cache reuse as `fresh`, `mixed`,
       or `reused`
     - flattened `inventory` (`files`, `lines`, `functions`, `classes`)
-    - flattened `findings` (`total`, `new`, `known`, `by_family`, `production`)
+    - flattened `findings` (`total`, `new`, `known`, `by_family`, `production`,
+      `new_by_source_kind`)
     - flattened `diff` (`new_clones`, `health_delta`)
     - `warnings`, `failures`
     - `analyze_changed_paths` is intentionally more compact than `get_run_summary`:
-      it returns `changed_files`, `health`, `health_delta`, `verdict`,
-      `new_findings`, `resolved_findings`, and an empty `changed_findings`
-      placeholder, while detailed changed payload stays in
+      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
+      detailed changed payload stays in
       `get_report_section(section="changed")`
 - workflow guidance:
     - the MCP surface is intentionally agent-guiding rather than list-first

docs/mcp.md

@@ -118,6 +118,9 @@ run-scoped URI templates.
 - `check_*` responses include only the relevant health dimension.
 - Finding responses use short MCP IDs and relative paths by default;
   `detail_level=full` restores the compatibility payload with URIs.
+- 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.
 - 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

extensions/vscode-codeclone/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Change Log
 
+## 0.2.2
+
+- surface repository-vs-focus semantics more clearly in triage and summary UX
+- explain new findings by source kind without widening the review flow
+
 ## 0.2.1
 
 - refresh packaged extension metadata for prerelease validation

extensions/vscode-codeclone/package-lock.json

@@ -2,7 +2,7 @@
   "name": "codeclone",
   "displayName": "CodeClone",
   "description": "Baseline-aware, triage-first structural review for Python, powered by CodeClone MCP.",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "preview": true,
   "publisher": "orenlab",
   "license": "MPL-2.0",