chore(EC-1851): trim AGENTS.md and add design docs per agentic SDLC best practices

[joejstuart]

Summary

• Reduces AGENTS.md from 243 to 75 lines following wg-agentic-sdlc repo scaffolding best practices
• Removes content agents discover on their own: cmd/ listing, internal/ package descriptions, rule filtering details that duplicated .cursor/rules/*.mdc
• Keeps only what prevents mistakes: test tags with timeouts, acceptance test flags, CGO/DNS issue, /etc/hosts, macOS Podman setup, debug mode, troubleshooting
• Adds internal/evaluator/DESIGN.md — why two PolicyResolvers, two-pass filtering design, scoring precedence, how to add filters
• Adds internal/validate/vsa/DESIGN.md — VSA purpose, storage backend rationale, DSSE signing decision, expiration model
• Design docs placed alongside code per Tier 2 best practices (not in .cursor/rules/)

Jira: https://redhat.atlassian.net/browse/EC-1851

Test plan

• Verify make ci still passes (no code changes)
• Confirm AGENTS.md is under 150-line target
• Validate DESIGN.md content against current source (no stale references)

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: 5333cbe3-09c5-4323-931b-5be2b8a432e3

📥 Commits

Reviewing files that changed from the base of the PR and between 8aec709 and 6a5102e.

📒 Files selected for processing (3)

• AGENTS.md
• internal/evaluator/DESIGN.md
• internal/validate/vsa/DESIGN.md

---

📝 Walkthrough

Walkthrough

Updated AGENTS.md developer guide with current build/test commands, acceptance-test workflows, macOS Podman setup, Go test timeouts, project conventions, DNS requirements, and troubleshooting. Added two new architecture design documents: one explaining evaluator policy rule filtering, the other describing VSA (Verification Summary Attestation) storage and expiration behavior.

Changes

Documentation Refresh

Layer / File(s)	Summary
AGENTS.md Getting-Started Guide Refresh AGENTS.md	Rewritten to provide updated Conforma CLI onboarding covering build/test/lint commands, acceptance-test workflows with -persist/-restore/@focus flags, macOS Podman machine setup, Go test timeouts and example invocations, key project conventions (multi-module layout, debug mode, commit messages), DNS/CGO requirements and /etc/hosts entries for acceptance tests, design document links, and condensed troubleshooting table for common test failures.
Evaluator Rule-Filtering Architecture Design internal/evaluator/DESIGN.md	New design document explaining the evaluator's policy resolver architecture: dual implementations for pipeline intention filtering (main path) and conftest-compatible mode (ec test), two-stage filtering flow (pre-evaluation package selection and post-evaluation result selection), scoring-based precedence for include/exclude pattern conflicts, and guidance for extending filters via IncludeExcludePolicyResolver.
VSA Verification Summary Attestation Architecture Design internal/validate/vsa/DESIGN.md	New design document describing VSA as a signed attestation (image + policy + timestamp) enabling cached validation, storage backend choices (filesystem for dev/testing, Rekor for transparency), DSSE wrapping and default signature verification, and expiration-driven re-validation requirements against current policy.

🎯 1 (Trivial) | ⏱️ ~5 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: trimming AGENTS.md and adding design documents in alignment with agentic SDLC best practices, which directly matches the changeset content.
Description check	✅ Passed	The description is directly related to the changeset, providing detailed context about the AGENTS.md reduction, content removal rationale, new design documents, and test plan items that correspond to the actual changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
acceptance	55.60% <ø> (ø)
generative	17.82% <ø> (ø)
integration	26.56% <ø> (ø)
unit	69.04% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.