From d44a581b1cf089a823f1c1a3a58ef9919daff545 Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Thu, 20 Aug 2026 15:19:19 +0000
Subject: [PATCH] docs(#1820): document test attestation input contract in
 AGENTS.md

Add a subsection to the Architecture section documenting the
Konflux test attestation input contract. Specifically:

- All test-result attestations include predicate.configuration[0].name
  and predicate.timestamp (RFC 3339, nanosecond precision).
- test_attestation.rego relies on these fields for deduplication
  (group by name, keep latest timestamp). Attestations without a
  valid timestamp are excluded by design, not a fail-open path.
- A separate enforcement story provides a safety net if the
  attestation format changes.

This helps review agents calibrate severity: missing-field edge
cases in test_attestation are low-severity theoretical concerns,
not high-severity vulnerabilities.

Closes #1820
---
 AGENTS.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 141d9a922..bd5566d82 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -63,6 +63,18 @@ These files have `effective_on` dates — rules with future dates are warnings,
 architectural constraints that aren't derivable from the code. Check there before reverse-engineering
 a subsystem.
 
+**Test attestation input contract:** Konflux test-result attestations (evaluated by
+`policy/release/test_attestation/test_attestation.rego`) always include
+`predicate.configuration[0].name` (the test name) and `predicate.timestamp` (RFC 3339 with
+nanosecond precision). The `test_attestation` package relies on these fields for deduplication:
+attestations are grouped by name and only the latest timestamp per group is evaluated. Attestations
+without a valid (non-empty string) `timestamp` are excluded from evaluation by design — this is
+intentional deduplication behavior, not a fail-open path. Missing-timestamp or missing-name edge
+cases in this package are low-severity theoretical concerns, not high-severity vulnerabilities,
+because the Konflux attestation producers guarantee these fields. A separate enforcement story
+exists to require certain test attestations, providing a safety net if the attestation format
+changes.
+
 ## Rego Evaluation Model (for AI reviewers)
 
 Rego is a declarative policy language (Datalog-inspired), not imperative code: