[architect] cmd/hive: 13K-line package main concentrates business logic; main_helpers.go is a 4,789-line grab-bag of ≥6 concerns

[hivecommons-hive]

Architecture Finding

Type: tech-debt/anti-pattern (business logic in package main)
Affected area: src/cmd/hive (v5 @ 88ff376; same shape on v4 @ a2df923)

src/cmd/hive is 35 non-test files / 13,182 lines of production code in package main, plus 16,050 lines of tests that must also live in package main. The largest file, main_helpers.go (4,789 lines, 116 top-level functions), mixes at least six unrelated concerns:

• GitHub App health diagnosis/classification: diagnoseGitHubApp, diagnoseGitHubAppFull, classifyGitHubAppFailure, classifyGitHubAppWriteForbidden, classifyGitHubAppRepoCoverage, healGitHubAppInstallation
• Advisory digest posting policy: shouldBuildAdvisoryDigest, shouldPostAdvisoryDigest, advisoryPostDue, recordAdvisoryPostSuccess, advisoryIssueUnresolved, ...
• Inference gateway routing: resolveLiteLLMInferenceRoute, resolveWatsonxGateway, resolveGatewayAuth, superviseLocalLiteLLM
• Eval-cycle orchestration: runEvalCycle, actionableAfterGitHubEnumerate
• Dashboard/notify wiring: buildRepoActivityWire, applyBudgetAlerts, applyNoCadenceAlert
• Logging/bootstrap: setupLogger, parseLogLevel, runHub, initAgentConfigDrivenSystems

main_globals.go (620 lines) additionally pins mutable package-level state (e.g. githubAppTokenCachePath, appKeys, reporterName) that tests monkey-patch.

Impact

• None of this logic is reusable or unit-testable from outside cmd/hive; every test must live in package main against shared mutable globals.
• The recurring "seams" pattern (eval_cycle_seams.go, and hub_boot_seams.go arriving via PR 🌱 top-up v5 with v4 through b6d99ce97 (v4.39.3) #7235) is a symptom: tests keep pinning function-variable seams inside main because the logic has no package boundary to test against.
• main_helpers.go is a merge-conflict hotspot — nearly every v4→v5 top-up touches it (e.g. 🌱 top-up v5 with v4 through b6d99ce97 (v4.39.3) #7235).

Recommendation

Staged extraction (each stage is behavior-preserving and independently reviewable):

1. GitHub App diagnosis/classification → pkg/github (or new pkg/apphealth) — pure functions over github.AppAuth, easiest first cut.
2. Advisory digest policy → pkg/advisory (it already owns Digest).
3. Gateway/LiteLLM routing → new pkg/inference or into pkg/config-adjacent resolver.
4. Only wiring, flag parsing, and main() remain in cmd/hive.

Coordination: do not start until PR #7235 (v5 top-up, edits main_helpers.go and adds hub_boot_seams.go) lands — this refactor would conflict with every in-flight top-up touching that file.

---

Filed by architect agent (ACMM L5 — hold-gated mode)

🐝 Hive Agent: architect | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=architect backend=copilot model=claude-opus-4-6 copilot=1.0.78

[github-actions]

PR #7253 has merged (#7253) and referenced this issue with a non-closing Refs #7238 rather than a closing keyword.

Can this issue now be closed, or is there remaining work it should keep tracking?