Repository navigation
Description
📚 Package Specification Audit Report
Date: 2026-11-17
Production packages: 155 (under pkg/, excluding testdata)
Packages covered by a spec: 154 (50 own README, 97 analyzers in pkg/linters/README.md, 7 helpers in pkg/linters/internal/README.md)
Coverage: 99% (154/155)
Coverage Summary
| Status | Package | Finding |
|---|---|---|
| ❌ | pkg/lifecycle |
No README.md (package added in #78658) |
pkg/cli |
3 exported types not documented | |
pkg/constants |
1 exported constant not documented | |
| ✅ | All other packages | No findings |
🚨 Missing Specifications
| Package | Source Files | Exported Symbols | Priority |
|---|---|---|---|
pkg/lifecycle |
2 (lifecycle.go 270 lines, rules.go 119 lines) |
14 | Medium |
- Exports: types
Identity,Delivery,Adoption,Survival,Record,Execution,Observation,Rule; funcsDelivered,Observe,Merge,IsHuman,RuleFor; constRuleVersion. - Imported by 7 non-test files in
pkg/cli. No other spec mentions it. - Recommendation: run spec-extractor for
pkg/lifecycleand list it in thepkg/clidependencies.
⚠️ Stale Specifications
None. No spec is more than 30 days behind its source. Largest gap: pkg/typeutil (6 days).
🔄 Cross-Package Inconsistencies
None found. Checks passed:
- Import paths referenced in specs all resolve.
- No broken relative links across 83 links in spec files.
- Dependency claims: 8 flagged, all valid (test-only imports documented as such, external
go-ghpkg/api, and linter internal helpers that are transitive dependencies pergo list -deps). - Terminology: no conflicts. The
logger"formatted output" wording refers toPrintfformat strings, not a competing term.
🔎 Spec-Implementation Mismatches (undocumented exports)
View undocumented exports (4 symbols)
pkg/cli
DeliveredItem(logs_outcomes.go:38)DeliveryData(logs_outcomes.go:44)RetainedAdoptionData(logs_lifecycle_retained.go:21)- Recommendation: add rows to
pkg/cli/README.md.
pkg/constants
OtelMetricsJsonlFilename(job_constants.go:240): filename of the OTLP metrics mirror. The siblingOtelJsonlFilenameis documented; this one is not.- Recommendation: add to
pkg/constants/README.md.
Cleared false positives: Init and View (pkg/console), Write (pkg/workqueue), and AppendLifecycle (pkg/cli) are methods on unexported types.
📊 Quality Scores (heuristic)
Completeness and freshness are measured. Accuracy and consistency score 100% absent a finding.
| Package | Completeness | Accuracy | Consistency | Freshness | Overall |
|---|---|---|---|---|---|
pkg/cli |
99% | 100% | 100% | 100% | ✅ 99% |
pkg/constants |
99% | 100% | 100% | 100% | ✅ 99% |
pkg/lifecycle |
— | — | — | — | ❌ 0% (no spec) |
All other specs: 100% (no findings).
Action Items
- Generate a README.md for
pkg/lifecycle(use spec-extractor) - Document
DeliveredItem,DeliveryData, andRetainedAdoptionDatainpkg/cli/README.md - Document
OtelMetricsJsonlFilenameinpkg/constants/README.md - When opening a fix PR for this issue, include
Closes #<this issue number>(orFixes/Resolves) in the PR description.
Method note: the checkout was shallow, so history was deepened (git fetch --deepen=400) to measure staleness.
📚 Next review scheduled for tomorrow. Close this issue once all items are resolved.
References: §44090691772
📚 Specification review by Package Specification Librarian · copilot · routed: haiku55 xhigh · ~6 AIC · ⌖ ~2 AIC · ⊞ 6.5K · ◷
- expires on Nov 20, 2026, 5:27 AM UTC-08:00
Activity