[repository-quality] 🎯 Repository Quality Improvement Report - Compile-Time Interface Compliance Gap (2026-07-13)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Compile-Time Interface Compliance Gap

Analysis Date: 2026-07-13
Focus Area: Compile-Time Interface Compliance Gap — Missing var _ Interface = (*ConcreteType)(nil) Assertions
Strategy Type: Custom
Custom Area: Yes — the repository has 22 interfaces and 9+ concrete implementors but zero compile-time satisfaction checks anywhere in pkg/ or cmd/.

Executive Summary

The pkg/workflow package defines 22 Go interfaces — including the critical Engine, CodingAgentEngine, FileCreationTracker, ToolConfig, SHAResolver, CommandProvider, and LogAnalysis families — all without a single var _ Interface = (*ConcreteType)(nil) compile-time assertion. Nine concrete engine structs (ClaudeEngine, CopilotEngine, CodexEngine, GeminiEngine, AntigravityEngine, OpenCodeEngine, CrushEngine, PiEngine, UniversalLLMConsumerEngine) embed BaseEngine and add their own methods, creating a silent risk: any future addition to an interface silently breaks the contract at link-time or only at the call site rather than at the declaration site.

The CodingAgentEngine interface is composed of 8 sub-interfaces (Engine, CapabilityProvider, WorkflowExecutor, MCPConfigProvider, LogParser, SecurityProvider, ModelEnvVarProvider, ConfigRenderer). A single missing method addition to any one of these cascades to all 9 engine structs with no early signal to developers.

Adding var _ CodingAgentEngine = (*ClaudeEngine)(nil) style assertions is a zero-cost, widely-adopted Go idiom that turns silent runtime incompatibilities into hard compile errors. This is quick work (one line per concrete type) and is already standard practice in similarly structured codebases.

Full Analysis Report

Focus Area: Compile-Time Interface Compliance Gap

Current State Assessment

Metrics Collected:

Metric	Value	Status
Total interfaces in pkg/	22	⚠️
var _ Interface = (...) assertions	0	❌
Concrete CodingAgentEngine implementors	9	❌
Sub-interfaces composing CodingAgentEngine	8	❌
Other interfaces with concrete implementors lacking assertions	5	❌
Interface families with production usage	22	⚠️

Findings

Strengths

• All 9 engine structs embed BaseEngine which provides default implementations for shared methods, reducing partial-implementation risk.
• Interfaces are well-documented with Go doc comments, especially in agentic_engine.go.
• CodingAgentEngine uses interface composition cleanly — changes to any sub-interface are centralised.

Areas for Improvement

• [HIGH] Zero var _ CodingAgentEngine = (*XxxEngine)(nil) assertions for 9 engine structs — silent contract breakage risk on any interface change.
• [HIGH] FileCreationTracker has 1 production implementor (cli.FileTracker) and 2 test mocks — none has a compile-time check.
• [MEDIUM] ToolConfig (implemented by MapToolConfig) and LogAnalysis/MutableLogAnalysis (implemented by FirewallAnalysis, DomainAnalysis) lack assertions.
• [MEDIUM] CommandProvider (alias for *cobra.Command) is used in shell completion but the interface is never asserted against *cobra.Command.
• [LOW] SHAResolver in pkg/actionpins is re-exported as a type alias in pkg/workflow; the aliasing file lacks any verification that the underlying type still satisfies the interface.

Detailed Analysis

Engine family (pkg/workflow/agentic_engine.go):

type CodingAgentEngine interface {
    Engine              // GetID, GetDisplayName, GetDescription, IsExperimental, GetGHSkillAgentName
    CapabilityProvider  // GetCapabilities
    WorkflowExecutor    // GetInstallationSteps, GetExecutionSteps, ...
    MCPConfigProvider   // GetMCPConfig
    LogParser           // ParseLogs
    SecurityProvider    // GetSecuritySteps
    ModelEnvVarProvider // GetModelEnvVarName
    ConfigRenderer      // RenderConfig
}

Implementors: ClaudeEngine, CopilotEngine, CodexEngine, GeminiEngine, AntigravityEngine, OpenCodeEngine, CrushEngine, PiEngine, UniversalLLMConsumerEngine — none has a var _ CodingAgentEngine = (*XxxEngine)(nil).

FileCreationTracker (pkg/workflow/compiler_types.go):
cli.FileTracker is the sole production implementor. Assertion missing in pkg/cli/file_tracker.go.

ToolConfig (pkg/workflow/mcp_config_types.go):
MapToolConfig is the only concrete implementation; no assertion.

LogAnalysis / MutableLogAnalysis (pkg/cli/log_aggregation.go):
FirewallAnalysis and DomainAnalysis implement MutableLogAnalysis; no assertions in either file.

