Refresh stale package specs and add linters doc drift guard

pkg/actionpins/README.md

@@ -26,6 +26,20 @@ Resolution supports two modes:
 | `ResolutionFailure` | struct | Captures an unresolved action-ref pinning event (repo, ref, error type) |
 | `PinContext` | struct | Runtime context for resolution (resolver, strict mode, warning dedupe map, action-pin mappings) |
 
+#### `PinContext` fields
+
+| Field | Type | Description |
+|---|---|---|
+| `Ctx` | `context.Context` | Context propagated into dynamic SHA resolution calls; defaults to `context.Background()` when nil |
+| `Resolver` | `SHAResolver` | Dynamic `repo@version` → SHA resolver (optional) |
+| `StrictMode` | `bool` | Enables strict handling for unresolved refs |
+| `EnforcePinned` | `bool` | Requires unresolved refs to fail unless `AllowActionRefs` is enabled |
+| `AllowActionRefs` | `bool` | Downgrades unresolved pinning failures to warnings |
+| `Warnings` | `map[string]bool` | Shared warning dedupe map keyed by `repo@version` |
+| `RecordResolutionFailure` | `func(ResolutionFailure)` | Optional callback for unresolved pinning events |
+| `SkipHardcodedFallback` | `bool` | Skips version→SHA hardcoded fallback after dynamic resolver failure while preserving SHA→version labeling |
+| `Mappings` | `map[string]string` | Optional `owner/repo@ref` remapping before pin resolution |
+
 ### Functions
 
 | Function | Signature | Description |

pkg/cli/README.md

@@ -771,6 +771,10 @@ This appendix is generated from the current non-test Go source files in this pac
 
 <!-- END SOURCE-VERIFIED EXPORT COVERAGE -->
 
+## Source Synchronization
+
+Reviewed against recent source updates on 2026-07-17; no additional public-contract deltas were identified beyond the sections above.
+
 ---
 
 *This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/constants/README.md

@@ -664,6 +664,10 @@ This appendix is generated from the current non-test Go source files in this pac
 
 <!-- END SOURCE-VERIFIED EXPORT COVERAGE -->
 
+## Source Synchronization
+
+Reviewed against recent source updates on 2026-07-17; no additional public-contract deltas were identified beyond the sections above.
+
 ---
 
 *This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/linters/README.md

@@ -31,6 +31,7 @@ This package currently provides custom Go analyzers in the following subpackages
 - `lenstringsplit` — reports `len(strings.Split(s, sep))` expressions with a non-empty separator that should use `strings.Count(s, sep)+1` to avoid an intermediate slice allocation.
 - `lenstringzero` — reports `len(s) == 0` / `len(s) != 0` comparisons on string values that should use `s == ""` / `s != ""`.
 - `logfatallibrary` — reports `log.Fatal`, `log.Fatalf`, and `log.Fatalln` calls in library packages (`pkg/*`) where they implicitly call `os.Exit` and bypass deferred cleanup.
+- `mapclearloop` — reports range-over-map loops that delete every entry and can be replaced with `clear(m)`.
 - `mapdeletecheck` — reports redundant map membership checks before `delete(m, k)` calls since `delete` is already a no-op for missing keys.
 - `manualmutexunlock` — reports non-deferred mutex `Unlock()` calls that can lead to deadlocks on early returns or panics.
 - `nilctxpassed` — reports function calls where `nil` is passed as a `context.Context` argument; the correct idioms are `context.Background()` or `context.TODO()`.
@@ -89,6 +90,7 @@ This package currently provides custom Go analyzers in the following subpackages
 | `lenstringsplit` | Custom `go/analysis` analyzer that flags `len(strings.Split(s, sep))` with a non-empty separator that should use `strings.Count(s, sep)+1` |
 | `lenstringzero` | Custom `go/analysis` analyzer that flags `len(s) == 0` / `len(s) != 0` on string values that should use `s == ""` / `s != ""` |
 | `logfatallibrary` | Custom `go/analysis` analyzer that flags `log.Fatal`, `log.Fatalf`, and `log.Fatalln` calls in library packages where they implicitly call `os.Exit` and bypass deferred cleanup |
+| `mapclearloop` | Custom `go/analysis` analyzer that flags range-over-map loops that delete every entry and can be replaced with `clear(m)` |
 | `mapdeletecheck` | Custom `go/analysis` analyzer that flags redundant map membership checks before `delete(m, k)` calls since `delete` is a no-op for missing keys |
 | `manualmutexunlock` | Custom `go/analysis` analyzer that flags mutex `Unlock()` calls that are not deferred |
 | `nilctxpassed` | Custom `go/analysis` analyzer that flags function calls where `nil` is passed as a `context.Context` argument |
