agent-trajectory-diff 0.3.0__tar.gz → 0.4.0__tar.gz

{agent_trajectory_diff-0.3.0 → agent_trajectory_diff-0.4.0}/.gitignore

@@ -82,3 +82,4 @@ website/.env.production.local
 
 # pytest-benchmark local results
 .benchmarks/
+_record_demo/

{agent_trajectory_diff-0.3.0 → agent_trajectory_diff-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-trajectory-diff
-Version: 0.3.0
+Version: 0.4.0
 Summary: A developer-first package to evaluate and find regressions in agent trajectories
 Project-URL: Homepage, https://github.com/lostmartian/agentdiff
 Project-URL: Repository, https://github.com/lostmartian/agentdiff
@@ -60,8 +60,26 @@ Or using `uv`:
 uv add agent-trajectory-diff
 ```
 
+Enable tab-completion for the CLI (bash/zsh/fish/powershell):
+```bash
+agentdiff --install-completion
+```
+> Tip: for a global `agentdiff` command without activating a venv, use `uv tool install agent-trajectory-diff` — then completion works anywhere.
+
 ## Quickstart
 
+### 0. No trace yet? Record one.
+
+Point `record` at any callable (your agent's entry function) and it captures a canonical trace:
+
+```bash
+agentdiff record my_agent:run --input '{"question": "What is AgentDiff?"}' --out traces/run.json
+```
+
+- `--input` takes a JSON object (passed as kwargs) or `@file.json`
+- A failed run is still recorded — diff it to see exactly what broke
+- Then compare: `agentdiff traces/baseline.json traces/run.json`
+
 ### 1. CLI Usage
 
 Compare two trajectory JSON traces from your terminal:
@@ -78,6 +96,8 @@ Options:
 - `--max-cost-delta`: Maximum cost increase percentage allowed.
 - `--baseline, -b PATH`: Compare against a persistent baseline trace file (see [Baseline workflow](#baseline-workflow)).
 - `--update-baseline`: Overwrite the persistent baseline with the candidate after a clean diff.
+- `--baseline-config PATH`: The `agentdiff.toml` the **baseline** was recorded with. When gate values differ from this run's config, the report flags the change (Goodhart guard — see [Gate governance](https://agentdiff.lostmartian.in/docs/configuration#gate-governance-goodhart-guard)).
+- `--stale-days N`: Warn via `--explain` when the baseline file is older than N days (default: config `stale_baseline_days` or 30 — advisory only).
 - `--config PATH`: Load defaults from an `agentdiff.toml` (auto-discovered if not given).
 
 #### Config-as-code (`agentdiff.toml`)

{agent_trajectory_diff-0.3.0 → agent_trajectory_diff-0.4.0}/README.md

@@ -40,8 +40,26 @@ Or using `uv`:
 uv add agent-trajectory-diff
 ```
 
+Enable tab-completion for the CLI (bash/zsh/fish/powershell):
+```bash
+agentdiff --install-completion
+```
+> Tip: for a global `agentdiff` command without activating a venv, use `uv tool install agent-trajectory-diff` — then completion works anywhere.
+
 ## Quickstart
 
+### 0. No trace yet? Record one.
+
+Point `record` at any callable (your agent's entry function) and it captures a canonical trace:
+
+```bash
+agentdiff record my_agent:run --input '{"question": "What is AgentDiff?"}' --out traces/run.json
+```
+
+- `--input` takes a JSON object (passed as kwargs) or `@file.json`
+- A failed run is still recorded — diff it to see exactly what broke
+- Then compare: `agentdiff traces/baseline.json traces/run.json`
+
 ### 1. CLI Usage
 
 Compare two trajectory JSON traces from your terminal:
@@ -58,6 +76,8 @@ Options:
 - `--max-cost-delta`: Maximum cost increase percentage allowed.
 - `--baseline, -b PATH`: Compare against a persistent baseline trace file (see [Baseline workflow](#baseline-workflow)).
 - `--update-baseline`: Overwrite the persistent baseline with the candidate after a clean diff.
+- `--baseline-config PATH`: The `agentdiff.toml` the **baseline** was recorded with. When gate values differ from this run's config, the report flags the change (Goodhart guard — see [Gate governance](https://agentdiff.lostmartian.in/docs/configuration#gate-governance-goodhart-guard)).
+- `--stale-days N`: Warn via `--explain` when the baseline file is older than N days (default: config `stale_baseline_days` or 30 — advisory only).
 - `--config PATH`: Load defaults from an `agentdiff.toml` (auto-discovered if not given).
 
 #### Config-as-code (`agentdiff.toml`)

{agent_trajectory_diff-0.3.0 → agent_trajectory_diff-0.4.0}/src/agentdiff/__init__.py

@@ -32,7 +32,7 @@ Typical flow::
     assert_no_regressions(report)
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 from agentdiff.adapters import (
     BaseAdapter,

{agent_trajectory_diff-0.3.0 → agent_trajectory_diff-0.4.0}/src/agentdiff/cli.py

@@ -2,25 +2,101 @@ import json
 import os
 import shutil
 import sys
+from pathlib import Path
 
 import typer
 
 from agentdiff.ci.baseline import decide_rotation
 from agentdiff.ci.github import post_pr_comment
-from agentdiff.config import AgentDiffConfig, load_config
+from agentdiff.config import AgentDiffConfig, find_config_file, load_config
 from agentdiff.engine.comparator import compare
 from agentdiff.engine.explanations import format_explanations, locate_culprit
 from agentdiff.engine.tree import render_tree
+from agentdiff.governance import diff_gate_thresholds, provenance_line
 from agentdiff.loader import load_trace
+from agentdiff.models.step import StepStatus
+from agentdiff.recorder import record_run, save_trace
 from agentdiff.reporters.markdown import generate_markdown
 from agentdiff.reporters.pr import generate_pr_markdown
 from agentdiff.reporters.terminal import print_report
+from agentdiff.staleness import check_baseline_staleness
 
 app = typer.Typer(
     help="AgentDiff CLI - Compare multi-turn agent execution trajectories."
 )
 
 
+@app.command(name="record")
+def record(
+    target: str = typer.Argument(
+        ...,
+        help="Callable to run, as 'module:function' or 'module:Class.method'.",
+    ),
+    out: str = typer.Option(
+        ...,
+        "--out",
+        "-o",
+        help="Path to write the captured trace JSON (e.g. traces/run.json).",
+    ),
+    input_json: str | None = typer.Option(
+        None,
+        "--input",
+        "-i",
+        help="JSON object passed to the callable as kwargs (or a single positional arg if not an object). Use '@file.json' to read from a file.",
+    ),
+    name: str | None = typer.Option(
+        None,
+        "--name",
+        help="Agent name recorded in the trace (default: function name).",
+    ),
+):
+    """Runs an agent callable once and captures its trajectory as a trace.
+
+    Example:
+        agentdiff record my_agent:run --input '{"question": "hi"}' --out traces/run.json
+
+    The captured trace is a canonical AgentDiff JSON, ready for:
+
+        agentdiff diff traces/baseline.json traces/run.json
+    """
+    task_input: dict | None = None
+    if input_json:
+        try:
+            if input_json.startswith("@"):
+                task_input = json.loads(
+                    Path(input_json[1:]).read_text(encoding="utf-8")
+                )
+            else:
+                task_input = json.loads(input_json)
+        except (json.JSONDecodeError, FileNotFoundError) as e:
+            typer.echo(f"Invalid --input: {e}", err=True)
+            sys.exit(2)
+        if not isinstance(task_input, dict):
+            task_input = {"input": task_input}
+
+    try:
+        trace = record_run(target, task_input=task_input, agent_name=name)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        sys.exit(2)
+    except Exception as e:
+        typer.echo(f"Recording failed: {e}", err=True)
+        sys.exit(3)
+
+    path = save_trace(trace, out)
+
+    if trace.steps[0].status == StepStatus.ERROR:
+        typer.echo(
+            f"Recorded FAILED run → {path}\n  error: {trace.steps[0].error_message}",
+            err=True,
+        )
+        sys.exit(1)
+
+    typer.echo(f"Recorded run → {path}")
+    typer.echo(f"  agent: {trace.agent_name} · latency: {trace.total_latency_ms:.0f}ms")
+    typer.echo(f"Next: agentdiff diff <baseline> {path}")
+
+
 def _resolve_cli(cfg: AgentDiffConfig, **values):
     """Returns config-provided values for any option left at its sentinel."""
     resolved = {}
@@ -106,9 +182,34 @@ def diff(
     max_drift: float = typer.Option(
         0.05, help="Max TDI a clean run may have for staged auto-rotation."
     ),
+    baseline_config: str | None = typer.Option(
+        None,
+        "--baseline-config",
+        help="Path to the agentdiff.toml the BASELINE was recorded with. When gate values differ from this run's config, the report flags the change (Goodhart guard).",
+    ),
+    stale_days: int | None = typer.Option(
+        None,
+        "--stale-days",
+        help="Warn (with --explain) when the baseline file is older than this many days (default: config or 30).",
+    ),
 ):
     """Compares baseline and candidate agent trajectories."""
     cfg = load_config(config)
+    config_source = config or (str(find_config_file()) if find_config_file() else None)
+    threshold_changes: list = []
+    if baseline_config:
+        try:
+            baseline_cfg = load_config(baseline_config)
+        except FileNotFoundError as e:
+            typer.echo(f"Baseline config not found: {e}", err=True)
+            sys.exit(2)
+        threshold_changes = diff_gate_thresholds(baseline_cfg, cfg)
+    gate_provenance = provenance_line(cfg, config_source)
+    stale_days = (
+        stale_days
+        if stale_days is not None
+        else getattr(cfg.cli, "stale_baseline_days", 30)
+    )
     values = _resolve_cli(
         cfg,
         adapter=adapter,
@@ -156,6 +257,11 @@ def diff(
         else:
             actual_baseline = baseline_path
 
+        # F7 — surface baseline age so stale baselines are re-recorded deliberately
+        staleness = check_baseline_staleness(
+            actual_baseline, stale_after_days=stale_days
+        )
+
         baseline = load_trace(actual_baseline, adapter)
     except (json.JSONDecodeError, ValueError, FileNotFoundError) as e:
         typer.echo(f"Error loading or parsing trace: {e}", err=True)
@@ -194,10 +300,11 @@ def diff(
             # For console printing we write directly, but we can capture it or format differently if output_file is active
             if output_file:
                 # If writing terminal format to file, output the text summary representation
-                output_content = report.summary()
+                output_content = report.summary() + f"\n{gate_provenance}\n"
             else:
-                print_report(report)
+                print_report(report, gate_provenance=gate_provenance)
         elif format.lower() == "json":
+            report.gate_provenance = gate_provenance
             output_content = report.model_dump_json(indent=2)
             if not output_file:
                 typer.echo(output_content)
@@ -212,6 +319,8 @@ def diff(
                 max_loops=max_loops,
                 max_cost_delta=max_cost_delta,
                 max_recovery_ratio=max_recovery_ratio,
+                threshold_changes=threshold_changes,
+                gate_provenance=gate_provenance,
             )
             if not output_file:
                 typer.echo(output_content)
@@ -225,6 +334,12 @@ def diff(
             culprit = locate_culprit(report)
             if culprit:
                 typer.echo("\n" + culprit.render())
+            if staleness.is_stale:
+                typer.echo(f"\n! {staleness.render()}")
+            if threshold_changes:
+                typer.echo("\nGate thresholds changed vs baseline config:")
+                for change in threshold_changes:
+                    typer.echo(f"  ! {change.render()}")
 
         # Print the collapsed divergence tree when requested
         if tree:
@@ -238,6 +353,8 @@ def diff(
                 max_loops=max_loops,
                 max_cost_delta=max_cost_delta,
                 max_recovery_ratio=max_recovery_ratio,
+                threshold_changes=threshold_changes,
+                gate_provenance=gate_provenance,
             )
             comment = post_pr_comment(body, pr)
             url = comment.get("html_url")
@@ -285,5 +402,46 @@ def main():
         sys.exit(3)
 
 
+def _install_diff_default() -> None:
+    """E1 compat: `agentdiff base.json cand.json` (no subcommand) means `diff`.
+
+    With two commands registered, Typer requires an explicit subcommand. We
+    patch the built click.Group so a leading positional that isn't a known
+    command is treated as `diff ...`. Works for the real CLI and CliRunner.
+    """
+    import typer.main
+
+    original_get_command = typer.main.get_command
+
+    def get_command_with_default(typer_app):
+        group = original_get_command(typer_app)
+        if not getattr(group, "_diff_default", False):
+            original_parse_args = group.parse_args
+
+            def parse_args(ctx, args):
+                if (
+                    args
+                    and args[0] not in group.commands
+                    and not args[0].startswith("-")
+                ):
+                    args = ["diff", *args]
+                original_parse_args(ctx, args)
+
+            group.parse_args = parse_args
+            group._diff_default = True
+        return group
+
+    typer.main.get_command = get_command_with_default
+
+    # typer.testing binds get_command at import time — patch its reference too
+    import typer.testing as testing_module
+
+    if getattr(testing_module, "_get_command", None) is original_get_command:
+        testing_module._get_command = get_command_with_default
+
+
+_install_diff_default()
+
+
 if __name__ == "__main__":
     main()

{agent_trajectory_diff-0.3.0 → agent_trajectory_diff-0.4.0}/src/agentdiff/config.py

@@ -69,6 +69,7 @@ class CliConfig:
     max_cost_delta: float = 10.0
     max_wasted_effort: float = 0.1
     max_recovery_ratio: float | None = None
+    stale_baseline_days: int = 30
 
 
 @dataclass

agent_trajectory_diff-0.4.0/src/agentdiff/governance.py

@@ -0,0 +1,86 @@
+"""Gate governance — detect when the gate itself changed (G6/G7).
+
+Goodhart guard: a threshold tuned until CI goes green stops being a control.
+These helpers make threshold changes visible *next to the diff they let
+through*, so loosening the gate is as reviewable as the code it guards.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agentdiff.config import AgentDiffConfig
+
+# The gate knobs that decide pass/fail in the CLI diff path, in display order.
+_GATED_KEYS: tuple[str, ...] = (
+    "max_divergence",
+    "max_loops",
+    "max_cost_delta",
+    "max_recovery_ratio",
+)
+
+# Defaults used when neither config nor flag provides a value (mirrors cli.py).
+_EFFECTIVE_DEFAULTS: dict[str, float | int | None] = {
+    "max_divergence": 0.3,
+    "max_loops": 0,
+    "max_cost_delta": 10.0,
+    "max_recovery_ratio": None,
+}
+
+
+@dataclass(frozen=True)
+class ThresholdChange:
+    """One gate knob that differs between the baseline config and this run."""
+
+    gate: str
+    old: float | int | None
+    new: float | int | None
+
+    def render(self) -> str:
+        return f"{self.gate}: `{self.old}` → `{self.new}`"
+
+
+def effective_gates(cfg: AgentDiffConfig) -> dict[str, float | int | None]:
+    """Resolves the effective gate values from a config (config or defaults)."""
+    resolved: dict[str, float | int | None] = {}
+    for key in _GATED_KEYS:
+        value = getattr(cfg.cli, key, None)
+        if value is None:
+            value = _EFFECTIVE_DEFAULTS[key]
+        resolved[key] = value
+    return resolved
+
+
+def diff_gate_thresholds(
+    baseline_cfg: AgentDiffConfig, candidate_cfg: AgentDiffConfig
+) -> list[ThresholdChange]:
+    """Returns gate knobs that differ between two configs, display-ordered."""
+    old_gates = effective_gates(baseline_cfg)
+    new_gates = effective_gates(candidate_cfg)
+    return [
+        ThresholdChange(gate=key, old=old_gates[key], new=new_gates[key])
+        for key in _GATED_KEYS
+        if old_gates[key] != new_gates[key]
+    ]
+
+
+def provenance_line(cfg: AgentDiffConfig, config_path: str | None) -> str:
+    """G7 — one-line, self-describing gate summary for any report.
+
+    Names the active thresholds and where they came from, so every diff
+    answers "what rules judged me?" without opening the config.
+    """
+    gates = effective_gates(cfg)
+    source = (
+        f"agentdiff.toml ({config_path})"
+        if config_path
+        else "defaults (no agentdiff.toml found)"
+    )
+    parts = [
+        f"max_divergence={gates['max_divergence']}",
+        f"max_loops={gates['max_loops']}",
+        f"max_cost_delta={gates['max_cost_delta']}%",
+    ]
+    if gates["max_recovery_ratio"] is not None:
+        parts.append(f"max_recovery_ratio={gates['max_recovery_ratio']}")
+    return f"Gate: {', '.join(parts)} — source: {source}"

{agent_trajectory_diff-0.3.0 → agent_trajectory_diff-0.4.0}/src/agentdiff/models/report.py

@@ -37,6 +37,11 @@ class DiffReport(BaseModel):
     recovery_step_ratio: float = 0.0
     step_diffs: list[StepDiff] = Field(default_factory=list)
     passed: bool = True
+    gate_provenance: str | None = Field(
+        default=None,
+        description="G7: one-line summary of active gate thresholds and their "
+        "source (agentdiff.toml path or defaults). Populated by the CLI.",
+    )
 
     def summary(self) -> str:
         """Returns a string summarizing the comparison report."""

agent_trajectory_diff-0.4.0/src/agentdiff/recorder.py

@@ -0,0 +1,158 @@
+"""Record an agent run and capture its trajectory as an AgentDiff trace.
+
+E3 — the ``record`` subcommand closes the biggest onboarding gap: "how do I
+get a trace?". Point it at any callable that returns a dict (or a string,
+which is wrapped as ``{"output": ...}``), and AgentDiff:
+
+1. imports the callable (``module:function`` or ``module.Class.method``),
+2. times its execution,
+3. captures the return value as the final output,
+4. writes a canonical Generic-format trace JSON ready for ``agentdiff diff``.
+
+The callable's *internal* steps (tool calls, LLM turns) are opaque to us —
+frameworks that expose those should export their native traces through the
+adapters instead. ``record`` is for agents (and plain functions) with no
+telemetry: one deterministic step per run, so diffs catch output/behavior
+changes, loops and cost deltas come from repeated runs, and the pytest
+plugin works unchanged.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import sys
+import time
+from collections.abc import Callable
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from agentdiff.models.step import StepStatus, StepType, TokenUsage, TraceStep
+from agentdiff.models.trace import AgentTrace
+
+_RECORD_STEP_ID = "recorded-run"
+
+
+def resolve_callable(target: str) -> Callable[..., Any]:
+    """Imports and returns the callable described by ``module:function``.
+
+    Also accepts ``module:Class.method`` (unbound — called with no args only
+    if it does not require self, e.g. a ``@staticmethod``) and ``module:function``
+    where ``function`` is any zero-arg callable object.
+    """
+    if ":" not in target:
+        raise ValueError(
+            f"Invalid target {target!r}. Use 'module:function' or 'module:Class.method'."
+        )
+    module_path, _, attr_path = target.partition(":")
+
+    # The user runs this from their project root; their agent module lives there.
+    # pytest does the same thing with rootdir insertion.
+    cwd = str(Path.cwd())
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as e:
+        raise ValueError(f"Cannot import module {module_path!r}: {e}") from e
+
+    obj: Any = module
+    for part in attr_path.split("."):
+        try:
+            obj = getattr(obj, part)
+        except AttributeError as e:
+            raise ValueError(
+                f"Cannot resolve {attr_path!r} in module {module_path!r}: {e}"
+            ) from e
+
+    if not callable(obj):
+        raise ValueError(
+            f"Target {target!r} resolved to a non-callable ({type(obj).__name__})."
+        )
+    return obj
+
+
+def record_run(
+    target: str,
+    task_input: dict[str, Any] | None = None,
+    agent_name: str | None = None,
+) -> AgentTrace:
+    """Runs ``target`` once and captures the execution as an :class:`AgentTrace`.
+
+    The callable is invoked with ``task_input`` unpacked as keyword arguments
+    when it is a dict, or as a single positional argument otherwise.
+    """
+    fn = resolve_callable(target)
+    task = task_input if task_input is not None else {}
+    name = agent_name or target.split(":")[-1]
+
+    started = time.perf_counter()
+    error_message: str | None = None
+    status = StepStatus.SUCCESS
+    result: Any = None
+    try:
+        if isinstance(task, dict) and task:
+            result = fn(**task)
+        elif isinstance(task, dict):
+            result = fn()
+        else:
+            result = fn(task)
+    except Exception as e:
+        status = StepStatus.ERROR
+        error_message = f"{type(e).__name__}: {e}"
+    latency_ms = (time.perf_counter() - started) * 1000.0
+
+    if result is None or isinstance(result, dict):
+        output: dict[str, Any] | None = result if isinstance(result, dict) else None
+        if result is not None and not isinstance(result, dict):
+            output = {"output": result}
+    elif isinstance(result, str):
+        output = {"output": result}
+    else:
+        output = {"output": _safe_serialize(result)}
+
+    step = TraceStep(
+        step_id=_RECORD_STEP_ID,
+        parent_id=None,
+        step_index=0,
+        step_type=StepType.TOOL_CALL,
+        name=name,
+        input_payload=task
+        if isinstance(task, dict)
+        else {"input": _safe_serialize(task)},
+        output_payload=output,
+        status=status,
+        error_message=error_message,
+        latency_ms=latency_ms,
+        tokens=TokenUsage(),
+    )
+
+    trace = AgentTrace(
+        trace_id=f"recorded-{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%S')}-{abs(hash(target)) % 10000:04d}",
+        agent_name=name,
+        task_input=task if isinstance(task, dict) else {"input": _safe_serialize(task)},
+        final_output=output if status == StepStatus.SUCCESS else None,
+        steps=[step],
+        total_latency_ms=latency_ms,
+        metadata={"recorded_from": target, "recorder": "agentdiff record"},
+    )
+    return trace
+
+
+def _safe_serialize(value: Any) -> Any:
+    """Best-effort JSON-safe conversion for arbitrary return values."""
+    try:
+        json.dumps(value)
+        return value
+    except (TypeError, ValueError):
+        return repr(value)
+
+
+def save_trace(trace: AgentTrace, out_path: str | Path) -> Path:
+    """Writes the trace as canonical AgentDiff JSON; returns the resolved path."""
+    path = Path(out_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(trace.model_dump_json(indent=2), encoding="utf-8")
+    return path

{agent_trajectory_diff-0.3.0 → agent_trajectory_diff-0.4.0}/src/agentdiff/reporters/pr.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from agentdiff.engine.explanations import locate_culprit
 from agentdiff.engine.tree import render_tree
+from agentdiff.governance import ThresholdChange
 from agentdiff.models.report import DiffReport
 
 DEFAULT_MAX_DIVERGENCE = 0.3
@@ -14,12 +15,18 @@ def generate_pr_markdown(
     max_loops: int = 0,
     max_cost_delta: float = DEFAULT_MAX_COST_DELTA,
     max_recovery_ratio: float | None = None,
+    threshold_changes: list[ThresholdChange] | None = None,
+    gate_provenance: str | None = None,
 ) -> str:
     """Renders a compact, PR-ready markdown comment.
 
     Summary status + gate thresholds, the collapsed divergence tree, and the
     root-cause step — everything a reviewer needs without the full diff.
     The Recovery Step Ratio row only appears when a threshold is provided.
+
+    When ``threshold_changes`` is non-empty (G6), a warning block renders
+    above the gate table: the gate itself moved in this PR, so the diff
+    above was judged against looser/tighter rules than the baseline had.
     """
     status = "⛔ **FAILED**" if not report.passed else "✅ **PASSED**"
 
@@ -28,12 +35,27 @@ def generate_pr_markdown(
         "",
         f"**Status:** {status}",
         "",
-        "| Gate | Value | Threshold |",
-        "| :--- | :--- | :--- |",
-        f"| TDI | `{report.trajectory_divergence_index:.4f}` | ≤ `{max_divergence}` |",
-        f"| Loops | `{len(report.loops_detected)}` | ≤ `{max_loops}` |",
-        f"| Cost delta | `{report.cost_delta_percentage:+.2f}%` | ≤ `{max_cost_delta}%` |",
     ]
+
+    if threshold_changes:
+        lines.append("> [!WARNING]")
+        lines.append(
+            "> **Gate thresholds changed in this PR** — the diff below was judged against this PR's rules, not the baseline's."
+        )
+        lines.append(">")
+        for change in threshold_changes:
+            lines.append(f"> - {change.render()}")
+        lines.append("")
+
+    lines.extend(
+        [
+            "| Gate | Value | Threshold |",
+            "| :--- | :--- | :--- |",
+            f"| TDI | `{report.trajectory_divergence_index:.4f}` | ≤ `{max_divergence}` |",
+            f"| Loops | `{len(report.loops_detected)}` | ≤ `{max_loops}` |",
+            f"| Cost delta | `{report.cost_delta_percentage:+.2f}%` | ≤ `{max_cost_delta}%` |",
+        ]
+    )
     if max_recovery_ratio is not None:
         lines.append(
             f"| Recovery Step Ratio | `{report.recovery_step_ratio:.2f} "
@@ -72,4 +94,7 @@ def generate_pr_markdown(
             )
         lines.append("")
 
+    if gate_provenance:
+        lines.append(f"<sub>{gate_provenance}</sub>")
+
     return "\n".join(lines)

{agent_trajectory_diff-0.3.0 → agent_trajectory_diff-0.4.0}/src/agentdiff/reporters/terminal.py

@@ -63,8 +63,13 @@ def render_diff_table(report: DiffReport) -> Table:
     return table
 
 
-def print_report(report: DiffReport):
-    """Outputs the complete DiffReport to the terminal."""
+def print_report(report: DiffReport, gate_provenance: str | None = None):
+    """Outputs the complete DiffReport to the terminal.
+
+    ``gate_provenance`` (G7) appends a one-line, self-describing gate summary
+    — active thresholds and their source — so the report answers "what rules
+    judged me?" without opening the config.
+    """
     console = Console()
 
     status_str = (
@@ -87,6 +92,8 @@ def print_report(report: DiffReport):
         f"  • Token Delta:   {report.token_delta_percentage:+.2f}%\n"
         f"  • Cost Delta:    {report.cost_delta_percentage:+.2f}%"
     )
+    if gate_provenance:
+        summary_text += f"\n\n[dim]{gate_provenance}[/dim]"
 
     panel = Panel(
         summary_text,

agent_trajectory_diff-0.4.0/src/agentdiff/staleness.py

@@ -0,0 +1,61 @@
+"""F7 — stale-baseline detection (regressional Goodhart guard).
+
+Baselines age silently: a golden trace from three sprints ago still anchors
+every diff, but the product it represented no longer exists. This module
+makes that age visible so teams re-record baselines deliberately instead of
+losing trust in a gate that "just got noisy".
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass
+
+DEFAULT_STALE_DAYS = 30
+
+
+@dataclass(frozen=True)
+class Staleness:
+    """How old a baseline file is, and whether that crosses the stale line."""
+
+    age_days: float
+    stale_after_days: int
+    missing: bool = False
+
+    @property
+    def is_stale(self) -> bool:
+        return not self.missing and self.age_days > self.stale_after_days
+
+    def render(self) -> str:
+        if self.missing:
+            return ""
+        age = f"{self.age_days:.0f} days" if self.age_days >= 1 else "less than a day"
+        line = f"Baseline is {age} old (last modified {time.strftime('%Y-%m-%d', time.localtime(self._mtime))})."
+        if self.is_stale:
+            line += (
+                f" Stale threshold is {self.stale_after_days} days - consider re-recording"
+                " it if the agent's expected behavior has legitimately changed"
+                " (agentdiff record ... --update-baseline)."
+            )
+        return line
+
+    _mtime: float = 0.0
+
+
+def check_baseline_staleness(
+    baseline_path: str | os.PathLike,
+    stale_after_days: int = DEFAULT_STALE_DAYS,
+) -> Staleness:
+    """Inspects the baseline file's modification time.
+
+    Missing files return ``missing=True`` with ``is_stale=False`` - a missing
+    baseline is a load error, not a staleness problem.
+    """
+    try:
+        mtime = os.path.getmtime(baseline_path)
+    except OSError:
+        return Staleness(age_days=0.0, stale_after_days=stale_after_days, missing=True)
+
+    age_days = max(0.0, (time.time() - mtime) / 86400)
+    return Staleness(age_days=age_days, stale_after_days=stale_after_days, _mtime=mtime)