[spec-librarian] Specification Audit — 2026-07-23 — 9 spec-implementation mismatches found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-07-23
Total Packages: 32
Packages with Specs: 32
Coverage: 100%

---

Coverage Summary

All 32 packages under pkg/ have a README.md specification and a spec_test.go accuracy test. No missing specifications.

---

✅ No Staleness Issues

All specification files share the same filesystem timestamp as their source files (cloned together). The spec_test.go files provide a continuous accuracy regression signal.

---

🚨 Spec–Implementation Mismatches

The following packages have SPEC_MISMATCH annotations in their spec_test.go files, indicating the README diverges from the implementation.

View all 9 mismatches across 6 packages

parser — 1 mismatch

• README shows: result.MarkdownBody in usage example
• Actual field: result.Markdown
• File: pkg/parser/README.md (Usage Examples section)
• Recommendation: Replace result.MarkdownBody with result.Markdown.

cli — 2 mismatches

• IsDockerAvailable README shows: func() bool; Actual: func(context.Context) bool
• IsDockerImageAvailable README shows: func(string) bool; Actual: func(context.Context, string) bool
• File: pkg/cli/README.md (Public API table)
• Recommendation: Add context.Context first parameter to both signatures.

constants — 2 mismatches

• README claims: All semantic types implement String() and IsValid(); Actual: EngineName and FeatureFlag do NOT implement these methods
• README documents: constants.MCPCLIFeatureFlag ("mcp-cli"); Actual: This constant does not exist
• File: pkg/constants/README.md
• Recommendation: (1) Correct the method matrix. (2) Remove MCPCLIFeatureFlag or add it to source.

github — 1 mismatch

• README usage example: Shows specific values for ComputeObjectiveValue/GetObjectiveLabels inconsistent with the built-in mapping
• File: pkg/github/README.md (Usage Examples section)
• Recommendation: Update values to match the actual built-in objective mapping.

stringutil — 1 mismatch

• README states: "lowercases and replaces non-alphanumeric characters with hyphens"
• Actual: Does NOT lowercase; preserves -, _, .; returns sentinel "clone-mode" for empty input (undocumented)
• File: pkg/stringutil/README.md
• Recommendation: Correct the description and document the empty-input sentinel.

workflow — 2 mismatches

• README shows: registry.Get("copilot") returning (engine, bool); Actual API: registry.GetEngine(id) (CodingAgentEngine, error) — no Get method exists
• README documents ActionMode values as sha, tag, local; Actual values: dev, release, script, action; DetectActionMode ignores the version parameter
• File: pkg/workflow/README.md
• Recommendation: (1) Replace registry.Get() with registry.GetEngine(). (2) Update ActionMode values.

---

🔄 Cross-Package Consistency

No import path issues or naming convention violations detected. All specs use canonical github.com/github/gh-aw/pkg/<name> import paths consistently.

---

📊 Quality Scores

Package	Completeness	Accuracy	Consistency	Freshness	Overall	Rating
constants	85%	65%	85%	90%	79%	⚠️ Needs Attention
workflow	85%	60%	85%	90%	79%	⚠️ Needs Attention
cli	90%	70%	85%	90%	83%	✅ Good
github	85%	75%	85%	90%	83%	✅ Good
parser	95%	85%	90%	90%	90%	✅ Good
stringutil	90%	65%	85%	90%	81%	✅ Good
All others (26)	95%+	95%+	90%+	90%+	93%+	✅ Good

---

Action Items

• Fix parser README: replace result.MarkdownBody → result.Markdown in usage example
• Fix cli README: add context.Context parameter to IsDockerAvailable and IsDockerImageAvailable signatures
• Fix constants README: correct String()/IsValid() method matrix; remove or add MCPCLIFeatureFlag
• Fix github README: update ComputeObjectiveValue/GetObjectiveLabels usage example values
• Fix stringutil README: correct behavior description (no lowercasing, preserved separators, document empty-input sentinel)
• Fix workflow README: replace registry.Get() with registry.GetEngine(); update ActionMode values to dev/release/script/action
• When opening a fix PR, include Closes #<this issue number> in the PR description

---

📚 Mismatches discovered via SPEC_MISMATCH annotations in spec_test.go files. Next review scheduled for tomorrow. Close this issue once all items are resolved.

📚 Specification review by Package Specification Librarian · sonnet46 49.1 AIC · ⌖ 7.92 AIC · ⊞ 6.1K · ◷

• expires on Jul 26, 2026, 5:50 AM UTC-08:00