Specification Audit — 2026-04-22 — 3 packages with API drift found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-04-22
Run ID: §24808113790
Total Packages: 22
Packages with Specs: 22
Coverage: 100% ✅

---

Coverage Summary

All 22 packages have README.md specifications with consistent # <name> Package title format and the spec-extractor attribution footer. No missing specifications were found.

---

🚨 API Drift Detected

The following packages have exported symbols in source that are not documented in their README.md.

pkg/actionpins — 1 undocumented function

Symbol	Source	Status
GetContainerPin(image string) (ContainerPin, bool)	actionpins.go:202	❌ Undocumented

The GetContainerPin function retrieves a pinned container image by its original image reference. It is part of the same public API as the documented GetActionPinsByRepo/GetActionPinByRepo but is missing from the ## Public API table.

pkg/parser — 1 undocumented function

Symbol	Source	Status
IsWorkflowSpec(path string) bool	remote_fetch.go:205	❌ Undocumented

IsWorkflowSpec is a public predicate used to distinguish workflow spec files from other files when resolving remote includes. It should be documented alongside the other remote-fetch helpers.

pkg/workflow — Multiple undocumented engine types ⚠️

The workflow README's Engine Architecture section documents CopilotEngine, ClaudeEngine, CodexEngine, and GeminiEngine, but the following additional engines and supporting types exist in source and are completely absent from the spec:

Symbol	Source	Status
CrushEngine struct	crush_engine.go:17	❌ Undocumented (only mentioned in prose)
NewCrushEngine() *CrushEngine	crush_engine.go:21	❌ Undocumented
OpenCodeEngine struct	opencode_engine.go:16	❌ Undocumented
NewOpenCodeEngine() *OpenCodeEngine	opencode_engine.go:20	❌ Undocumented
UniversalLLMConsumerEngine struct	universal_llm_consumer_engine.go:23	❌ Undocumented
UniversalLLMBackend type	universal_llm_consumer_engine.go:16	❌ Undocumented
EngineCatalog struct	engine_definition.go:169	❌ Undocumented
NewEngineCatalog(*EngineRegistry) *EngineCatalog	engine_definition.go:186	❌ Undocumented

EngineCatalog is particularly notable — it has 5 exported methods (Register, Get, IDs, All, Resolve) and represents a complete second-level engine lookup abstraction separate from EngineRegistry, yet is entirely absent from the spec.

---

📊 Quality Scores

View all 22 package quality scores

Package	Completeness	Accuracy	Consistency	Overall
actionpins	85%	95%	95%	⚠️ 88%
agentdrain	95%	95%	95%	✅ 95%
cli	90%	90%	95%	✅ 92%
console	95%	95%	95%	✅ 95%
constants	95%	95%	95%	✅ 95%
envutil	95%	95%	95%	✅ 95%
fileutil	95%	95%	95%	✅ 95%
gitutil	95%	95%	95%	✅ 95%
logger	95%	95%	95%	✅ 95%
parser	85%	95%	95%	⚠️ 90%
repoutil	95%	95%	95%	✅ 95%
semverutil	95%	95%	95%	✅ 95%
sliceutil	95%	95%	95%	✅ 95%
stats	95%	95%	95%	✅ 95%
stringutil	95%	95%	95%	✅ 95%
styles	95%	95%	95%	✅ 95%
testutil	95%	95%	95%	✅ 95%
timeutil	95%	95%	95%	✅ 95%
tty	95%	95%	95%	✅ 95%
types	90%	95%	95%	✅ 93%
typeutil	90%	95%	95%	✅ 93%
workflow	70%	90%	90%	⚠️ 75%

---

Action Items

• Add GetContainerPin to pkg/actionpins/README.md Public API table (use spec-extractor)
• Add IsWorkflowSpec to pkg/parser/README.md public API section (use spec-extractor)
• Add CrushEngine, NewCrushEngine, OpenCodeEngine, NewOpenCodeEngine, UniversalLLMConsumerEngine, UniversalLLMBackend, EngineCatalog, and NewEngineCatalog to pkg/workflow/README.md Engine Architecture section (use spec-extractor)
• When opening a fix PR for this issue, include Closes #<this issue number> (or Fixes/Resolves) in the PR description.

---

📚 Next review scheduled for tomorrow. Close this issue once all items are resolved.

References:

• §24808113790

📚 Specification review by Package Specification Librarian · ● 4.1M · ◷