[spec-librarian] Specification Audit — 2026-07-26 — 2 critical issues found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-07-26
Total Packages: 33
Packages with Specs: 33
Coverage: 100%

---

Coverage Summary

All 33 packages under pkg/ have a README.md specification. However, 2 packages have critical specification gaps where recently-added exported symbols are not documented.

---

🚨 Critical: Missing Exported Symbols

The following packages have exported symbols that are completely absent from their README specifications:

intent — Policy API undocumented (added 2026-07-26)

pkg/intent/policy.go introduced PolicyCompiler.Compile and 4 associated exported types on 2026-07-26 (#48036), but the README.md was last updated on 2026-07-06 and contains no mention of:

Symbol	Kind	Notes
PolicyCompiler	struct	Compiler that evaluates attribution policies
ExecutionPolicy	struct	Result type of PolicyCompiler.Compile
RepositoryContext	struct	Repository context passed to Compile
PolicyRule	struct	Individual rule in a compiled policy
PolicyCondition	struct	Condition expression within a PolicyRule
PolicyCompiler.Compile	method	Core method — resolves IntentRecord + RepositoryContext → ExecutionPolicy

Recommendation: Re-run spec-extractor for pkg/intent to document the full policy compiler API.

fileutil — Executable helpers undocumented (41 days stale)

pkg/fileutil/executable.go exports ValidateExecutablePath and ResolveExecutablePath, neither of which appears in the README.md. The spec was last updated 2026-06-14; the executable source was last updated 2026-07-25 (#47909, #47546).

Symbol	Signature	Notes
ValidateExecutablePath	func(path string) (string, error)	Validates a path is a regular executable
ResolveExecutablePath	func(name string) (string, error)	Resolves a named executable from PATH

Recommendation: Re-run spec-extractor for pkg/fileutil to add the executable helper functions.

---

⚠️ Stale Specifications (source changed after spec update)

View stale specifications (12 packages)

Note: Several of these are test-only or internal refactor changes that do not affect public API accuracy. They are listed for completeness; the critical ones are intent and fileutil above.

Package	Spec Date	Source Date	Days Behind	Notes
errorutil	2026-05-31	2026-07-18	48	Test improvements only; API unchanged
fileutil	2026-06-14	2026-07-25	41	Missing exported symbols — see Critical section
intent	2026-07-06	2026-07-26	20	Missing exported types/method — see Critical section
setutil	2026-07-06	2026-07-18	12	Dependency metadata update only
stringutil	2026-07-15	2026-07-23	8	Internal helper extraction (isASCIIAlphanumeric); no public API change
actionpins	2026-07-18	2026-07-25	7	Test quality improvements and container substitution (already documented in README)
styles	2026-07-15	2026-07-19	4	Internal largefunc lint fix; no public API change
agentdrain	2026-07-18	2026-07-22	4	Minor test/logging changes
constants	2026-07-23	2026-07-26	3	Likely minor constant additions — verify
console	2026-07-22	2026-07-25	3	Dead function removal + goleak tests; verify no public API removed
gitutil	2026-07-23	2026-07-25	2	Debug logging additions
cli	2026-07-24	2026-07-26	2	Recent changes — verify spec currency
colorwriter	2026-07-18	2026-07-20	2	Palette/NO_COLOR update
parser	2026-07-25	2026-07-26	1	Very recent; verify next audit

---

📊 Quality Scores

Package	Completeness	Accuracy	Consistency	Freshness	Overall	Status
intent	40%	70%	80%	35%	❌ 53%	Critical — policy API missing
fileutil	70%	80%	85%	30%	❌ 62%	Critical — executable helpers absent
errorutil	100%	100%	90%	50%	⚠️ 82%	Spec accurate; test-only drift
actionpins	95%	90%	85%	65%	✅ 84%	Minor test drift
console	90%	85%	90%	70%	✅ 84%	Dead fn removal — verify
stringutil	100%	95%	90%	80%	✅ 92%	Internal refactor only
All others	95%+	90%+	90%+	90%+	✅ 90%+	Healthy

---

Action Items

• [HIGH] Update pkg/intent README to document PolicyCompiler, ExecutionPolicy, RepositoryContext, PolicyRule, PolicyCondition, and PolicyCompiler.Compile (from #48036)
• [HIGH] Update pkg/fileutil README to document ValidateExecutablePath and ResolveExecutablePath from executable.go
• [LOW] Verify pkg/console README is still accurate after dead function removal (#47598, #47339)
• [LOW] Verify pkg/constants README reflects changes from [2026-07-26]
• 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.

📚 Specification review by Package Specification Librarian · sonnet46 · 105.2 AIC · ⌖ 8.04 AIC · ⊞ 6.2K · ◷

• expires on Jul 29, 2026, 5:51 AM UTC-08:00

[github-actions]

This issue was automatically closed because it expired on 2026-07-29T13:51:26.524Z.

Closed by Workflow