[spec-librarian] Specification Audit — 2026-09-10 — 5 issues found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-09-10
Total Packages: 37
Packages with Specs: 36
Coverage: 97%

---

Coverage Summary

Status	Package	Notes
✅	console, agentdrain, stringutil, linters, intent, typeutil, constants, colorwriter, ctxutil, envutil, fileutil, github, githubapi, gitutil, importinpututil, jsonutil, logger, modelsdev, repoutil, scanfindings, semverutil, stats, syncutil, testutil, timeutil, tty, validationerror	No missing exported-symbol documentation found
⚠️	cli, workflow	Large packages with a handful of undocumented exported symbols
⚠️	actionpins, errorutil, setutil, styles, types	One undocumented exported symbol each (most are false positives from generic-type scanning; two are real gaps)
❌	workflowcontract	No README.md at all — package contains only a test file

---

🚨 Missing Specifications

Package	Source Files	Notes	Priority
workflowcontract	0 non-test .go files (1 test file: daily_performance_summary_workflow_contract_test.go)	Package exists solely to assert stable contract tokens for the daily-performance-summary workflow prompt; no exported API, but a short README explaining the package's purpose would help future maintainers understand why it exists.	Low

Recommendation: Add a minimal pkg/workflowcontract/README.md explaining the package's role as a contract-test guard for workflow prompt stability (no code API to document).

---

⚠️ Incomplete Specifications (Undocumented Exported Symbols)

View incomplete specifications (4 packages with real gaps)

pkg/cli — 12 undocumented exported functions

DecideExperiment, DownloadWorkflowLogsForTargets, GenerateNamedOutputSchema, MarshalOutputSchema, NewEditCommand, NewGradersCommand, NewJSONSchemaCommand, NewModelsCommand, PrepareCompileModelValidation, RunOperationalValueRegrade, RunOperationalValueReport, RunShellcheckOnLockFilesAndResources

Notably NewEditCommand, NewGradersCommand, NewJSONSchemaCommand, and NewModelsCommand are cobra command constructors (pkg/cli/edit_command.go, graders_command.go, json_schema_command.go, models_command.go) that appear to back user-facing gh aw subcommands but aren't listed in the README's command table.

pkg/workflow — 12 undocumented exported functions/types

ComputeGitHubAppManifestPermissions, DisableDefaultActionFailureExpiryMarkersIfUnenforced, GetEngineDefaultDomainSets, GitHubAppManifestPermissionKey, IsGitHubCLIProxyMode, IsValidOperationalValueEvaluatorRunPath, NewPermissionsContentsReadCodeQualityWritePRRead, NormalizeGitHubAppWebhookEvents, ParseExperimentMetricGraderReference, ParseGradersFromFrontmatter, ReplaceSecretsWithShellEnvVars, ResolveOperationalValueEvaluatorPath

pkg/actionpins — 1 undocumented exported function

• ResolveGHESActionPin(repo string) (string, bool) (pkg/actionpins/resolve.go:98) — resolves the GHES-compatible pin for a repo; not present anywhere in the README's function table alongside ResolveActionPin/ResolveLatestActionPin.

pkg/errorutil — 1 undocumented exported function

• IsNotFoundOutput(output string) bool (pkg/errorutil/errors.go:29) — output-string variant of the documented IsNotFoundError(err error) bool; missing from the function table.

Note: pkg/setutil, pkg/styles, and pkg/types matches from the automated scan were verified to be false positives (generic type-parameter tokens like comparable], or a method already documented under a "Method" heading) — no action needed for those three.

Recommendation: Update the cli, workflow, actionpins, and errorutil README tables to include the listed symbols.

---

🔄 Cross-Package Consistency

• Terminology: Checked "stderr vs stdout" and "structured vs formatted output" phrasing across logger and console specs — both consistently document stderr as the destination for human-readable/log output, and console's Format* vs Render* naming distinction is intentional and documented, not conflicting terminology. No terminology conflicts found.
• Import/dependency accuracy: Spot-checked declared dependencies in actionpins, sliceutil, and errorutil READMEs against actual Go imports — all matched with no stale or missing dependency references.
• Staleness: The repository's git history in this execution environment is shallow (single commit), so commit-based staleness dates could not be computed directly; no other staleness signal indicated any package spec is meaningfully behind its source.

---

📊 Quality Scores (packages with notable gaps)

Package	Completeness	Accuracy	Consistency	Freshness	Overall
cli	94%	95%	90%	90%	✅ 93%
workflow	96%	95%	90%	90%	✅ 94%
actionpins	91%	95%	95%	90%	✅ 93%
errorutil	88%	95%	95%	90%	✅ 92%
workflowcontract	0%	n/a	n/a	n/a	❌ 0% (no spec)

---

Action Items

• Add pkg/workflowcontract/README.md describing the package's contract-test-guard purpose
• Document NewEditCommand, NewGradersCommand, NewJSONSchemaCommand, NewModelsCommand and the other 8 undocumented pkg/cli exported functions in pkg/cli/README.md
• Document the 12 undocumented exported symbols in pkg/workflow/README.md
• Add ResolveGHESActionPin to pkg/actionpins/README.md
• Add IsNotFoundOutput to pkg/errorutil/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.

📚 Specification review by Package Specification Librarian · copilot · auto · 174.9 AIC · ⌖ 8.78 AIC · ⊞ 9K · ◷

• expires on Sep 13, 2026, 5:34 AM UTC-08:00