[repository-quality] 🎯 Repository Quality Improvement Report - Compile-Time Interface Satisfaction Assertions (2026-07-15)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Compile-Time Interface Satisfaction Assertions

Analysis Date: 2026-07-15
Focus Area: Compile-Time Interface Satisfaction Assertions
Strategy Type: Custom
Custom Area: Yes — zero var _ Interface = (*Concrete)(nil) guards exist in all production Go files; this is a never-covered, repo-specific gap directly affecting refactoring safety for the 7+ engine types

Executive Summary

The repository defines 21 interfaces across pkg/ and cmd/, including the critical CodingAgentEngine composite interface (itself composed of 10 sub-interfaces) implemented by 7+ concrete engine types. Zero production files contain a compile-time interface satisfaction assertion (var _ Interface = (*ConcreteType)(nil)). Only 5 such assertions exist, all in test files, covering only LogAnalysis/MutableLogAnalysis for two types and one engine type in a single test.

This means any refactoring that silently breaks an engine's contract (e.g., removing a method, changing a signature) will be caught only at the call site, potentially far from the broken type, making root cause analysis harder. The ConditionNode interface (10 concrete expression node types) and SHAResolver interface (ActionResolver concrete type) are similarly unguarded.

Adopting the Go idiom of placing var _ Interface = (*Type)(nil) assertions directly in the implementation files collapses the feedback loop from "somewhere fails to compile" to "this file fails to compile at its declaration site" — a zero-cost, no-runtime-overhead improvement.

Full Analysis Report

Focus Area: Compile-Time Interface Satisfaction Assertions

Current State Assessment

Metrics Collected:

Metric	Value	Status
Production var _ Interface = ... assertions	0	❌
Test-file var _ Interface = ... assertions	5	⚠️
Exported interfaces (production)	16	—
CodingAgentEngine concrete implementors	7+	❌ unguarded
ConditionNode concrete implementors	10	❌ unguarded
SHAResolver concrete implementors	1	❌ unguarded
FileCreationTracker concrete implementors	1	❌ unguarded
ValidatableTool concrete implementors	1	❌ unguarded
ToolConfig concrete implementors	1	❌ unguarded

Findings

Strengths

• pkg/cli/log_aggregation_test.go already demonstrates the pattern correctly (var _ LogAnalysis = (*DomainAnalysis)(nil)) — the team knows the idiom
• pkg/workflow/pi_engine_test.go has one engine assertion (var _ CodingAgentEngine = NewPiEngine())

Areas for Improvement

• [HIGH] CodingAgentEngine — 7 concrete types (CopilotEngine, GeminiEngine, AntigravityEngine, ClaudeEngine, CodexEngine, PiEngine, BehaviorDefinedEngine, UniversalLLMConsumerEngine) have zero production-side assertions; the sub-interfaces (Engine, CapabilityProvider, WorkflowExecutor, MCPConfigProvider, LogParser, SecurityProvider, ModelEnvVarProvider, InferenceProviderResolver, AgentFileProvider, ConfigRenderer, HarnessRunner) are also unguarded in production
• [HIGH] ConditionNode — 10 expression node structs (ExpressionNode, AndNode, OrNode, NotNode, DisjunctionNode, FunctionCallNode, PropertyAccessNode, StringLiteralNode, BooleanLiteralNode, ComparisonNode) have no assertions
• [MEDIUM] SHAResolver — ActionResolver in pkg/workflow/action_resolver.go has no assertion
• [MEDIUM] FileCreationTracker — FileTracker in pkg/cli/file_tracker.go has no assertion; it's injected via SetFileTracker and silently ignored if nil
• [LOW] ValidatableTool, ToolConfig, CommandProvider — single-implementor interfaces with no guards

Detailed Analysis

Why it matters for this repo specifically:

