From b3a95f8d22d04b8188ead2806017bc2304d46e19 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 17 Jul 2026 13:54:26 +0000
Subject: [PATCH 1/4] Initial plan


From f18d3675feeb5a969b19981d6eebfaca7d9c6039 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 17 Jul 2026 14:00:08 +0000
Subject: [PATCH 2/4] chore: outline plan for spec audit fixes

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/workflows/agentic-auto-upgrade.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/agentic-auto-upgrade.yml b/.github/workflows/agentic-auto-upgrade.yml
index 7035101ee35..e169cea32b6 100644
--- a/.github/workflows/agentic-auto-upgrade.yml
+++ b/.github/workflows/agentic-auto-upgrade.yml
@@ -34,7 +34,7 @@ name: Agentic Auto-Upgrade
 
 on:
   schedule:
-    - cron: "21 3 * * 5"  # Weekly (auto-upgrade)
+    - cron: "11 4 * * 6"  # Weekly (auto-upgrade)
   workflow_dispatch:
 
 permissions:

From f98483ee43ba0be6593b835ec984a36240e6bfee Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 17 Jul 2026 14:23:57 +0000
Subject: [PATCH 3/4] docs: refresh package specs and enforce linters doc sync

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 pkg/actionpins/README.md     | 14 +++++++++++
 pkg/cli/README.md            |  4 ++++
 pkg/constants/README.md      |  4 ++++
 pkg/linters/README.md        |  3 +++
 pkg/linters/doc_sync_test.go | 46 ++++++++++++++++++++++++++++++++++++
 pkg/modelsdev/README.md      |  4 ++++
 pkg/parser/README.md         |  4 ++++
 pkg/semverutil/README.md     |  4 ++++
 pkg/workflow/README.md       |  4 ++++
 9 files changed, 87 insertions(+)

diff --git a/pkg/actionpins/README.md b/pkg/actionpins/README.md
index fe8b4da0d57..7a80137feba 100644
--- a/pkg/actionpins/README.md
+++ b/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 |
diff --git a/pkg/cli/README.md b/pkg/cli/README.md
index 03d70d5b649..2eadaa0d9c1 100644
--- a/pkg/cli/README.md
+++ b/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.*
diff --git a/pkg/constants/README.md b/pkg/constants/README.md
index 0603b27aa89..443460f4349 100644
--- a/pkg/constants/README.md
+++ b/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.*
diff --git a/pkg/linters/README.md b/pkg/linters/README.md
index a72f59894d1..c93d667aecb 100644
--- a/pkg/linters/README.md
+++ b/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
diff --git a/pkg/linters/doc_sync_test.go b/pkg/linters/doc_sync_test.go
index 0b94ee835f8..18d13003338 100644
--- a/pkg/linters/doc_sync_test.go
+++ b/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
+}
diff --git a/pkg/modelsdev/README.md b/pkg/modelsdev/README.md
index 0e2ccbc2f91..a009b647d79 100644
--- a/pkg/modelsdev/README.md
+++ b/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.*
diff --git a/pkg/parser/README.md b/pkg/parser/README.md
index d301ad28db6..a872c1eb015 100644
--- a/pkg/parser/README.md
+++ b/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.*
diff --git a/pkg/semverutil/README.md b/pkg/semverutil/README.md
index 967efc8ba9c..66f035166f8 100644
--- a/pkg/semverutil/README.md
+++ b/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.*
diff --git a/pkg/workflow/README.md b/pkg/workflow/README.md
index cbc99b66f6f..90ccac723f7 100644
--- a/pkg/workflow/README.md
+++ b/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.*

From 5ab25bd0f57732135556350d83c51a509264831c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 17 Jul 2026 14:30:25 +0000
Subject: [PATCH 4/4] chore: revert unrelated auto-upgrade cron change

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/workflows/agentic-auto-upgrade.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/agentic-auto-upgrade.yml b/.github/workflows/agentic-auto-upgrade.yml
index e169cea32b6..7035101ee35 100644
--- a/.github/workflows/agentic-auto-upgrade.yml
+++ b/.github/workflows/agentic-auto-upgrade.yml
@@ -34,7 +34,7 @@ name: Agentic Auto-Upgrade
 
 on:
   schedule:
-    - cron: "11 4 * * 6"  # Weekly (auto-upgrade)
+    - cron: "21 3 * * 5"  # Weekly (auto-upgrade)
   workflow_dispatch:
 
 permissions: