roam-code 12.26__tar.gz → 12.26.1__tar.gz

{roam_code-12.26/src/roam_code.egg-info → roam_code-12.26.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.26
+Version: 12.26.1
 Summary: Instant codebase comprehension for AI coding agents
 Author: CosmoHac
 License-Expression: Apache-2.0

{roam_code-12.26 → roam_code-12.26.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "roam-code"
-version = "12.26"
+version = "12.26.1"
 description = "Instant codebase comprehension for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{roam_code-12.26 → roam_code-12.26.1}/src/roam/commands/cmd_audit_trail_conformance.py

@@ -124,6 +124,56 @@ def _check_retention(records: list[dict], retention_days: int) -> tuple[bool, st
     )
 
 
+def _checks_to_sarif(
+    checks: list[dict],
+    audit_trail_path: Path,
+    score: int,
+) -> dict:
+    """Render the 6-check verdict as a SARIF 2.1.0 envelope.
+
+    Each FAIL becomes a SARIF result; each rule (one per check id) is
+    declared in the run's tool.driver.rules. GitHub Code Scanning ingests
+    this directly, surfacing the failures as triage items in the Security
+    tab — useful for quarterly compliance gates.
+    """
+    from roam.output.sarif import to_sarif
+
+    rules = [
+        {
+            "id": c["id"],
+            "shortDescription": f"EU AI Act Article 12 conformance check: {c['id'].replace('_', ' ')}",
+            "defaultLevel": "warning",
+            "helpUri": "https://artificialintelligenceact.eu/article/12/",
+            "properties": {"category": "compliance", "regulation": "EU AI Act Article 12"},
+        }
+        for c in checks
+    ]
+    results = []
+    for c in checks:
+        if c["passed"]:
+            continue
+        results.append(
+            {
+                "ruleId": c["id"],
+                "level": "error" if score < 67 else "warning",
+                "message": {"text": c["message"]},
+                "locations": [
+                    {
+                        "physicalLocation": {
+                            "artifactLocation": {"uri": str(audit_trail_path)},
+                        }
+                    }
+                ],
+            }
+        )
+    return to_sarif(
+        tool_name="roam-code",
+        version="audit-trail-conformance-check",
+        rules=rules,
+        results=results,
+    )
+
+
 @click.command(name="audit-trail-conformance-check")
 @click.option(
     "--input",
@@ -144,12 +194,19 @@ def _check_retention(records: list[dict], retention_days: int) -> tuple[bool, st
     is_flag=True,
     help="Exit 5 (gate failure) when conformance score < 100; useful for quarterly compliance gates.",
 )
+@click.option(
+    "--sarif-output",
+    type=click.Path(),
+    default=None,
+    help="Write SARIF to this file (default: stdout when global --sarif is set). Requires --sarif.",
+)
 @click.pass_context
 def audit_trail_conformance_check(
     ctx,
     input_path: str | None,
     retention_days: int,
     gate: bool,
+    sarif_output: str | None,
 ) -> None:
     """Score the audit trail against an EU AI Act Article 12 checklist.
 
@@ -168,6 +225,7 @@ def audit_trail_conformance_check(
     triage signal: "would this trail survive a procurement review?".
     """
     json_mode = ctx.obj.get("json") if ctx.obj else False
+    sarif = ctx.obj.get("sarif") if ctx.obj else False
 
     path = Path(input_path) if input_path else DEFAULT_AUDIT_TRAIL_PATH
     records = _load_records(path)
@@ -211,7 +269,16 @@ def audit_trail_conformance_check(
         "disclaimer": "Triage signal only — not legal advice.",
     }
 
-    if json_mode:
+    if sarif:
+        from roam.output.sarif import write_sarif
+
+        sarif_doc = _checks_to_sarif(checks, path, score)
+        sarif_text = write_sarif(sarif_doc, sarif_output)
+        if not sarif_output:
+            click.echo(sarif_text)
+        elif not json_mode:
+            click.echo(f"VERDICT: {verdict} — SARIF written to {sarif_output}")
+    elif json_mode:
         click.echo(
             to_json(
                 json_envelope(
@@ -224,7 +291,7 @@ def audit_trail_conformance_check(
                 )
             )
         )
-    else:
+    elif not sarif:
         click.echo(f"VERDICT: {verdict}")
         click.echo(f"  path:    {path}")
         click.echo(f"  records: {len(records)}")

{roam_code-12.26 → roam_code-12.26.1}/src/roam/commands/cmd_metrics_push.py

@@ -102,21 +102,12 @@ def _load_last_pr_analysis(path: Path | None = None) -> dict | None:
         return None
 
 
-def _build_payload(
-    audit_envelope: dict,
-    *,
-    repo_id: str,
-    git_meta: dict,
-    anonymize: bool,
-    include_hotspots: bool,
-    last_pr_envelope: dict | None = None,
-) -> dict:
-    """Compose the metrics-only payload from a ``roam audit`` envelope.
+def _extract_metrics(audit_envelope: dict) -> dict:
+    """Pull the allow-listed numeric metrics out of an audit envelope.
 
-    Source-code bodies are NEVER included. Only numbers, file paths
-    (or hashes when --anonymize), bucket counts, and aggregate scores.
-    Per the Cloud Lite spec, the receiving API rejects any payload
-    containing keys outside this allow-listed schema.
+    Source-code bodies are NEVER included — only numbers, bucket counts,
+    aggregate scores. The receiving API rejects any payload containing
+    keys outside this allow-listed schema.
     """
     summary = audit_envelope.get("summary") or {}
     sections = audit_envelope.get("sections") or {}
@@ -125,9 +116,8 @@ def _build_payload(
     dead_summary = (sections.get("dead") or {}).get("summary") or {}
     pyramid_summary = (sections.get("test_pyramid") or {}).get("summary") or {}
     danger_summary = (sections.get("hotspots_danger") or {}).get("summary") or {}
-    danger_section = sections.get("hotspots_danger") or {}
 
-    metrics = {
+    return {
         "health_score": health_summary.get("health_score") or summary.get("health_score"),
         "debt_total_minutes": debt_summary.get("total_remediation_minutes") or debt_summary.get("total_minutes"),
         "debt_total_hours": debt_summary.get("total_remediation_hours"),
@@ -153,6 +143,72 @@ def _build_payload(
         "tangle_ratio": health_summary.get("tangle_ratio"),
     }
 
+
+def _extract_hotspots(audit_envelope: dict, *, anonymize: bool, limit: int = 10) -> list[dict]:
+    """Pull the top-N danger-zone rows. Path is hashed under anonymize."""
+    danger_section = (audit_envelope.get("sections") or {}).get("hotspots_danger") or {}
+    danger_zone = danger_section.get("danger_zone") or []
+    out: list[dict] = []
+    for row in danger_zone[:limit]:
+        path = row.get("path", "")
+        entry = {
+            "danger_score": row.get("danger_score"),
+            "churn": row.get("churn"),
+            "complexity": row.get("complexity"),
+            "max_fan_in": row.get("max_fan_in"),
+        }
+        if anonymize:
+            entry["path_hash"] = _path_hash(path) if path else None
+        else:
+            entry["path"] = path
+        out.append(entry)
+    return out
+
+
+def _build_last_pr_block(last_pr_envelope: dict) -> dict:
+    """Compose the last_pr_analysis block from a saved pr-analyze envelope.
+
+    Folds in only summary numerics + verdict + primary language + timestamp.
+    Computes ``age_days`` + ``stale`` (>7 days) so dashboards can grey
+    stale entries without needing to compute age client-side.
+    """
+    pr_summary = last_pr_envelope.get("summary") or {}
+    ai_section = last_pr_envelope.get("ai_likelihood") or {}
+    ts = (last_pr_envelope.get("_meta") or {}).get("timestamp")
+    block = {
+        "verdict": pr_summary.get("verdict"),
+        "blast_radius": pr_summary.get("blast_radius"),
+        "ai_likelihood": pr_summary.get("ai_likelihood"),
+        "rule_violations": pr_summary.get("rule_violations"),
+        "high_severity_critique": pr_summary.get("high_severity_critique"),
+        "primary_language": ai_section.get("primary_language"),
+        "timestamp": ts,
+    }
+    if ts:
+        try:
+            pr_dt = _dt.datetime.fromisoformat(ts.replace("Z", "+00:00"))
+            age_days = (_dt.datetime.now(_dt.timezone.utc) - pr_dt).days
+            block["age_days"] = age_days
+            block["stale"] = age_days > 7
+        except (TypeError, ValueError):
+            pass
+    return block
+
+
+def _build_payload(
+    audit_envelope: dict,
+    *,
+    repo_id: str,
+    git_meta: dict,
+    anonymize: bool,
+    include_hotspots: bool,
+    last_pr_envelope: dict | None = None,
+) -> dict:
+    """Compose the metrics-only payload from a ``roam audit`` envelope.
+
+    Refactor (P23): metrics, hotspots, and last-pr-analysis blocks are
+    extracted into helpers above. This function is now a flat coordinator.
+    """
     payload: dict = {
         "schema": "roam-metrics-v1",
         "schema_version": "1.0.0",
@@ -162,55 +218,12 @@ def _build_payload(
         "timestamp": utc_timestamp(),
         "tool_version": detect_roam_version(),
         "anonymized": bool(anonymize),
-        "metrics": metrics,
+        "metrics": _extract_metrics(audit_envelope),
     }
-
     if include_hotspots:
-        danger_zone = danger_section.get("danger_zone") or []
-        hotspot_rows: list[dict] = []
-        for row in danger_zone[:10]:
-            path = row.get("path", "")
-            entry = {
-                "danger_score": row.get("danger_score"),
-                "churn": row.get("churn"),
-                "complexity": row.get("complexity"),
-                "max_fan_in": row.get("max_fan_in"),
-            }
-            if anonymize:
-                entry["path_hash"] = _path_hash(path) if path else None
-            else:
-                entry["path"] = path
-            hotspot_rows.append(entry)
-        payload["hotspots"] = hotspot_rows
-
+        payload["hotspots"] = _extract_hotspots(audit_envelope, anonymize=anonymize)
     if last_pr_envelope:
-        # Fold the latest pr-analyze summary into the payload so Cloud Lite
-        # can show "last PR verdict" alongside health-trend without a 2nd call.
-        # No diff text or source bodies — only summary numerics + verdict.
-        pr_summary = last_pr_envelope.get("summary") or {}
-        ai_section = last_pr_envelope.get("ai_likelihood") or {}
-        ts = (last_pr_envelope.get("_meta") or {}).get("timestamp")
-        last_pr_block = {
-            "verdict": pr_summary.get("verdict"),
-            "blast_radius": pr_summary.get("blast_radius"),
-            "ai_likelihood": pr_summary.get("ai_likelihood"),
-            "rule_violations": pr_summary.get("rule_violations"),
-            "high_severity_critique": pr_summary.get("high_severity_critique"),
-            "primary_language": ai_section.get("primary_language"),
-            "timestamp": ts,
-        }
-        # Synergy C.1.hhh: surface "stale" so dashboards can grey it out
-        # without needing to compute age client-side.
-        if ts:
-            try:
-                pr_dt = _dt.datetime.fromisoformat(ts.replace("Z", "+00:00"))
-                age_days = (_dt.datetime.now(_dt.timezone.utc) - pr_dt).days
-                last_pr_block["age_days"] = age_days
-                last_pr_block["stale"] = age_days > 7
-            except (TypeError, ValueError):
-                pass
-        payload["last_pr_analysis"] = last_pr_block
-
+        payload["last_pr_analysis"] = _build_last_pr_block(last_pr_envelope)
     return payload
 
 

{roam_code-12.26 → roam_code-12.26.1}/src/roam/commands/cmd_pr_analyze.py

@@ -204,9 +204,18 @@ def _load_baseline(path: Path) -> dict | None:
 
 
 def _save_baseline(path: Path, bundle: dict) -> None:
-    """Write the current envelope to disk for later drift comparison."""
+    """Write the current envelope to disk for later drift comparison.
+
+    Stamps ``_meta.timestamp`` (UTC) at save time so consumers — drift
+    detection + ``pr-comment-render --from-baseline`` age line — can
+    compute baseline age without needing the original CLI envelope.
+    """
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(_json.dumps(bundle, indent=2), encoding="utf-8")
+    out = dict(bundle)
+    meta = dict(out.get("_meta") or {})
+    meta["timestamp"] = utc_timestamp()
+    out["_meta"] = meta
+    path.write_text(_json.dumps(out, indent=2), encoding="utf-8")
 
 
 def _compute_drift(current: dict, baseline: dict | None) -> dict | None:
@@ -1365,6 +1374,135 @@ def _determine_verdict(
     return "SAFE", ["all signals below review thresholds"]
 
 
+# ----------------------------------------------------- pr_analyze sub-helpers ---
+#
+# Extracted from pr_analyze (Phase P24, 2026-05-06) to drop the
+# coordinator's cognitive complexity below the project's 99-cc gate.
+
+
+def _serve_from_cache(
+    diff_text: str,
+    rules_path: Path,
+    block_threshold: int,
+    language_override: str | None,
+    cache_dir_path: Path,
+    *,
+    json_mode: bool,
+    quiet: bool,
+    gate: bool,
+) -> bool:
+    """Try the envelope cache. On hit emit the cached output and return True.
+
+    Returns False on miss so the caller continues with the slow pr-prep
+    pipeline. Top-level ``cache_hit`` + ``cache_key`` keys survive the
+    json_envelope() ``_meta`` rebuild.
+    """
+    key = _cache_key(diff_text, rules_path, block_threshold, language_override)
+    cached = _load_cache(cache_dir_path, key)
+    if cached is None:
+        return False
+    cached["cache_hit"] = True
+    cached["cache_key"] = key
+    s = cached.get("summary") or {}
+    if json_mode:
+        click.echo(to_json(json_envelope("pr-analyze", **cached)))
+    elif quiet:
+        click.echo(
+            f"VERDICT: {s.get('verdict', '?')} (cached, blast {s.get('blast_radius', '?')}, "
+            f"ai {s.get('ai_likelihood', '?')}, rules {s.get('rule_violations', 0)})"
+        )
+    else:
+        click.echo(f"VERDICT: {s.get('verdict', '?')} [cache hit]")
+    if gate and s.get("verdict") == "BLOCK":
+        sys.exit(EXIT_GATE_BLOCK)
+    return True
+
+
+def _apply_drift(
+    bundle: dict,
+    base_path: Path,
+    verdict: str,
+    reasons: list[str],
+) -> tuple[str, list[str]]:
+    """Compute drift vs baseline + auto-escalate verdict on regression.
+
+    Mutates ``bundle`` in place to add the drift block and updated summary.
+    Returns the (possibly escalated) ``(verdict, reasons)``.
+    """
+    baseline_envelope = _load_baseline(base_path)
+    drift = _compute_drift(bundle, baseline_envelope)
+    if not drift:
+        return verdict, reasons
+    bundle["drift"] = drift
+    if drift["regression"] and verdict == "SAFE":
+        verdict = "REVIEW"
+        reasons.append(
+            f"Drift regression vs baseline: blast {drift['blast_radius_delta']:+d}, "
+            f"ai {drift['ai_likelihood_delta']:+d}, +{drift['new_violation_count']} violations"
+        )
+        bundle["summary"]["verdict"] = verdict
+        bundle["summary"]["reasons"] = reasons
+    elif (
+        drift["regression"]
+        and verdict == "REVIEW"
+        and (drift["blast_radius_delta"] >= 20 or drift["new_violation_count"] >= 3)
+    ):
+        verdict = "BLOCK"
+        reasons.append("Drift regression severe enough to escalate REVIEW → BLOCK")
+        bundle["summary"]["verdict"] = verdict
+        bundle["summary"]["reasons"] = reasons
+    return verdict, reasons
+
+
+def _emit_audit_trail(
+    bundle: dict,
+    trail_path: Path,
+    diff_text: str,
+    intent: str | None,
+    reviewers_payload: dict | None,
+    verdict: str,
+    reasons: list[str],
+) -> tuple[str, list[str]]:
+    """Pre-verify chain integrity, append the new record, escalate on tampering.
+
+    Mutates ``bundle`` in place to add the audit_trail block. Returns the
+    (possibly escalated) ``(verdict, reasons)``.
+    """
+    # Lazy import to avoid pulling cmd_audit_trail_verify on every pr-analyze.
+    from roam.commands.cmd_audit_trail_verify import _verify_chain
+
+    _, chain_issues = _verify_chain(trail_path)
+    real_issues = [i for i in chain_issues if "not found" not in i.get("issue", "")]
+    chain_was_valid = not real_issues
+
+    audit_record = _emit_audit_trail_record(
+        audit_trail_path=trail_path,
+        diff_text=diff_text,
+        bundle=bundle,
+        intent=intent,
+        reviewers_payload=reviewers_payload,
+    )
+    bundle["audit_trail"] = {
+        "path": str(trail_path),
+        "record": audit_record,
+        "chain_status": {
+            "pre_emission_chain_valid": chain_was_valid,
+            "pre_emission_issues": real_issues,
+        },
+    }
+    if not chain_was_valid:
+        reasons.append(
+            f"Audit-trail chain broken before append ({len(real_issues)} pre-existing issue(s)) — "
+            "tampering or partial-write corruption detected"
+        )
+        if verdict != "BLOCK":
+            bundle["summary"]["verdict_pre_chain_break"] = verdict
+            verdict = "BLOCK"
+            bundle["summary"]["verdict"] = verdict
+            bundle["summary"]["reasons"] = reasons
+    return verdict, reasons
+
+
 # ----------------------------------------------------------- batch processing ---
 
 
@@ -1788,28 +1926,17 @@ def pr_analyze(
     # Cache lookup — bypasses pr-prep (the slow part) on hit.
     cache_dir_path = Path(cache_dir) if cache_dir else DEFAULT_CACHE_DIR
     rules_path = Path(rules_file) if rules_file else (Path(".roam") / "rules.yml")
-    cached_bundle: dict | None = None
-    if cache:
-        key = _cache_key(diff_text, rules_path, block_threshold, language_override)
-        cached_bundle = _load_cache(cache_dir_path, key)
-        if cached_bundle is not None:
-            # Surface as top-level keys so json_envelope's _meta rebuild doesn't strip them.
-            cached_bundle["cache_hit"] = True
-            cached_bundle["cache_key"] = key
-            if json_mode:
-                click.echo(to_json(json_envelope("pr-analyze", **cached_bundle)))
-            elif quiet:
-                s = cached_bundle.get("summary") or {}
-                click.echo(
-                    f"VERDICT: {s.get('verdict', '?')} (cached, blast {s.get('blast_radius', '?')}, "
-                    f"ai {s.get('ai_likelihood', '?')}, rules {s.get('rule_violations', 0)})"
-                )
-            else:
-                s = cached_bundle.get("summary") or {}
-                click.echo(f"VERDICT: {s.get('verdict', '?')} [cache hit]")
-            if gate and (cached_bundle.get("summary") or {}).get("verdict") == "BLOCK":
-                sys.exit(EXIT_GATE_BLOCK)
-            return
+    if cache and _serve_from_cache(
+        diff_text,
+        rules_path,
+        block_threshold,
+        language_override,
+        cache_dir_path,
+        json_mode=json_mode,
+        quiet=quiet,
+        gate=gate,
+    ):
+        return
 
     prep_payload = _capture_pr_prep(commit_range, high_callers)
     ai = _compute_ai_likelihood(diff_text, language_override=language_override)
@@ -1883,28 +2010,7 @@ def pr_analyze(
 
     # --- Baseline drift detection -----------------------------------------
     base_path = Path(baseline_path) if baseline_path else DEFAULT_BASELINE_PATH
-    baseline_envelope = _load_baseline(base_path)
-    drift = _compute_drift(bundle, baseline_envelope)
-    if drift:
-        bundle["drift"] = drift
-        # Adjust verdict ONE tier upward on regression (SAFE → REVIEW; REVIEW → BLOCK)
-        if drift["regression"] and verdict == "SAFE":
-            verdict = "REVIEW"
-            reasons.append(
-                f"Drift regression vs baseline: blast {drift['blast_radius_delta']:+d}, "
-                f"ai {drift['ai_likelihood_delta']:+d}, +{drift['new_violation_count']} violations"
-            )
-            bundle["summary"]["verdict"] = verdict
-            bundle["summary"]["reasons"] = reasons
-        elif (
-            drift["regression"]
-            and verdict == "REVIEW"
-            and (drift["blast_radius_delta"] >= 20 or drift["new_violation_count"] >= 3)
-        ):
-            verdict = "BLOCK"
-            reasons.append("Drift regression severe enough to escalate REVIEW → BLOCK")
-            bundle["summary"]["verdict"] = verdict
-            bundle["summary"]["reasons"] = reasons
+    verdict, reasons = _apply_drift(bundle, base_path, verdict, reasons)
 
     if save_baseline:
         # Save AFTER drift logic so saved envelope reflects the post-drift verdict
@@ -1922,50 +2028,17 @@ def pr_analyze(
         _save_cache(cache_dir_path, cache_save_key, bundle)
         bundle.setdefault("_meta", {})["cache_saved_to"] = str(_cache_path(cache_dir_path, cache_save_key))
 
-    audit_record: dict | None = None
-    audit_chain_status: dict | None = None
     if audit_trail:
         trail_path = Path(audit_trail_path) if audit_trail_path else DEFAULT_AUDIT_TRAIL_PATH
-
-        # Pre-emission integrity check — if the existing chain is broken,
-        # surface the issue BEFORE appending so we don't compound corruption.
-        # Lazy import to avoid pulling cmd_audit_trail_verify on every pr-analyze.
-        from roam.commands.cmd_audit_trail_verify import _verify_chain
-
-        _, chain_issues = _verify_chain(trail_path)
-        # Filter out the "audit trail not found" issue — that's the genesis case.
-        real_issues = [i for i in chain_issues if "not found" not in i.get("issue", "")]
-        chain_was_valid = not real_issues
-        audit_chain_status = {
-            "pre_emission_chain_valid": chain_was_valid,
-            "pre_emission_issues": real_issues,
-        }
-
-        audit_record = _emit_audit_trail_record(
-            audit_trail_path=trail_path,
-            diff_text=diff_text,
-            bundle=bundle,
-            intent=intent,
-            reviewers_payload=reviewers_payload,
+        verdict, reasons = _emit_audit_trail(
+            bundle,
+            trail_path,
+            diff_text,
+            intent,
+            reviewers_payload,
+            verdict,
+            reasons,
         )
-        bundle["audit_trail"] = {
-            "path": str(trail_path),
-            "record": audit_record,
-            "chain_status": audit_chain_status,
-        }
-
-        # Auto-escalate verdict if the chain was tampered with — a broken
-        # audit trail in CI is a compliance incident, gate must fire.
-        if not chain_was_valid:
-            reasons.append(
-                f"Audit-trail chain broken before append ({len(real_issues)} pre-existing issue(s)) — "
-                "tampering or partial-write corruption detected"
-            )
-            if verdict != "BLOCK":
-                bundle["summary"]["verdict_pre_chain_break"] = verdict
-                verdict = "BLOCK"
-                bundle["summary"]["verdict"] = verdict
-                bundle["summary"]["reasons"] = reasons
 
     if json_mode:
         click.echo(to_json(json_envelope("pr-analyze", **bundle)))

{roam_code-12.26 → roam_code-12.26.1/src/roam_code.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.26
+Version: 12.26.1
 Summary: Instant codebase comprehension for AI coding agents
 Author: CosmoHac
 License-Expression: Apache-2.0

{roam_code-12.26 → roam_code-12.26.1}/src/roam_code.egg-info/SOURCES.txt

@@ -623,6 +623,7 @@ tests/test_v1221_query_timeout.py
 tests/test_v1221_untested_commands.py
 tests/test_v12_2.py
 tests/test_v2_edge_cases.py
+tests/test_v2_integration.py
 tests/test_v6_features.py
 tests/test_v71_features.py
 tests/test_v7_features.py

{roam_code-12.26 → roam_code-12.26.1}/tests/test_audit_trail_conformance.py

@@ -257,6 +257,75 @@ def test_cli_gate_exits_5_on_partial_conformance(tmp_path):
     assert result.exit_code == EXIT_GATE_FAILURE
 
 
+def test_cli_sarif_emits_valid_envelope(tmp_path):
+    """--sarif emits a valid SARIF 2.1.0 doc with a result per failed check."""
+    runner = CliRunner()
+    from roam.cli import cli
+
+    trail = tmp_path / "trail.jsonl"
+    rec = _full_record("SAFE", _dt.datetime.now(_dt.timezone.utc).isoformat().replace("+00:00", "Z"))
+    _write_chain(trail, [rec])
+
+    # Global --sarif comes BEFORE the subcommand name
+    result = runner.invoke(cli, ["--sarif", "audit-trail-conformance-check", "--input", str(trail)])
+    assert result.exit_code == 0
+    doc = _json.loads(result.output)
+    assert doc["version"] == "2.1.0"
+    assert doc["runs"][0]["tool"]["driver"]["name"] == "roam-code"
+    # Recent-only timestamps fail retention → at least 1 result
+    results = doc["runs"][0]["results"]
+    assert len(results) >= 1
+    rule_ids = {r["ruleId"] for r in results}
+    assert "retention" in rule_ids
+    # Each rule has helpUri pointing at the regulation
+    rules = doc["runs"][0]["tool"]["driver"]["rules"]
+    assert all("artificialintelligenceact.eu" in r.get("helpUri", "") for r in rules)
+
+
+def test_cli_sarif_writes_to_file(tmp_path):
+    """--sarif --sarif-output writes to the file + emits a single VERDICT line."""
+    runner = CliRunner()
+    from roam.cli import cli
+
+    trail = tmp_path / "trail.jsonl"
+    _write_chain(
+        trail,
+        [_full_record("SAFE", _dt.datetime.now(_dt.timezone.utc).isoformat().replace("+00:00", "Z"))],
+    )
+    sarif_path = tmp_path / "out.sarif"
+    result = runner.invoke(
+        cli,
+        [
+            "--sarif",
+            "audit-trail-conformance-check",
+            "--input",
+            str(trail),
+            "--sarif-output",
+            str(sarif_path),
+        ],
+    )
+    assert result.exit_code == 0
+    assert sarif_path.exists()
+    doc = _json.loads(sarif_path.read_text(encoding="utf-8"))
+    assert doc["version"] == "2.1.0"
+    assert "VERDICT:" in result.output
+
+
+def test_cli_sarif_with_perfect_score_emits_no_results(tmp_path):
+    """A 100/100 trail produces a SARIF with rules but zero findings."""
+    runner = CliRunner()
+    from roam.cli import cli
+
+    trail = tmp_path / "trail.jsonl"
+    old_ts = (_dt.datetime.now(_dt.timezone.utc) - _dt.timedelta(days=200)).isoformat().replace("+00:00", "Z")
+    recent_ts = _dt.datetime.now(_dt.timezone.utc).isoformat().replace("+00:00", "Z")
+    _write_chain(trail, [_full_record("SAFE", old_ts), _full_record("REVIEW", recent_ts)])
+
+    result = runner.invoke(cli, ["--sarif", "audit-trail-conformance-check", "--input", str(trail)])
+    doc = _json.loads(result.output)
+    assert doc["runs"][0]["results"] == []  # all 6 checks passed
+
+
 def test_cli_custom_retention_days(tmp_path):
     runner = CliRunner()
     from roam.cli import cli