[spec-librarian] Specification Audit — 2026-07-09 — 16 issues found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-07-09
Total Packages: 32
Packages with Specs: 32
Coverage: 100%

---

Coverage Summary

All 32 packages under pkg/ have a README.md specification. However, 14 specs are stale (source code changed after the last spec update), and 2 specs have implementation mismatches.

---

⚠️ Stale Specifications

The following specifications have source code that is newer than the last spec update:

View stale specifications (14 packages)

Package	Spec Date	Source Date	Days Behind	Priority
syncutil	2026-05-31	2026-06-26	26	🔴 High
importinpututil	2026-06-07	2026-07-01	24	🔴 High
github	2026-06-12	2026-07-01	19	🔴 High
actionpins	2026-06-26	2026-07-09	13	🟠 Medium
agentdrain	2026-06-26	2026-07-09	13	🟠 Medium
repoutil	2026-06-28	2026-07-05	7	🟡 Low
semverutil	2026-06-29	2026-07-05	6	🟡 Low
cli	2026-07-04	2026-07-09	5	🟡 Low
constants	2026-07-04	2026-07-09	5	🟡 Low
styles	2026-06-30	2026-07-02	2	🟢 Minimal
logger	2026-07-07	2026-07-09	2	🟢 Minimal
parser	2026-07-08	2026-07-09	1	🟢 Minimal
stringutil	2026-07-07	2026-07-08	1	🟢 Minimal
workflow	2026-07-08	2026-07-09	1	🟢 Minimal

Notable changes driving staleness

syncutil (26 days): Added debug logging (syncutilLog) and updated Override/Reset method implementations. Spec predates this refactor.

