[sergo] Sergo Report: String Literal Centralization + Interface Pollution - 2026-05-14

[github-actions[bot]]

Executive Summary

Run 9 of the Sergo Go static-analysis agent. Strategy mix: 50% cached (extend Run 8's magic-literal-duplication scan from numeric/octal literals to string literals) + 50% new (interface-pollution audit using Serena LSP find_referencing_symbols to count interface implementers/users). Both halves converged on the same theme — DRY violations and shape duplication that the compiler can't catch.

Two strong findings drove issue creation:

1. GetWorkflowDir() doc/code contract drift + 27 literal-bypass sites — the README documents an env-var override the implementation never reads, and 27 production sites hardcode the literal so the helper is bypassed anyway.
2. SHAResolver / ActionSHAResolver interface duplication — identical single-method interfaces in two packages, satisfied by the same single concrete type, used inconsistently across 17+ sites.

Serena LSP fully operational. No tool changes (23 tools stable since Run 4). find_referencing_symbols performed well on focused single-symbol queries (~2.3 s round-trip).

Tools Snapshot

• Total tools: 23 (stable since Run 4)
• New tools: None
• Removed tools: None
• Modified tools: None
• Tools used today: activate_project, find_referencing_symbols (LSP audit of two interface symbols)

Strategy Selection

Cached Reuse Component (50%) — String literal duplication

• Adapted from: Run 8 (magic-literal-duplication, score 8/10) which surfaced file-mode octals → FilePermSensitive/Public/DirPermSensitive/Public constants (now present in pkg/constants/constants.go:73-91 — confirming Run 8 issue #aw_sg8a1 drove that work).
• Modification: Pivot from numeric literals to string literals — specifically path/URL-shaped strings that have a canonical home.
• Targets: .github/workflows literal, GH_AW_* env-var literals, .lock.yml extension literal.

New Exploration Component (50%) — Interface pollution audit

• Approach: Enumerate all top-level type X interface { ... } decls in non-test pkg/ (21 found). For each, use Serena find_referencing_symbols to count usage and locate implementers.
• Hypothesis: Find at least one interface with ≤1 implementer (the classic Go anti-pattern), or two interfaces with identical signatures.

Combined Rationale

Both halves attack "declared-twice, used-once" — string literals on the data side, interface types on the abstraction side. Constants/helpers and interfaces both come in two failure modes: under-adopted (helper exists, callers bypass it) and over-declared (two parallel forms compete). Run 9 found exactly one of each.

Codebase Context

• Production Go files (non-test): 796
• Top-level interfaces in pkg/ non-test: 21
• Focus packages: pkg/constants, pkg/cli, pkg/workflow, pkg/actionpins, pkg/parser

Findings Summary

Severity	Count
High	1
Medium	2
Low	2

Detailed Findings

High — GetWorkflowDir() doc/code contract drift + 27 literal-bypass sites

• pkg/constants/constants.go:334-336 — GetWorkflowDir() returns filepath.Join(".github", "workflows") with no env-var read.
• pkg/constants/README.md:349, 488 — both claim GH_AW_WORKFLOWS_DIR is read at call time.
• 27 prod sites grep-hit on ".github/workflows" literal (21 files): pkg/cli/workflows.go:36-38 (local shim duplicates the literal), pkg/cli/enable.go:280, pkg/cli/run_workflow_execution.go:203, pkg/cli/compile_watch.go:32, pkg/cli/add_command.go:331, pkg/cli/resolver.go:23, pkg/cli/compile_orchestrator.go:53, pkg/cli/lint_command.go:77, pkg/cli/remove_command.go:215, 331, 360, pkg/cli/fix_command.go:118, pkg/cli/mcp_list.go:24, pkg/cli/list_workflows_command.go:74, pkg/cli/upgrade_command.go:275, pkg/cli/mcp_safe_update_cache.go:21, pkg/cli/logs_utils.go:33, pkg/cli/update_container_pins.go:171, pkg/cli/compile_validation.go:186, pkg/cli/trial_helpers.go:69, pkg/parser/import_bfs.go:402, pkg/parser/import_remote.go:61, etc.
• Only 13 prod sites call constants.GetWorkflowDir().
• Recommendation: Add os.Getenv("GH_AW_WORKFLOWS_DIR") read in helper; sweep literals to call site. → Issue #aw_sg9a1.

Medium — SHAResolver / ActionSHAResolver interface duplication

Two packages declare structurally identical single-method interfaces:

• pkg/actionpins/actionpins.go:59-61 → SHAResolver
• pkg/workflow/action_resolver.go:16-18 → ActionSHAResolver

Via Serena find_referencing_symbols:

• actionpins.SHAResolver: 1 use (consumer field PinContext.Resolver at pkg/actionpins/actionpins.go:88).
• workflow.ActionSHAResolver: 15+ uses in pkg/cli/copilot_setup.go, pkg/workflow/action_pins.go, pkg/workflow/action_reference.go, pkg/workflow/maintenance_workflow.go, pkg/workflow/maintenance_workflow_yaml.go, pkg/workflow/side_repo_maintenance.go.

Single production implementer: *workflow.ActionResolver (which structurally satisfies both). The duplicate exists only by historical accident; pkg/workflow already imports pkg/actionpins.

• Recommendation: Delete workflow.ActionSHAResolver, switch ~17 call sites to actionpins.SHAResolver. → Issue #aw_sg9a2.

Medium — ValidatableTool interface with single implementer

• pkg/workflow/permissions_toolset_data.go:73-78 defines ValidatableTool (2-method interface).
• Only impl: *GitHubToolConfig (same file, line 81+).
• Consumed by exactly one function: ValidatePermissions (in same package).
• Classic interface pollution: producer-side interface with N=1 implementer used by 1 function. Defensible because the abstraction makes the validation function testable, but worth flagging.
• Not filed — single-implementer interfaces sometimes pay off later; lower priority than the duplication issues above.

Low — ".lock.yml" string literal in 21 production files (41 occurrences)

No central helper exists. Most call sites concatenate workflow basename + literal. Candidate for a constants.LockFileExtension or constants.LockFileName(workflowID) helper, but the literal is shorter than the constant reference would be (".lock.yml" vs constants.LockFileExtension), so net DX is unclear. Note for future runs.

Low — GH_AW_* env-var literals (216 occurrences in 42 files) partial adoption of constants.EnvVar* names

pkg/constants/engine_constants.go already defines EnvVarPrompt, EnvVarMCPConfig, EnvVarSafeOutputs, EnvVarMaxTurns, EnvVarStartupTimeout, EnvVarToolTimeout, EnvVarGitHubToken, etc. (lines 196-320). Significant coverage but inconsistent uptake — many pkg/workflow/*_engine.go files still inline the literal. Pattern is bigger than one issue, and many literals are actually appearing in YAML template generation (not Go code) where the constant won't help. Deferred.

Improvement Tasks Generated

Task 1: Fix GetWorkflowDir() env-var contract + sweep 27 literal sites

• Severity: High
• Issue: #aw_sg9a1
• Effort: Medium
• Validation: Add env-var unit test; replace 27 literal sites; run go test ./....

Task 2: Consolidate SHAResolver / ActionSHAResolver

• Severity: Medium
• Issue: #aw_sg9a2
• Effort: Small
• Validation: Delete workflow.ActionSHAResolver; switch 17 sites to actionpins.SHAResolver; go build ./....

Success Metrics

• Findings generated: 5 (1 high, 2 medium, 2 low)
• Issues created: 2 (skipping ValidatableTool — defensible single-impl; and string-literal long-tail items — low ROI)
• Files analyzed: 21 prod files for the workflow-dir scan; 21 interface declarations for the pollution scan; 4+ packages cross-referenced via Serena LSP
• Success score: 9/10
  • Findings quality (4/4): one bug + one duplication, both with clear fixes and bounded blast radius.
  • Coverage (3/3): scan covered all top-level interfaces in pkg/ + all .github/workflows literal sites.
  • Task generation (2/3): 2 tasks instead of 3, because the third candidate (ValidatableTool) is defensible.

Historical Context

Strategy Performance

Run	Strategy	Score
4	Concurrency safety + resource lifecycle	9/10
5	Function complexity + long fn hot spots	9/10
6	Parameter-list scan + deep nesting	9/10
7	Switch complexity + exported-API usage	9/10
8	Dead code + magic literal	8/10
9	String literal + interface pollution	9/10

Cumulative Statistics

• Total runs: 9
• Total findings: 83
• Total tasks generated: 25
• Average success score: ~8.5/10
• Most successful strategy family: complexity/duplication scans (Runs 4-7, 9)

Confirmed prior issue traction

• Run 8 issue #aw_sg8a1 (file-perm constants) → FilePermSensitive/Public/DirPermSensitive/Public now present at pkg/constants/constants.go:73-91. ✅

Recommendations

Immediate

1. Land #aw_sg9a1 (GetWorkflowDir contract + sweep) — high impact, fixes a doc/code contract bug.
2. Land #aw_sg9a2 (interface consolidation) — small, mechanical, clears up an import-graph wart.

Longer-term

• Audit other producer-package interfaces with single implementers (e.g. ValidatableTool) when refactoring permission logic; consider inlining if no second impl materializes within a release cycle.
• The GH_AW_* env-var literal sprawl is partially addressed by constants.EnvVar*; consider a one-off lint rule to fail-CI on new "GH_AW_*" literals outside pkg/constants/.

Next Run Preview

Suggested focus areas

• Function-receiver consistency — pointer vs value receivers within the same type set (Go gotcha).
• Sentinel-error vs ad-hoc errors.New — gather all errors.New calls in pkg/; identify candidates for package-level Err* sentinels.
• Logger-prefix consistency — every package uses logger.New("<pkg>:<file>"); check for typos / drift in 200+ call sites.

Strategy evolution

• Pattern is emerging: "helper exists, callers bypass it" is the most consistently fruitful failure mode (Runs 5, 7, 8, 9). Worth a dedicated audit pass on every Default*/Get* helper in pkg/constants/ and pkg/*util/ next.

---

Generated by Sergo - The Serena Go Expert
Run ID: 25842525997
Strategy: string-literal-centralization-plus-interface-pollution-audit

Generated by Sergo - Serena Go Expert · ● 16.6M · ◷

• expires on May 15, 2026, 5:06 AM UTC