xrefkit 0.4.10__tar.gz → 0.4.11__tar.gz

{xrefkit-0.4.10/xrefkit.egg-info → xrefkit-0.4.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.10
+Version: 0.4.11
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License

{xrefkit-0.4.10 → xrefkit-0.4.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrefkit"
-version = "0.4.10"
+version = "0.4.11"
 description = "Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit"
 readme = "README.md"
 requires-python = ">=3.11"

{xrefkit-0.4.10 → xrefkit-0.4.11}/tests/test_dashboard.py

@@ -628,3 +628,33 @@ class DashboardTests(unittest.TestCase):
             self.assertIn("<script>alert(1)</script>", html)
             self.assertIn("<script>alert(2)</script>", html)
             self.assertNotIn("<script>alert(1)", html)
+
+    def test_dashboard_includes_decision_trace_panel_and_records(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            ledger = root / "work" / "decision-trace" / "events.jsonl"
+            ledger.parent.mkdir(parents=True, exist_ok=True)
+            ledger.write_text(
+                json.dumps({
+                    "recorded_by": "ai_protocol",
+                    "event_id": "DEC-001",
+                    "event_type": "decision-change",
+                    "status": "provisional",
+                    "resolution": None,
+                    "reason": "try Y",
+                    "depends_on": [],
+                    "branch": "hypothesis/decision-Y",
+                }) + "\n",
+                encoding="utf-8",
+            )
+            payload = build_payload(root, root / "work" / "sessions")
+            html = _html_page(payload)
+
+            self.assertEqual(payload["decision_trace"]["summary"]["events"], 1)
+            self.assertEqual(payload["decision_trace"]["summary"]["groups"], {"decision": 1})
+            self.assertIn('data-panel="decision-trace"', html)
+            self.assertIn('id="decision-trace"', html)
+            self.assertIn("DEC-001", html)
+            self.assertIn("hypothesis/decision-Y", html)
+            self.assertIn("Dependency graph (Mermaid)", html)
+            self.assertIn("Impact groups", html)

xrefkit-0.4.11/tests/test_decision_trace.py

@@ -0,0 +1,301 @@
+import json
+import argparse
+import subprocess
+import uuid
+
+from xrefkit.decision_trace import main
+from xrefkit.skillrun import run_workflow_instruction
+
+
+def test_event_impact_and_graph(tmp_path, capsys):
+    assert main([
+        "event", "--root", str(tmp_path), "--event-id", "DEC-1",
+        "--event-type", "decision-change", "--reason", "initial decision",
+    ]) == 0
+    assert main([
+        "event", "--root", str(tmp_path), "--event-id", "EVAL-1",
+        "--event-type", "evaluation", "--reason", "evaluate provisional result",
+        "--depends-on", "DEC-1",
+    ]) == 0
+    capsys.readouterr()
+
+    assert main(["impact", "--root", str(tmp_path), "--event-id", "DEC-1", "--json"]) == 0
+    impact = json.loads(capsys.readouterr().out)
+    assert impact["direct_impact"] == ["EVAL-1"]
+    assert impact["needs_human_review"] == ["EVAL-1"]
+    assert impact["summary"]["groups"] == {"evaluation": 1}
+    assert impact["groups"]["evaluation"][0]["review_required"] is True
+
+    assert main(["graph", "--root", str(tmp_path)]) == 0
+    graph = capsys.readouterr().out
+    assert "DEC-1<br/>provisional" in graph
+    assert "EVAL-1<br/>provisional" in graph
+    assert "-->" in graph
+
+
+def test_duplicate_event_is_rejected(tmp_path):
+    args = [
+        "event", "--root", str(tmp_path), "--event-id", "DEC-1",
+        "--event-type", "decision-note", "--reason", "record",
+    ]
+    assert main(args) == 0
+    assert main(args) == 2
+    assert len((tmp_path / "work" / "decision-trace" / "events.jsonl").read_text(encoding="utf-8").splitlines()) == 1
+
+
+def test_checkpoint_commits_manifest_and_creates_tag(tmp_path):
+    def git(*args):
+        return subprocess.run(["git", *args], cwd=tmp_path, check=True, capture_output=True, text=True)
+
+    git("init")
+    git("config", "user.email", "test@example.invalid")
+    git("config", "user.name", "Decision Trace Test")
+    (tmp_path / "README.md").write_text("base\n", encoding="utf-8")
+    git("add", "README.md")
+    git("commit", "-m", "initial")
+
+    assert main([
+        "checkpoint", "--root", str(tmp_path), "--checkpoint-id", "CP-1",
+        "--purpose", "before AI run", "--json",
+    ]) == 0
+    manifest = tmp_path / "work" / "decision-trace" / "checkpoints" / "CP-1.json"
+    assert manifest.exists()
+    assert json.loads(manifest.read_text(encoding="utf-8"))["git_commit"]
+    assert git("rev-parse", "checkpoint/CP-1^{}").stdout.strip() == git("rev-parse", "HEAD").stdout.strip()
+    assert "checkpoint: CP-1" in git("log", "-1", "--pretty=%s").stdout
+
+
+def test_checkpoint_stops_on_dirty_worktree(tmp_path):
+    subprocess.run(["git", "init"], cwd=tmp_path, check=True, capture_output=True)
+    (tmp_path / "README.md").write_text("uncommitted\n", encoding="utf-8")
+    assert main([
+        "checkpoint", "--root", str(tmp_path), "--checkpoint-id", "CP-1",
+        "--purpose", "before AI run",
+    ]) == 2
+
+
+def test_branch_is_created_from_fixed_ref(tmp_path):
+    def git(*args):
+        return subprocess.run(["git", *args], cwd=tmp_path, check=True, capture_output=True, text=True)
+
+    git("init")
+    git("config", "user.email", "test@example.invalid")
+    git("config", "user.name", "Decision Trace Test")
+    (tmp_path / "README.md").write_text("base\n", encoding="utf-8")
+    git("add", "README.md")
+    git("commit", "-m", "initial")
+    base = git("rev-parse", "HEAD").stdout.strip()
+
+    assert main([
+        "branch", "--root", str(tmp_path), "--branch", "hypothesis/decision-Y",
+        "--from-ref", "HEAD", "--purpose", "provisional decision Y", "--json",
+    ]) == 0
+    assert git("rev-parse", "hypothesis/decision-Y").stdout.strip() == base
+
+
+def test_branch_delete_preserves_disposal_adr(tmp_path):
+    def git(*args):
+        return subprocess.run(["git", *args], cwd=tmp_path, check=True, capture_output=True, text=True)
+
+    git("init")
+    git("config", "user.email", "test@example.invalid")
+    git("config", "user.name", "Decision Trace Test")
+    (tmp_path / "README.md").write_text("base\n", encoding="utf-8")
+    git("add", "README.md")
+    git("commit", "-m", "initial")
+    git("branch", "hypothesis/decision-Y")
+
+    assert main([
+        "branch-delete", "--root", str(tmp_path), "--branch", "hypothesis/decision-Y",
+        "--event-id", "ADR-002", "--reason", "performance evaluation failed", "--force", "--json",
+    ]) == 0
+    assert git("branch", "--list", "hypothesis/decision-Y").stdout.strip() == ""
+    events = [
+        json.loads(line)
+        for line in (tmp_path / "work" / "decision-trace" / "events.jsonl").read_text(encoding="utf-8").splitlines()
+    ]
+    assert [event["status"] for event in events] == ["disposal-requested", "deleted"]
+    assert events[1]["depends_on"] == ["ADR-002"]
+
+
+def test_resolution_is_a_new_final_event(tmp_path):
+    assert main([
+        "event", "--root", str(tmp_path), "--event-id", "DEC-001",
+        "--event-type", "decision-change", "--reason", "try Y",
+    ]) == 0
+    assert main([
+        "resolve", "--root", str(tmp_path), "--event-id", "RES-001",
+        "--target-event-id", "DEC-001", "--resolution", "rejected",
+        "--reason", "evaluation failed", "--json",
+    ]) == 0
+    events = [
+        json.loads(line)
+        for line in (tmp_path / "work" / "decision-trace" / "events.jsonl").read_text(encoding="utf-8").splitlines()
+    ]
+    assert events[0]["status"] == "provisional"
+    assert events[0]["resolution"] is None
+    assert events[1]["event_type"] == "resolution"
+    assert events[1]["resolution"] == "rejected"
+    assert events[1]["target_event_id"] == "DEC-001"
+
+
+def test_return_check_and_execute_checkpoint_before_branching(tmp_path):
+    def git(*args):
+        return subprocess.run(["git", *args], cwd=tmp_path, check=True, capture_output=True, text=True)
+
+    git("init")
+    git("config", "user.email", "test@example.invalid")
+    git("config", "user.name", "Decision Trace Test")
+    (tmp_path / "README.md").write_text("base\n", encoding="utf-8")
+    git("add", "README.md")
+    git("commit", "-m", "initial")
+    assert main([
+        "event", "--root", str(tmp_path), "--event-id", "DEC-001",
+        "--event-type", "decision-note", "--reason", "historical decision",
+    ]) == 0
+
+    assert main([
+        "return-check", "--root", str(tmp_path), "--target-event-id", "DEC-001",
+        "--to-ref", "HEAD", "--json",
+    ]) == 0
+    assert main([
+        "return-execute", "--root", str(tmp_path), "--event-id", "RET-001",
+        "--target-event-id", "DEC-001", "--to-ref", "HEAD",
+        "--branch", "hypothesis/resume-DEC-001", "--checkpoint-id", "CP-RETURN-001",
+        "--reason", "reconsider historical decision", "--confirmed", "--json",
+    ]) == 0
+    assert git("branch", "--list", "hypothesis/resume-DEC-001").stdout.strip()
+    events = [
+        json.loads(line)
+        for line in (tmp_path / "work" / "decision-trace" / "events.jsonl").read_text(encoding="utf-8").splitlines()
+    ]
+    assert events[-1]["event_type"] == "return"
+    assert events[-1]["status"] == "provisional"
+    assert events[-1]["human_decision"] == "confirmed"
+
+
+def test_current_only_context_contains_only_dependency_lineage(tmp_path, capsys):
+    for event_id, event_type, reason, dependencies in [
+        ("DEC-001", "decision-note", "old decision", []),
+        ("DEC-002", "decision-change", "new decision", ["DEC-001"]),
+        ("EVAL-001", "evaluation", "evaluate new decision", ["DEC-002"]),
+        ("DEC-OLD", "decision-note", "unrelated old path", []),
+    ]:
+        command = [
+            "event", "--root", str(tmp_path), "--event-id", event_id,
+            "--event-type", event_type, "--reason", reason,
+        ]
+        for dependency in dependencies:
+            command.extend(["--depends-on", dependency])
+        assert main(command) == 0
+    capsys.readouterr()
+
+    assert main(["context", "--root", str(tmp_path), "--event-id", "EVAL-001", "--json"]) == 0
+    context = json.loads(capsys.readouterr().out)
+    assert [event["event_id"] for event in context["events"]] == ["DEC-001", "DEC-002", "EVAL-001"]
+    assert context["excluded_event_ids"] == ["DEC-OLD"]
+    assert context["policy"] == "current-only"
+
+
+def test_source_check_verifies_commit_and_path(tmp_path):
+    source = tmp_path / "source"
+    ledger = tmp_path / "ledger"
+    source.mkdir()
+    ledger.mkdir()
+
+    def git(*args):
+        return subprocess.run(["git", *args], cwd=source, check=True, capture_output=True, text=True)
+
+    git("init")
+    git("config", "user.email", "test@example.invalid")
+    git("config", "user.name", "Decision Trace Test")
+    (source / "src.txt").write_text("source\n", encoding="utf-8")
+    git("add", "src.txt")
+    git("commit", "-m", "source")
+    commit = git("rev-parse", "HEAD").stdout.strip()
+    assert main([
+        "event", "--root", str(ledger), "--event-id", "SRC-001",
+        "--event-type", "source-link", "--reason", "link source",
+        "--source-repo", str(source), "--source-commit", commit, "--source-path", "src.txt",
+    ]) == 0
+    assert main([
+        "source-check", "--root", str(ledger), "--event-id", "SRC-001",
+        "--source-root", str(source), "--json",
+    ]) == 0
+
+
+def test_validate_checks_ledger_references(tmp_path, capsys):
+    assert main([
+        "event", "--root", str(tmp_path), "--event-id", "DEC-001",
+        "--event-type", "decision-note", "--reason", "record",
+    ]) == 0
+    capsys.readouterr()
+    assert main(["validate", "--root", str(tmp_path), "--json"]) == 0
+    result = json.loads(capsys.readouterr().out)
+    assert result["valid"] is True
+    assert result["event_count"] == 1
+
+
+def test_evaluation_point_records_criteria_as_provisional(tmp_path):
+    assert main([
+        "event", "--root", str(tmp_path), "--event-id", "DEC-001",
+        "--event-type", "decision-change", "--reason", "try change",
+    ]) == 0
+    assert main([
+        "evaluation-point", "--root", str(tmp_path), "--event-id", "EVP-001",
+        "--target-event-id", "DEC-001", "--criteria", "performance under threshold",
+        "--criteria", "source diff is traceable", "--evidence", "VER-001",
+        "--reason", "whole evaluation after provisional application",
+    ]) == 0
+    events = [
+        json.loads(line)
+        for line in (tmp_path / "work" / "decision-trace" / "events.jsonl").read_text(encoding="utf-8").splitlines()
+    ]
+    assert events[-1]["event_type"] == "evaluation-point"
+    assert events[-1]["status"] == "provisional"
+    assert events[-1]["criteria"] == ["performance under threshold", "source diff is traceable"]
+
+
+def test_workflow_run_creates_automatic_checkpoint_in_git_worktree(tmp_path):
+    def git(*args):
+        return subprocess.run(["git", *args], cwd=tmp_path, check=True, capture_output=True, text=True)
+
+    git("init")
+    git("config", "user.email", "test@example.invalid")
+    git("config", "user.name", "Decision Trace Test")
+    (tmp_path / "README.md").write_text("base\n", encoding="utf-8")
+    git("add", "README.md")
+    git("commit", "-m", "initial")
+    run_id = str(uuid.uuid4())
+    result = run_workflow_instruction(argparse.Namespace(
+        root=str(tmp_path), task="continue protocol work", task_file=None,
+        completion_condition=["run log is created"], use_default_completion_conditions=False,
+        run_id=run_id, out=str(tmp_path / "run.md"), flow_id=None, root_run_id=None,
+        parent_run_id=None, work_item_id=None, node_id=None, purpose=None,
+        scope_in=[], scope_out=[], owner=None, authority=None, expected_evidence=[], stop_condition=[],
+    ))
+    assert result.ok is True
+    assert result.decision_trace_checkpoint["checkpoint"]["run_id"] == run_id
+    assert "AI Decision Trace Checkpoint" in (tmp_path / "run.md").read_text(encoding="utf-8")
+    assert git("rev-parse", f"checkpoint/CP-RUN-{run_id}^{{}}").stdout.strip()
+
+
+def test_worktree_creates_isolated_hypothesis_checkout(tmp_path):
+    def git(*args):
+        return subprocess.run(["git", *args], cwd=tmp_path, check=True, capture_output=True, text=True)
+
+    git("init")
+    git("config", "user.email", "test@example.invalid")
+    git("config", "user.name", "Decision Trace Test")
+    (tmp_path / "README.md").write_text("base\n", encoding="utf-8")
+    git("add", "README.md")
+    git("commit", "-m", "initial")
+    worktree_path = tmp_path.parent / f"{tmp_path.name}-hypothesis"
+    assert main([
+        "worktree", "--root", str(tmp_path), "--path", str(worktree_path),
+        "--branch", "hypothesis/parallel-Y", "--from-ref", "HEAD",
+        "--purpose", "parallel hypothesis evaluation", "--json",
+    ]) == 0
+    assert (worktree_path / "README.md").exists()
+    assert git("-C", str(worktree_path), "branch", "--show-current").stdout.strip() == "hypothesis/parallel-Y"
+    git("worktree", "remove", "--force", str(worktree_path))

xrefkit-0.4.11/tests/test_wbs.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+
+import pytest
+
+from xrefkit.wbs import WbsError, parse_wbs, render_rollup, write_csv
+
+
+VALID = """| ID | Feature | Phase | Task | Assignee | Estimate(Person-Days) | Actual(Person-Days) | Status |
+| --- | --- | --- | --- | --- | ---: | ---: | --- |
+| T-001 | Intake | Analysis | A \\| B | Aki | 2 | 1 | done |
+| T-002 | Intake | Implementation | Build | Aki | 3 | 0 | doing |
+| T-003 | Reporting | Test | Check | Ren | 1 | 0 | todo |
+"""
+
+
+def test_parse_accepts_escaped_pipe_and_rolls_up() -> None:
+    headers, rows = parse_wbs(VALID)
+    assert headers[1] == "Feature"
+    assert rows[0][3] == "A | B"
+    output = render_rollup(rows)
+    assert "| Intake | 5 | 1 | 2 |" in output
+    assert "| Total | 6 | 1 | 3 |" in output
+
+
+@pytest.mark.parametrize(
+    "text, message",
+    [
+        (VALID.replace("| T-003 | Reporting | Test | Check | Ren | 1 | 0 | todo |", "| T-003 | Reporting | Test | Check | Ren | 1 | todo |"), "expected 8 cells"),
+        (VALID.replace("| T-003 | Reporting | Test | Check | Ren | 1 | 0 | todo |", "| T-003 | Reporting | Test | Check | Ren | -1 | 0 | todo |"), "must not be negative"),
+        (VALID.replace("| T-003 | Reporting | Test | Check | Ren | 1 | 0 | todo |", "| T-003 | Reporting | Test | Check | Ren | 1 | 0 | blocked |"), "Status must be"),
+    ],
+)
+def test_parse_rejects_invalid_rows(text: str, message: str) -> None:
+    with pytest.raises(WbsError, match=message):
+        parse_wbs(text)
+
+
+def test_csv_is_excel_readable(tmp_path: Path) -> None:
+    headers, rows = parse_wbs(VALID)
+    target = tmp_path / "wbs.csv"
+    write_csv(headers, rows, target)
+    assert target.read_bytes().startswith(b"\xef\xbb\xbf")
+    assert "T-001" in target.read_text(encoding="utf-8-sig")

{xrefkit-0.4.10 → xrefkit-0.4.11}/xrefkit/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.4.10"
+__version__ = "0.4.11"

{xrefkit-0.4.10 → xrefkit-0.4.11}/xrefkit/cli.py

@@ -6,7 +6,7 @@ import sys
 from collections.abc import Sequence
 
 
-_OPERATIONS = {"xref", "ctx", "goal", "gate", "pack", "dashboard", "analysis", "skill", "workflow", "host"}
+_OPERATIONS = {"xref", "ctx", "goal", "gate", "pack", "dashboard", "analysis", "skill", "workflow", "host", "trace"}
 _V2 = {"package", "show"}
 
 
@@ -28,6 +28,7 @@ def _print_help() -> None:
         "  goal       manage desired-state Goals and continuation state\n"
         "  dashboard  inspect runtime state\n"
         "  analysis   generate proposal-only observation reports\n"
+        "  trace      AI protocol adapter for decision changes and Git checkpoints\n"
         "  mcp        start the MCP server or initialize a client Prompt Flow\n"
         "  skills     synchronize released Skill and Knowledge bundles\n"
         "  package    inspect installed Skill packages\n"

{xrefkit-0.4.10 → xrefkit-0.4.11}/xrefkit/dashboard.py

@@ -760,6 +760,52 @@ def _missing_information_ranking(runs: list[DashboardRun]) -> list[dict[str, obj
     return rows
 
 
+def _decision_trace_payload(root: Path) -> dict[str, object]:
+    try:
+        from xrefkit.decision_trace import _graph, _impact_group, _read_events, _validate
+
+        events = _read_events(root)
+        groups: dict[str, int] = {}
+        for event in events:
+            group = _impact_group(event)
+            groups[group] = groups.get(group, 0) + 1
+        return {
+            "events": events,
+            "graph": _graph(root),
+            "validation": _validate(root),
+            "summary": {"events": len(events), "groups": dict(sorted(groups.items()))},
+        }
+    except (OSError, ValueError) as exc:
+        return {
+            "events": [],
+            "graph": "flowchart TD\n    empty[\"No decision-trace events\"]",
+            "validation": {"valid": False, "event_count": 0, "issues": [str(exc)]},
+            "summary": {"events": 0, "groups": {}},
+        }
+
+
+def _decision_trace_rows(trace: object) -> str:
+    if not isinstance(trace, dict):
+        return "<tr><td colspan='6'>No decision-trace records found.</td></tr>"
+    events = trace.get("events", [])
+    if not isinstance(events, list) or not events:
+        return "<tr><td colspan='6'>No decision-trace records found.</td></tr>"
+    rows: list[str] = []
+    for event in events:
+        if not isinstance(event, dict):
+            continue
+        rows.append(
+            "<tr>"
+            f"<td><code>{html.escape(str(event.get('event_id') or '-'))}</code></td>"
+            f"<td>{html.escape(str(event.get('event_type') or '-'))}</td>"
+            f"<td>{html.escape(str(event.get('status') or '-'))}</td>"
+            f"<td>{html.escape(str(event.get('resolution') or '-'))}</td>"
+            f"<td>{html.escape(str(event.get('branch') or '-'))}</td>"
+            f"<td>{html.escape(str(event.get('reason') or '-'))}</td>"
+            "</tr>"
+        )
+    return "\n".join(rows) or "<tr><td colspan='6'>No decision-trace records found.</td></tr>"
+
 def _flow_rows(flows: object) -> str:
     if not isinstance(flows, list) or not flows:
         return "<tr><td colspan='9'>No Prompt Flows found.</td></tr>"
@@ -989,6 +1035,7 @@ def build_payload(
     runs = collect_runs(root, sessions_dir, mcp_events_by_run, audit_errors)
     flows = collect_flows(runs)
     recoveries = collect_recoveries(runs)
+    decision_trace = _decision_trace_payload(root)
     summary = _summary(runs)
     summary["flows"] = len(flows)
     summary["recoveries"] = len(recoveries)
@@ -1003,6 +1050,7 @@ def build_payload(
         "runs": [run.to_dict() for run in runs],
         "flows": flows,
         "recoveries": recoveries,
+        "decision_trace": decision_trace,
     }
     payload["boundary_analysis"] = analyze_dashboard_payload(
         payload,
@@ -1026,8 +1074,10 @@ def _html_page(payload: dict[str, object]) -> str:
     summary = payload["summary"]
     runs = payload["runs"]
     flows = payload.get("flows", [])
+    decision_trace = payload.get("decision_trace", {})
     assert isinstance(summary, dict)
     assert isinstance(runs, list)
+    assert isinstance(decision_trace, dict)
     boundary_analysis = payload.get("boundary_analysis")
     if not isinstance(boundary_analysis, dict):
         boundary_analysis = {}
@@ -1070,6 +1120,26 @@ def _html_page(payload: dict[str, object]) -> str:
     xid_rows = "\n".join(_xid_usage_card(run) for run in runs if _has_xid_records(run))
     unused_xid_rows = _unused_xid_ranking_table(payload.get("unused_xid_ranking", []))
     missing_information_rows = _missing_information_ranking_table(payload.get("missing_information_ranking", []))
+    decision_trace_summary = decision_trace.get("summary", {})
+    if not isinstance(decision_trace_summary, dict):
+        decision_trace_summary = {}
+    decision_trace_rows = _decision_trace_rows(decision_trace)
+    decision_trace_groups = decision_trace_summary.get("groups", {})
+    if not isinstance(decision_trace_groups, dict):
+        decision_trace_groups = {}
+    decision_trace_group_rows = "".join(
+        f"<tr><td>{html.escape(str(group))}</td><td>{html.escape(str(count))}</td></tr>"
+        for group, count in sorted(decision_trace_groups.items())
+    ) or "<tr><td colspan='2'>No impact groups found.</td></tr>"
+    decision_trace_validation = decision_trace.get("validation", {})
+    if not isinstance(decision_trace_validation, dict):
+        decision_trace_validation = {}
+    decision_trace_issues = decision_trace_validation.get("issues", [])
+    if not isinstance(decision_trace_issues, list):
+        decision_trace_issues = []
+    decision_trace_issue_html = "" if not decision_trace_issues else "<ul>" + "".join(
+        f"<li>{html.escape(str(issue))}</li>" for issue in decision_trace_issues[:10]
+    ) + "</ul>"
     missing_information_cards = "\n".join(
         _missing_information_card(run)
         for run in runs
@@ -1345,6 +1415,7 @@ def _html_page(payload: dict[str, object]) -> str:
       <button class="tab" data-panel="xids">XID Usage</button>
       <button class="tab" data-panel="analysis">Analysis</button>
       <button class="tab" data-panel="missing-information">Missing Information</button>
+      <button class="tab" data-panel="decision-trace">Decision Trace</button>
     </nav>
     <section class="controls" aria-label="Skill run filters">
       <input id="run-search" class="search" type="search" placeholder="Search skill, path, run ID, session, repository, or status" aria-label="Search Skill runs">
@@ -1413,6 +1484,17 @@ def _html_page(payload: dict[str, object]) -> str:
       </div>
       {analysis_proposal_rows}
     </section>
+    <section id="decision-trace" class="panel">
+      <p class="category-note">AI decision-trace events, provisional resolutions, branches, and the current dependency graph. This panel observes records; it does not execute adoption or return operations.</p>
+      <section class="metrics"><div class="metric"><span>Trace events</span><strong>{html.escape(str(decision_trace_summary.get('events', 0)))}</strong></div><div class="metric"><span>Validation</span><strong>{html.escape(str(decision_trace_validation.get('valid', False)))}</strong></div></section>
+      <table class="table">
+        <thead><tr><th>Event</th><th>Type</th><th>Status</th><th>Resolution</th><th>Branch</th><th>Reason</th></tr></thead>
+        <tbody>{decision_trace_rows}</tbody>
+      </table>
+      <div class="box"><h3>Impact groups</h3><table class="table"><thead><tr><th>Group</th><th>Events</th></tr></thead><tbody>{decision_trace_group_rows}</tbody></table></div>
+      <div class="box"><h3>Dependency graph (Mermaid)</h3><pre>{html.escape(str(decision_trace.get('graph') or ''))}</pre></div>
+      {decision_trace_issue_html}
+    </section>
     <section id="missing-information" class="panel">
       <p class="category-note">Information required to correlate Skill execution, MCP access, Knowledge application, and downstream feedback.</p>
       <div class="box"><h3>Missing Information Ranking</h3>{missing_information_rows}</div>