Close package spec audit gaps across workflow/actionpins/stats and normalize README consistency (#26759)

Author: Copilot

pkg/actionpins/README.md

@@ -37,6 +37,19 @@ Resolution supports two modes:
 | `ResolveActionPin` | `func(actionRepo, version string, ctx *PinContext) (string, error)` | Resolves a pinned reference with optional dynamic SHA lookup and fallback behavior |
 | `GetCachedActionPin` | `func(repo string, ctx *PinContext) string` | Returns a pinned reference preferring cache/dynamic resolution when available |
 
+## Usage Example
+
+```go
+ctx := &actionpins.PinContext{StrictMode: true}
+
+reference, err := actionpins.ResolveActionPin("actions/checkout", "v5", ctx)
+if err != nil {
+	panic(err)
+}
+
+fmt.Println(reference) // actions/checkout@<sha> # v5
+```
+
 ## Dependencies
 
 **Internal**:

pkg/console/README.md

@@ -1,4 +1,4 @@
-# Console Package
+# console Package
 
 The `console` package provides utilities for formatting and rendering terminal output in GitHub Agentic Workflows. It covers message formatting, table and section rendering, interactive prompts, progress bars, spinners, struct rendering, and accessibility support.
 
@@ -783,3 +783,7 @@ if console.IsAccessibleMode() {
     // Use simpler, non-animated output
 }
 ```
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/envutil/README.md

@@ -44,3 +44,7 @@ concurrency := envutil.GetIntFromEnv("GH_AW_MAX_CONCURRENT_DOWNLOADS", 5, 1, 20,
 - Warning messages use `console.FormatWarningMessage` so they render consistently in terminals.
 - All warnings go to `os.Stderr` to avoid polluting structured stdout output.
 - The function only handles integers; floating-point or string env vars should be read directly via `os.Getenv`.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/logger/README.md

@@ -1,4 +1,4 @@
-# Logger Package
+# logger Package
 
 A simple, debug-style logging framework for Go that follows the pattern matching syntax of the [debug npm package](https://www.npmjs.com/package/debug).
 
@@ -212,3 +212,7 @@ slogLogger.Warn("something unusual happened", "count", 42)
 - Colors assigned using FNV-1a hash for consistent namespace-to-color mapping
 - Color palette chosen for readability on both light and dark terminals
 - Uses ANSI 256-color codes for better compatibility
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/repoutil/README.md

@@ -40,3 +40,7 @@ repoutil.SplitRepoSlug("github/gh-aw/x") // error: invalid repo format: github/g
 
 - All debug output uses `logger.New("repoutil:repoutil")` and is only emitted when `DEBUG=repoutil:*`.
 - For paths that include sub-folders (e.g. GitHub Actions `uses:` fields such as `github/codeql-action/upload-sarif`), use `gitutil.ExtractBaseRepo` first to strip the sub-path before calling `SplitRepoSlug`.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/semverutil/README.md

@@ -101,3 +101,7 @@ semverutil.IsCompatible("v6.0.0", "v5")     // false
 - All debug output uses `logger.New("semverutil:semverutil")` and is only emitted when `DEBUG=semverutil:*`.
 - The package intentionally delegates to `golang.org/x/mod/semver` for canonical semver logic rather than implementing its own parsing.
 - `ParseVersion` uses `semver.Canonical` before splitting into components, ensuring correct handling of short forms like `v1` (canonicalized to `v1.0.0`).
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/sliceutil/README.md

@@ -77,3 +77,7 @@ unique := sliceutil.Deduplicate(items)
 - `Any` is implemented via `slices.ContainsFunc` from the standard library.
 - `Deduplicate` uses a `map[T]bool` for O(n) time complexity.
 - None of these functions sort their output; callers that require sorted results should call `slices.Sort` on the returned slice.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/stats/README.md

@@ -30,6 +30,21 @@ The `stats` package provides `StatVar`, a compact accumulator for numeric metric
 | `SampleStdDev` | `func() float64` | Returns sample standard deviation |
 | `Median` | `func() float64` | Returns the exact median (middle value or midpoint of two middle values) |
 
+## Usage Example
+
+```go
+var s stats.StatVar
+
+s.Add(10)
+s.Add(20)
+s.Add(30)
+
+fmt.Println(s.Count())  // 3
+fmt.Println(s.Mean())   // 20
+fmt.Println(s.StdDev()) // 8.164965...
+fmt.Println(s.Median()) // 20
+```
+
 ## Dependencies
 
 **Standard library only**:

pkg/stringutil/README.md

@@ -177,3 +177,7 @@ Returns a human-readable description of the token type (e.g. `"fine-grained pers
 - All debug output uses namespace-prefixed loggers (`stringutil:identifiers`, `stringutil:sanitize`, `stringutil:urls`, `stringutil:pat_validation`) and is only emitted when `DEBUG=stringutil:*`.
 - `SanitizeErrorMessage` is intentionally conservative: it excludes common GitHub Actions keywords to avoid over-redacting legitimate error messages.
 - `StripANSI` handles both CSI sequences (`ESC[`) and other ESC-prefixed sequences to cover the full range of ANSI escape codes found in terminal output.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/styles/README.md

@@ -99,3 +99,7 @@ form := huh.NewForm(...).WithTheme(styles.HuhTheme)
 - The package uses `charm.land/lipgloss/v2` and `charm.land/lipgloss/v2/compat` for adaptive color support.
 - For visual examples and detailed usage guidelines, see `scratchpad/styles-guide.md`.
 - All `*` styles export pre-configured `lipgloss.Style` values (not functions), so they can be used with method chaining: `styles.Error.Copy().Underline(true)`.
+
+---
+
+*This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*