sourcecode 1.30.13__py3-none-any.whl → 1.30.15__py3-none-any.whl

sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.30.13"
+__version__ = "1.30.15"

sourcecode/cli.py

@@ -1622,6 +1622,11 @@ def prepare_context_cmd(
         "--symptom",
         help="(fix-bug) Keyword hint for the bug: boosts matching files and surfaces related code notes.",
     ),
+    format: Optional[str] = typer.Option(
+        None,
+        "--format",
+        help="Output format: json (default) | github-comment (Markdown PR comment for review-pr task)",
+    ),
 ) -> None:
     """Task-specific context for AI coding agents.
 
@@ -1895,7 +1900,12 @@ def prepare_context_cmd(
     if llm_prompt:
         out["llm_prompt"] = builder.render_prompt(output)
 
-    _pc_content = json.dumps(out, indent=2, ensure_ascii=False)
+    if format == "github-comment" and task == "review-pr":
+        from sourcecode.pr_comment_renderer import render_github_comment
+        _pc_content = render_github_comment(out)
+    else:
+        _pc_content = json.dumps(out, indent=2, ensure_ascii=False)
+
     if output_path is not None:
         output_path.write_text(_pc_content, encoding="utf-8")
     else:

sourcecode/flow_analyzer.py

@@ -33,43 +33,57 @@ _METHOD_NAME_RE = re.compile(
     r'(\w+)\s*\(',
 )
 
-# Runtime signal patterns: (compiled_regex, note_text)
-# Only signals with explicit code evidence — no inference.
-# Three categories: condition | branch | async
-_RUNTIME_SIGNALS: list[tuple[re.Pattern, str]] = [
+# Runtime signal patterns: (compiled_regex, note_text, epistemic_level)
+# epistemic_level follows the 4-value contract:
+#   STRUCTURAL SIGNAL  — annotation or type-system evidence directly observed in source
+#   INFERRED (LOW CONFIDENCE) — heuristic code-pattern match; no full structural proof
+_RUNTIME_SIGNALS: list[tuple[re.Pattern, str, str]] = [
     # ── Conditional / auth guards ─────────────────────────────────────────────
     (re.compile(r'@PreAuthorize|@Secured|@RolesAllowed', re.IGNORECASE),
-     "condition: authorization check present (@PreAuthorize / @Secured)"),
+     "condition: authorization check present (@PreAuthorize / @Secured)",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'isAuthenticated\(\)|hasRole\(|hasAuthority\(|SecurityContextHolder', re.IGNORECASE),
-     "condition: reads authentication context"),
+     "condition: reads authentication context",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'featureFlag|FeatureToggle|\.isEnabled\s*\(|\.isActive\s*\(', re.IGNORECASE),
-     "condition: feature flag gates execution"),
+     "condition: feature flag gates execution",
+     "INFERRED (LOW CONFIDENCE)"),
     # Null/empty guard with early return — matches if (...null/empty...) return/throw on same line
     (re.compile(r'if\s*\([^)]*(?:==\s*null|!=\s*null|isEmpty\s*\(\)|isBlank\s*\(\))[^)]*\)'
                 r'\s*(?:\{?\s*)?(?:return|throw)\b', re.IGNORECASE),
-     "condition: null/empty guard with early return"),
+     "condition: null/empty guard with early return",
+     "STRUCTURAL SIGNAL"),
 
     # ── Optional execution / branching ────────────────────────────────────────
     (re.compile(r'@Cacheable|@CacheEvict|@CachePut', re.IGNORECASE),
-     "branch: Spring cache may short-circuit downstream call"),
+     "branch: Spring cache annotation present — downstream call may be short-circuited",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'\.getIfPresent\s*\(|cache\.get\s*\(|cacheManager\.', re.IGNORECASE),
-     "branch: manual cache lookup may short-circuit"),
+     "branch: manual cache lookup detected — downstream call may be short-circuited",
+     "INFERRED (LOW CONFIDENCE)"),
     (re.compile(r'Optional\s*<|\.orElseThrow\s*\(|\.orElseGet\s*\(|\.orElse\s*\(', re.IGNORECASE),
-     "branch: result may be absent (Optional)"),
+     "branch: Optional type in use — result may be absent",
+     "STRUCTURAL SIGNAL"),
 
     # ── Async / side effects ──────────────────────────────────────────────────
     (re.compile(r'@Async\b'),
-     "async: runs in separate thread (@Async)"),
+     "async: @Async annotation present — runs in separate thread",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'CompletableFuture|\.supplyAsync\s*\(|\.runAsync\s*\('),
-     "async: non-blocking future-based execution"),
+     "async: CompletableFuture detected — non-blocking execution",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'\basync\s+def\b|\bawait\b', re.IGNORECASE),
-     "async: non-blocking (async/await)"),
+     "async: async/await detected — non-blocking execution",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'publishEvent\s*\(|applicationEventPublisher|eventPublisher\.', re.IGNORECASE),
-     "async: Spring application event emitted"),
+     "async: Spring application event emitted",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'kafkaTemplate\.|KafkaProducer|@KafkaListener', re.IGNORECASE),
-     "async: Kafka message produced"),
+     "async: Kafka producer detected",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'rabbitTemplate\.|amqpTemplate\.|@RabbitListener', re.IGNORECASE),
-     "async: RabbitMQ message sent"),
+     "async: RabbitMQ producer detected",
+     "STRUCTURAL SIGNAL"),
 ]
 
 
@@ -98,18 +112,19 @@ def _read_safe(root: Path, rel_path: str) -> str:
         return ""
 
 
-def _collect_runtime_notes(content: str, lang: str) -> list[str]:
+def _collect_runtime_notes(content: str, lang: str) -> list[dict]:
     """Scan comment-stripped content for explicit runtime behavior signals.
 
     Returns only notes backed by a direct code pattern match.
