From 172fe0930591161ff6d4771222773f3d6fc3dfd8 Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Tue, 21 Jul 2026 13:59:09 +0000
Subject: [PATCH] docs(#1784): correct collection-registration guidance in
 AGENTS.md

The Architecture section and "Add a new collection" bullet in AGENTS.md
incorrectly described collections as importing policy packages and
directed developers to edit collection files when adding new rules.
In reality, collection files are minimal package declarations and rules
declare their own collection membership via `collections:` in their
METADATA `custom:` annotations. This was already corrected in
`.claude/rules/policy-rules.md` and `docs/patterns/add-release-policy-rule.md`
during PR #1779 but the same error in AGENTS.md was missed.

Updated both sections to accurately describe the mechanism, consistent
with the other documentation files and the reference implementation in
`policy/release/attestation_type/attestation_type.rego`.

Closes #1784
---
 AGENTS.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 39a2c4081..7b7e17a50 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -47,9 +47,11 @@ Every policy rule requires METADATA annotations. Missing or malformed annotation
 
 ## Architecture (design rationale and non-obvious parts)
 
-**Collections** (`policy/*/collection/`) group related rules. Each collection imports specific policy
-packages. Examples: `minimal` (basic validation), `slsa3` (SLSA Level 3), `redhat` (Red Hat-specific).
-When adding a new rule, you must add it to the appropriate collection(s) or it won't be evaluated.
+**Collections** (`policy/*/collection/`) group related rules. Collection files are minimal package
+declarations (e.g., `package collection.minimal`) — they do not import policy packages. Rules declare
+their own collection membership via a `collections:` list in their METADATA `custom:` annotations
+(see `policy/release/attestation_type/attestation_type.rego` for the pattern). Examples: `minimal`
+(basic validation), `slsa3` (SLSA Level 3), `redhat` (Red Hat-specific).
 
 **SLSA dual-format:** The library in `policy/lib/tekton/` normalizes both SLSA v0.2 and v1.0
 attestation formats. Policies consume the normalized form — don't branch on SLSA version in rules.
@@ -63,7 +65,7 @@ These files have `effective_on` dates — rules with future dates are warnings,
 - **Add a pipeline policy rule:** follow the pattern in `policy/pipeline/required_tasks.rego`
 - **Add a shared library function:** see `policy/lib/tekton/` for reference implementation (must have test coverage)
 - **Fetch and parse an OCI blob:** use `oci.parsed_blob(ref)` from `data.lib.oci`, not `json.unmarshal(ec.oci.blob(ref))` directly. A Regal lint rule (`prefer-parsed-blob`) enforces this
-- **Add a new collection:** follow the pattern in `policy/release/collection/` — import specific policy packages
+- **Add a new collection:** follow the pattern in `policy/release/collection/` — a minimal package declaration (no imports needed)
 
 ## PR Conventions