importinpututil (24 days): Added pkg/logger dependency (Add debug logging to 5 pkg/ files #42640). Spec states no internal dependencies — this is now incorrect.

github (19 days): refactor: extract helpers to bring 3 functions under the 60-line largefunc limit (#42624). Spec may not reflect helper extraction.

actionpins (13 days): Multiple firewall bumps and Improve actionpins spec coverage for fallback, mapping, and context propagation (#43871). Further changes since that spec update.

agentdrain (13 days): pkg/agentdrain: add nil-guard to Analyze and improve anomaly test quality (#44455). Spec predates this nil-guard addition.

cli (5 days): Multiple changes including refactor: split logs_orchestrator.go (#44051), SPDD 2026-07-08: close spec sync gaps (#44358), Align CLI docs (#44312), chore: remove dead functions — 1 function removed (#44330).

constants (5 days): feat: detect OAuth tokens in activation job for COPILOT_GITHUB_TOKEN and GH_AW_GITHUB_TOKEN (#44204), firewall bumps.

workflow (1 day): Add checkout.safe-output-github-app support for safe_outputs checkout auth (#44444) — new checkout auth option not covered in spec. Performance fixes and yamllint fixes.

---

🚨 Spec-Implementation Mismatches

View mismatches (2 critical issues)

1. importinpututil — Incorrect Dependency Claim

• File: pkg/importinpututil/README.md
• Claim: "This package has no external or internal gh-aw dependencies — it uses only the Go standard library."
• Reality: pkg/importinpututil/import_input.go imports github.com/github/gh-aw/pkg/logger (added in commit [log] Add debug logging to 5 pkg/ files #42640)
• Impact: Misleads consumers about the dependency graph
• Recommendation: Update the Dependencies section to list logger as an internal dependency

2. linters — Missing bytescomparestring Subpackage

• File: pkg/linters/README.md
• Missing: The bytescomparestring analyzer subpackage was added in [linter-miner] linter: add bytescomparestring — flag string(a)==string(b) where a,b are []byte ([linter-miner] linter: add bytescomparestring — flag string(a)==string(b) where a,b are []byte #44389) on 2026-07-08 20:19 UTC, after the last spec update (2026-07-08 01:55 UTC)
• Impact: Consumers of the linters package do not know this analyzer exists
• Subpackage path: pkg/linters/bytescomparestring
• Description: Flags string(a)==string(b) where a,b are []byte — should use bytes.Equal(a, b) instead
• Recommendation: Add bytescomparestring to the Overview list and Public API table in the linters README

---

🔄 Cross-Package Consistency

View consistency check results

Dependency Graph Accuracy

Package	README Claim	Actual Import	Status
syncutil	Depends on logger	✅ Yes	OK
importinpututil	No internal deps	❌ Imports logger	MISMATCH
github	Depends on logger	✅ Yes	OK
repoutil	Depends on logger	✅ Yes	OK

Terminology Consistency

• Debug output guidance: All package specs consistently use DEBUG=package:* convention. ✅
• stderr vs stdout: cli spec clearly states diagnostics go to stderr, structured output to stdout. Other packages follow same convention implicitly. ✅
• Spec footer format: All specs use the same *This specification is automatically maintained by the [spec-extractor]... footer. ✅

Naming Conventions

• All exported function/type names follow Go PascalCase. ✅
• All README files use consistent ### header depth. ✅

---

📊 Quality Scores

Package	Completeness	Accuracy	Consistency	Freshness	Overall	Rating
colorwriter	95%	95%	90%	100%	95%	✅
console	95%	95%	90%	100%	95%	✅
envutil	95%	95%	90%	100%	95%	✅
errorutil	95%	95%	90%	100%	95%	✅
fileutil	95%	95%	90%	100%	95%	✅
gitutil	95%	95%	90%	100%	95%	✅
intent	95%	95%	90%	100%	95%	✅
jsonutil	95%	95%	90%	100%	95%	✅
modelsdev	95%	95%	90%	100%	95%	✅
setutil	95%	95%	90%	100%	95%	✅
sliceutil	95%	95%	90%	100%	95%	✅
stats	95%	95%	90%	100%	95%	✅
testutil	95%	95%	90%	100%	95%	✅
timeutil	95%	95%	90%	100%	95%	✅
tty	95%	95%	90%	100%	95%	✅
types	95%	95%	90%	100%	95%	✅
typeutil	95%	95%	90%	100%	95%	✅
linters	90%	80%	90%	70%	⚠️ 83%	⚠️
styles	90%	90%	90%	85%	⚠️ 89%	✅
logger	90%	90%	90%	85%	⚠️ 89%	✅
actionpins	90%	85%	90%	60%	⚠️ 81%	✅
agentdrain	90%	85%	90%	60%	⚠️ 81%	✅
cli	90%	85%	90%	70%	⚠️ 84%	✅
constants	90%	85%	90%	70%	⚠️ 84%	✅
repoutil	95%	95%	90%	70%	⚠️ 88%	✅
semverutil	95%	95%	90%	70%	⚠️ 88%	✅
parser	90%	85%	90%	80%	⚠️ 86%	✅
workflow	90%	85%	90%	80%	⚠️ 86%	✅
github	85%	80%	90%	50%	⚠️ 76%	⚠️
importinpututil	85%	60%	90%	30%	❌ 66%	⚠️
syncutil	90%	80%	90%	30%	❌ 73%	⚠️
stringutil	90%	88%	90%	80%	⚠️ 87%	✅

---

Action Items

• [Critical] Fix importinpututil README: add pkg/logger to the Dependencies section (spec incorrectly claims no internal deps)
• [Critical] Update linters README: add bytescomparestring analyzer to the overview list and subpackage API table
• [High] Re-run spec-extractor for syncutil (26 days stale)
• [High] Re-run spec-extractor for importinpututil (24 days stale — also has mismatch)
• [High] Re-run spec-extractor for github (19 days stale)
• [Medium] Re-run spec-extractor for actionpins and agentdrain (13 days stale)
• [Low] Re-run spec-extractor for repoutil, semverutil, cli, constants (5-7 days stale)
• [Informational] Review workflow spec for new checkout.safe-outputs-github-app auth option (1 day stale)
• 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 · 234.8 AIC · ⌖ 8.97 AIC · ⊞ 6K · ◷

• expires on Jul 12, 2026, 6:20 AM UTC-08:00