Specification Audit — 2026-04-13 — 20 issues found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-04-13
Total Packages: 20
Packages with Specs: 2 (console, logger)
Coverage: 10%

---

Coverage Summary

Status	Package	Spec	Source Files (non-test)	Exported Symbols
⚠️	console	Exists (incomplete)	25+ newer than README	50+ undocumented
⚠️	logger	Exists (incomplete)	3 newer than README	NewSlogHandler, NewSlogLoggerWithHandler missing
❌	agentdrain	Missing	10	36
❌	cli	Missing	237	2,156
❌	constants	Missing	7	35
❌	envutil	Missing	1	11
❌	fileutil	Missing	2	17
❌	gitutil	Missing	1	12
❌	parser	Missing	40	378
❌	repoutil	Missing	1	8
❌	semverutil	Missing	1	13
❌	sliceutil	Missing	1	14
❌	stringutil	Missing	6	71
❌	styles	Missing	3	12
❌	testutil	Missing	1	8
❌	timeutil	Missing	1	4
❌	tty	Missing	2	4
❌	types	Missing	3	4
❌	typeutil	Missing	1	11
❌	workflow	Missing	322	3,845

---

🚨 Missing Specifications (18 packages)

The following packages have no README.md specification:

Package	Source Files	Exported Symbols	Priority
cli	237	2,156	🔴 Critical
workflow	322	3,845	🔴 Critical
parser	40	378	🔴 Critical
agentdrain	10	36	🟡 Medium
constants	7	35	🟡 Medium
stringutil	6	71	🟡 Medium
styles	3	12	🟢 Low
fileutil	2	17	🟢 Low
tty	2	4	🟢 Low
types	3	4	🟢 Low
envutil	1	11	🟢 Low
gitutil	1	12	🟢 Low
repoutil	1	8	🟢 Low
semverutil	1	13	🟢 Low
sliceutil	1	14	🟢 Low
testutil	1	8	🟢 Low
timeutil	1	4	🟢 Low
typeutil	1	11	🟢 Low

Recommendation: Run the spec-extractor workflow to generate specifications for these packages, prioritizing cli, workflow, and parser.

---

⚠️ Stale / Incomplete Specifications

View stale specification details (2 packages)

console — Significantly Incomplete

• Source files newer than README.md: 25 files
• README coverage: ~15% of exported API — focuses on design philosophy, Spinner, ProgressBar, and RenderStruct, but omits the entire primary API surface

Undocumented exported functions (partial list):

• Formatting: FormatError, FormatSuccessMessage, FormatInfoMessage, FormatWarningMessage, FormatErrorMessage, FormatCommandMessage, FormatProgressMessage, FormatPromptMessage, FormatVerboseMessage, FormatCountMessage, FormatLocationMessage, FormatListItem, FormatSectionHeader, FormatErrorChain, FormatErrorWithSuggestions, FormatBanner, FormatNumber, FormatFileSize
• Rendering: RenderTable, RenderTitleBox, RenderErrorBox, RenderInfoSection, RenderComposedSections, RenderTree
• Interaction: ConfirmAction, ShowInteractiveList, PromptSelect, PromptMultiSelect, PromptInput, PromptSecretInput, PromptInputWithValidation, RunForm
• Terminal: ClearScreen, ClearLine, ShowWelcomeBanner, IsAccessibleMode, LogVerbose, PrintBanner, ToRelativePath
• Layout: LayoutTitleBox, LayoutInfoSection, LayoutEmphasisBox, LayoutJoinVertical
• Types: NewListItem, NewProgressBar, NewIndeterminateProgressBar

Recommendation: Re-run spec-extractor for console to generate a complete API reference section.

---

logger — Missing Slog Integration

• Source files newer than README.md: 3 files
• Missing from README: NewSlogHandler and NewSlogLoggerWithHandler — the slog adapter functions that allow bridging the Logger to Go's standard log/slog package are completely absent from the specification

Undocumented exported symbols:

• NewSlogHandler(logger *Logger) *SlogHandler — creates a slog.Handler backed by this logger
• NewSlogLoggerWithHandler(logger *Logger) *slog.Logger — creates a *slog.Logger using this handler
• SlogHandler type — the exported handler struct

Recommendation: Update logger/README.md to document the slog adapter (or re-run spec-extractor).

---

📊 Quality Scores

Package	Completeness	Accuracy	Consistency	Freshness	Overall
console	15%	85%	80%	40%	❌ 48%
logger	75%	90%	85%	70%	⚠️ 78%
cli	—	—	—	—	❌ (no spec)
workflow	—	—	—	—	❌ (no spec)
parser	—	—	—	—	❌ (no spec)

---

Action Items

• Generate specifications for 18 packages without README.md — use spec-extractor workflow
• Priority: cli, workflow, parser first (largest packages, highest impact)
• Update console/README.md to document the full Format*, Render*, Prompt*, and terminal API surface
• Update logger/README.md to document NewSlogHandler, NewSlogLoggerWithHandler, and SlogHandler type

---

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

References:

• §24372287032

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