refactor(copy): centralize user-facing strings across CLI, report, and MCP

Author: orenlab

AGENTS.md

@@ -410,6 +410,8 @@ Architecture is layered, but grounded in current code (not aspirational diagrams
 
 - **CLI entry + orchestration surface** (`codeclone/main.py`, `codeclone/surfaces/cli/*`, `codeclone/ui_messages/*`)
   owns argument parsing, runtime/config resolution, summaries, report writes, and exit routing.
+  User-facing copy lives in `ui_messages/` submodules (`help`, `labels`, `runtime`,
+  `markers`, `formatters`, `controller`, `styling`).
 - **Config layer** (`codeclone/config/*`) is the single source of truth for option specs, parser construction,
   `pyproject.toml` loading, and CLI > pyproject > defaults resolution.
 - **Core orchestration** (`codeclone/core/*`) owns bootstrap → discovery → worker processing → project metrics →
@@ -509,7 +511,8 @@ Use this map to route changes to the right owner module.
 - `codeclone/surfaces/mcp/server.py` — optional MCP launcher/server wiring, transport config, and MCP tool/resource
   registration; keep dependency loading lazy so base installs/CI do not require MCP runtime packages.
 - `codeclone/surfaces/mcp/messages/*` — MCP user-facing copy (tool/resource descriptions, help topics, workflow and
-  intent messages, parameter Field docs). Keep message policy centralized like `ui_messages/`.
+  intent messages, parameter Field docs, patch-contract hints, verification copy, remediation shapes). Keep message
+  policy centralized like `ui_messages/`.
 - `codeclone/audit/*` — audit event schema, validation, writer/reader; passive evidence only.
 - `codeclone/budget/*` — patch/token budget estimation shared by CLI and MCP surfaces.
 - `tests/test_mcp_service.py`, `tests/test_mcp_server.py` — MCP contract and integration tests; run these when
@@ -520,6 +523,9 @@ Use this map to route changes to the right owner module.
 - `codeclone/domain/*.py` — centralized domain taxonomies/IDs (families, categories, source scopes, risk/severity
   levels); use these constants in pipeline/report/UI instead of scattering raw literals.
 - `codeclone/ui_messages/*` — CLI text/marker/help constants and formatter helpers. Keep message policy centralized.
+- `codeclone/report/messages/*` — report-layer user copy (glossary, suggestions,
+  explainability, overview, security, chrome, text/markdown/sarif projections,
+  gate prefixes).
 - `docs/`, `mkdocs.yml`, `.github/workflows/docs.yml`, `scripts/build_docs_example_report.py` — docs-site source,
   publication workflow, and live sample-report generation; keep published docs aligned with code contracts.
 - `extensions/vscode-codeclone/*` — stable VS Code extension surface; keep it baseline-aware, triage-first,
@@ -758,8 +764,9 @@ These rules exist because of real incidents in this repo. They are non-negotiabl
   `codeclone/report/html/assets/*`) are imported, not duplicated locally inside
   `codeclone/report/html/sections/*`.
   If you need a helper that doesn't exist, add it to the shared module.
-- Glossary terms used in stat-card labels live in `codeclone/report/html/widgets/glossary.py`. Adding a
-  new label without a glossary entry is a contract gap.
+- Glossary term definitions live in `codeclone/report/messages/glossary.py`;
+  `codeclone/report/html/widgets/glossary.py` renders HTML tooltips from that
+  catalog. Adding a new stat-card label without a glossary entry is a contract gap.
 
 ### Conflict avoidance
 

CHANGELOG.md

@@ -33,9 +33,15 @@ review receipts, and workflow consolidation tools.
 - CLI controller query modes: `--blast-radius` and `--patch-verify`.
 - Audit trail events for intent lifecycle and token budget tracking.
 - MCP tool JSON schemas now include concise per-parameter descriptions.
