Specification Audit — 2026-04-18 — 1 issue found: API drift in `pkg/constants`

[github-actions]

📚 Package Specification Audit Report

Date: 2026-04-18
Total Packages: 22
Packages with Specs: 22
Coverage: 100% ✅
Workflow Run: §24616267618

---

Coverage Summary

All 22 packages under pkg/ have a README.md specification. 21 of 22 are fully up-to-date. One package has newly added exported symbols not yet reflected in its specification.

---

🔍 API Drift Detected

pkg/constants — 6 undocumented exported symbols

The following constants exist in source but are not documented in pkg/constants/README.md:

View undocumented constants (6 symbols)

New GitHub guard-policy environment variables (engine_constants.go)

These three constants provide fallback environment variable names for the tools.github guard policy fields. They were added when the guard policy feature was introduced but the spec was not updated.

Constant	Value	Description
EnvVarGitHubBlockedUsers	"GH_AW_GITHUB_BLOCKED_USERS"	Fallback env var for tools.github.blocked-users
EnvVarGitHubApprovalLabels	"GH_AW_GITHUB_APPROVAL_LABELS"	Fallback env var for tools.github.approval-labels
EnvVarGitHubTrustedUsers	"GH_AW_GITHUB_TRUSTED_USERS"	Fallback env var for tools.github.trusted-users

New Copilot BYOK constants (engine_constants.go)

Constant	Value	Description
CopilotBYOKDummyAPIKey	"dummy-byok-key-for-offline-mode"	Placeholder API key for BYOK offline mode
CopilotBYOKDefaultModel	"claude-sonnet-4.6"	Explicit fallback model for Copilot BYOK mode

New minimum version constraint (version_constants.go)

Constant	Value	Description
AWFAllowHostPortsMinVersion	"v0.25.24"	Minimum AWF version that supports --allow-host-ports

---

📊 Quality Scores

Package	Completeness	Notes	Overall
actionpins	100%	All public types and functions documented	✅
agentdrain	100%	All public API documented including LoadDefaultWeights	✅
cli	100%	High-level overview format appropriate for large package	✅
console	100%	Comprehensive including WASM-only functions	✅
constants	73%	6 undocumented exported constants (guard policy env vars, BYOK, min version)	⚠️
envutil	100%		✅
fileutil	100%		✅
gitutil	100%		✅
logger	100%	Including SlogHandler adapter	✅
parser	100%	Comprehensive overview for large package	✅
repoutil	100%		✅
semverutil	100%		✅
sliceutil	100%		✅
stats	100%		✅
stringutil	100%	All sub-files covered	✅
styles	100%	All color vars and pre-configured styles	✅
testutil	100%		✅
timeutil	100%		✅
tty	100%		✅
types	100%		✅
typeutil	100%		✅
workflow	100%	Comprehensive overview for large package	✅

---

Action Items

• Update pkg/constants/README.md to document the 3 new GitHub guard-policy env vars (EnvVarGitHubBlockedUsers, EnvVarGitHubApprovalLabels, EnvVarGitHubTrustedUsers) — add to the Model Environment Variables section
• Update pkg/constants/README.md to document CopilotBYOKDummyAPIKey and CopilotBYOKDefaultModel — add a new Copilot BYOK subsection under Engine Constants
• Update pkg/constants/README.md to document AWFAllowHostPortsMinVersion — add to the Minimum Version Constraints section alongside AWFExcludeEnvMinVersion, AWFCliProxyMinVersion

---

📚 Next review scheduled for tomorrow. Close this issue once all items are resolved.

📚 Specification review by Package Specification Librarian · ● 5M · ◷