[spec-librarian] Specification Audit — 2026-08-04 — 2 issues found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-08-04
Total Packages: 34
Packages with Specs: 33
Coverage: 97%

---

Coverage Summary

Audit covered all 34 packages under pkg/. 33 have a README.md; symbol-level cross-checks (exported func/type vs README mentions) were performed for all small/medium packages (constants, stringutil, setutil, sliceutil, semverutil, syncutil, typeutil, timeutil, jsonutil, errorutil, envutil, fileutil, intent, types, actionpins, colorwriter, styles, tty, testutil, logger, stats, github, githubapi, repoutil, importinpututil, modelsdev, agentdrain, linters). The three largest packages (parser, workflow, cli, console) were spot-checked at a structural level only, since full symbol-by-symbol diffing (500–5,700+ exported funcs each) was out of scope for a single daily run.

Note: this checkout is a shallow git clone (single visible commit), so file-modification-date-based staleness detection (spec vs. source last-changed dates) could not be computed reliably and was skipped this run.

---

🚨 Missing Specifications

Package	Source Files	Priority
ctxutil	1 (ctxutil.go, single helper OrBackground)	Low

Recommendation: pkg/ctxutil is a tiny (22-line) single-function helper package. A short README.md documenting OrBackground(ctx context.Context) context.Context and its nil-fallback convention would bring coverage to 100%, but this is low priority given its size and self-documenting godoc comment.

---

⚠️ Stale / Incomplete Specifications

View incomplete specification (1 package)

pkg/intent — undocumented exported types

• File: pkg/intent/policy.go
• Undocumented types: PolicyRule (lines 74–80), PolicyCondition (lines 82–88)
• Both types are actively used by the documented PolicyCompiler.Rules []PolicyRule field and PolicyRule.When PolicyCondition, but neither appears anywhere in pkg/intent/README.md. The README's public API table documents PolicyCompiler.Compile(...) but omits the two structs that make up a policy rule's shape (ID, Scope, When, Set for PolicyRule; Domain, Priority, Risk, Org for PolicyCondition), which a consumer configuring PolicyCompiler.Rules would need.
• Recommendation: Add a short "Types" section to pkg/intent/README.md documenting PolicyRule and PolicyCondition field-by-field, consistent with how RepositoryContext and ExecutionPolicy are already documented in the same file.

---

🔄 Cross-Package Inconsistencies

None found. Import path (github.com/github/gh-aw/...) usage is consistent across all 33 specs, and stdout/stderr terminology in pkg/logger, pkg/colorwriter, and pkg/tty specs is consistent (all describe "stderr" as the output destination for logs/styled diagnostic writers).

---

📊 Quality Scores (sampled packages)

Package	Completeness	Notes	Overall
intent	90%	Missing PolicyRule/PolicyCondition docs	⚠️ Needs Attention
ctxutil	0% (no spec)	Trivial package, low impact	❌ Missing
stringutil, setutil, sliceutil, semverutil, syncutil, typeutil, timeutil, jsonutil, errorutil, envutil, fileutil, constants, types, actionpins, colorwriter, styles, tty, testutil, logger, stats, github, githubapi, repoutil, importinpututil, modelsdev, agentdrain, linters	100% (all exported symbols found in README)	—	✅ Good

---

Action Items

• Document PolicyRule and PolicyCondition in pkg/intent/README.md
• (Optional, low priority) Add a minimal pkg/ctxutil/README.md for the single OrBackground helper
• 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 · auto · 131.2 AIC · ⌖ 2.53 AIC · ⊞ 8.7K · ◷

• expires on Aug 7, 2026, 5:55 AM UTC-08:00