[spec-librarian] Specification Audit — 2026-06-26 — 3 issues found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-06-26
Total Packages: 30
Packages with Specs: 29
Coverage: 96.7% (29/30)

---

Coverage Summary

Status	Package	Last Spec Update	Last Source Update	Notes
✅	agentdrain	2026-06-26	2026-06-26	Current
✅	cli	2026-06-19	2026-06-26	Internal changes only
✅	console	2026-06-26	2026-06-26	Current
✅	constants	2026-06-26	2026-06-26	Current
✅	envutil	2026-06-14	2026-06-14	Current
✅	errorutil	2026-05-31	2026-05-31	Current
✅	fileutil	2026-06-14	2026-06-14	Current
✅	github	2026-06-12	2026-06-14	spec_test.go change only
✅	gitutil	2026-06-14	2026-06-18	spec_test.go change only
✅	importinpututil	2026-06-07	2026-06-18	spec_test.go change only
✅	jsonutil	2026-05-23	2026-05-23	Current
✅	logger	2026-06-14	2026-06-14	Current
✅	parser	2026-06-16	2026-06-26	Internal implementation change only
✅	repoutil	2026-05-09	2026-05-23	spec_test.go change only
✅	semverutil	2026-05-09	2026-05-29	Internal strconv fix only
✅	setutil	2026-06-21	2026-06-26	spec_test.go change only
✅	sliceutil	2026-06-25	2026-06-25	Current
✅	stats	2026-05-31	2026-05-31	Current
✅	stringutil	2026-06-09	2026-06-09	Current
✅	styles	2026-06-23	2026-06-24	Internal Windows/ConPTY fix only
✅	syncutil	2026-05-31	2026-06-26	Spec pre-documents Reset; code matches
✅	testutil	2026-06-09	2026-06-09	Current
✅	timeutil	2026-06-12	2026-06-12	Current
✅	tty	2026-06-25	2026-06-25	Current
✅	types	2026-06-25	2026-06-25	Current
✅	typeutil	2026-06-25	2026-06-25	Current
✅	workflow	2026-06-25	2026-06-26	Internal function only
⚠️	actionpins	2026-06-07	2026-06-26	New exported field missing from spec
⚠️	linters	2026-06-22	2026-06-26	4 new subpackages undocumented
❌	intent	—	2026-06-17	No README.md

---

🚨 Missing Specifications

The following packages have no README.md:

Package	Source Files	Exported Symbols	Priority
intent	1 (resolver.go)	8 (6 types, 2 methods)	Medium

Details: pkg/intent has AttributionStatus, AttributionSource, IntentRecord, RootReference, PullRequestData, Resolver types plus Resolver.ResolvePullRequest and Resolver.ResolveIssue methods. No spec_test.go either.

Recommendation: Run the spec-extractor workflow to generate a specification for pkg/intent.

---

⚠️ Stale Specifications

The following specifications have confirmed API discrepancies (not just internal changes):

View stale specifications (2 packages)

actionpins — New exported field missing from spec

• Spec last updated: 2026-06-07
• Source last updated: 2026-06-26 (commit 27b2f4f2)
• Change: New exported field Mappings map[string]string added to PinContext struct
• Impact: The Mappings field redirects owner/repo@ref action references to replacement references before pin resolution. It is set from aw.json action_pins configuration. Callers using PinContext cannot discover this field from the current README.
• Missing documentation:

  type PinContext struct {
      // ...existing fields...
      // Mappings redirects action repository@version references to replacement
      // repository@version references before pin resolution.
      // Keys and values use the format "owner/repo@ref". Set from aw.json action_pins.
      Mappings map[string]string
  }

• Recommendation: Re-run spec-extractor for pkg/actionpins to add Mappings to the PinContext documentation.

linters — 4 new analyzer subpackages undocumented

• Spec last updated: 2026-06-22

• Source last updated: 2026-06-26

• Missing subpackages (not in README overview, table, dependencies section, or spec_test.go):

  Subpackage	Added	Description
  lenstringsplit	2026-06-24	Flags len(strings.Split(s, sep)) with non-empty sep → use strings.Count(s, sep)+1
  sprintferrorsnew	2026-06-20	Flags errors.New(fmt.Sprintf(...)) → use fmt.Errorf
  sprintferrdot	2026-06-19	Flags redundant .Error() calls in fmt format functions
  stringreplaceminusone	2026-06-24	Flags strings.Replace(..., -1) → use strings.ReplaceAll

• Note: These packages also need to be added to pkg/linters/spec_test.go for spec compliance testing.

• Recommendation: Re-run spec-extractor for pkg/linters to add all four subpackages to the README and spec_test.go.

---

🔄 Cross-Package Inconsistencies

View inconsistencies (1 minor issue)

Terminology: Thread Safety Descriptions

Multiple packages describe thread safety using slightly different phrasing:

• syncutil README: "safe for concurrent use" (consistent with Go standard library phrasing)
• console README: "thread-safe via Bubble Tea's message-passing model"
• gitutil README: "safe for concurrent use"
• actionpins README: "safe for concurrent access"

Recommendation: Standardize on "safe for concurrent use" (Go standard library convention) across all specifications. Low priority.

---

📊 Quality Scores

Package	Completeness	Accuracy	Consistency	Freshness	Overall	Status
actionpins	90%	75%	90%	35%	74%	⚠️
linters	89%	90%	90%	50%	81%	⚠️
intent	0%	0%	0%	0%	0%	❌
all others	95%+	95%+	90%+	80%+	≥90%	✅

Score formula: Completeness (30%) + Accuracy (30%) + Consistency (20%) + Freshness (20%)

• ✅ Good: ≥ 80% — specification is healthy
• ⚠️ Needs Attention: 50–79% — specification has issues
• ❌ Critical: < 50% — specification needs immediate update

---

Action Items

• Generate specification for pkg/intent (missing README.md and spec_test.go) — use spec-extractor
• Update pkg/actionpins spec: add PinContext.Mappings field documentation — use spec-extractor
• Update pkg/linters spec: add lenstringsplit, sprintferrorsnew, sprintferrdot, stringreplaceminusone to README overview, subpackage table, dependencies section, and spec_test.go — use spec-extractor
• (Optional) Standardize thread-safety phrasing to "safe for concurrent use" across all specs
• 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 · 211.9 AIC · ⌖ 8.04 AIC · ⊞ 6.1K · ◷

• expires on Jun 29, 2026, 6:08 AM UTC-08:00

[github-actions]

This issue was automatically closed because it expired on 2026-06-29T14:08:04.331Z.

Closed by Workflow