Specification Audit — 2026-04-20 — 6 issues found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-04-20
Workflow Run: §24695694937
Total Packages: 22
Packages with Specs: 22
Coverage: 100%

All package specifications exist and were last updated on 2026-04-20 (same commit as source). No timestamp-based staleness detected.

---

Coverage Summary

Status	Package	Last Spec Update	Last Source Update
✅	actionpins	2026-04-20	2026-04-20
✅	agentdrain	2026-04-20	2026-04-20
⚠️	cli	2026-04-20	2026-04-20
✅	console	2026-04-20	2026-04-20
✅	constants	2026-04-20	2026-04-20
✅	envutil	2026-04-20	2026-04-20
✅	fileutil	2026-04-20	2026-04-20
✅	gitutil	2026-04-20	2026-04-20
✅	logger	2026-04-20	2026-04-20
✅	parser	2026-04-20	2026-04-20
✅	repoutil	2026-04-20	2026-04-20
✅	semverutil	2026-04-20	2026-04-20
✅	sliceutil	2026-04-20	2026-04-20
✅	stats	2026-04-20	2026-04-20
✅	stringutil	2026-04-20	2026-04-20
✅	styles	2026-04-20	2026-04-20
✅	testutil	2026-04-20	2026-04-20
✅	timeutil	2026-04-20	2026-04-20
✅	tty	2026-04-20	2026-04-20
✅	types	2026-04-20	2026-04-20
✅	typeutil	2026-04-20	2026-04-20
⚠️	workflow	2026-04-20	2026-04-20

---

🔄 Spec–Implementation Mismatches

pkg/workflow/README.md — Phantom Function

The Compiler Options table documents NewCompilerWithVersion(string) but this function does not exist in the source code:

pkg/workflow/README.md:48 | `NewCompilerWithVersion(string)` | Creates a `Compiler` with a specific version |

The actual API uses WithVersion(string) CompilerOption (defined in pkg/workflow/compiler_types.go), which is also missing from the Compiler Options table.

Fix: Replace NewCompilerWithVersion(string) in the table with WithVersion(string).

---

pkg/cli/README.md — Undocumented Commands

The following commands are registered in cmd/gh-aw/main.go but are absent from pkg/cli/README.md:

Command	Defined in main.go	Description
gh aw new	line 108 (newCmd)	Create a new workflow file (supports --force, --interactive, --engine)
gh aw enable	line 193 (enableCmd)	Enable a workflow
gh aw disable	line 212 (disableCmd)	Disable a workflow
gh aw version	line 448 (versionCmd)	Show version information

Fix: Add these four commands to the Command Groups table in pkg/cli/README.md.

---

pkg/cli/README.md — Phantom Command

The Command Groups table documents gh aw deps (line 50) but there is no depsCmd registered in cmd/gh-aw/main.go. The supporting code (pkg/cli/deps_*.go) contains helper types and functions (DependencyReport, CheckOutdatedDependencies, etc.) but no NewDepsCommand() entry point.

Fix: Either remove the gh aw deps row from the Command Groups table, or clarify that deps functions are internal utilities (not a CLI command), or implement and register the missing command.

---

📊 Quality Scores

Package	Completeness	Accuracy	Consistency	Freshness	Overall
All others (20 packages)	~95%	~95%	90%	100%	✅ ~95%
workflow	95%	85%	90%	100%	⚠️ 92%
cli	80%	82%	90%	100%	⚠️ 88%

---

Action Items

• pkg/workflow/README.md: Replace phantom NewCompilerWithVersion(string) with WithVersion(string) CompilerOption in the Compiler Options table
• pkg/cli/README.md: Add gh aw new, gh aw enable, gh aw disable, gh aw version to the Command Groups table
• pkg/cli/README.md: Resolve the gh aw deps discrepancy — either remove the row or implement and register the command
• 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.

References:

• §24695694937

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