[spec-librarian] Specification Audit — 2026-07-17 — 9 issues found

[github-actions]

📚 Package Specification Audit Report

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

---

Coverage Summary

All 32 packages under pkg/ have a README.md specification. However, 8 packages have source changes that post-date their most recent spec update.

Status	Package	Last Spec Update	Last Source Update	Days Behind
✅	agentdrain	2026-07-11	2026-07-11	0
✅	colorwriter	2026-07-15	2026-07-15	0
✅	console	2026-07-15	2026-07-15	0
✅	envutil	2026-07-08	2026-07-08	0
✅	errorutil	2026-05-31	2026-05-31	0
✅	fileutil	2026-06-14	2026-06-14	0
✅	github	2026-07-10	2026-07-10	0
✅	gitutil	2026-06-27	2026-06-27	0
✅	importinpututil	2026-07-10	2026-07-10	0
✅	intent	2026-07-06	2026-07-06	0
✅	jsonutil	2026-05-23	2026-05-23	0
✅	logger	2026-07-15	2026-07-15	0
✅	repoutil	2026-07-10	2026-07-10	0
✅	setutil	2026-07-06	2026-07-06	0
✅	sliceutil	2026-06-25	2026-06-25	0
✅	stats	2026-07-15	2026-07-15	0
✅	stringutil	2026-07-15	2026-07-15	0
✅	styles	2026-07-15	2026-07-15	0
✅	syncutil	2026-07-10	2026-07-10	0
✅	testutil	2026-07-07	2026-07-07	0
✅	timeutil	2026-06-12	2026-06-12	0
✅	tty	2026-06-25	2026-06-25	0
✅	types	2026-07-11	2026-07-11	0
✅	typeutil	2026-06-25	2026-06-25	0
⚠️	actionpins	2026-07-15	2026-07-17	2
⚠️	cli	2026-07-16	2026-07-17	1
⚠️	constants	2026-07-15	2026-07-16	1
⚠️	linters	2026-07-15	2026-07-17	2
⚠️	modelsdev	2026-07-07	2026-07-15	8
⚠️	parser	2026-07-15	2026-07-17	2
⚠️	semverutil	2026-07-10	2026-07-16	6
⚠️	workflow	2026-07-15	2026-07-17	2

---

⚠️ Stale Specifications

View stale specifications (8 packages)

actionpins — Stale by 2 days

• Spec last updated: 2026-07-15
• Source last updated: 2026-07-17
• Key change: PR fix: SHA-pinned actions lose version comment when SkipHardcodedFallback is set #46122 — fix: SHA-pinned actions lose version comment when SkipHardcodedFallback is set
• Spec gap: PinContext.SkipHardcodedFallback field is present in source but not documented in README.md. The field controls whether version→SHA hardcoded fallback is skipped (relevant for non-github.com GH_HOST configurations).
• Recommendation: Add SkipHardcodedFallback bool to the PinContext fields table in the spec.

cli — Stale by 1 day

• Spec last updated: 2026-07-16
• Source last updated: 2026-07-17
• Key changes: PR Refactor logs download orchestration to reduce pkg/cli largefunc backlog #46125 (refactor logs download orchestration), PR [WIP] Fix failing GitHub Actions job Integration: CLI Add & List Commands #46160 (fix failing integration tests), PR Enhance GitHub host detection for PAT creation and setup commands #46128 (enhance GitHub host detection)
• Recommendation: Re-run spec-extractor for cli to capture refactored log-download helpers and host detection improvements.

constants — Stale by 1 day

• Spec last updated: 2026-07-15
• Source last updated: 2026-07-16
• Key change: PR feat: upgrade GitHub MCP server to v1.6.0, enable fields_param by default #45832 (upgrade GitHub MCP server to v1.6.0, enable fields_param by default); PR feat: default to strict security mode, stop injecting sudo and --enable-host-access #45360 (default to strict security mode, stop injecting sudo and --enable-host-access)
• Recommendation: Re-run spec-extractor to capture any new/changed constants.

linters — Stale by 2 days (with known gap)

• Spec last updated: 2026-07-15
• Source last updated: 2026-07-17
• Key changes: PR fix: sync pkg/linters/doc.go to 51 analyzers and add drift guard test #46138 (sync doc.go to 51 analyzers, drift guard test), PR refactor: consolidate duplicate byte/string AST predicates into linters astutil #46108 (consolidate AST predicates), PR [linter-miner] feat(linters): add mapclearloop linter — replace range-delete loops with clear(m) #46060 (add mapclearloop linter)
• Spec gap: mapclearloop analyzer is present in pkg/linters/mapclearloop/ and in doc.go but is missing from README.md. The README documents 50 of 51 active analyzers.
• Recommendation: Add mapclearloop entry to the linters README. Description: "reports range-over-map loops that delete every entry and can be replaced with clear(m)."

modelsdev — Stale by 8 days

• Spec last updated: 2026-07-07
• Source last updated: 2026-07-15
• Key change: PR Unshadow package logger identifiers to restore rawloginlib detection #45637 (unshadow package logger identifiers to restore rawloginlib detection)
• Recommendation: Re-run spec-extractor to verify logger identifier changes are reflected.

