Refresh package specs for spec-audit mismatches and stale README coverage

pkg/actionpins/README.md

@@ -92,6 +92,8 @@ reference, err := actionpins.ResolveActionPin("actions/checkout", "v4", ctx)
 // reference resolves against acme-corp/checkout@v4 pins
 ```
 
+Because `PinContext.Warnings` is used for one-time mapping diagnostics, callers that provide a non-nil `PinContext` and reuse it across `Mappings`-based `ResolveActionPin` calls SHOULD initialize `Warnings` with a non-nil map for warning deduplication. Passing `nil` as `ctx` is safe: `ResolveActionPin` allocates a fresh context internally.
+
 ### Container Pins
 
 `ContainerPin` provides a pinned image reference for container images:

pkg/agentdrain/README.md

@@ -4,6 +4,8 @@
 
 The `agentdrain` package implements the [Drain](https://jiemingzhu.github.io/pub/pjhe_icws2017.pdf) log template mining algorithm adapted for analyzing structured agent pipeline events. It is used for anomaly detection in agentic workflow runs.
 
+The package also embeds default trained weights under `data/`, so callers can bootstrap a `Coordinator` with pre-trained clusters instead of starting from an empty model.
+
 ## Overview
 
 Drain is an online log parsing algorithm that groups log lines into clusters based on token similarity. Each cluster has a *template* — a tokenized log pattern where variable tokens are replaced with a wildcard (`<*>`). When a new log line arrives, Drain finds the most similar existing cluster or creates a new one.

pkg/cli/README.md

@@ -8,6 +8,8 @@ The `cli` package implements all commands exposed through the `gh aw` CLI extens
 
 The package is intentionally decomposed into many small files grouped by feature domain (e.g., `compile_*.go`, `audit_*.go`, `run_*.go`, `mcp_*.go`). This structure keeps individual files under 300 lines and promotes independent testing of each sub-domain.
 
+Besides Cobra entry points, the package also exposes reusable helpers for workflow resolution, dependency analysis, PR creation, and run auditing so multiple commands can share the same business logic and tests.
+
 All diagnostic output MUST go to `stderr` using `console` formatting helpers. Structured output (JSON, hashes, graphs) goes to `stdout`.
 
 ## Command Groups

pkg/constants/README.md

@@ -544,6 +544,7 @@ dir := constants.GetWorkflowDir() // ".github/workflows"
 - Version constants are intentionally plain string literals (not derived from build tags or embedded files) so that individual upgrades can be made as targeted one-line changes.
 - `GetWorkflowDir()` reads `GH_AW_WORKFLOWS_DIR` from the environment at call time, allowing the directory to be overridden in tests and CI.
 - `AgenticEngines` is deprecated in favour of `workflow.NewEngineCatalog(workflow.NewEngineRegistry()).IDs()` but is kept for backward compatibility.
+- `DefaultGitHubTools` is a deprecated compatibility alias for `DefaultGitHubToolsLocal`; `DefaultGitHubToolsLocal` and `DefaultGitHubToolsRemote` are currently identical and exist as separate names for future divergence.
 
 ---
 

pkg/github/README.md

@@ -112,7 +112,7 @@ fmt.Println(defaults) // ObjectiveMapping{labels: 12, logic: max, priorities: 7}
 
 - All label comparisons are case-insensitive: labels are normalised with `strings.ToLower(strings.TrimSpace(...))` before lookup.
 - The default `MultiLabelLogic` is `"max"`. Callers that do not set this field get max-value semantics automatically.
-- `PriorityLabels` is only consulted when `MultiLabelLogic` is `"first"`; it establishes evaluation precedence among matching labels.
+- `PriorityLabels` is only consulted when `MultiLabelLogic` is `"first"`; the implementation walks the issue's labels in their existing order and returns the value for the first label that also appears in `PriorityLabels`. If no priority entry matches, it falls back to the first matched value collected from `LabelToValue`.
 - Debug output is controlled by the `DEBUG=github:*` environment variable and is only emitted when that variable is set.
 
 ---

pkg/importinpututil/README.md

@@ -86,7 +86,11 @@ if !ok {
 
 ## Dependencies
 
-This package has no external or internal `gh-aw` dependencies — it uses only the Go standard library.
+**Internal**:
+- `github.com/github/gh-aw/pkg/logger` — package-scoped debug logging for path resolution and value formatting
+
+**External**:
+- None beyond the Go standard library (`encoding/json`, `fmt`, `reflect`, `sort`, `strings`).
 
 ## Design Notes
 

pkg/linters/README.md

@@ -7,6 +7,7 @@ The `linters` package namespace contains custom static analysis linters used by
 This package currently provides custom Go analyzers in the following subpackages:
 
 - `appendbytestring` — reports `append(b, []byte(s)...)` calls where `b` is `[]byte` and `s` is a string, which can be simplified to `append(b, s...)`.
+- `bytescomparestring` — reports `string(a) == string(b)` and `string(a) != string(b)` comparisons where `a` and `b` are `[]byte` values; use `bytes.Equal(a, b)` for `==` and `!bytes.Equal(a, b)` for `!=`.
 - `contextcancelnotdeferred` — reports context cancel functions that are called directly instead of deferred.
 - `ctxbackground` — reports `context.Background()` calls inside functions that already receive a `context.Context` parameter.
 - `deferinloop` — reports `defer` statements placed directly inside `for`/`range` loop bodies, which execute when the enclosing function returns rather than each iteration and can cause resource leaks.
@@ -58,6 +59,7 @@ This package currently provides custom Go analyzers in the following subpackages
 | Subpackage | Description |
 |------------|-------------|
 | `appendbytestring` | Custom `go/analysis` analyzer that flags `append(b, []byte(s)...)` calls where `s` is a string that can be simplified to `append(b, s...)` |
+| `bytescomparestring` | Custom `go/analysis` analyzer that flags `string(a) == string(b)` / `!=` comparisons on `[]byte` values; use `bytes.Equal(a, b)` for `==` and `!bytes.Equal(a, b)` for `!=` |
 | `contextcancelnotdeferred` | Custom `go/analysis` analyzer that flags context cancel functions called directly instead of deferred |
 | `ctxbackground` | Custom `go/analysis` analyzer that flags `context.Background()` calls inside functions that already receive a context parameter |
 | `deferinloop` | Custom `go/analysis` analyzer that flags `defer` statements inside `for`/`range` loop bodies that execute when the enclosing function returns rather than each iteration |
@@ -169,6 +171,7 @@ _ = timesleepnocontext.Analyzer
 
 **Internal**:
 - `github.com/github/gh-aw/pkg/linters/appendbytestring` — append-byte-string analyzer subpackage
+- `github.com/github/gh-aw/pkg/linters/bytescomparestring` — bytes-compare-string analyzer subpackage
 - `github.com/github/gh-aw/pkg/linters/contextcancelnotdeferred` — context-cancel-not-deferred analyzer subpackage
 - `github.com/github/gh-aw/pkg/linters/ctxbackground` — context-background analyzer subpackage
 - `github.com/github/gh-aw/pkg/linters/deferinloop` — defer-in-loop analyzer subpackage

pkg/repoutil/README.md

@@ -36,6 +36,7 @@ if err != nil {
 
 - 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`.
