SRP-decompose GoldenPathSynthesizer (1553-line static grab-bag → focused modules)

Update — 2026-06-28: consolidated to ONE lane (no-micro)

Per the micro-ticket scope-gate (#14263 / #14265, merged 2026-06-27), this does NOT fan out into per-cluster subs/PRs. The clusters below are the extraction map, not a sub-list. Two extractions already shipped under the old framing — #14283 (embedding helpers, cluster 8) and #14287 (capture-timestamp formatter, an adjacent helper); they stand. All remaining clusters (1–7, 9) ship together in ONE consolidated, behavior-preserving PR that resolves this ticket — one CI run, one review cycle. This is a single refactor lane, not a multi-sub epic; the epic label can drop to refactoring.

Done when: clusters 1–7 + 9 are extracted to focused modules with stable re-export shims, every unit/integration spec green, and GoldenPathSynthesizer.mjs is reduced to its orchestration core — in one PR.

Context

ai/services/graph/GoldenPathSynthesizer.mjs is a 1553-line singleton:true class with ~37 static methods + 3 top-level export functions — a static-utility grab-bag masquerading as a singleton. Operator-named in #13822's dogfood ("10 tickets on this file alone") as a concrete instance of the architectural debt the broad tech-debt-radar must surface (a grep sweep reads the file as clean; the real debt is structural). The Golden Path topology is agent-OS Brain substrate (README identity), so its maintainability is load-bearing.

The Problem

A 1553-line class mixing ~9 unrelated responsibilities is hard to test in isolation, hard to reason about, and concentrates change-risk — a touch to any one concern reloads the whole file's cognitive surface. The singleton:true framing is misleading: these are stateless static utilities, not a stateful singleton. The 3 top-level export functions (embedding helpers) are outright misplaced (embedding utils living in a Golden-Path file).

The Architectural Reality

V-B-A'd method clustering — the extraction map for the consolidated decomposition. Each is a behavior-preserving move to a focused module. These clusters organize the work inside one PR; they are not per-cluster subs/PRs (that fan-out is the micro-ticket anti-pattern barred by #14263/#14265):

1. agent-identity / family resolution — getIdentityGithubLogin, getCoreSwarmAgentFamilies, getAgentLogins, getStaleAssignmentMaintainers, parseSelfIdLogin, resolveAuthorFamily, hasCrossFamilyReview.
2. issue-markdown parsing — collectIssueMarkdownFiles, extractIssueCommentBlocks, extractAssignmentEvents, findLastQualifyingAssignmentActivity, findLatestIssueActivity.
3. stale-assignment detect + render — buildStaleAssignmentCandidates, renderStaleAssignmentCandidatesSection.
4. silent-thread detect + render — buildSilentThreadCandidates, renderSilentThreadCandidatesSection.
5. computed-recommendation / focus-contradiction — isActionableComputedRecommendation, isRoutingConflictFocusCandidate, isContentComputedRecommendation, findComputedFocusContradiction, renderComputedGoldenPathContradictionSection / *EmptySection / *FailureSection.
6. current-focus scoring + render — scoreCurrentFocusIssue, buildCurrentFocusCandidates, renderCurrentFocusCandidatesSection.
7. PR-cycle status + render — getActivePrCycleStatus, renderActivePrCycleState, renderRecentOpenPrSummary, renderStrategicInterpretationDegradedReason.
8. embedding helpers — the 3 export functions getEmbeddingVectorLength / getEmbeddingModelName / buildEmbeddingDimensionMismatchMessage (clearly misplaced; the recommended first sub — lowest blast).
9. frontier-edge + summary-doc — pruneStaleFrontierGuideEdges, getRecentSummaryDocuments, renderConsolidationGapsSection.

Intended Solution

Behavior-preserving extraction of the remaining clusters (1–7, 9) into focused modules, public API kept stable (re-export shim from GoldenPathSynthesizer for any externally-consumed symbol), green tests throughout. One consolidated PR covers all remaining clusters — not per-lane micro-PRs (#14263/#14265: one feature = one lane = one PR; bundle by default). The moves are mechanical (cut + re-export shim), so they review as one coherent diff in a single CI/review cycle. No big-bang rewrite — behavior is strictly preserved.

Out of Scope

• Behavior changes / logic enhancements — this epic is structural only (pure moves + re-export shims).
• The singleton:true → static-class reframe is a candidate cleanup, but the consolidated PR decides each module's destination shape (a module of pure functions vs a focused class).

Decision Record impact

none — a behavior-preserving structural decomposition; no ADR authority touched. (If an extraction surfaces an AiConfig/ADR-0019 boundary — cf. the adjacent taskDefinitions.mjs tension #13822 noted — the PR flags it.)

Related

• Origin: #13822 dogfood (the operator's "10 tickets on this file" architectural-debt observation + the broad-radar-vs-grep point).
• Sibling architectural-cleanup: #14277 (TopologyInferenceEngine service-boundary debt).

Live latest-open sweep: checked the latest 20 open issues + the A2A claim queue at 2026-06-27T23:44Z; no equivalent GoldenPathSynthesizer-decomposition ticket found.

Origin Session ID: 090a68e6-1a28-4b20-a5fd-842ebac3e729 Authored by Grace (@neo-opus-grace · Claude Opus 4.8, Claude Code).