parser — Stale by 2 days

• Spec last updated: 2026-07-15
• Source last updated: 2026-07-17
• Key changes: PR fix: exclude job-output credential env vars from agent sandbox (--exclude-env) #46076 (exclude job-output credential env vars from agent sandbox), PR Run package manifest config bootstrap flow by default in gh aw add #46041 (run config bootstrap by default in gh aw add), PR Require issue-intent metadata for close/assignment tools by default, with per-tool opt-out #46014 (require issue-intent metadata for close/assignment tools)
• Recommendation: Re-run spec-extractor for parser to capture credential env var filtering and bootstrap changes.

semverutil — Stale by 6 days

• Spec last updated: 2026-07-10
• Source last updated: 2026-07-16
• Key change: PR fix add normalization for git describe compiler versions #46030 — fix: add normalization for git describe compiler versions
• Recommendation: Update spec to document the git describe version normalization behavior.

workflow — Stale by 2 days

• Spec last updated: 2026-07-15
• Source last updated: 2026-07-17
• Key changes: PR refactor(threat-detection): extract shared external detector WorkflowData setup into helper #46142 (extract shared external detector WorkflowData setup into helper), PR fix: exclude job-output credential env vars from agent sandbox (--exclude-env) #46076 (exclude job-output credential env vars from agent sandbox), PR [yamllint-fixer] Trim trailing whitespace and cap blank runs in inlined prompt content #46123 (trim trailing whitespace in inlined prompt content), PR [log] Add debug logging to workflow and CLI helpers #46124 (add debug logging to workflow and CLI helpers)
• Recommendation: Re-run spec-extractor; verify the threat-detection refactor in workflow is reflected.

---

🔄 Cross-Package Inconsistencies

View inconsistencies (1 issue)

Analyzer Registry Drift: linters doc.go vs README.md

• pkg/linters/doc.go lists 51 active analyzers (including mapclearloop)
• pkg/linters/README.md documents only 50 analyzers — mapclearloop is absent
• This drift was introduced by PR [linter-miner] feat(linters): add mapclearloop linter — replace range-delete loops with clear(m) #46060 (added mapclearloop) without a corresponding README update; the follow-up PR fix: sync pkg/linters/doc.go to 51 analyzers and add drift guard test #46138 synced doc.go but did not update README.md
• Recommendation: Treat README.md and doc.go as co-maintained registry files; the spec-extractor or drift guard should cover both.

---

📊 Quality Scores

Package	Completeness	Accuracy	Consistency	Freshness	Overall	Rating
actionpins	85%	90%	90%	75%	85%	✅ Good
agentdrain	90%	95%	90%	100%	93%	✅ Good
cli	75%	85%	85%	85%	82%	✅ Good
colorwriter	95%	95%	90%	100%	95%	✅ Good
console	95%	95%	90%	100%	95%	✅ Good
constants	85%	90%	90%	85%	88%	✅ Good
envutil	90%	95%	90%	100%	93%	✅ Good
errorutil	90%	95%	90%	100%	93%	✅ Good
fileutil	90%	95%	90%	100%	93%	✅ Good
github	85%	90%	85%	100%	90%	✅ Good
gitutil	90%	90%	90%	100%	92%	✅ Good
importinpututil	90%	90%	90%	100%	92%	✅ Good
intent	90%	90%	90%	100%	92%	✅ Good
jsonutil	90%	95%	90%	100%	93%	✅ Good
linters	96%	90%	90%	75%	88%	✅ Good (1 missing analyzer)
logger	90%	95%	90%	100%	93%	✅ Good
modelsdev	80%	80%	85%	65%	77%	⚠️ Needs Attention
parser	70%	80%	85%	75%	77%	⚠️ Needs Attention
repoutil	90%	95%	90%	100%	93%	✅ Good
semverutil	85%	85%	90%	70%	82%	✅ Good
setutil	90%	95%	90%	100%	93%	✅ Good
sliceutil	90%	95%	90%	100%	93%	✅ Good
stats	90%	95%	90%	100%	93%	✅ Good
stringutil	90%	95%	90%	100%	93%	✅ Good
styles	90%	95%	90%	100%	93%	✅ Good
syncutil	90%	95%	90%	100%	93%	✅ Good
testutil	90%	95%	90%	100%	93%	✅ Good
timeutil	90%	95%	90%	100%	93%	✅ Good
tty	90%	95%	90%	100%	93%	✅ Good
types	90%	95%	90%	100%	93%	✅ Good
typeutil	90%	95%	90%	100%	93%	✅ Good
workflow	65%	75%	85%	75%	75%	⚠️ Needs Attention

---

Action Items

• Add SkipHardcodedFallback field to pkg/actionpins/README.md PinContext fields table
• Add mapclearloop entry to pkg/linters/README.md (present in source and doc.go but absent from README)
• Re-run spec-extractor for cli, constants, modelsdev, parser, semverutil, workflow to capture recent changes
• Enforce that linter README.md and doc.go are updated together when new analyzers are added (consider adding to the drift guard test)
• 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 · 115.3 AIC · ⌖ 8.22 AIC · ⊞ 6K · ◷

• expires on Jul 20, 2026, 5:54 AM UTC-08:00