+- `NormalizeRepoForAPI` only treats three-segment strings as `HOST/owner/repo`; plain `owner/repo` values are returned unchanged with an empty host.
 
 ---
 

pkg/semverutil/README.md

@@ -143,6 +143,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`).
+- `IsCompatible` returns `false` for invalid versions on either side before comparing majors, preventing two malformed version strings from being treated as compatible.
 
 ---
 

pkg/syncutil/README.md

@@ -54,6 +54,7 @@ func getCurrentRepoSlug() (string, error) {
 
 - The internal mutex ensures that `loader` is invoked at most once, even when multiple goroutines call `Get` concurrently.
 - If `loader` returns an error, the error is cached alongside the zero value of `T`; subsequent calls return the same error without re-invoking `loader`.
+- `Override` marks the loader as complete and caches both the supplied result and the supplied error until `Reset` is called.
 - `Reset` acquires the same mutex, making it safe to call concurrently with `Get`.
 - The zero value of `OnceLoader[T]` is ready to use; no constructor is needed.
 

pkg/workflow/README.md

@@ -112,6 +112,8 @@ The package is intentionally large (~320 source files) because it encodes all Gi
 | `PermissionsConfig` | struct | GitHub Actions permissions (shorthand + detailed fields) |
 | `GitHubActionsPermissionsConfig` | struct | Detailed permissions with all scope fields |
 | `GitHubAppPermissionsConfig` | struct | GitHub App permission scopes |
+| `CheckoutConfig` | struct | Parsed `checkout:` entry controlling repository/ref/path/auth/fetch behavior for generated checkout steps |
+| `CheckoutManager` | struct | Merges and resolves one or more `checkout:` entries into deterministic checkout-step plans |
 | `ObservabilityConfig` | struct | OTLP/observability configuration |
 | `RateLimitConfig` | struct | Rate limit settings |
 | `OTLPConfig` | struct | OpenTelemetry protocol configuration |
@@ -120,6 +122,14 @@ The package is intentionally large (~320 source files) because it encodes all Gi
 | `NetworkPermissions` | struct | Parsed `network:` frontmatter block; controls allowed/blocked domain lists |
 | `EngineNetworkConfig` | struct | Combines `*EngineConfig` and `*NetworkPermissions` for engine helpers that need both |
 
+#### Checkout configuration
+
+The `checkout:` frontmatter key is parsed by `ParseCheckoutConfigs` into one or more `CheckoutConfig` values. Each entry may target the current repository or a cross-repository checkout, and supports authentication via `github-token` or `github-app` (mutually exclusive) plus optional `safe-outputs-github-app`.
+
+- `github-app` changes the authentication used by the generated `actions/checkout` step itself.
+- `safe-outputs-github-app` mints a GitHub App token only for later `safe_outputs` git operations (fetch/push) against the checkout target; it does **not** change activation or agent-job checkout authentication.
+- `CheckoutManager` merges compatible checkout requests, unions sparse-checkout patterns, deduplicates overlapping repo/ref pairs, and tracks whether any checkout requires GitHub App token minting for later safe_outputs operations.
+
 #### Engine Configuration Fields
 
 `EngineConfig` is populated by `ExtractEngineConfig` from the `engine:` frontmatter key. It is stored on `EngineNetworkConfig.Engine` and forwarded to each engine's `GetExecutionSteps` / `GetInstallationSteps` implementations.