+    Each entry: {note: str, epistemic_level: str}.
     Returns [] when no signals are found.
     """
     clean = _strip_comments(content, lang)
-    notes: list[str] = []
+    notes: list[dict] = []
     seen: set[str] = set()
-    for pattern, note in _RUNTIME_SIGNALS:
+    for pattern, note, epistemic_level in _RUNTIME_SIGNALS:
         if note not in seen and pattern.search(clean):
-            notes.append(note)
+            notes.append({"note": note, "epistemic_level": epistemic_level})
             seen.add(note)
     return notes
 
@@ -348,8 +363,11 @@ def analyze_execution_paths(
             "entry_point": {"step": entry_point_str, "notes": entry_notes},
             "path": path_items,
             "end_state": _detect_end_state([item["step"] for item in path_items]),
+            "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)",
         })
 
+    return result
+
 
 # ── Behavioral impact helpers ─────────────────────────────────────────────────
 
@@ -363,9 +381,13 @@ def _domain_from_class(class_name: str) -> str:
     return re.sub(r"(?<=[a-z])(?=[A-Z])", " ", stripped).strip().lower()
 
 
-def _impact_item(statement: str, support: str, certainty: str) -> dict:
-    truth_level = "observed" if certainty == "high" else "inferred"
-    return {"statement": statement, "support": support, "certainty": certainty, "truth_level": truth_level}
+def _impact_item(statement: str, support: str, certainty: str, *, epistemic_level: Optional[str] = None) -> dict:
+    if epistemic_level is None:
+        if certainty in ("high", "medium"):
+            epistemic_level = "STRUCTURAL SIGNAL"
+        else:
+            epistemic_level = "INFERRED (LOW CONFIDENCE)"
+    return {"statement": statement, "support": support, "epistemic_level": epistemic_level}
 
 
 def _impact_descriptions(
@@ -381,27 +403,27 @@ def _impact_descriptions(
 
     if changed_type in _REPO_ARTIFACT_TYPES:
         items.append(_impact_item(
-            f"{domain} persistence may be affected (inferred from path)" if domain else "persistence may be affected (inferred from path)",
-            f"{changed_class} classified as repository from path",
+            f"{domain} persistence layer modified" if domain else "persistence layer modified",
+            f"{changed_class} classified as {changed_type} (artifact_type evidence)",
             certainty,
         ))
     elif changed_type in _SERVICE_ARTIFACT_TYPES:
         if end_state == "DB write":
             items.append(_impact_item(
-                f"{domain} persistence may be affected (repository with DB write in path)" if domain else "persistence may be affected (repository with DB write in path)",
-                f"{changed_class} delegates to repository with DB write",
+                f"{domain} service layer: DB write in call path" if domain else "service layer: DB write in call path",
+                f"{changed_class} delegates to repository with DB write (code evidence)",
                 certainty,
             ))
         else:
             items.append(_impact_item(
-                f"{domain} behavior may change" if domain else "behavior may change",
-                f"{changed_class} is a service in path",
+                f"{domain} service layer modified" if domain else "service layer modified",
+                f"{changed_class} is a service (artifact_type={changed_type})",
                 certainty,
             ))
     else:
         items.append(_impact_item(
-            f"{domain} behavior may change" if domain else "behavior may change",
-            f"{changed_class} is in path",
+            f"{domain} component modified" if domain else "component modified",
+            f"{changed_class} found in traced call path (artifact_type={changed_type})",
             certainty,
         ))
 
@@ -440,15 +462,16 @@ def _impact_descriptions_for_controller(
                 domain = d
                 break
         items.append(_impact_item(
-            f"{domain} persistence may be affected (repository with DB write in path)" if domain else "data persistence may be affected (repository with DB write in path)",
-            "repository with DB write detected in path",
+            f"{domain} persistence layer: repository with DB write in call path" if domain else "persistence layer: repository with DB write in call path",
+            "repository with DB write detected in traced call path (code evidence)",
             certainty,
         ))
     else:
         items.append(_impact_item(
-            "request handler behavior may change",
             "controller entry point modified",
+            "controller entry point is in changed files (direct diff evidence)",
             certainty,
+            epistemic_level="FACT",
         ))
 
     if re.search(r"@PreAuthorize|@Secured|@RolesAllowed|hasRole\(|isAuthenticated", ctrl_clean, re.IGNORECASE):
@@ -541,6 +564,7 @@ def analyze_behavioral_impact(
             "affected_path": affected_path,
             "impact": _impact_descriptions_for_controller(affected_path, end_state, ctrl_clean, evidence_level),
             "end_state": end_state,
+            "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)",
             "confidence": confidence,
             "evidence_level": evidence_level,
             "trace": trace,
@@ -638,6 +662,7 @@ def analyze_behavioral_impact(
                 "affected_path": affected_path,
                 "impact": _impact_descriptions(changed_class, changed_type, end_state, ctrl_clean, evidence_level),
                 "end_state": end_state,
+                "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)",
                 "confidence": confidence,
                 "evidence_level": evidence_level,
                 "trace": trace,

sourcecode/pr_comment_renderer.py

@@ -0,0 +1,369 @@
+"""pr_comment_renderer.py — Renders review-pr output as a GitHub PR comment.
+
+Mandatory 5-section format:
+  1. PR Change Summary       — FACT only
+  2. Impacted Execution Flow — STRUCTURAL SIGNAL or FACT only, per-step evidence
+  3. Review Priority Order   — ranked by evidence-backed impact
+  4. Risk / Impact Signals   — labeled signals, never "risk" as conclusion
+  5. Review Guidance         — uncertain items, evidence gaps
+
+Contract:
+- Every statement carries an explicit epistemic label.
+- No speculation without label.
+- No hidden confidence blending.
+- Sections omitted when evidence is insufficient.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+_BADGE: dict[str, str] = {
+    "FACT":                      "`FACT`",
+    "STRUCTURAL SIGNAL":         "`STRUCTURAL SIGNAL`",
+    "INFERRED (LOW CONFIDENCE)": "`INFERRED (LOW CONFIDENCE)`",
+    "OMITTED":                   "`OMITTED`",
+}
+
+_STRUCTURAL_EVIDENCE = frozenset({"direct_injection", "direct_call"})
+
+_MAX_PRIORITY_FILES = 10
+_MAX_FLOW_PATHS = 3
+_MAX_SIGNALS = 12
+_MAX_UNCERTAIN = 6
+
+
+def _badge(level: str) -> str:
+    return _BADGE.get(level, f"`{level}`")
+
+
+def _short(path: str) -> str:
+    parts = Path(path).parts
+    return "/".join(parts[-2:]) if len(parts) > 2 else path
+
+
+def _evidence_to_epistemic(evidence_level: str) -> str:
+    if evidence_level in _STRUCTURAL_EVIDENCE:
+        return "STRUCTURAL SIGNAL"
+    if evidence_level == "heuristic_only":
+        return "INFERRED (LOW CONFIDENCE)"
+    return "OMITTED"
+
+
+# ── Section 1: PR Change Summary ──────────────────────────────────────────────
+
+def _section_change_summary(out: dict) -> str:
+    runtime: list[dict] = out.get("runtime_changes", [])
+    build: dict = out.get("build_changes", {})
+    build_files: list[str] = build.get("files", []) if build else []
+    base = out.get("base_ref") or out.get("since") or "HEAD~1"
+
+    committed: list[dict] = out.get("committed_changes", [])
+    uncommitted: list[dict] = out.get("uncommitted_changes", [])
+
+    lines = [
+        "### 1. PR Change Summary",
+        "",
+        f"**Diff:** `git diff {base}...HEAD`  |  "
+        f"**Committed:** {len(committed)} files {_badge('FACT')}  |  "
+        f"**Unstaged:** {len(uncommitted)} files {_badge('FACT')}",
+        "",
+    ]
+
+    if uncommitted:
+        lines.append(
+            f"> **Note:** {len(uncommitted)} file(s) in working tree not committed — "
+            "present in analysis, absent from PR diff."
+        )
+        lines.append("")
+
+    if not runtime and not build_files:
+        lines.append("*No runtime files changed.*")
+        return "\n".join(lines)
+
+    lines += ["| File | Artifact Type | Role | Source |",
+              "|------|--------------|------|--------|"]
+
+    for rc in runtime:
+        path = rc.get("path", "")
+        atype = rc.get("artifact_type", "")
+        effect = rc.get("change_effect", {})
+        stmt = effect.get("statement", "") if isinstance(effect, dict) else ""
+        diff_src = rc.get("diff_source", "committed")
+        src_label = "committed" if "committed" in diff_src else "unstaged"
+        lines.append(f"| `{_short(path)}` | `{atype}` | {stmt} | {src_label} |")
+
+    for bf in build_files:
+        lines.append(f"| `{_short(bf)}` | `build_manifest` | build / dependency configuration | committed |")
+
+    lines.append("")
+    lines.append(f"*All file entries above are {_badge('FACT')} — directly observed in diff.*")
+    return "\n".join(lines)
+
+
+# ── Section 2: Impacted Execution Flow ────────────────────────────────────────
+
+def _section_execution_flow(out: dict) -> str:
+    behavioral: list[dict] = out.get("behavioral_impact", [])
+
+    # Only STRUCTURAL SIGNAL or FACT paths — exclude heuristic_only
+    strong = [
+        bi for bi in behavioral
+        if bi.get("evidence_level", "none") in _STRUCTURAL_EVIDENCE
+    ]
+    weak = [
+        bi for bi in behavioral
+        if bi.get("evidence_level", "none") == "heuristic_only"
+    ]
+
+    lines = ["### 2. Impacted Execution Flow", ""]
+
+    if not strong and not weak:
+        lines.append("*No traceable execution flow — insufficient structural evidence.*")
+        return "\n".join(lines)
+
+    if strong:
+        for bi in strong[:_MAX_FLOW_PATHS]:
+            ev = bi.get("evidence_level", "")
+            ep = _evidence_to_epistemic(ev)
+            entry = bi.get("entry_point", "")
+            affected: list[str] = bi.get("affected_path", [])
+            end_state = bi.get("end_state", "")
+            trace: list[str] = bi.get("trace", [])
+
+            end_state_ep = bi.get("end_state_epistemic_level", "INFERRED (LOW CONFIDENCE)")
+            steps = [f"`{entry}`"] + [f"`{s}`" for s in affected]
+            if end_state:
+                steps.append(f"**{end_state}** {_badge(end_state_ep)}")
+
+            lines.append(f"**Flow:** {' → '.join(steps)}")
+            lines.append(f"**Evidence:** {_badge(ep)}")
+
+            if trace:
+                for t in trace:
+                    lines.append(f"- {t}")
+            lines.append("")
+
+    if weak:
+        lines.append(f"**Excluded from flow** ({len(weak)} path(s) — evidence insufficient):")
+        for bi in weak[:3]:
+            entry = bi.get("entry_point", "")
+            lines.append(
+                f"- `{entry}` path — {_badge('INFERRED (LOW CONFIDENCE)')}: "
+                "class reference detected but no injection or call evidence"
+            )
+        lines.append("")
+
+    return "\n".join(lines).rstrip()
+
+
+# ── Section 3: Review Priority Order ─────────────────────────────────────────
+
+def _section_priority_order(out: dict) -> str:
+    order: list[str] = out.get("suggested_review_order", []) or out.get("review_hotspots", [])
+    runtime: list[dict] = out.get("runtime_changes", [])
+
+    cls_map: dict[str, dict] = {rc["path"]: rc for rc in runtime}
+
+    lines = ["### 3. Review Priority Order", ""]
+
+    if not order:
+        lines.append("*No priority order available — diff scope too narrow to rank.*")
+        return "\n".join(lines)
+
+    for i, path in enumerate(order[:_MAX_PRIORITY_FILES], 1):
+        rc = cls_map.get(path, {})
+        effect = rc.get("change_effect", {})
+        stmt = effect.get("statement", "application source") if isinstance(effect, dict) else "application source"
+        ep = effect.get("epistemic_level", "STRUCTURAL SIGNAL") if isinstance(effect, dict) else "STRUCTURAL SIGNAL"
+        atype = rc.get("artifact_type", "source")
+        lines.append(f"{i}. `{_short(path)}` — {_badge(ep)}: {atype} — {stmt}")
+
+    return "\n".join(lines)
+
+
+# ── Section 4: Risk / Impact Signals ─────────────────────────────────────────
+
+def _section_signals(out: dict) -> str:
+    lines = ["### 4. Risk / Impact Signals", ""]
+    signals: list[str] = []
+
+    # Security files in diff — FACT (files are in diff)
+    sec = out.get("security_impact", {})
+    if sec:
+        files: list[str] = sec.get("affected_resources", [])
+        ep = sec.get("epistemic_level", "STRUCTURAL SIGNAL")
+        basis = sec.get("basis", "")
+        if files:
+            names = ", ".join(f"`{_short(f)}`" for f in files)
+            signals.append(f"{_badge(ep)}: security-classified files changed — {names}")
+            if basis:
+                signals.append(f"  *Classification basis: {basis}*")
+        risk_ep = sec.get("risk_epistemic_level", "INFERRED (LOW CONFIDENCE)")
+        signals.append(
+            f"{_badge(risk_ep)}: authentication / access-control behavior may be affected — "
+            "inspect changed security files to confirm"
+        )
+
+    # Transactional boundary — STRUCTURAL SIGNAL if @Transactional detected, else INFERRED
+    txn = out.get("transactional_impact", {})
+    if txn:
+        files_t: list[str] = txn.get("affected_transactions", [])
+        ep_t = txn.get("epistemic_level", "STRUCTURAL SIGNAL")
+        basis_t = txn.get("basis", "")
+        risk_ep_t = txn.get("risk_epistemic_level", "INFERRED (LOW CONFIDENCE)")
+        if files_t:
+            names_t = ", ".join(f"`{_short(f)}`" for f in files_t)
+            signals.append(f"{_badge(ep_t)}: service/business-logic files changed — {names_t}")
+            if basis_t:
+                signals.append(f"  *Classification basis: {basis_t}*")
+        signals.append(
+            f"{_badge(risk_ep_t)}: transactional boundary may be affected — "
+            "@Transactional scope not confirmed by AST"
+        )
+
+    # Configuration files — FACT
+    cfg = out.get("configuration_impact", {})
+    if cfg:
+        cfg_files: list[str] = cfg.get("changed_configs", [])
+        if cfg_files:
+            names_c = ", ".join(f"`{_short(f)}`" for f in cfg_files)
+            signals.append(f"{_badge('FACT')}: configuration files modified — {names_c}")
+
+    # Behavioral impact signals — use each item's epistemic_level
+    behavioral: list[dict] = out.get("behavioral_impact", [])
+    for bi in behavioral[:_MAX_FLOW_PATHS]:
+        for item in bi.get("impact", []):
+            stmt = item.get("statement", "")
+            ep_i = item.get("epistemic_level", "INFERRED (LOW CONFIDENCE)")
+            support = item.get("support", "")
+            if stmt:
+                signals.append(f"{_badge(ep_i)}: {stmt}")
+                if support:
+                    signals.append(f"  *{support}*")
+
+    # Runtime notes from execution paths
+    exec_paths: list[dict] = out.get("execution_paths", [])
+    seen_notes: set[str] = set()
+    for ep_dict in exec_paths:
+        entry_notes: list = ep_dict.get("entry_point", {}).get("notes", [])
+        path_notes: list = [n for item in ep_dict.get("path", []) for n in item.get("notes", [])]
+        for note_obj in entry_notes + path_notes:
+            if isinstance(note_obj, dict):
+                note = note_obj.get("note", "")
+                n_ep = note_obj.get("epistemic_level", "STRUCTURAL SIGNAL")
+                if note and note not in seen_notes:
+                    signals.append(f"{_badge(n_ep)}: {note}")
+                    seen_notes.add(note)
+
+    if not signals:
+        lines.append("*No impact signals detected — insufficient evidence.*")
+        return "\n".join(lines)
+
+    lines.extend(signals[:_MAX_SIGNALS])
+    return "\n".join(lines)
+
+
+# ── Section 5: Review Guidance ────────────────────────────────────────────────
+
+def _section_guidance(out: dict) -> str:
+    lines = ["### 5. Review Guidance", ""]
+
+    # Inspect first — top priority files
+    order: list[str] = out.get("suggested_review_order", []) or out.get("review_hotspots", [])
+    runtime: list[dict] = out.get("runtime_changes", [])
+    cls_map: dict[str, dict] = {rc["path"]: rc for rc in runtime}
+
+    if order:
+        lines.append("**Inspect first:**")
+        for path in order[:3]:
+            rc = cls_map.get(path, {})
+            effect = rc.get("change_effect", {})
+            stmt = effect.get("statement", "") if isinstance(effect, dict) else ""
+            ep = effect.get("epistemic_level", "STRUCTURAL SIGNAL") if isinstance(effect, dict) else "STRUCTURAL SIGNAL"
+            label = f" — {stmt}" if stmt else ""
+            lines.append(f"- `{_short(path)}`{label} {_badge(ep)}")
+        lines.append("")
+
+    # Uncertain — heuristic-only behavioral paths
+    behavioral: list[dict] = out.get("behavioral_impact", [])
+    weak_paths = [
+        bi for bi in behavioral
+        if bi.get("evidence_level", "none") == "heuristic_only"
+    ]
+    if weak_paths:
+        lines.append("**Uncertain (heuristic-only — verify manually):**")
+        for bi in weak_paths[:_MAX_UNCERTAIN]:
+            entry = bi.get("entry_point", "")
+            affected: list[str] = bi.get("affected_path", [])
+            path_str = " → ".join(affected) if affected else "unknown"
+            lines.append(
+                f"- `{entry}` → {path_str} "
+                f"{_badge('INFERRED (LOW CONFIDENCE)')}: class reference only, no injection/call proof"
+            )
+        lines.append("")
+
+    # Evidence gaps
+    gaps: list[str] = out.get("gaps", [])
+    cov = out.get("test_coverage_risk", {})
+    test_files: list[str] = cov.get("changed_files_without_tests", [])
+    test_basis = cov.get("basis", "")
+    cov_ep = cov.get("epistemic_level", "INFERRED (LOW CONFIDENCE)")
+
+    gap_items: list[str] = list(gaps)
+    if test_files:
+        shown = test_files[:5]
+        omitted = len(test_files) - len(shown)
+        names = ", ".join(f"`{_short(f)}`" for f in shown)
+        suffix = f" +{omitted} more" if omitted else ""
+        gap_items.append(
+            f"changed files without test coverage: {names}{suffix} "
+            f"{_badge(cov_ep)}"
+            + (f" — {test_basis}" if test_basis else "")
+        )
+
+    if gap_items:
+        lines.append("**Evidence gaps / missing coverage:**")
+        for g in gap_items:
+            lines.append(f"- {g}")
+    else:
+        lines.append("*No evidence gaps detected.*")
+
+    return "\n".join(lines)
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+def render_github_comment(out: dict) -> str:
+    """Render review-pr TaskOutput dict as a GitHub PR comment (Markdown).
+
+    5 mandatory sections. Every statement carries an explicit epistemic label.
+    """
+    base = out.get("base_ref") or out.get("since") or "HEAD~1"
+    header = (
+        "## sourcecode PR Analysis\n\n"
+        f"**Base:** `{base}`  |  "
+        f"**Review type:** pull request  |  "
+        f"**Epistemic contract:** FACT · STRUCTURAL SIGNAL · INFERRED (LOW CONFIDENCE) · OMITTED"
+    )
+
+    sections = [
+        header,
+        _section_change_summary(out),
+        _section_execution_flow(out),
+        _section_priority_order(out),
+        _section_signals(out),
+        _section_guidance(out),
+    ]
+
+    footer = (
+        "*Generated by [sourcecode](https://github.com/sourcecode-ai/sourcecode). "
+        "Labels: "
+        "`FACT` = diff/AST evidence · "
+        "`STRUCTURAL SIGNAL` = annotation/import/wiring · "
+        "`INFERRED (LOW CONFIDENCE)` = heuristic pattern · "
+        "`OMITTED` = insufficient evidence.*"
+    )
+    sections.append(footer)
+
+    return "\n\n---\n\n".join(s for s in sections if s.strip())