The CodingAgentEngine interface is a 10-interface composite. Adding a new method to any sub-interface (e.g., HarnessRunner) requires all 7+ concrete engine types to implement it. Today, the compiler points to call sites in pkg/workflow/compiler_orchestrator_engine.go or similar, not to the concrete type file. With assertions in copilot_engine.go, gemini_engine.go, etc., the compiler immediately flags the right file.

The expression ConditionNode hierarchy (pkg/workflow/expression_nodes.go) is the most concentrated: all 10 concrete types live in one file, making a single block of assertions trivial to add and highly protective during future AST refactoring.

SHAResolver is used as a parameter type in 12+ functions across pkg/workflow/ and pkg/cli/. ActionResolver in action_resolver.go is the sole production implementation; an assertion there prevents silent drift.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items.

Improvement Tasks

Task 1: Add compile-time assertions for all CodingAgentEngine concrete types

Priority: High
Estimated Effort: Small
Focus Area: Compile-Time Interface Satisfaction Assertions

Description: Add var _ CodingAgentEngine = (*CopilotEngine)(nil) (and equivalent for each engine) in each concrete engine's Go file. For value-receiver engines (PiEngine, CodexEngine), use the value form var _ CodingAgentEngine = PiEngine{}. Also add assertions for the sub-interfaces (e.g. var _ HarnessRunner = (*CopilotEngine)(nil)) in the concrete type files if the type is known to implement them.

Acceptance Criteria:

• pkg/workflow/copilot_engine.go has var _ CodingAgentEngine = (*CopilotEngine)(nil)
• pkg/workflow/gemini_engine.go has var _ CodingAgentEngine = (*GeminiEngine)(nil)
• pkg/workflow/antigravity_engine.go has var _ CodingAgentEngine = (*AntigravityEngine)(nil)
• pkg/workflow/claude_engine.go has var _ CodingAgentEngine = (*ClaudeEngine)(nil)
• pkg/workflow/codex_engine.go has var _ CodingAgentEngine = (*CodexEngine)(nil) (or value form)
• pkg/workflow/pi_engine.go has var _ CodingAgentEngine = (*PiEngine)(nil) (or value form)
• pkg/workflow/behavior_defined_engine.go has var _ CodingAgentEngine = (*BehaviorDefinedEngine)(nil)
• pkg/workflow/universal_llm_consumer_engine.go has var _ CodingAgentEngine = (*UniversalLLMConsumerEngine)(nil)
• make build passes after changes

Code Region: pkg/workflow/copilot_engine.go, pkg/workflow/gemini_engine.go, pkg/workflow/antigravity_engine.go, pkg/workflow/claude_engine.go, pkg/workflow/codex_engine.go, pkg/workflow/pi_engine.go, pkg/workflow/behavior_defined_engine.go, pkg/workflow/universal_llm_consumer_engine.go

Add compile-time interface satisfaction assertions for all CodingAgentEngine concrete types in gh-aw.

In each of the following files, add a `var _ CodingAgentEngine = (*Type)(nil)` line immediately after the `type` declaration (or at the top of the file near the imports, after the package declaration). For pointer-receiver types use `(*Type)(nil)`; for value-receiver types use `Type{}`.

Files and concrete types:
- `pkg/workflow/copilot_engine.go`: `CopilotEngine`
- `pkg/workflow/gemini_engine.go`: `GeminiEngine`
- `pkg/workflow/antigravity_engine.go`: `AntigravityEngine`
- `pkg/workflow/claude_engine.go`: `ClaudeEngine`
- `pkg/workflow/codex_engine.go`: `CodexEngine`
- `pkg/workflow/pi_engine.go`: `PiEngine`
- `pkg/workflow/behavior_defined_engine.go`: `BehaviorDefinedEngine`
- `pkg/workflow/universal_llm_consumer_engine.go`: `UniversalLLMConsumerEngine`

