[repository-quality] 🎯 Repository Quality Improvement Report: Engine Catalog Adoption Gap & Experimental Flag Propagation (2026-06-17)

[github-actions[bot]]

🎯 Repository Quality Improvement Report — Engine Catalog Adoption Gap & Experimental Flag Propagation

Analysis Date: 2026-06-17
Focus Area: Engine Catalog Adoption Gap & Experimental Flag Propagation
Strategy Type: Custom (random = 7, 0–59 tier)
Custom Area: Yes — the EngineCatalog abstraction is partially adopted; constants.AgenticEngines was deprecated in favour of catalog.IDs() but 3 production callsites remain, and EngineDefinition lacks an experimental field despite 3 engines needing it.

Executive Summary

The pkg/workflow engine layer has a layered API: the lower-level EngineRegistry (runtime singletons) and the higher-level EngineCatalog (declarative metadata from data/engines/*.md). The migration to the catalog is incomplete: constants.AgenticEngines carries a Deprecated comment pointing to catalog.IDs(), yet three loop-based callsites in pkg/cli/logs_orchestrator.go still reference the old slice, risking silent divergence when a new engine is added.

Beyond the deprecation drift, EngineDefinition has no experimental field, even though Pi, Antigravity, and OpenCode set experimental: true in their Go constructors. Callers that use only the definition (e.g. gh aw add, documentation generators) cannot surface experimentalness without resolving the full runtime. A third gap: all 8 built-in engine definition markdown files leave models.default empty, forcing forecast and token-usage tools to maintain separate hard-coded model maps.

Full Analysis Report

Current State Assessment

Metrics Collected:

Metric	Value	Status
constants.AgenticEngines deprecated callsites in production	3 (logs_orchestrator.go:355,370,938)	❌
Engines with experimental:true in Go but not in EngineDefinition	3 (pi, antigravity, opencode)	⚠️
Engine definition files with empty models.default	8 / 8	⚠️
CLI files using NewEngineCatalog	1 of 5 (add_interactive_engine.go)	⚠️
Engine constants / definition files / runtime adapters	8 / 8 / 8	✅

Findings

Strengths

• Engine count is consistent across all three layers (8 each).
• compiler_types.go already creates both the registry and catalog together.
• pkg/cli/add_interactive_engine.go correctly uses NewEngineCatalog.
• EngineCatalog.Resolve() includes a backward-compat prefix-fallback for old engine IDs.

Areas for Improvement

• [HIGH] 3 deprecated AgenticEngines loops in logs_orchestrator.go — silent divergence risk on new engine additions.
• [MEDIUM] EngineDefinition has no experimental field; catalog consumers can't determine experimentalness.
• [MEDIUM] completions.go:ValidEngineNames() uses GetSupportedEngines() instead of catalog.IDs().
• [LOW] All 8 engine definition files have empty models.default / models.supported.

Detailed Analysis

Deprecated AgenticEngines callsites: All three sites in logs_orchestrator.go iterate over constants.AgenticEngines and call registry.GetEngine(id) for pointer comparison. Replace the loop source with workflow.NewEngineCatalog(workflow.NewEngineRegistry()).IDs() — keep GetGlobalEngineRegistry() for the pointer lookup itself.

Missing experimental field: EngineDefinition has no Experimental bool field; adding yaml:"experimental,omitempty" and updating the three markdown files completes the data model.

completions.go:ValidEngineNames(): One-line fix — use catalog.IDs() instead of registry.GetSupportedEngines(). Mirrors the pattern in add_interactive_engine.go:88.

Empty models.default: All 8 engine files omit models.default though the struct supports it; default IDs are already in model_aliases.go.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Migrate logs_orchestrator.go Deprecated AgenticEngines to Catalog API

Priority: High | Effort: Small | Focus Area: Engine Catalog Adoption

Description: Replace 3 constants.AgenticEngines loop usages in pkg/cli/logs_orchestrator.go (lines ~355, ~370, ~938) with workflow.NewEngineCatalog(workflow.NewEngineRegistry()).IDs().

Acceptance Criteria:

• constants.AgenticEngines has zero references in pkg/cli/logs_orchestrator.go
• Engine-filter matching logic uses catalog.IDs() as the loop source
• go test ./pkg/cli/... and make lint pass

Code Region: pkg/cli/logs_orchestrator.go lines ~354–373 and ~930–945

Replace the three for-range loops over `constants.AgenticEngines` in
`pkg/cli/logs_orchestrator.go` with `workflow.NewEngineCatalog(workflow.NewEngineRegistry()).IDs()`.
Keep `workflow.GetGlobalEngineRegistry().GetEngine(id)` for the pointer-comparison
inside each loop — only the iteration source changes. Verify with
`go test ./pkg/cli/...` and `make lint`.

---

Task 2: Add experimental Field to EngineDefinition and Engine Markdown Files

Priority: Medium | Effort: Small | Focus Area: Engine Definition Schema Completeness

Description: Add Experimental bool \yaml:"experimental,omitempty"`toEngineDefinitioninengine_definition.go. Update pi.md, antigravity.md, and opencode.mdwithexperimental: true`. Add loader tests asserting the field is read correctly.

Acceptance Criteria:

• EngineDefinition.Experimental bool field added with correct yaml tag
• pi.md, antigravity.md, opencode.md have experimental: true
• Loader test asserts Experimental == true for those three; false for others
• go test ./pkg/workflow/... and make lint pass

Code Region: pkg/workflow/engine_definition.go, pkg/workflow/data/engines/pi.md, pkg/workflow/data/engines/antigravity.md, pkg/workflow/data/engines/opencode.md

In `pkg/workflow/engine_definition.go`, add `Experimental bool \`yaml:"experimental,omitempty"\``
to the `EngineDefinition` struct. Update the three experimental engine markdown files
(`pi.md`, `antigravity.md`, `opencode.md`) to include `experimental: true` under their
`engine:` frontmatter block. Add assertions in `engine_definition_loader_test.go`.
Run `go test ./pkg/workflow/...` and `make lint`.

---

Task 3: Migrate completions.go:ValidEngineNames() to Catalog API

Priority: Medium | Effort: Small | Focus Area: Engine Catalog Adoption

Description: ValidEngineNames() in pkg/cli/completions.go calls GetGlobalEngineRegistry().GetSupportedEngines(). Change it to workflow.NewEngineCatalog(workflow.NewEngineRegistry()).IDs() following the pattern in add_interactive_engine.go:88.

Acceptance Criteria:

• ValidEngineNames() uses catalog.IDs() not registry.GetSupportedEngines()
• Shell completion for --engine still returns all 8 engine names
• go test ./pkg/cli/... passes

Code Region: pkg/cli/completions.go lines ~64–70

In `pkg/cli/completions.go`, replace the body of `ValidEngineNames()` with:
  catalog := workflow.NewEngineCatalog(workflow.NewEngineRegistry())
  return catalog.IDs()
Follow the existing pattern in `pkg/cli/add_interactive_engine.go:88`.
Run `go test ./pkg/cli/...`.

---

Task 4: Populate models.default in Built-in Engine Definition Files

Priority: Low | Effort: Small | Focus Area: Engine Definition Schema Completeness

Description: All 8 engine definition markdown files leave models.default empty. Add the known default model identifier (referencing model_aliases.go) for at least claude, codex, gemini, and copilot. Add loader test assertions.

Acceptance Criteria:

• claude.md, codex.md, gemini.md, copilot.md have models.default populated
• EngineDefinition.Models.Default != "" for those four in loader tests
• go test ./pkg/workflow/... passes

Code Region: pkg/workflow/data/engines/*.md

For `claude.md`, `codex.md`, `gemini.md`, and `copilot.md`, add a `models:` section
under the `engine:` frontmatter with `default: <model-id>`. Use the same default model
IDs referenced in `pkg/workflow/model_aliases.go`. Add assertions in
`engine_definition_loader_test.go` and run `go test ./pkg/workflow/...`.

---

📊 Historical Context

Previous Focus Areas (last 10 runs)

Date	Focus Area	Type	Custom
2026-06-16	Benchmark Infrastructure Completeness	Reuse	N
2026-06-15	Documentation	Standard	N
2026-06-12	Cobra Example Field Migration	Custom	Y
2026-06-10	Security	Standard	N
2026-06-08	Compiler Error Hint Rendering Gap	Custom	Y

---

🎯 Recommendations

Immediate Actions (This Week)

1. Migrate logs_orchestrator.go deprecated AgenticEngines loops — Priority: High

Short-term Actions (This Month)

1. Add experimental to EngineDefinition — Priority: Medium
2. Migrate completions.go:ValidEngineNames() — Priority: Medium

Long-term Actions (This Quarter)

1. Populate models.default in engine definition files — Priority: Low

---

📈 Success Metrics

• Deprecated AgenticEngines callsites: 3 → 0
• Engines missing experimental in definition: 3 → 0
• Engine definitions with models.default set: 0/8 → ≥4/8

---

Next Steps

1. Review and prioritise the 4 tasks above
2. Assign Tasks 1–3 to Copilot coding agent via planner agent
3. Track constants.AgenticEngines reference count as zero-target metric
4. Re-evaluate engine catalog completeness after next engine addition

---

References: §27694766267

Generated by ⚡ Repository Quality Improvement Agent · ◷

• expires on Jun 18, 2026, 6:18 AM UTC-08:00