Correct misleading collection-registration guidance in AGENTS.md

[fullsend-ai-retro]

What happened

PR #1779 added AgentReady scaffolding including documentation about the repo's collection mechanism. The fullsend review agent's initial review (run 29461958211) correctly identified that docs/patterns/add-release-policy-rule.md and .claude/rules/policy-rules.md incorrectly described collection registration (they said to edit collection files, when collections are actually declared via collections: in rule file METADATA annotations). The author fixed both files in commit 375f923f. However, AGENTS.md lines 50-52 contain the same misleading guidance: "Each collection imports specific policy packages... When adding a new rule, you must add it to the appropriate collection(s) or it won't be evaluated." This suggests developers should edit collection files, but collection files (e.g., policy/release/collection/minimal/minimal.rego) contain only a package declaration — rules declare their own collection membership via METADATA annotations. CodeRabbit's second-pass review flagged a related issue in AGENTS.md (lines 62-66) but the finding was not addressed before merge on Jul 21.

What could go better

The incomplete fix was merged because: (1) the review agent flagged the collection mechanism error in 2 of 3 affected files but missed the same error in AGENTS.md, despite AGENTS.md being part of the PR diff; (2) the re-review on the final commit (run 29517353505) did not verify that the fix was applied consistently across all files describing the same concept; (3) the human reviewer approved with no comments. Confidence is high that this is a genuine documentation error — verified by examining actual collection files, rule files, and the corrected guidance in the other two files.

Proposed change

Update AGENTS.md lines 50-52 to accurately describe the collection mechanism. Replace the current text with guidance consistent with .claude/rules/policy-rules.md and docs/patterns/add-release-policy-rule.md: clarify that rules declare collection membership via a collections: list in their METADATA custom: annotations (following the pattern in policy/release/attestation_type/attestation_type.rego), and that collection files themselves are minimal package declarations that do not need to be edited when adding new rules.

Validation criteria

AGENTS.md accurately describes the collection mechanism, matching the pattern demonstrated in policy/release/attestation_type/attestation_type.rego (METADATA annotations with collections: key) and consistent with the guidance in .claude/rules/policy-rules.md and docs/patterns/add-release-policy-rule.md. An AI agent or contributor following AGENTS.md should correctly declare collection membership in a new rule file's METADATA rather than attempting to edit collection files.

---

Generated by retro agent from #1779

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 1:51 PM UTC · Completed 1:54 PM UTC
Commit: 87c4a29 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Severity: Medium · Category: Documentation

Problem

The AGENTS.md Architecture section contains misleading guidance about how collections work. It states that collections "import specific policy packages" and that developers must "add [rules] to the appropriate collection(s)", implying that collection files should be edited. In reality:

• Collection files (e.g., policy/release/collection/minimal/minimal.rego) are minimal package declarations — they do not import policy packages.
• Rules declare their own collection membership via a collections: list under custom: in their METADATA 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 before merge.

A secondary instance exists in the "Add a new collection" bullet, which also says "import specific policy packages."

Recommended Fix

1. Architecture section (lines 50-52): Replace with guidance that collection files are minimal package declarations and rules declare membership via collections: in METADATA annotations.
2. "Add a new collection" bullet: Update to describe collection files as minimal package declarations, not files that import policy packages.

Use the corrected text in .claude/rules/policy-rules.md and the reference implementation in policy/release/attestation_type/attestation_type.rego as the source of truth.

Proposed Test

Verify consistency across all three documentation files:
- AGENTS.md Architecture section: should describe collections as minimal
  package declarations; rules declare membership via `collections:` in METADATA
- .claude/rules/policy-rules.md: already correct (reference)
- docs/patterns/add-release-policy-rule.md: already correct (reference)

Grep check: AGENTS.md should NOT contain "imports specific policy packages"
in the collections context. Should contain guidance about METADATA annotations
for collection membership.

---

Labels: This is a documentation fix (documentation label) and is well-scoped enough to be a good first issue. Marking as ready-to-code since it has clear guidance and validation criteria. Size XS since it involves updating a few lines in one file.

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 1:55 PM UTC · Completed 1:59 PM UTC
Commit: 87c4a29 · View workflow run →