Example of the pattern:
```go
var _ CodingAgentEngine = (*CopilotEngine)(nil)

Ensure make build passes after all changes.

---

#### Task 2: Add compile-time assertions for ConditionNode expression types

**Priority**: High
**Estimated Effort**: Small
**Focus Area**: Compile-Time Interface Satisfaction Assertions

**Description:** Add `var _ ConditionNode = (*ExpressionNode)(nil)` (and variants for all 10 concrete node structs) in `pkg/workflow/expression_nodes.go`, grouped as a block after all the struct definitions.

**Acceptance Criteria:**
- [ ] All 10 concrete types (`ExpressionNode`, `AndNode`, `OrNode`, `NotNode`, `DisjunctionNode`, `FunctionCallNode`, `PropertyAccessNode`, `StringLiteralNode`, `BooleanLiteralNode`, `ComparisonNode`) have a `var _ ConditionNode` assertion
- [ ] Assertions are grouped as a single `var (...)` block at the top/bottom of the file
- [ ] `make build` passes

**Code Region:** `pkg/workflow/expression_nodes.go`

```markdown
Add compile-time interface satisfaction assertions for all ConditionNode implementations in `pkg/workflow/expression_nodes.go`.

At the bottom of the file (or after all type declarations), add a grouped assertion block:

```go
var (
    _ ConditionNode = (*ExpressionNode)(nil)
    _ ConditionNode = (*AndNode)(nil)
    _ ConditionNode = (*OrNode)(nil)
    _ ConditionNode = (*NotNode)(nil)
    _ ConditionNode = (*DisjunctionNode)(nil)
    _ ConditionNode = (*FunctionCallNode)(nil)
    _ ConditionNode = (*PropertyAccessNode)(nil)
    _ ConditionNode = (*StringLiteralNode)(nil)
    _ ConditionNode = (*BooleanLiteralNode)(nil)
    _ ConditionNode = (*ComparisonNode)(nil)
)

Ensure make build passes after the change.

---

#### Task 3: Add compile-time assertions for SHAResolver and FileCreationTracker

**Priority**: Medium
**Estimated Effort**: Small
**Focus Area**: Compile-Time Interface Satisfaction Assertions

**Description:** Add `var _ SHAResolver = (*ActionResolver)(nil)` in `pkg/workflow/action_resolver.go` and `var _ FileCreationTracker = (*FileTracker)(nil)` in `pkg/cli/file_tracker.go`.

**Acceptance Criteria:**
- [ ] `pkg/workflow/action_resolver.go` contains `var _ SHAResolver = (*ActionResolver)(nil)` (or `var _ actionpins.SHAResolver = ...` using the canonical type)
- [ ] `pkg/cli/file_tracker.go` contains `var _ workflow.FileCreationTracker = (*FileTracker)(nil)` (adjust import as needed) or the assertion is placed where the interface is accessible
- [ ] `make build` passes

**Code Region:** `pkg/workflow/action_resolver.go`, `pkg/cli/file_tracker.go`

```markdown
Add compile-time interface satisfaction assertions for SHAResolver and FileCreationTracker in gh-aw.

1. In `pkg/workflow/action_resolver.go`, add near the type declaration:
```go
var _ SHAResolver = (*ActionResolver)(nil)

(SHAResolver is defined in pkg/actionpins and aliased in pkg/workflow/action_pins.go)

2. In pkg/cli/file_tracker.go, the FileTracker struct must satisfy workflow.FileCreationTracker. Add:

var _ workflow.FileCreationTracker = (*FileTracker)(nil)

Check the existing import of the workflow package; if missing, add it.

Ensure make build passes after both changes.

---

#### Task 4: Add compile-time assertions for ValidatableTool and ToolConfig

**Priority**: Low
**Estimated Effort**: Small
**Focus Area**: Compile-Time Interface Satisfaction Assertions

**Description:** Add `var _ ValidatableTool = (*GitHubToolConfig)(nil)` in `pkg/workflow/permissions_toolset_data.go` and `var _ ToolConfig = MapToolConfig(nil)` in `pkg/workflow/mcp_config_types.go`.

**Acceptance Criteria:**
- [ ] `pkg/workflow/permissions_toolset_data.go` has `var _ ValidatableTool = (*GitHubToolConfig)(nil)`
- [ ] `pkg/workflow/mcp_config_types.go` has `var _ ToolConfig = MapToolConfig(nil)`
- [ ] `make build` passes

**Code Region:** `pkg/workflow/permissions_toolset_data.go`, `pkg/workflow/mcp_config_types.go`

```markdown
Add compile-time interface satisfaction assertions for ValidatableTool and ToolConfig in gh-aw.

