Repository navigation
Specification Audit — 2026-04-22 — 3 packages with API drift found #27928
Description
📚 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% | |
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% | |
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% |
Action Items
- Add
GetContainerPintopkg/actionpins/README.mdPublic API table (use spec-extractor) - Add
IsWorkflowSpectopkg/parser/README.mdpublic API section (use spec-extractor) - Add
CrushEngine,NewCrushEngine,OpenCodeEngine,NewOpenCodeEngine,UniversalLLMConsumerEngine,UniversalLLMBackend,EngineCatalog, andNewEngineCatalogtopkg/workflow/README.mdEngine Architecture section (use spec-extractor) - When opening a fix PR for this issue, include
Closes #<this issue number>(orFixes/Resolves) in the PR description.
📚 Next review scheduled for tomorrow. Close this issue once all items are resolved.
References:
📚 Specification review by Package Specification Librarian · ● 4.1M · ◷
Activity