-- MCP message catalog at `codeclone/surfaces/mcp/messages/*` for tool/resource
-  descriptions, help topics, workflow/intent copy, and parameter Field docs
-  (mirrors CLI `ui_messages/`).
+- Split monolithic `codeclone/ui_messages/__init__.py` into focused modules
+  (`help`, `labels`, `runtime`, `markers`, `formatters`, `controller`, `styling`;
+  stable names re-exported from `__init__.py`).
+- `codeclone/report/messages/glossary.py` for HTML tooltip definitions.
+- `codeclone/report/messages/` modules for suggestions, explainability, overview,
+  security, chrome, projections, gate reason prefixes, plus `markdown.py` and
+  `sarif.py` for Markdown/SARIF projection copy.
+- MCP `messages/patch_contract`, `verification`, `remediation`, `errors`,
+  `receipt`, `claims`, and `blast_radius` modules.
 - `help(detail="compact")` includes `anti_patterns`; `trust_boundaries` help topic.
 - Analyze responses include a single `next_tool` hint; summary adds
   `security_surfaces.note` for report-only inventory semantics.
@@ -48,6 +54,16 @@ review receipts, and workflow consolidation tools.
 - MCP long UI strings moved out of `server.py`, `_session_shared.py`, and session
   mixins into `codeclone/surfaces/mcp/messages/*`; `_tool_param_docs.py` re-exports
   `messages/params.py`.
+- Controller CLI screen copy centralized in `ui_messages/controller.py`.
+- HTML glossary terms moved to `report/messages/glossary.py`.
+- Report suggestion/explainability copy moved to `report/messages/*`; gate reason
+  prefixes shared between `gates/evaluator.py` and `gates/reasons.py`.
+- Text, Markdown, and SARIF renderers and HTML overview/structural/security/chrome
+  sections consume `report/messages/*` instead of inline copy.
+- MCP tool/resource `title=` strings centralized in `messages/tools.py` and
+  `messages/resources.py`; validation errors use `messages/errors.py`.
+- MCP receipt, claim-guard, and blast-radius user copy moved to
+  `surfaces/mcp/messages/*`.
 - `pydantic` is now a base dependency (MCP schema export today; validation
   migration planned separately).
 - MCP always loads `golden_fixture_paths` from pyproject governance keys even when

codeclone/report/gates/evaluator.py

@@ -15,6 +15,7 @@
 from ...utils.coerce import as_int as _as_int
 from ...utils.coerce import as_mapping as _as_mapping
 from ...utils.coerce import as_sequence as _as_sequence
+from ..messages import gates as gate_msgs
 
 if TYPE_CHECKING:
     from ...models import CoverageJoinResult, ProjectMetrics
@@ -271,9 +272,9 @@ def _complexity_threshold_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         0 <= config.fail_complexity < state.complexity_max,
-        "Complexity threshold exceeded: "
-        f"max CC={state.complexity_max}, "
-        f"threshold={config.fail_complexity}.",
+        gate_msgs.GATE_REASON_COMPLEXITY_THRESHOLD
+        + f"max CC={state.complexity_max}, "
+        + f"threshold={config.fail_complexity}.",
     )
 
 
@@ -284,9 +285,9 @@ def _coupling_threshold_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         0 <= config.fail_coupling < state.coupling_max,
-        "Coupling threshold exceeded: "
-        f"max CBO={state.coupling_max}, "
-        f"threshold={config.fail_coupling}.",
+        gate_msgs.GATE_REASON_COUPLING_THRESHOLD
+        + f"max CBO={state.coupling_max}, "
+        + f"threshold={config.fail_coupling}.",
     )
 
 
@@ -297,9 +298,9 @@ def _cohesion_threshold_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         0 <= config.fail_cohesion < state.cohesion_max,
-        "Cohesion threshold exceeded: "
-        f"max LCOM4={state.cohesion_max}, "
-        f"threshold={config.fail_cohesion}.",
+        gate_msgs.GATE_REASON_COHESION_THRESHOLD
+        + f"max LCOM4={state.cohesion_max}, "
+        + f"threshold={config.fail_cohesion}.",
     )
 
 
@@ -310,8 +311,8 @@ def _health_threshold_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         config.fail_health >= 0 and state.health_score < config.fail_health,
-        "Health score below threshold: "
-        f"score={state.health_score}, threshold={config.fail_health}.",
+        gate_msgs.GATE_REASON_HEALTH_THRESHOLD
+        + f"score={state.health_score}, threshold={config.fail_health}.",
     )
 
 
@@ -322,7 +323,7 @@ def _dependency_cycles_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         config.fail_cycles and state.dependency_cycles > 0,
-        f"Dependency cycles detected: {state.dependency_cycles} cycle(s).",
+        f"{gate_msgs.GATE_REASON_CYCLES_DETECTED}{state.dependency_cycles}{gate_msgs.GATE_SUFFIX_CYCLES}.",
     )
 
 
@@ -333,7 +334,7 @@ def _dead_code_high_confidence_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         config.fail_dead_code and state.dead_high_confidence > 0,
-        f"Dead code detected (high confidence): {state.dead_high_confidence} item(s).",
+        f"{gate_msgs.GATE_REASON_DEAD_CODE_DETECTED}{state.dead_high_confidence}{gate_msgs.GATE_SUFFIX_ITEMS}.",
     )
 
 
@@ -344,8 +345,7 @@ def _new_high_risk_functions_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         config.fail_on_new_metrics and state.diff_new_high_risk_functions > 0,
-        "New high-risk functions vs metrics baseline: "
-        f"{state.diff_new_high_risk_functions}.",
+        f"{gate_msgs.GATE_REASON_NEW_HIGH_RISK_FUNCTIONS}{state.diff_new_high_risk_functions}.",
     )
 
 
@@ -356,8 +356,7 @@ def _new_high_coupling_classes_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         config.fail_on_new_metrics and state.diff_new_high_coupling_classes > 0,
-        "New high-coupling classes vs metrics baseline: "
-        f"{state.diff_new_high_coupling_classes}.",
+        f"{gate_msgs.GATE_REASON_NEW_HIGH_COUPLING}{state.diff_new_high_coupling_classes}.",
     )
 
 
@@ -368,7 +367,7 @@ def _new_dependency_cycles_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         config.fail_on_new_metrics and state.diff_new_cycles > 0,
-        f"New dependency cycles vs metrics baseline: {state.diff_new_cycles}.",
+        f"{gate_msgs.GATE_REASON_NEW_CYCLES}{state.diff_new_cycles}.",
     )
 
 
@@ -379,7 +378,7 @@ def _new_dead_code_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         config.fail_on_new_metrics and state.diff_new_dead_code > 0,
-        f"New dead code items vs metrics baseline: {state.diff_new_dead_code}.",
+        f"{gate_msgs.GATE_REASON_NEW_DEAD_CODE}{state.diff_new_dead_code}.",
     )
 
 
@@ -390,7 +389,7 @@ def _health_regression_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         config.fail_on_new_metrics and state.diff_health_delta < 0,
-        f"Health score regressed vs metrics baseline: delta={state.diff_health_delta}.",
+        f"{gate_msgs.GATE_REASON_HEALTH_REGRESSION}{state.diff_health_delta}.",
     )
 
 
