[spec-librarian] Specification Audit — 2026-11-10 — 121 issues found #76522

The inventory includes each directory under pkg/ containing at least one non-_test.go Go source file; testdata fixture directories are excluded. Existing README files in directories without qualifying Go source are not counted as package specs.

The 38 covered directories are actionpins, agentdrain, atif, cli, colorwriter, console, constants, ctxutil, envutil, errorutil, fileutil, github, githubapi, gitutil, importinpututil, intent, jsonutil, linters, logger, modelsdev, parser, repoutil, scanfindings, semverutil, setutil, sliceutil, stats, stringutil, styles, syncutil, testutil, timeutil, tty, types, typeutil, validationerror, workflow, and workqueue (all paths prefixed by pkg/).

Missing specs, grouped exhaustively:

• Higher priority: pkg/workflow/actions (13 non-test Go files), pkg/workflow/actionslanguageservice (10), pkg/workflow/aw (6), pkg/workflow/cachepolicy (1), pkg/workflow/checkoutpolicy (1), pkg/workflow/codemod (4), pkg/workflow/compilerenv (1), pkg/workflow/gradershell (6), pkg/workflow/lint (41), pkg/workflow/shellpattern (1), and pkg/workflow/taint (29).
• Other: pkg/cli/data (1).
• Linter analyzers: all 94 direct children of pkg/linters/ containing non-test Go files lack their own README; pkg/linters/README.md documents the parent, not these child directories.
• Internal linter helpers: pkg/linters/internal/analyzerutil, pkg/linters/internal/analyzerutil/analyzertest, pkg/linters/internal/astutil, pkg/linters/internal/coverage, pkg/linters/internal/filecheck, pkg/linters/internal/nolint, and pkg/linters/internal/resourcetracker.

Recommendation: Apply the spec-extractor to the missing packages, prioritizing the workflow packages; if analyzer-level specs are intentionally unnecessary, explicitly amend the coverage policy rather than silently counting the parent README as a child specification.

The following exported API names are not mentioned in the corresponding README (name-presence check, independently checked against declarations):

• pkg/parser/README.md: ExtractMarkdownMetadataBlocks (pkg/parser/markdown_metadata.go:27), CompileAgentMetadata (:69), and CompileMarkdownMetadata (:88).
• pkg/workflow/README.md: (*Compiler).ParseWorkflowDocument (pkg/workflow/compiler_document.go:12), ParseExperimentMetricOutcomeReference (pkg/workflow/compiler_experiments.go:478), and DefaultModelRoutingBatchNotice (pkg/workflow/model_routing_default.go:267).
• pkg/workqueue/README.md: ObsoleteWorkIDs (pkg/workqueue/deployment.go:149).

Recommendation: Document signatures, semantics, and applicable constraints for these APIs; regenerate the source-verified coverage appendices where appropriate.

pkg/envutil/README.md:115 says all warnings go to stderr, but pkg/envutil/envutil.go:16-21 sends warnings to a supplied logger, and pkg/logger/logger.go:122-125 drops Printf output when that logger is disabled. pkg/logger/README.md:161-163 describes emitted log output, not a guarantee that every warning is emitted. Clarify the disabled-logger case in the envutil spec and decide whether the implementation or the unconditional wording is intended.

This checkout is shallow. For every covered package, the latest visible Git date for both its README and non-test source is 2026-11-09, which is the history boundary and cannot establish the true last change date or days behind. No stale or fresh status is inferred from this apparent zero-day difference. Repeat the date comparison against complete history.

All 38 specifications were scanned for literal exported function names and documented function declarations; this is a lexical screening, not proof of complete symbol, signature, or behavior coverage. The apparent phantom TestMyFunction in pkg/testutil/README.md:33 is an example, not a package API finding. The console and logger specifications agree that diagnostic/log output uses stderr; the envutil exception above is a verified qualification. Dependency and naming screening surfaced comment/example and noncanonical-name candidates, but no verified cross-package import or dependency conflict is asserted. An exhaustive semantic dependency/terminology review remains outstanding.

Quality scores: Not assigned for the 38 specs: weighted accuracy, consistency, and freshness cannot be established reliably from name matching and shallow history. In particular, a name mention is not equivalent to accurate documentation. Reassess completeness and accuracy against all exported symbols, verify cross-package guidance, and use full history before applying the requested 30/30/20/20 scoring and good/needs-attention/critical ratings.