What happened
PR #1770 (#1770) introduced the test_attestation package and lib/intoto/trust.rego, creating a dual-path architecture for test result validation. The existing test.rego validates pipeline task results (TEST_OUTPUT from SLSA provenance), while the new test_attestation.rego validates in-toto test-result attestations verified through Sigstore/SLSA provenance chains. The trust verification layer in trust.rego couples lib.intoto, lib.sigstore, lib.tekton, and OCI builtins. The relationship between these packages — and the requirement to keep them at feature parity — is not documented in AGENTS.md.
What could go better
An agent making changes to test.rego rules (e.g., adding a new result type or changing failure semantics) would not know it also needs to update test_attestation.rego for parity, or vice versa. Similarly, an agent modifying the trust verification chain (trust.rego) needs to understand the fail-closed model and its coupling to multiple library packages. Without this context, an agent would likely produce incomplete changes that miss one side of the dual-path architecture, leading to rework. The AGENTS.md 'Common Change Patterns' table currently covers basic patterns (new release rule, new lib function) but does not mention these more complex cross-cutting concerns.
Confidence: Medium-high. This is a structural documentation gap rather than a speculative concern — the dual-path architecture exists and the parity requirement is evident from the EC-1950 ticket reference and the parallel rule structure.
Proposed change
Add entries to the 'Common Change Patterns' table in AGENTS.md and a brief 'Architecture' subsection covering:
-
Dual test validation paths: Add a row to the table: Add/modify test result validation → Update both policy/release/test/ (pipeline task results) AND policy/release/test_attestation/ (in-toto attestations). These packages must maintain feature parity.
-
Trust verification chain: Add a row: Modify attestation trust verification → policy/lib/intoto/trust.rego couples intoto, sigstore, tekton, and OCI builtins. Fail-closed: if any step fails, the statement is excluded (no error emitted). Consumer deny rules surface the absence.
-
Test mock patterns: Add a note under the existing testing guidance: Tests for test_attestation require Sigstore/OCI mock infrastructure (~100 lines per test file). See test_attestation_test.rego and lib/intoto/trust_test.rego for the canonical mock patterns (referrer descriptors, SLSA provenance builders, verify mocks).
This change belongs in the source repo's AGENTS.md since it is repo-specific architectural knowledge.
Validation criteria
- An agent working on a change to
test.rego (e.g., adding a new result status) can discover from AGENTS.md that test_attestation.rego also needs updating.
- An agent modifying trust verification understands the fail-closed model without needing to reverse-engineer it from code comments.
- The next PR that touches either test package or the trust chain shows reduced rework iterations compared to baseline.
Generated by retro agent from #1770
What happened
PR #1770 (#1770) introduced the
test_attestationpackage andlib/intoto/trust.rego, creating a dual-path architecture for test result validation. The existingtest.regovalidates pipeline task results (TEST_OUTPUT from SLSA provenance), while the newtest_attestation.regovalidates in-toto test-result attestations verified through Sigstore/SLSA provenance chains. The trust verification layer intrust.regocoupleslib.intoto,lib.sigstore,lib.tekton, and OCI builtins. The relationship between these packages — and the requirement to keep them at feature parity — is not documented in AGENTS.md.What could go better
An agent making changes to
test.regorules (e.g., adding a new result type or changing failure semantics) would not know it also needs to updatetest_attestation.regofor parity, or vice versa. Similarly, an agent modifying the trust verification chain (trust.rego) needs to understand the fail-closed model and its coupling to multiple library packages. Without this context, an agent would likely produce incomplete changes that miss one side of the dual-path architecture, leading to rework. The AGENTS.md 'Common Change Patterns' table currently covers basic patterns (new release rule, new lib function) but does not mention these more complex cross-cutting concerns.Confidence: Medium-high. This is a structural documentation gap rather than a speculative concern — the dual-path architecture exists and the parity requirement is evident from the EC-1950 ticket reference and the parallel rule structure.
Proposed change
Add entries to the 'Common Change Patterns' table in
AGENTS.mdand a brief 'Architecture' subsection covering:Dual test validation paths: Add a row to the table:
Add/modify test result validation→Update both policy/release/test/ (pipeline task results) AND policy/release/test_attestation/ (in-toto attestations). These packages must maintain feature parity.Trust verification chain: Add a row:
Modify attestation trust verification→policy/lib/intoto/trust.rego couples intoto, sigstore, tekton, and OCI builtins. Fail-closed: if any step fails, the statement is excluded (no error emitted). Consumer deny rules surface the absence.Test mock patterns: Add a note under the existing testing guidance:
Tests for test_attestation require Sigstore/OCI mock infrastructure (~100 lines per test file). See test_attestation_test.rego and lib/intoto/trust_test.rego for the canonical mock patterns (referrer descriptors, SLSA provenance builders, verify mocks).This change belongs in the source repo's AGENTS.md since it is repo-specific architectural knowledge.
Validation criteria
test.rego(e.g., adding a new result status) can discover from AGENTS.md thattest_attestation.regoalso needs updating.Generated by retro agent from #1770