@@ -403,8 +402,8 @@ def _typing_coverage_threshold_reason(
     return _reason_if(
         config.min_typing_coverage >= 0
         and typing_percent < float(config.min_typing_coverage),
-        "Typing coverage below threshold: "
-        f"coverage={typing_percent:.1f}%, threshold={config.min_typing_coverage}%.",
+        gate_msgs.GATE_REASON_TYPING_THRESHOLD
+        + f"coverage={typing_percent:.1f}%, threshold={config.min_typing_coverage}%.",
     )
 
 
@@ -417,9 +416,9 @@ def _docstring_coverage_threshold_reason(
     return _reason_if(
         config.min_docstring_coverage >= 0
         and docstring_percent < float(config.min_docstring_coverage),
-        "Docstring coverage below threshold: "
-        f"coverage={docstring_percent:.1f}%, "
-        f"threshold={config.min_docstring_coverage}%.",
+        gate_msgs.GATE_REASON_DOCSTRING_THRESHOLD
+        + f"coverage={docstring_percent:.1f}%, "
+        + f"threshold={config.min_docstring_coverage}%.",
     )
 
 
@@ -434,9 +433,9 @@ def _typing_regression_reason(
             state.diff_typing_param_permille_delta < 0
             or state.diff_typing_return_permille_delta < 0
         ),
-        "Typing coverage regressed vs metrics baseline: "
-        f"params_delta={state.diff_typing_param_permille_delta}, "
-        f"returns_delta={state.diff_typing_return_permille_delta}.",
+        gate_msgs.GATE_REASON_TYPING_REGRESSION
+        + f"params_delta={state.diff_typing_param_permille_delta}, "
+        + f"returns_delta={state.diff_typing_return_permille_delta}.",
     )
 
 
@@ -447,8 +446,7 @@ def _docstring_regression_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         config.fail_on_docstring_regression and state.diff_docstring_permille_delta < 0,
-        "Docstring coverage regressed vs metrics baseline: "
-        f"delta={state.diff_docstring_permille_delta}.",
+        f"{gate_msgs.GATE_REASON_DOCSTRING_REGRESSION}{state.diff_docstring_permille_delta}.",
     )
 
 
@@ -459,8 +457,7 @@ def _api_breaking_changes_reason(
 ) -> tuple[str, ...]:
     return _reason_if(
         config.fail_on_api_break and state.api_breaking_changes > 0,
-        "Public API breaking changes vs metrics baseline: "
-        f"{state.api_breaking_changes}.",
+        f"{gate_msgs.GATE_REASON_API_BREAKING}{state.api_breaking_changes}.",
     )
 
 
@@ -473,9 +470,9 @@ def _coverage_hotspots_reason(
         config.fail_on_untested_hotspots
         and state.coverage_join_status == "ok"
         and state.coverage_hotspots > 0,
-        "Coverage hotspots detected: "
-        f"hotspots={state.coverage_hotspots}, "
-        f"threshold={config.coverage_min}%.",
+        gate_msgs.GATE_REASON_COVERAGE_HOTSPOTS
+        + f"hotspots={state.coverage_hotspots}, "
+        + f"threshold={config.coverage_min}%.",
     )
 
 

codeclone/report/gates/reasons.py

@@ -8,6 +8,8 @@
 
 from typing import Protocol
 
