feat(cli): show human-readable violation explanations in text output

- Render `explain_violation()` output instead of raw violation messages
- Improve dependency/node explanation phrasing and add dep-type verb mapping
- Document example CLI output and explanation behavior
- Add/adjust tests to assert explanations across verbosity levels

Author: akhundMurad

docs/cli.md

@@ -46,6 +46,21 @@ pacta scan . --model architecture.yml --rules rules.pacta.yml --baseline baselin
 pacta scan . --model architecture.yml --rules rules.pacta.yml --format json
 ```
 
+**Example output:**
+
+```
+✗ 1 violations (1 error)
+
+  ✗ ERROR [no-domain-infra] Domain cannot depend on Infrastructure @ src/domain/service.py:5:1
+    status: new
+    "app.domain.BillingService" in domain layer imports "app.infra.PostgresClient" in infra layer
+```
+
+Violations are displayed with human-readable explanations:
+
+- **For dependency violations:** Shows which module imports/calls/uses another, with their respective layers
+- **For node violations:** Shows the element type and where it was found (layer, container, context)
+
 ## snapshot save
 
 Save architecture snapshot without running rules.

pacta/reporting/renderers/text.py

@@ -1,6 +1,7 @@
 from typing import Literal
 
 from pacta.reporting.types import EngineError, Report, Violation
+from pacta.rules.explain import explain_violation
 
 Verbosity = Literal["quiet", "normal", "verbose"]
 
@@ -166,7 +167,8 @@ def _render_violation(self, v: Violation, verbosity: Verbosity) -> list[str]:
         # Always show status
         out.append(f"    status: {v.status}")
 
-        out.append(f"    {v.message}")
+        # Always show human-readable explanation
+        out.append(f"    {explain_violation(v)}")
 
         # Show suggestion in normal and verbose modes
         if verbosity in ("normal", "verbose") and v.suggestion:

pacta/rules/explain.py

@@ -10,48 +10,65 @@
 
 def explain_violation(v: Violation) -> str:
     """
-    Turn a Violation into a compact explanation suitable for CLI/IDE tooltips.
+    Turn a Violation into a human-readable explanation suitable for CLI/IDE tooltips.
     """
     ctx = v.context or {}
     target = ctx.get("target")
 
     if target == "dependency":
-        dep_type = ctx.get("dep_type", "?")
-        src = ctx.get("src_fqname") or ctx.get("src_id") or "<?>"
-        dst = ctx.get("dst_fqname") or ctx.get("dst_id") or "<?>"
+        dep_type = ctx.get("dep_type", "dependency")
+        src = ctx.get("src_fqname") or ctx.get("src_id") or "unknown"
+        dst = ctx.get("dst_fqname") or ctx.get("dst_id") or "unknown"
         src_layer = ctx.get("src_layer")
         dst_layer = ctx.get("dst_layer")
 
-        parts: list[str] = []
-        parts.append(f"Dependency violation ({dep_type}).")
-        parts.append(f"{src} -> {dst}")
-        if src_layer or dst_layer:
-            parts.append(f"layers: {src_layer or '?'} -> {dst_layer or '?'}")
-        return " ".join(parts)
+        # Build natural language explanation
+        verb = _dep_type_verb(dep_type)
+
+        if src_layer and dst_layer:
+            return f'"{src}" in {src_layer} layer {verb} "{dst}" in {dst_layer} layer'
+        else:
+            return f'"{src}" {verb} "{dst}"'
 
     if target == "node":
-        ident = ctx.get("fqname") or ctx.get("node_id") or "<?>"
-        kind = ctx.get("kind", "?")
+        ident = ctx.get("fqname") or ctx.get("node_id") or "unknown"
+        kind = ctx.get("kind", "element")
         layer = ctx.get("layer")
-        context = ctx.get("context")
+        context_name = ctx.get("context")
         container = ctx.get("container")
 
-        parts = [f"Node violation ({kind}): {ident}"]
-        extras = []
+        # Build natural language explanation
+        location_parts = []
         if layer:
-            extras.append(f"layer={layer}")
-        if context:
-            extras.append(f"context={context}")
+            location_parts.append(f"{layer} layer")
         if container:
-            extras.append(f"container={container}")
-        if extras:
-            parts.append(f"({', '.join(extras)})")
-        return " ".join(parts)
+            location_parts.append(f"container {container}")
+        if context_name:
+            location_parts.append(f"context {context_name}")
+
+        if location_parts:
+            location = ", ".join(location_parts)
+            return f'{kind} "{ident}" found in {location}'
+        else:
+            return f'{kind} "{ident}" violates architectural constraint'
 
     # Fallback
     return v.message
 
 
+def _dep_type_verb(dep_type: str) -> str:
+    """Convert dependency type to a human-readable verb."""
+    verbs = {
+        "import": "imports",
+        "call": "calls",
+        "inherit": "inherits from",
+        "instantiate": "instantiates",
+        "use": "uses",
+        "reference": "references",
+    }
+    return verbs.get(dep_type, f"depends on ({dep_type})")
+
+
 def explain_rule(rule: Rule) -> str:
     """
     Explain a compiled Rule at a high level (for listing rules, debug output).

tests/cli/test_cli.py

@@ -298,6 +298,79 @@ def test_scan_mode_changed_only(self, tmp_path):
         assert mock_scan.call_args.kwargs["mode"] == "changed_only"
 
 
+class TestHumanReadableOutput:
+    """Tests for human-readable violation output (always enabled by default)."""
+
+    def test_scan_shows_human_readable_explanation(self, tmp_path, capsys):
+        """Test that scan command shows human-readable explanations by default."""
+        repo_root = tmp_path / "repo"
+        repo_root.mkdir()
+
+        violation = Violation(
+            rule=RuleRef(
+                id="test_rule",
+                name="Test Rule",
+                severity=Severity.ERROR,
+            ),
+            message="Test violation message",
+            location=None,
+            status="new",
+            context={
+                "target": "dependency",
+                "dep_type": "import",
+                "src_fqname": "app.domain",
+                "dst_fqname": "app.infra",
+                "src_layer": "domain",
+                "dst_layer": "infra",
+            },
+        )
+
+        mock_report = create_test_report(repo_root, violations=[violation])
+
+        with patch("pacta.cli.scan.run_engine_scan", return_value=mock_report):
+            exit_code = main(["scan", str(repo_root)])
+
+        assert exit_code == 1  # Has violations
+        captured = capsys.readouterr()
+        # Human-readable explanation is always shown
+        assert "app.domain" in captured.out
+        assert "app.infra" in captured.out
+        assert "imports" in captured.out
+
+    def test_scan_verbose_shows_human_readable_explanation(self, tmp_path, capsys):
+        """Test that verbose mode also shows human-readable explanations."""
+        repo_root = tmp_path / "repo"
+        repo_root.mkdir()
+
+        violation = Violation(
+            rule=RuleRef(
+                id="test_rule",
+                name="Test Rule",
+                severity=Severity.ERROR,
+            ),
+            message="Test violation message",
+            location=None,
+            status="new",
+            context={
+                "target": "dependency",
+                "dep_type": "import",
+                "src_fqname": "app.domain",
+                "dst_fqname": "app.infra",
+            },
+        )
+
+        mock_report = create_test_report(repo_root, violations=[violation])
+
+        with patch("pacta.cli.scan.run_engine_scan", return_value=mock_report):
+            exit_code = main(["scan", str(repo_root), "--verbose"])
+
+        assert exit_code == 1
+        captured = capsys.readouterr()
+        # Should have explanation and verbose details
+        assert "imports" in captured.out
+        assert "Summary:" in captured.out  # verbose marker
+
+
 class TestErrorHandling:
     """Tests for CLI error handling."""
 

tests/reporting/test_reporting.py

@@ -448,6 +448,101 @@ def test_text_renderer_normal_no_violations(runinfo):
     assert "✓ No violations" in text
 
 
+# ----------------------------
+# Tests: TextReportRenderer human-readable explanations (always enabled)
+# ----------------------------
+
+
+def test_text_renderer_shows_human_readable_explanation(runinfo):
+    from pacta.reporting.builder import DefaultReportBuilder
+    from pacta.reporting.renderers.text import TextReportRenderer
+
+    violations = [
+        {
+            "rule": {"id": "r1", "name": "No domain -> infra", "severity": "error"},
+            "message": "Domain depends on Infra",
+            "status": "new",
+            "context": {
+                "target": "dependency",
+                "dep_type": "import",
+                "src_fqname": "app.domain.service",
+                "dst_fqname": "app.infra.database",
+                "src_layer": "domain",
+                "dst_layer": "infra",
+            },
+        }
+    ]
+    report = DefaultReportBuilder(tool="pacta", version="0.1.0").build(run=runinfo, violations=violations)
+    text = TextReportRenderer(verbosity="normal").render(report)
+
+    # Should contain human-readable explanation by default
+    assert "app.domain.service" in text
+    assert "app.infra.database" in text
+    assert "domain layer" in text
+    assert "infra layer" in text
+    assert "imports" in text
+
+
+def test_text_renderer_node_violation_shows_explanation(runinfo):
+    from pacta.reporting.builder import DefaultReportBuilder
+    from pacta.reporting.renderers.text import TextReportRenderer
+
+    violations = [
+        {
+            "rule": {"id": "r2", "name": "No services in domain", "severity": "warning"},
+            "message": "Services should not be in domain layer",
+            "status": "new",
+            "context": {
+                "target": "node",
+                "fqname": "app.domain.BillingService",
+                "kind": "class",
+                "layer": "domain",
+                "container": "backend",
+            },
+        }
+    ]
+    report = DefaultReportBuilder(tool="pacta", version="0.1.0").build(run=runinfo, violations=violations)
+    text = TextReportRenderer(verbosity="normal").render(report)
+
+    # Should contain human-readable node violation explanation
+    assert "class" in text
+    assert "app.domain.BillingService" in text
+    assert "domain layer" in text
+    assert "container backend" in text
+
+
+def test_text_renderer_explanation_works_with_all_verbosity_levels(runinfo):
+    from pacta.reporting.builder import DefaultReportBuilder
+    from pacta.reporting.renderers.text import TextReportRenderer
+
+    violations = [
+        {
+            "rule": {"id": "r1", "name": "Test", "severity": "error"},
+            "message": "Test message",
+            "status": "new",
+            "context": {
+                "target": "dependency",
+                "dep_type": "import",
+                "src_fqname": "a.b",
+                "dst_fqname": "c.d",
+            },
+        }
+    ]
+    report = DefaultReportBuilder(tool="pacta", version="0.1.0").build(run=runinfo, violations=violations)
+
+    # Test with normal verbosity - should show human-readable explanation
+    text_normal = TextReportRenderer(verbosity="normal").render(report)
+    assert "imports" in text_normal
+
+    # Test with verbose verbosity - should also show explanation
+    text_verbose = TextReportRenderer(verbosity="verbose").render(report)
+    assert "imports" in text_verbose
+
+    # quiet mode doesn't show violations
+    text_quiet = TextReportRenderer(verbosity="quiet").render(report)
+    assert "imports" not in text_quiet  # quiet mode only shows summary
+
+
 # ----------------------------
 # Edge-cases: normalization of partial locations
 # ----------------------------

tests/rules/test_explain.py

@@ -32,12 +32,12 @@ def test_explain_violation_dependency_contains_key_info():
     )
 
     text = explain_violation(v)
-    assert "Dependency violation" in text
-    assert "import" in text
+    # Human-readable format: "X" in Y layer imports "Z" in W layer
     assert "app.domain" in text
     assert "app.infra.db" in text
-    assert "domain" in text
-    assert "infra" in text
+    assert "domain layer" in text
+    assert "infra layer" in text
+    assert "imports" in text
 
 
 def test_explain_violation_dependency_falls_back_to_ids_if_fqname_missing():
@@ -53,8 +53,10 @@ def test_explain_violation_dependency_falls_back_to_ids_if_fqname_missing():
     )
 
     text = explain_violation(v)
+    # Falls back to IDs when fqname not available
     assert "python://repo::a" in text
     assert "python://repo::b" in text
+    assert "imports" in text
 
 
 def test_explain_violation_node_contains_kind_and_identity():
@@ -72,12 +74,12 @@ def test_explain_violation_node_contains_kind_and_identity():
     )
 
     text = explain_violation(v)
-    assert "Node violation" in text
+    # Human-readable format: kind "name" found in layer, container, context
     assert "class" in text
     assert "app.domain.BillingService" in text
-    assert "layer=domain" in text
-    assert "context=billing" in text
-    assert "container=billing" in text
+    assert "domain layer" in text
+    assert "context billing" in text
+    assert "container billing" in text
 
 
 def test_explain_violation_unknown_target_falls_back_to_message():