1. In `pkg/workflow/permissions_toolset_data.go`, after the `type GitHubToolConfig` struct definition, add:
```go
var _ ValidatableTool = (*GitHubToolConfig)(nil)

2. In pkg/workflow/mcp_config_types.go, after type MapToolConfig map[string]any, add:

var _ ToolConfig = MapToolConfig(nil)

Ensure make build passes after both changes.

---

## 📊 Historical Context

<details>
<summary>Previous Focus Areas</summary>

| Date | Focus Area | Type | Custom | Key Outcomes |
|------|------------|------|--------|--------------|
| 2026-07-14 | Logger Name Collision & Instantiation Hygiene | Custom | Y | 3 duplicate logger names, 6 shadowing vars, 3 inline struct-literal loggers |
| 2026-07-08 | Deprecated API Alias Proliferation & Zombie Callsite Cleanup | Custom | Y | 3 deprecated callsites, 4 always-true guards, zombie function |
| 2026-07-07 | Environment Variable Access Fragmentation | Custom | Y | 45 nolint suppressions, 6 duplicated env vars |
| 2026-07-06 | Context-Blind Sleep Gap | Custom | Y | 7 time.Sleep calls in ctx-orphaned helpers |
| 2026-07-03 | ADR-42150 Implementation Gap | Custom | Y | 5 callsites using wrong key form |

</details>

---

## 🎯 Recommendations

### Immediate Actions (This Week)
1. Add CodingAgentEngine assertions for all 8 concrete engine types — Priority: High
2. Add ConditionNode assertions for all 10 expression node types — Priority: High

### Short-term Actions (This Month)
1. Add SHAResolver and FileCreationTracker assertions — Priority: Medium

### Long-term Actions (This Quarter)
1. Add a custom linter (`interfaceassert`) that warns when a public interface has concrete implementors in the same package without a `var _ Interface = ...` guard — Priority: Low

---

## 📈 Success Metrics

- **Production `var _` assertions**: 0 → 21+
- **Interfaces covered**: 0/16 exported → 16/16 exported
- **CodingAgentEngine concrete types guarded**: 1/8 (test-only) → 8/8 (production)

---

## Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on improvement items
4. Re-evaluate remaining interface coverage in 30 days

---

**References:**
- [§29418473001](https://github.com/github/gh-aw/actions/runs/29418473001)

*Generated by Repository Quality Improvement Agent*




> Generated by [⚡ Repository Quality Improvement Agent](https://github.com/github/gh-aw/actions/runs/29418473001) · 58.3 AIC · ⌖ 5.98 AIC · ⊞ 6.6K · [◷](https://github.com/search?q=repo%3Agithub%2Fgh-aw+%22gh-aw-workflow-call-id%3A+github%2Fgh-aw%2Frepository-quality-improver%22&type=discussions)
> - [x] expires <!-- gh-aw-expires: 2026-07-16T13:24:48.702Z --> on Jul 16, 2026, 5:24 AM UTC-08:00

<!-- gh-aw-agentic-workflow: Repository Quality Improvement Agent, engine: copilot, version: 1.0.70, model: claude-sonnet-4.6, id: 29418473001, workflow_id: repository-quality-improver, run: https://github.com/github/gh-aw/actions/runs/29418473001 -->

<!-- gh-aw-workflow-id: repository-quality-improver -->
<!-- gh-aw-workflow-call-id: github/gh-aw/repository-quality-improver -->

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-16T13:24:48.702Z.

Closed by Workflow