📚 Package Specification Audit Report
Date: 2026-07-07
Total Packages: 32
Packages with Specs: 32
Coverage: 100%
Coverage Summary
All 32 packages under pkg/ have a README.md specification. 100% coverage is maintained.
| Status |
Package |
Last Spec Update |
Last Source Update |
Days Behind |
| ❌ |
modelsdev |
2026-07-03 |
2026-07-05 |
2 (API gap) |
| ⚠️ |
console |
2026-07-03 |
2026-07-06 |
3 (deps gap) |
| ⚠️ |
logger |
2026-06-28 |
2026-07-05 |
7 (deps gap) |
| ⚠️ |
syncutil |
2026-05-31 |
2026-06-26 |
26 (minor) |
| ⚠️ |
importinpututil |
2026-06-07 |
2026-07-01 |
24 (minor) |
| ⚠️ |
stringutil |
2026-06-09 |
2026-06-29 |
20 (minor) |
| ⚠️ |
github |
2026-06-12 |
2026-07-01 |
19 (minor) |
| ⚠️ |
envutil |
2026-06-14 |
2026-06-29 |
15 (minor) |
| ⚠️ |
actionpins |
2026-06-26 |
2026-07-07 |
11 (minor) |
| ⚠️ |
repoutil |
2026-06-28 |
2026-07-05 |
7 (minor) |
| ⚠️ |
semverutil |
2026-06-29 |
2026-07-05 |
6 (minor) |
| ✅ |
cli |
2026-07-04 |
2026-07-07 |
3 |
| ✅ |
constants |
2026-07-04 |
2026-07-07 |
3 |
| ✅ |
parser |
2026-07-04 |
2026-07-07 |
3 |
| ✅ |
workflow |
2026-07-04 |
2026-07-07 |
3 |
| ✅ |
linters |
2026-07-05 |
2026-07-07 |
2 |
| ✅ |
styles |
2026-06-30 |
2026-07-02 |
2 |
| ✅ |
colorwriter |
2026-07-05 |
2026-07-05 |
0 |
| ✅ |
intent |
2026-07-06 |
2026-07-06 |
0 |
| ✅ |
setutil |
2026-07-06 |
2026-07-06 |
0 |
| ✅ |
agentdrain |
2026-06-26 |
2026-06-27 |
1 |
| ✅ |
gitutil |
2026-06-27 |
2026-06-27 |
0 |
| ✅ |
errorutil |
2026-05-31 |
2026-05-31 |
0 |
| ✅ |
fileutil |
2026-06-14 |
2026-06-14 |
0 |
| ✅ |
jsonutil |
2026-05-23 |
2026-05-23 |
0 |
| ✅ |
sliceutil |
2026-06-25 |
2026-06-25 |
0 |
| ✅ |
stats |
2026-05-31 |
2026-05-31 |
0 |
| ✅ |
testutil |
2026-06-09 |
2026-06-09 |
0 |
| ✅ |
timeutil |
2026-06-12 |
2026-06-12 |
0 |
| ✅ |
tty |
2026-06-25 |
2026-06-25 |
0 |
| ✅ |
types |
2026-06-25 |
2026-06-25 |
0 |
| ✅ |
typeutil |
2026-06-25 |
2026-06-25 |
0 |
🚨 Missing API Documentation
The following packages have exported symbols that are not documented in their README.md:
pkg/modelsdev — 2 undocumented exported functions
The refactor commit #43340 on 2026-07-04 consolidated model-normalization helpers from pkg/cli into pkg/modelsdev and added two new public functions. The README.md was not updated.
| Function |
Signature |
Status |
NormalizeProvider |
func(provider string) string |
❌ Not in README |
NormalizeComparableModelID |
func(value string) string |
❌ Not in README |
FindPricing |
func(ctx context.Context, provider, model string) (map[string]float64, bool) |
✅ Documented |
Recommendation: Re-run spec-extractor for pkg/modelsdev to add documentation for NormalizeProvider and NormalizeComparableModelID.
⚠️ Stale Specifications
View stale specifications (8 packages with significant staleness)
pkg/syncutil — Stale by 26 days
- Spec last updated: 2026-05-31
- Source last updated: 2026-06-26
- Recent changes: "feat: add XML markers, deduplication, labels, and release links" touched
onceloader.go — API unchanged (OnceLoader[T], Get, Override, Reset methods all still present)
- Assessment: Spec content is accurate; staleness is due to a non-API-breaking change
- Recommendation: Update spec commit date by re-running spec-extractor to reset the staleness clock
pkg/importinpututil — Stale by 24 days
- Spec last updated: 2026-06-07
- Source last updated: 2026-07-01
- Recent changes: "Add debug logging to 5 pkg/ files" (only internal debug logging added, public API unchanged)
- Assessment: Spec content is accurate;
ResolvePathValue and FormatResolvedValue are both documented
- Recommendation: Re-run spec-extractor to refresh the staleness date
pkg/stringutil — Stale by 20 days
- Spec last updated: 2026-06-09
- Source last updated: 2026-06-29
- Recent changes: "fix: apply 13 lint-monster correctness/style findings" and "Cache compiled regexp in
applySanitizePattern" (internal refactor, public API unchanged)
- Assessment: All 25 exported functions and types are documented; spec content is accurate
- Recommendation: Re-run spec-extractor to reset the staleness clock
pkg/github — Stale by 19 days
- Spec last updated: 2026-06-12
- Source last updated: 2026-07-01
- Recent changes: "refactor: extract helpers to bring 3 functions under the 60-line largefunc limit" (internal refactor, all public symbols
ObjectiveMapping, DefaultObjectiveMapping, LoadObjectiveMappingFromConfig etc. are documented)
- Assessment: Spec content is accurate; source changes were internal refactors
- Recommendation: Re-run spec-extractor to reset the staleness clock
pkg/envutil — Stale by 15 days
- Spec last updated: 2026-06-14
- Source last updated: 2026-06-29
- Recent changes: "fix: resolve osgetenvlibrary lint findings in boundary-layer packages" (only lint compliance, single function
GetIntFromEnv documented correctly)
- Assessment: Spec content is accurate
- Recommendation: Re-run spec-extractor to reset the staleness clock
pkg/actionpins — Stale by 11 days
- Spec last updated: 2026-06-26
- Source last updated: 2026-07-07
- Recent changes: Firewall bump
v0.27.26 (no API changes); "Improve actionpins spec coverage" was a spec update but source then changed again due to a dead-code removal pass
- Assessment: All 9 exported functions and 8 types are documented; spec content is accurate
- Recommendation: Re-run spec-extractor to reset the staleness clock
pkg/repoutil — Stale by 7 days
- Spec last updated: 2026-06-28
- Source last updated: 2026-07-05
- Recent changes: "Refactor duplicated update-check state helpers" (internal centralization; both
SplitRepoSlug and NormalizeRepoForAPI are documented)
- Assessment: Spec content is accurate
- Recommendation: Re-run spec-extractor to reset the staleness clock
pkg/logger — Stale by 7 days
- Spec last updated: 2026-06-28
- Source last updated: 2026-07-05
- Recent changes: "refactor: extract pkg/colorwriter" (added
colorwriter as a dependency but the README's ## Dependencies section was not updated — see Cross-Package Inconsistencies)
- Assessment: API symbols are accurate but dependencies section is incomplete
- Recommendation: Update
pkg/logger/README.md to add colorwriter to the dependencies section
🔄 Cross-Package Inconsistencies
View inconsistencies (2 dependency declaration issues)
Missing Dependency: pkg/console — colorwriter and stringutil not listed
The pkg/console package imports both colorwriter and stringutil in its production code (verified in source), but neither appears in the README.md ## Dependencies section.
- Current README deps:
logger, styles, tty, testutil (test-only)
- Actual source imports:
colorwriter, logger, stringutil, styles, tty
- Missing from README:
colorwriter — color-profile-aware writer for output; stringutil — string sanitization and formatting utilities
- Introduced by: PR that extracted
pkg/colorwriter from pkg/console (2026-06-28), which was not fully reflected in the dependencies list
- Recommendation: Add
colorwriter and stringutil to pkg/console/README.md dependencies section
Missing Dependency: pkg/logger — colorwriter not listed
The pkg/logger package imports colorwriter in both colorprofile_writer.go and colorprofile_writer_wasm.go, but colorwriter is absent from the README's ## Dependencies section.
- Current README deps:
timeutil, styles
- Actual source imports:
colorwriter, styles, timeutil
- Missing from README:
colorwriter — color-profile-aware writer for terminal output
- Introduced by: PR
#43459 "refactor: extract pkg/colorwriter to eliminate duplicated colorprofile_writer.go across console and logger"
- Recommendation: Add
colorwriter to pkg/logger/README.md dependencies section
📊 Quality Scores
| Package |
Completeness |
Accuracy |
Consistency |
Freshness |
Overall |
Rating |
modelsdev |
33% |
90% |
85% |
65% |
68% |
⚠️ |
console |
95% |
92% |
78% |
80% |
87% |
✅ |
logger |
95% |
90% |
78% |
80% |
86% |
✅ |
actionpins |
100% |
95% |
90% |
60% |
87% |
✅ |
syncutil |
100% |
98% |
95% |
55% |
87% |
✅ |
stringutil |
100% |
97% |
90% |
60% |
87% |
✅ |
linters |
100% |
95% |
92% |
90% |
94% |
✅ |
workflow |
95% |
90% |
88% |
88% |
91% |
✅ |
parser |
95% |
88% |
90% |
87% |
90% |
✅ |
cli |
95% |
92% |
90% |
88% |
92% |
✅ |
All packages not listed above scored ≥ 88% and are in a healthy state.
Action Items
📚 Next review scheduled for tomorrow. Close this issue once all items are resolved.
📚 Specification review by Package Specification Librarian · 252.9 AIC · ⌖ 6.51 AIC · ⊞ 6K · ◷
📚 Package Specification Audit Report
Date: 2026-07-07
Total Packages: 32
Packages with Specs: 32
Coverage: 100%
Coverage Summary
All 32 packages under
pkg/have aREADME.mdspecification. 100% coverage is maintained.modelsdevconsoleloggersyncutilimportinpututilstringutilgithubenvutilactionpinsrepoutilsemverutilcliconstantsparserworkflowlintersstylescolorwriterintentsetutilagentdraingitutilerrorutilfileutiljsonutilsliceutilstatstestutiltimeutilttytypestypeutil🚨 Missing API Documentation
The following packages have exported symbols that are not documented in their
README.md:pkg/modelsdev— 2 undocumented exported functionsThe refactor commit
#43340on 2026-07-04 consolidated model-normalization helpers frompkg/cliintopkg/modelsdevand added two new public functions. TheREADME.mdwas not updated.NormalizeProviderfunc(provider string) stringNormalizeComparableModelIDfunc(value string) stringFindPricingfunc(ctx context.Context, provider, model string) (map[string]float64, bool)Recommendation: Re-run spec-extractor for
pkg/modelsdevto add documentation forNormalizeProviderandNormalizeComparableModelID.View stale specifications (8 packages with significant staleness)
pkg/syncutil— Stale by 26 daysonceloader.go— API unchanged (OnceLoader[T],Get,Override,Resetmethods all still present)pkg/importinpututil— Stale by 24 daysResolvePathValueandFormatResolvedValueare both documentedpkg/stringutil— Stale by 20 daysapplySanitizePattern" (internal refactor, public API unchanged)pkg/github— Stale by 19 daysObjectiveMapping,DefaultObjectiveMapping,LoadObjectiveMappingFromConfigetc. are documented)pkg/envutil— Stale by 15 daysGetIntFromEnvdocumented correctly)pkg/actionpins— Stale by 11 daysv0.27.26(no API changes); "Improve actionpins spec coverage" was a spec update but source then changed again due to a dead-code removal passpkg/repoutil— Stale by 7 daysSplitRepoSlugandNormalizeRepoForAPIare documented)pkg/logger— Stale by 7 dayscolorwriteras a dependency but the README's## Dependenciessection was not updated — see Cross-Package Inconsistencies)pkg/logger/README.mdto addcolorwriterto the dependencies section🔄 Cross-Package Inconsistencies
View inconsistencies (2 dependency declaration issues)
Missing Dependency:
pkg/console—colorwriterandstringutilnot listedThe
pkg/consolepackage imports bothcolorwriterandstringutilin its production code (verified in source), but neither appears in theREADME.md## Dependenciessection.logger,styles,tty,testutil(test-only)colorwriter,logger,stringutil,styles,ttycolorwriter— color-profile-aware writer for output;stringutil— string sanitization and formatting utilitiespkg/colorwriterfrompkg/console(2026-06-28), which was not fully reflected in the dependencies listcolorwriterandstringutiltopkg/console/README.mddependencies sectionMissing Dependency:
pkg/logger—colorwriternot listedThe
pkg/loggerpackage importscolorwriterin bothcolorprofile_writer.goandcolorprofile_writer_wasm.go, butcolorwriteris absent from the README's## Dependenciessection.timeutil,stylescolorwriter,styles,timeutilcolorwriter— color-profile-aware writer for terminal output#43459"refactor: extract pkg/colorwriter to eliminate duplicated colorprofile_writer.go across console and logger"colorwritertopkg/logger/README.mddependencies section📊 Quality Scores
modelsdevconsoleloggeractionpinssyncutilstringutillintersworkflowparsercliAction Items
pkg/modelsdev/README.mdto documentNormalizeProviderandNormalizeComparableModelID(re-run spec-extractor formodelsdev)pkg/console/README.mddependencies section to addcolorwriterandstringutilpkg/logger/README.mddependencies section to addcolorwritersyncutil,importinpututil,stringutil,github,envutil,actionpins,repoutilCloses #<this issue number>(orFixes/Resolves) in the PR description.