[spec-librarian] Specification Audit — 2026-06-21 — 4 issues found

[github-actions]

📚 Package Specification Audit Report

Date: 2026-06-21
Total Packages: 30
Packages with Specs: 29
Coverage: 96.7% (29/30)

---

Coverage Summary

Status	Package	Last Spec Update	Last Source Update
❌	intent	—	2026-06-21
✅	actionpins	2026-06-21	2026-06-21
✅	agentdrain	2026-06-21	2026-06-21
⚠️	cli	2026-06-21	2026-06-21
✅	console	2026-06-21	2026-06-21
✅	constants	2026-06-21	2026-06-21
✅	envutil	2026-06-21	2026-06-21
✅	errorutil	2026-06-21	2026-06-21
✅	fileutil	2026-06-21	2026-06-21
✅	github	2026-06-21	2026-06-21
✅	gitutil	2026-06-21	2026-06-21
✅	importinpututil	2026-06-21	2026-06-21
✅	jsonutil	2026-06-21	2026-06-21
✅	linters	2026-06-21	2026-06-21
✅	logger	2026-06-21	2026-06-21
✅	parser	2026-06-21	2026-06-21
✅	repoutil	2026-06-21	2026-06-21
✅	semverutil	2026-06-21	2026-06-21
⚠️	setutil	2026-06-21	2026-06-21
✅	sliceutil	2026-06-21	2026-06-21
✅	stats	2026-06-21	2026-06-21
✅	stringutil	2026-06-21	2026-06-21
✅	styles	2026-06-21	2026-06-21
✅	syncutil	2026-06-21	2026-06-21
✅	testutil	2026-06-21	2026-06-21
✅	timeutil	2026-06-21	2026-06-21
✅	tty	2026-06-21	2026-06-21
✅	types	2026-06-21	2026-06-21
✅	typeutil	2026-06-21	2026-06-21
⚠️	workflow	2026-06-21	2026-06-21

---

🚨 Missing Specifications

The following package has no README.md:

Package	Source Files	Exported Symbols	Priority
intent	1 (resolver.go)	5 types, 10 constants, 2 public methods	High

The intent package is actively imported by pkg/cli (in outcome_eval.go) and provides core intent-attribution types (AttributionStatus, AttributionSource, IntentRecord, RootReference, PullRequestData) plus a Resolver with ResolvePullRequest and ResolveIssue methods.

Recommendation: Run the spec-extractor workflow to generate a README.md for pkg/intent.

---

⚠️ Stale Specifications

No staleness by commit date — all READMEs and source files share the same commit date (2026-06-21). However, spec-implementation gaps were identified in the workflow package (see Cross-Package Inconsistencies below).

---

🔄 Cross-Package Inconsistencies

View inconsistencies (3 issues)

Issue 1: pkg/cli README missing dependencies

pkg/cli/README.md lists 21 internal dependencies in its ## Dependencies section but omits two packages that are imported by non-test production code:

• github.com/github/gh-aw/pkg/intent — imported by pkg/cli/outcome_eval.go for AttributionStatus, Resolver, etc.
• github.com/github/gh-aw/pkg/github — imported by pkg/cli/audit_report.go, outcome_eval.go, outcomes_command.go, and outcomes_history.go

Recommendation: Add both missing entries to the ## Dependencies → Internal list in pkg/cli/README.md.

---

Issue 2: pkg/workflow README missing exported functions

The workflow package has 306 exported functions; the README documents 306 table rows, but a cross-check reveals at least 22 exported functions are not listed, including:

Category	Undocumented Functions
Generator functions	GenerateAntigravityInstallerSteps, GenerateCopilotInstallerSteps, GenerateNodeJsSetupStep, GenerateNpmInstallSteps, GenerateNpmInstallStepsWithScope, GenerateRuntimeSetupSteps, GenerateLockMetadata, GenerateMultiSecretValidationStep, GenerateAutoUpdateWorkflow, GenerateMaintenanceWorkflow, GenerateCentralSlashCommandWorkflow, GenerateHeredocDelimiterFromContent
Permissions helpers	GetAllPermissionScopes, GetAllGitHubAppOnlyScopes, ValidatePermissionScopeNames
Detection / filter helpers	DetectRuntimeRequirements, DetectKnownCredentialLeakingActions, DetectKnownCredentialLeakingActionsFromWorkflowData, FilterLabelCommandEvents, FilterCommentEvents, FilterEnvForSecrets, IsConditionalDetection

Recommendation: Re-run spec-extractor for pkg/workflow to regenerate the README and capture these missing exports.

---

Issue 3: pkg/setutil README missing spec-extractor footer

All 29 package READMEs include the standard attribution footer:

*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

The pkg/setutil/README.md is the only spec that is missing this footer.

Recommendation: Re-run spec-extractor for pkg/setutil to add the standard footer.

---

📊 Quality Scores

Package	Completeness	Accuracy	Consistency	Freshness	Overall
intent	0%	—	—	—	❌ 0%
workflow	70%	90%	90%	100%	⚠️ 84%
cli	90%	80%	90%	100%	⚠️ 88%
setutil	100%	100%	75%	100%	✅ 94%
All other packages (25)	95%+	90%+	95%+	100%	✅ 95%+

Completeness weight 30%, Accuracy 30%, Consistency 20%, Freshness 20%.

---

Action Items

• Generate specification for pkg/intent (run spec-extractor)
• Update pkg/workflow/README.md to document 22+ missing exported functions (run spec-extractor)
• Add pkg/intent and pkg/github to the ## Dependencies section in pkg/cli/README.md
• Add spec-extractor footer to pkg/setutil/README.md (run spec-extractor)
• 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 · 177.1 AIC · ⌖ 10.2 AIC · ⊞ 6.1K · ◷

• expires on Jun 24, 2026, 5:56 AM UTC-08:00

[copilot-swe-agent]

The agent encountered an error and was unable to start working on this issue: Please try again later, or contact support if the problem persists. (Request id: 1280:1C114:D6DB33:31A2627:6A37ED93)