artifact: add agent artifact bundle example

Adds a deterministic committed example artifact for the agent artifact bundle, a generator script, and exact regeneration parity coverage.

Author: ProfRandom92

artifacts/agent_artifact_bundle_example.json

@@ -0,0 +1,44 @@
+{
+  "artifact_id": "agent_artifact_bundle_example_v1",
+  "bundle": {
+    "branch": "feat/agent-artifact-bundle-example",
+    "changed_files": [
+      "artifacts/agent_artifact_bundle_example.json",
+      "scripts/generate_agent_artifact_bundle_example.py",
+      "tests/test_agent_artifact_bundle.py"
+    ],
+    "mcp_context_output_ref": "artifacts/mcp_context_layer_example.json",
+    "ok": true,
+    "result": "PASS",
+    "safe_pr_gate": {
+      "allow_dirty": false,
+      "allowed_prefixes": [],
+      "branch": "feat/agent-artifact-bundle-example",
+      "changed_paths": [
+        "artifacts/agent_artifact_bundle_example.json",
+        "scripts/generate_agent_artifact_bundle_example.py",
+        "tests/test_agent_artifact_bundle.py"
+      ],
+      "ok": true,
+      "problems": [],
+      "result": "PASS",
+      "status_short": []
+    },
+    "validation_evidence": [
+      {
+        "command": "python -m compileall -q scripts/agent_artifact_bundle.py scripts/generate_agent_artifact_bundle_example.py",
+        "result": "pass"
+      },
+      {
+        "command": "pytest tests/test_agent_artifact_bundle.py -q",
+        "result": "pass"
+      }
+    ]
+  },
+  "evaluation_mode": "deterministic",
+  "external_apis": "none",
+  "generated_by": "AgentArtifactBundleExampleGenerator",
+  "llm_judges": "none",
+  "schema_version": "agent_artifact_bundle_example.v1",
+  "version": "1.0"
+}

scripts/generate_agent_artifact_bundle_example.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Generate a deterministic agent artifact bundle example."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from scripts.agent_artifact_bundle import build_agent_artifact_bundle
+from scripts.safe_pr_gate import GateState
+
+ARTIFACT_ID = "agent_artifact_bundle_example_v1"
+OUTPUT_PATH = REPO_ROOT / "artifacts" / "agent_artifact_bundle_example.json"
+
+EXAMPLE_STATE = GateState(
+    branch="feat/agent-artifact-bundle-example",
+    status_short=(),
+    changed_paths=(
+        "artifacts/agent_artifact_bundle_example.json",
+        "scripts/generate_agent_artifact_bundle_example.py",
+        "tests/test_agent_artifact_bundle.py",
+    ),
+)
+VALIDATION_COMMANDS = [
+    "python -m compileall -q scripts/agent_artifact_bundle.py scripts/generate_agent_artifact_bundle_example.py",
+    "pytest tests/test_agent_artifact_bundle.py -q",
+]
+VALIDATION_RESULTS = ["pass", "pass"]
+MCP_CONTEXT_OUTPUT_REF = "artifacts/mcp_context_layer_example.json"
+
+
+def build_agent_artifact_bundle_example() -> dict[str, Any]:
+    return {
+        "artifact_id": ARTIFACT_ID,
+        "bundle": build_agent_artifact_bundle(
+            EXAMPLE_STATE,
+            allow_main=False,
+            validation_commands=VALIDATION_COMMANDS,
+            validation_results=VALIDATION_RESULTS,
+            mcp_context_output_ref=MCP_CONTEXT_OUTPUT_REF,
+        ),
+        "evaluation_mode": "deterministic",
+        "external_apis": "none",
+        "generated_by": "AgentArtifactBundleExampleGenerator",
+        "llm_judges": "none",
+        "schema_version": "agent_artifact_bundle_example.v1",
+        "version": "1.0",
+    }
+
+
+def generate_agent_artifact_bundle_example(output_path: Path = OUTPUT_PATH) -> Path:
+    artifact = build_agent_artifact_bundle_example()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(artifact, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return output_path
+
+
+def main() -> int:
+    output_path = generate_agent_artifact_bundle_example()
+    print(output_path.relative_to(REPO_ROOT).as_posix())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/test_agent_artifact_bundle.py

@@ -1,12 +1,19 @@
 from __future__ import annotations
 
 import json
+from pathlib import Path
 
 import pytest
 
 import scripts.agent_artifact_bundle as agent_artifact_bundle
+from scripts.generate_agent_artifact_bundle_example import (
+    ARTIFACT_ID,
+    generate_agent_artifact_bundle_example,
+)
 from scripts.safe_pr_gate import GateState, evaluate_gate
 
+ARTIFACT_PATH = Path("artifacts/agent_artifact_bundle_example.json")
+
 
 def test_build_agent_artifact_bundle_is_deterministic_and_includes_optional_metadata() -> None:
     state = GateState(
@@ -160,3 +167,44 @@ def test_main_reports_main_branch_as_deterministic_error_json(
         "ok": False,
         "result": "ERROR",
     }
+
+
+def test_agent_artifact_bundle_example_matches_generator_output(tmp_path: Path) -> None:
+    output_path = tmp_path / "agent_artifact_bundle_example.json"
+    generate_agent_artifact_bundle_example(output_path)
+
+    assert output_path.read_text(encoding="utf-8") == ARTIFACT_PATH.read_text(encoding="utf-8")
+
+
+def test_agent_artifact_bundle_example_has_stable_schema_and_content() -> None:
+    artifact = json.loads(ARTIFACT_PATH.read_text(encoding="utf-8"))
+
+    assert set(artifact) == {
+        "artifact_id",
+        "bundle",
+        "evaluation_mode",
+        "external_apis",
+        "generated_by",
+        "llm_judges",
+        "schema_version",
+        "version",
+    }
+    assert artifact["artifact_id"] == ARTIFACT_ID
+    assert artifact["schema_version"] == "agent_artifact_bundle_example.v1"
+    assert artifact["version"] == "1.0"
+    assert artifact["evaluation_mode"] == "deterministic"
+    assert artifact["external_apis"] == "none"
+    assert artifact["llm_judges"] == "none"
+
+    bundle = artifact["bundle"]
+    assert bundle["branch"] == "feat/agent-artifact-bundle-example"
+    assert bundle["ok"] is True
+    assert bundle["result"] == "PASS"
+    assert bundle["changed_files"] == [
+        "artifacts/agent_artifact_bundle_example.json",
+        "scripts/generate_agent_artifact_bundle_example.py",
+        "tests/test_agent_artifact_bundle.py",
+    ]
+    assert bundle["mcp_context_output_ref"] == "artifacts/mcp_context_layer_example.json"
+    assert bundle["safe_pr_gate"]["ok"] is True
+    assert bundle["safe_pr_gate"]["result"] == "PASS"