Skip to content

[spec-librarian] Specification Audit — 2026-11-17 — 2 issues found #78747

Backlog

Description

@github-actions

📚 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; funcs Delivered, Observe, Merge, IsHuman, RuleFor; const RuleVersion.
  • Imported by 7 non-test files in pkg/cli. No other spec mentions it.
  • Recommendation: run spec-extractor for pkg/lifecycle and list it in the pkg/cli dependencies.

⚠️ 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-gh pkg/api, and linter internal helpers that are transitive dependencies per go list -deps).
  • Terminology: no conflicts. The logger "formatted output" wording refers to Printf format 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 sibling OtelJsonlFilename is 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, and RetainedAdoptionData in pkg/cli/README.md
  • Document OtelMetricsJsonlFilename in pkg/constants/README.md
  • When opening a fix PR for this issue, include Closes #<this issue number> (or Fixes/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

Metadata

Metadata

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions