[spec-enforcer] Enforce specifications for actionpins, agentdrain, cli

[github-actions]

Specification Test Enforcement

This PR adds specification-driven tests for the following packages, derived from their README.md specifications.

Package	Tests Added	Tests Passing	Spec Sections Covered
actionpins	2	2	Public API, Types, Thread Safety, Design Decisions
agentdrain	3	3	Public API, Types, Design Notes, Core Components
cli	3	3	Public API, Key Functions, Design Decisions

Test Derivation

All tests are derived from README.md specifications, not from implementation source code. Minimal source reads were limited to exact function signatures and import paths.

New Tests Added

actionpins

• TestSpec_PublicAPI_ResolveActionPin_EmbeddedMatch — validates the "Embedded-only lookup from bundled pin data" path returns a pinned reference containing the correct SHA
• TestSpec_PublicAPI_GetActionPins_SPEC_MISMATCH — documents and validates the spec gap (see Mismatches below)

agentdrain

• TestSpec_PublicAPI_Coordinator_TrainEvent — explicitly validates Coordinator.TrainEvent routes events and returns a MatchResult with correct stage (previously only tested indirectly)
• TestSpec_PublicAPI_Coordinator_LoadDefaultWeights — validates LoadDefaultWeights does not error on a fresh coordinator
• TestSpec_PublicAPI_Miner_ClusterCount_SPEC_MISMATCH — documents the spec gap and validates equivalent behavior via len(Clusters())

cli

• TestSpec_PublicAPI_GetAllCodemods — validates each returned Codemod has non-empty ID, Name, Description, and non-nil Apply
• TestSpec_PublicAPI_ResolveArtifactFilter — validates "all" returns nil (no filter), empty input returns nil, and a named set expands to concrete artifact names
• TestSpec_PublicAPI_GroupRunsByWorkflow — validates flat run slice is correctly grouped by WorkflowName

Spec-Implementation Mismatches

Package	Mismatch
actionpins	GetActionPins() []ActionPin is documented in the README ("Returns all loaded pins") but not implemented. Only GetActionPinsByRepo(repo string) exists.
agentdrain	miner.ClusterCount() is shown in the README usage example but the method does not exist on Miner. Use len(miner.Clusters()) as the equivalent.

Round-Robin State

• Packages processed this run: actionpins, agentdrain, cli
• Next packages in rotation: console, constants, envutil (indices 3–5)
• Total eligible packages: 22 (with README.md)

---

Auto-generated by Package Specification Enforcer workflow — Run §24774139718

Generated by Package Specification Enforcer · ● 461.9K · ◷

• expires on Apr 25, 2026, 10:56 AM UTC