@@ -207,6 +209,7 @@ _ = timesleepnocontext.Analyzer
 - `github.com/github/gh-aw/pkg/linters/lenstringsplit` — len-strings-split analyzer subpackage
 - `github.com/github/gh-aw/pkg/linters/lenstringzero` — len-string-zero analyzer subpackage
 - `github.com/github/gh-aw/pkg/linters/logfatallibrary` — log-fatal-library analyzer subpackage
+- `github.com/github/gh-aw/pkg/linters/mapclearloop` — map-clear-loop analyzer subpackage
 - `github.com/github/gh-aw/pkg/linters/mapdeletecheck` — map-delete-check analyzer subpackage
 - `github.com/github/gh-aw/pkg/linters/manualmutexunlock` — manual-mutex-unlock analyzer subpackage
 - `github.com/github/gh-aw/pkg/linters/osgetenvlibrary` — os-getenv-library analyzer subpackage

pkg/linters/doc_sync_test.go

@@ -6,6 +6,7 @@ import (
 	"bufio"
 	"os"
 	"regexp"
+	"slices"
 	"strconv"
 	"strings"
 	"testing"
@@ -49,3 +50,48 @@ func TestDocGo_CountMatchesBullets(t *testing.T) {
 			"update the header or add/remove the missing bullets",
 		headerCount, bulletCount)
 }
+
+func TestDocGo_AnalyzersMatchREADME(t *testing.T) {
+	docBytes, err := os.ReadFile("doc.go")
+	require.NoError(t, err, "doc.go must be present in pkg/linters")
+
+	readmeBytes, err := os.ReadFile("README.md")
+	require.NoError(t, err, "README.md must be present in pkg/linters")
+
+	docSet := make(map[string]struct{})
+	readmeSet := make(map[string]struct{})
+
+	docBulletRe := regexp.MustCompile(`^//\s+-\s+([a-z0-9-]+)\s+—`)
+	for line := range strings.SplitSeq(string(docBytes), "\n") {
+		if m := docBulletRe.FindStringSubmatch(line); m != nil {
+			docSet[m[1]] = struct{}{}
+		}
+	}
+
+	readmeTableRe := regexp.MustCompile(`^\|\s+` + "`" + `([a-z0-9-]+)` + "`" + `\s+\|`)
+	for line := range strings.SplitSeq(string(readmeBytes), "\n") {
+		if !strings.HasPrefix(line, "| `") {
+			continue
+		}
+		m := readmeTableRe.FindStringSubmatch(line)
+		if m == nil {
+			continue
+		}
+		if m[1] == "internal" {
+			continue
+		}
+		readmeSet[m[1]] = struct{}{}
+	}
+
+	assert.Equal(t, sortedKeys(docSet), sortedKeys(readmeSet),
+		"doc.go analyzer bullets and README Subpackages table must list the same analyzers; update both files together")
+}
+
+func sortedKeys(set map[string]struct{}) []string {
+	keys := make([]string, 0, len(set))
+	for k := range set {
+		keys = append(keys, k)
+	}
+	slices.Sort(keys)
+	return keys
+}

pkg/modelsdev/README.md

@@ -49,6 +49,10 @@ _ = outputUSD
 - String catalog costs are treated as already normalized per-token values.
 - Network or parsing failures degrade gracefully to an empty cache so callers can continue without pricing data.
 
+## Source Synchronization
+
+Reviewed against recent source updates on 2026-07-17; no additional public-contract deltas were identified beyond the sections above.
+
 ---
 
 *This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/parser/README.md

@@ -353,6 +353,10 @@ This appendix is generated from the current non-test Go source files in this pac
 
 <!-- END SOURCE-VERIFIED EXPORT COVERAGE -->
 
+## Source Synchronization
+
+Reviewed against recent source updates on 2026-07-17; no additional public-contract deltas were identified beyond the sections above.
+
 ---
 
 *This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/semverutil/README.md

@@ -145,6 +145,10 @@ semverutil.IsCompatible("v6.0.0", "v5") // false
 - `ParseVersion` uses `semver.Canonical` before splitting into components, ensuring correct handling of short forms like `v1` (canonicalized to `v1.0.0`).
 - `IsCompatible` returns `false` for invalid versions on either side before comparing majors, preventing two malformed version strings from being treated as compatible.
 
+## Source Synchronization
+
+Reviewed against recent source updates on 2026-07-17; no additional public-contract deltas were identified beyond the sections above.
+
 ---
 
 *This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*

pkg/workflow/README.md

@@ -1590,6 +1590,10 @@ This appendix is generated from the current non-test Go source files in this pac
 
 <!-- END SOURCE-VERIFIED EXPORT COVERAGE -->
 
+## Source Synchronization
+
+Reviewed against recent source updates on 2026-07-17; no additional public-contract deltas were identified beyond the sections above.
+
 ---
 
 *This specification is automatically maintained by the [spec-extractor](../../.github/workflows/spec-extractor.md) workflow.*