---

🤖 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 9 CodingAgentEngine Implementors

Priority: High
Estimated Effort: Small
Focus Area: Compile-Time Interface Compliance Gap

Description: Add one var _ workflow.CodingAgentEngine = (*XxxEngine)(nil) assertion at the package level in each of the 9 engine source files. This turns any future missing-method error from a silent link-time or call-site failure into an immediate compile error pinpointing the affected type.

Acceptance Criteria:

• Each of the 9 engine files (claude_engine.go, copilot_engine.go, codex_engine.go, gemini_engine.go, antigravity_engine.go, opencode_engine.go, crush_engine.go, pi_engine.go, universal_llm_consumer_engine.go) contains exactly one var _ CodingAgentEngine = (*XxxEngine)(nil) assertion at the top of the file (after the package declaration and imports).
• make build passes without errors.
• make lint passes without errors.

Code Region: pkg/workflow/*_engine.go

In each of the following files, add a compile-time interface assertion immediately after the import block:
- pkg/workflow/claude_engine.go → var _ CodingAgentEngine = (*ClaudeEngine)(nil)
- pkg/workflow/copilot_engine.go → var _ CodingAgentEngine = (*CopilotEngine)(nil)
- pkg/workflow/codex_engine.go → var _ CodingAgentEngine = (*CodexEngine)(nil)
- pkg/workflow/gemini_engine.go → var _ CodingAgentEngine = (*GeminiEngine)(nil)
- pkg/workflow/antigravity_engine.go → var _ CodingAgentEngine = (*AntigravityEngine)(nil)
- pkg/workflow/opencode_engine.go → var _ CodingAgentEngine = (*OpenCodeEngine)(nil)
- pkg/workflow/crush_engine.go → var _ CodingAgentEngine = (*CrushEngine)(nil)
- pkg/workflow/pi_engine.go → var _ CodingAgentEngine = (*PiEngine)(nil)
- pkg/workflow/universal_llm_consumer_engine.go → var _ CodingAgentEngine = (*UniversalLLMConsumerEngine)(nil)

The assertion line should appear just after the import block and before the first type or var declaration. No other changes are needed. Run `make build` and `make lint` to verify.

---

Task 2: Add Compile-Time Assertions for Engine Sub-Interfaces in BaseEngine

Priority: High
Estimated Effort: Small
Focus Area: Compile-Time Interface Compliance Gap

Description: BaseEngine provides default implementations for all sub-interfaces that compose CodingAgentEngine (Engine, CapabilityProvider, WorkflowExecutor, MCPConfigProvider, LogParser, SecurityProvider, ModelEnvVarProvider, ConfigRenderer, HarnessProvider, LLMProviderResolver, AgentFileProvider, ConfigRenderer). Add compile-time assertions for BaseEngine against each of these sub-interfaces in agentic_engine.go.

Acceptance Criteria:

• pkg/workflow/agentic_engine.go contains a var _ XxxInterface = (*BaseEngine)(nil) assertion for every sub-interface that BaseEngine provides method implementations for.
• make build passes.
• make lint passes.

Code Region: pkg/workflow/agentic_engine.go

In pkg/workflow/agentic_engine.go, after the type definitions for BaseEngine (around line 316), add a block of compile-time assertions for each sub-interface that BaseEngine satisfies. Check which interface methods BaseEngine has implementations for (grep for `func (e *BaseEngine)`) and add one assertion per interface satisfied. Place the assertions after the import block or in a dedicated section near the BaseEngine type definition. Run `make build` to confirm no missing methods.

---

Task 3: Add Compile-Time Assertions for FileCreationTracker and ToolConfig

Priority: Medium
Estimated Effort: Small
Focus Area: Compile-Time Interface Compliance Gap

Description: cli.FileTracker (in pkg/cli/file_tracker.go) is the production implementor of workflow.FileCreationTracker. MapToolConfig (in pkg/workflow/mcp_config_types.go) is the concrete implementor of ToolConfig. Both lack compile-time assertions.

Acceptance Criteria:

• pkg/cli/file_tracker.go contains var _ workflow.FileCreationTracker = (*FileTracker)(nil).
• pkg/workflow/mcp_config_types.go contains var _ ToolConfig = MapToolConfig(nil) (or the appropriate zero value for a map type).
• make build passes.

Code Region: pkg/cli/file_tracker.go, pkg/workflow/mcp_config_types.go

1. In pkg/cli/file_tracker.go, add after the import block:
   var _ workflow.FileCreationTracker = (*FileTracker)(nil)
   Import pkg/workflow if not already imported.

2. In pkg/workflow/mcp_config_types.go, find the MapToolConfig type declaration and add below it:
   var _ ToolConfig = MapToolConfig(nil)
   (MapToolConfig is a map type so the zero value is nil.)

Run `make build` to verify.

---

Task 4: Add Compile-Time Assertions for LogAnalysis and MutableLogAnalysis

Priority: Medium
Estimated Effort: Small
Focus Area: Compile-Time Interface Compliance Gap

Description: FirewallAnalysis (in pkg/cli/firewall_log.go) and DomainAnalysis (in pkg/cli/access_log.go) both implement MutableLogAnalysis. Neither has a compile-time assertion. Adding assertions here ensures that the AddMetrics(other LogAnalysis) method signature stays in sync.

Acceptance Criteria:

• pkg/cli/firewall_log.go contains var _ MutableLogAnalysis = (*FirewallAnalysis)(nil).
• pkg/cli/access_log.go contains var _ MutableLogAnalysis = (*DomainAnalysis)(nil).
• make build passes.
• make lint passes.

Code Region: pkg/cli/firewall_log.go, pkg/cli/access_log.go

1. In pkg/cli/firewall_log.go, add after the FirewallAnalysis type declaration:
   var _ MutableLogAnalysis = (*FirewallAnalysis)(nil)

2. In pkg/cli/access_log.go, add after the DomainAnalysis type declaration:
   var _ MutableLogAnalysis = (*DomainAnalysis)(nil)

Run `make build` and `make lint` to confirm.

---

Task 5: Add a Custom Linter Rule Requiring Interface Compliance Assertions

Priority: Low
Estimated Effort: Medium
Focus Area: Compile-Time Interface Compliance Gap

Description: The pattern of missing var _ Interface = (*Impl)(nil) will reoccur as new interfaces and implementors are added. Create a new Go analysis linter (pkg/linters/missinginterfaceassert/) that warns when a concrete struct implements an interface (via method set analysis) but no corresponding var _ Interface = (*Struct)(nil) assertion exists in the same package. This prevents regression of the compliance gap.

Acceptance Criteria:

• New linter at pkg/linters/missinginterfaceassert/ with Analyzer, doc.go, and testdata.
• Linter is registered in pkg/linters/doc.go and the spec test.
• At least 3 testdata cases: missing assertion (flagged), assertion present (not flagged), interface in different package (not flagged).
• make lint passes.
• make test passes.

Code Region: pkg/linters/missinginterfaceassert/

Create a new custom linter under pkg/linters/missinginterfaceassert/ following the existing linter pattern (see pkg/linters/wgdonenotdeferred/ as a reference). The linter should:
1. Walk all named types that are structs.
2. For each struct, use types.Implements to check if it satisfies any interface defined in the same package or an imported package.
3. Check whether a var _ Interface = (*Struct)(nil) (or var _ Interface = Struct{}) declaration exists in any file of the same package.
4. If no such declaration exists, report a diagnostic on the struct type declaration.

Register the new analyzer in pkg/linters/doc.go and ensure it appears in pkg/linters/spec_test.go's expected analyzer list. Add testdata cases in pkg/linters/missinginterfaceassert/testdata/src/missinginterfaceassert/.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-07-08	Deprecated API Alias Proliferation & Zombie Callsite Cleanup	Custom	Y	4 tasks, deprecated API cleanup
2026-07-07	Environment Variable Access Fragmentation	Custom	Y	5 tasks, envutil expansion
2026-07-06	Context-Blind Sleep Gap	Custom	Y	4 tasks, select-based cancellation
2026-07-03	ADR-42150 dispatch-repository Key Canonicalization	Custom	Y	5 tasks, key format migration
2026-07-02	Remote Fetch API Context Gap	Custom	Y	4 tasks, context propagation

---

🎯 Recommendations

Immediate Actions (This Week)

1. Add var _ CodingAgentEngine assertions in all 9 engine files — Priority: High

Short-term Actions (This Month)

1. Add assertions for FileCreationTracker, ToolConfig, LogAnalysis implementors — Priority: Medium
2. Add BaseEngine sub-interface assertions — Priority: High

Long-term Actions (This Quarter)

1. Implement missinginterfaceassert linter to prevent regression — Priority: Low

---

📈 Success Metrics

• Interface compliance assertions: 0 → 22+ (one per concrete implementor per interface)
• Engine structs with assertions: 0/9 → 9/9
• Linter coverage for future regressions: 0% → 100% (if linter implemented)

---

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 this focus area in 2 weeks

---

References:

• §29254094444

Generated by Repository Quality Improvement Agent

Generated by ⚡ Repository Quality Improvement Agent · 50.9 AIC · ⌖ 6.03 AIC · ⊞ 6.6K · ◷

• expires on Jul 14, 2026, 5:41 AM UTC-08:00