[spec-librarian] Specification Audit — 2026-08-01 — 5 issues found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-08-01
Total Packages: 33
Packages with Specs: 33
Coverage: 100%

---

Coverage Summary

All 33 packages under pkg/ have a README.md. No packages are missing specifications.

Note: staleness-by-date detection could not be performed — this checkout is a shallow clone with a single squashed commit, so per-file git history/dates are not available. This finding uses direct source-vs-README symbol comparison instead.

---

🚨 Missing Specifications

None — all 33 packages have a README.md.

---

⚠️ Incomplete Specifications (undocumented exported symbols)

The following specs are missing references to some exported top-level functions from their package's non-test .go files:

View incomplete specifications (5 packages)

pkg/intent — 1 undocumented function (9/10 documented, 90%)

• Missing: Compile (method (PolicyCompiler) Compile)
• Recommendation: Add Compile to the Public API table in pkg/intent/README.md, describing its role in the PolicyCompiler workflow.

pkg/actionpins — 1 undocumented function (9/10 documented, 90%)

• Missing: ApplyContainerPinMapping
• Recommendation: Document ApplyContainerPinMapping alongside the existing ApplyActionPinMapping-style entries in pkg/actionpins/README.md.

pkg/console — 7 undocumented functions (74/81 documented, 91%)

• Missing: FormatCommandMessageStderr, FormatErrorStderr, FormatProgressMessageStderr, FormatWarningMessageStderr, Init, PrintSectionHeader, View
• Recommendation: Add entries for the *Stderr formatter variants and the Init/PrintSectionHeader/View helpers to the Public API section.

pkg/cli — 10 undocumented functions (212/222 documented, 95%)

• Missing: GetPermission, GetRepo, RoundTrip, RunGrantOnLockFiles, RunGrypeOnLockFiles, RunSyftOnLockFiles, RunYamllintOnFiles, SetPermission, SetRepo, WriteHeader
• Recommendation: Given pkg/cli is the largest package (378 source files), consider a spec-extractor re-run scoped to the security-scanning (Grype/Syft), lint-runner, and HTTP round-tripper helpers, which appear to be newer additions not yet reflected in the README.

pkg/workflow — 41 undocumented functions (529/570 documented, 92%)

• Missing (sample): AddBoolPtr, AddTemplatableBool, AddTemplatableStringSlice, ContainsJobOutputExpr, CopilotRequestsTipNeeded, GetExperimentalFeatureUsage, GetSecretFailureMessage, HasAnyWriteScope, IsIntentionalFailure, NewPermissionsIssuesWrite (and 8 other NewPermissions* constructors), ParseEvalsFromFrontmatter, ParseExperimentMetricEvalReference, SetBatchMode, SetCopilotTipNeeded, SetExperimentalFeatureUsage, WorkflowStateBranchName
• Recommendation: The NewPermissions* family (10 constructors) and the templatable-field builder helpers (Add*) look like a cohesive, recently-added API surface. Recommend a targeted spec-extractor pass over pkg/workflow to add a dedicated "Permissions builders" and "Templatable field helpers" subsection.

---

🔄 Cross-Package Consistency Checks

View consistency checks performed

• Import paths: Verified every github/gh-aw/pkg/<name> reference across all 33 READMEs resolves to an actual package directory under pkg/. No stale or incorrect import paths found.
• Naming conventions: Package names in READMEs match directory names; no naming drift detected.
• Dependency graph: No dependency references in specs were found pointing to non-existent or renamed packages.
• Terminology (stdout/stderr): stdout/stderr terminology usage across pkg/cli, pkg/colorwriter, pkg/console, pkg/envutil, pkg/logger, pkg/testutil, pkg/tty, pkg/workflow, pkg/fileutil specs was reviewed. Usage is contextual (e.g., pkg/console correctly documents *Stderr-suffixed formatter variants that write to stderr while default formatters write to stdout) — no genuine conflicting guidance was found.

No cross-package inconsistencies identified this run.

---

📊 Quality Scores (Completeness dimension, symbol-based)

Package	Documented / Total	Completeness	Overall
intent	9/10	90%	✅ Good
actionpins	9/10	90%	✅ Good
console	74/81	91%	✅ Good
cli	212/222	95%	✅ Good
workflow	529/570	92%	✅ Good
(other 28 packages)	100%	100%	✅ Good

All flagged packages remain in the "Good" band overall (completeness gap is small relative to package size); none are "Needs Attention" or "Critical". This audit is a light touch-up list rather than an urgent quality issue.

---

Action Items

• Add Compile to pkg/intent/README.md
• Add ApplyContainerPinMapping to pkg/actionpins/README.md
• Add the 7 missing *Stderr/Init/PrintSectionHeader/View entries to pkg/console/README.md
• Add the 10 missing lint/security-scan/HTTP helper entries to pkg/cli/README.md
• Add the 41 missing entries (notably NewPermissions* builders and Add* templatable-field helpers) to pkg/workflow/README.md
• 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.

Note: Git history in this checkout was too shallow (1 commit) to compute spec-vs-source staleness by date. If a future run has full history available, re-run staleness detection (Phase 2) properly.

📚 Specification review by Package Specification Librarian · auto · 50 AIC · ⌖ 7.85 AIC · ⊞ 8.6K · ◷

• expires on Aug 4, 2026, 5:47 AM UTC-08:00