+from ..messages import gates as gate_msgs
+
 __all__ = [
     "parse_metric_reason_entry",
     "policy_context",
@@ -65,58 +67,53 @@ def tail(prefix: str) -> str:
         return trimmed[len(prefix) :]
 
     simple_prefixes: tuple[tuple[str, str], ...] = (
-        ("New high-risk functions vs metrics baseline: ", "new_high_risk_functions"),
-        (
-            "New high-coupling classes vs metrics baseline: ",
-            "new_high_coupling_classes",
-        ),
-        ("New dependency cycles vs metrics baseline: ", "new_dependency_cycles"),
-        ("New dead code items vs metrics baseline: ", "new_dead_code_items"),
+        (gate_msgs.GATE_REASON_NEW_HIGH_RISK_FUNCTIONS, "new_high_risk_functions"),
+        (gate_msgs.GATE_REASON_NEW_HIGH_COUPLING, "new_high_coupling_classes"),
+        (gate_msgs.GATE_REASON_NEW_CYCLES, "new_dependency_cycles"),
+        (gate_msgs.GATE_REASON_NEW_DEAD_CODE, "new_dead_code_items"),
     )
     for prefix, kind in simple_prefixes:
         if trimmed.startswith(prefix):
             return kind, tail(prefix)
 
-    if trimmed.startswith("Health score regressed vs metrics baseline: delta="):
+    if trimmed.startswith(gate_msgs.GATE_REASON_HEALTH_REGRESSION):
         return "health_delta", trimmed.rsplit("=", maxsplit=1)[1]
     typing_detail = _parse_two_part_metric_detail(
         trimmed,
-        prefix="Typing coverage regressed vs metrics baseline: ",
+        prefix=gate_msgs.GATE_REASON_TYPING_REGRESSION,
         right_label="returns_delta",
     )
     if typing_detail is not None:
         return "typing_coverage_delta", typing_detail
-    if trimmed.startswith("Docstring coverage regressed vs metrics baseline: delta="):
+    if trimmed.startswith(gate_msgs.GATE_REASON_DOCSTRING_REGRESSION):
         return "docstring_coverage_delta", trimmed.rsplit("=", maxsplit=1)[1]
-    if trimmed.startswith("Public API breaking changes vs metrics baseline: "):
-        return "api_breaking_changes", tail(
-            "Public API breaking changes vs metrics baseline: "
-        )
+    if trimmed.startswith(gate_msgs.GATE_REASON_API_BREAKING):
+        return "api_breaking_changes", tail(gate_msgs.GATE_REASON_API_BREAKING)
     coverage_detail = _parse_two_part_metric_detail(
         trimmed,
-        prefix="Coverage hotspots detected: ",
+        prefix=gate_msgs.GATE_REASON_COVERAGE_HOTSPOTS,
         right_label="threshold",
     )
     if coverage_detail is not None:
         return "coverage_hotspots", coverage_detail
 
-    if trimmed.startswith("Dependency cycles detected: "):
-        return "dependency_cycles", tail("Dependency cycles detected: ").replace(
-            " cycle(s)", ""
+    if trimmed.startswith(gate_msgs.GATE_REASON_CYCLES_DETECTED):
+        return "dependency_cycles", tail(gate_msgs.GATE_REASON_CYCLES_DETECTED).replace(
+            gate_msgs.GATE_SUFFIX_CYCLES, ""
         )
 
-    if trimmed.startswith("Dead code detected (high confidence): "):
+    if trimmed.startswith(gate_msgs.GATE_REASON_DEAD_CODE_DETECTED):
         return "dead_code_items", tail(
-            "Dead code detected (high confidence): "
-        ).replace(" item(s)", "")
+            gate_msgs.GATE_REASON_DEAD_CODE_DETECTED
+        ).replace(gate_msgs.GATE_SUFFIX_ITEMS, "")
 
     threshold_prefixes: tuple[tuple[str, str], ...] = (
-        ("Complexity threshold exceeded: ", "complexity_max"),
-        ("Coupling threshold exceeded: ", "coupling_max"),
-        ("Cohesion threshold exceeded: ", "cohesion_max"),
-        ("Health score below threshold: ", "health_score"),
-        ("Typing coverage below threshold: ", "typing_coverage"),
-        ("Docstring coverage below threshold: ", "docstring_coverage"),
+        (gate_msgs.GATE_REASON_COMPLEXITY_THRESHOLD, "complexity_max"),
+        (gate_msgs.GATE_REASON_COUPLING_THRESHOLD, "coupling_max"),
+        (gate_msgs.GATE_REASON_COHESION_THRESHOLD, "cohesion_max"),
+        (gate_msgs.GATE_REASON_HEALTH_THRESHOLD, "health_score"),
+        (gate_msgs.GATE_REASON_TYPING_THRESHOLD, "typing_coverage"),
+        (gate_msgs.GATE_REASON_DOCSTRING_THRESHOLD, "docstring_coverage"),
     )
     for prefix, kind in threshold_prefixes:
         threshold_detail = _parse_two_part_metric_detail(
@@ -203,7 +200,11 @@ def print_gating_failure_block(
     entries: tuple[tuple[str, object], ...] | list[tuple[str, object]],
     args: _GatingArgs,
 ) -> None:
-    console.print(f"\n\u2717 GATING FAILURE [{code}]", style="bold red", markup=False)
+    console.print(
+        f"\n\u2717 {gate_msgs.GATE_FAILURE_HEADER.format(code=code)}",
+        style="bold red",
+        markup=False,
+    )
     normalized_entries = [("policy", policy_context(args=args, gate_kind=code))]
     normalized_entries.extend((key, str(value)) for key, value in entries)
     width = max(len(key) for key, _ in normalized_entries)