Summary

Refactor the repository's highest-complexity, highest-churn internal orchestration surfaces into explicit state, transaction, and ownership boundaries without changing public behavior or contracts.

Problem to solve

Several active edit surfaces combine state machines, policy, cleanup, registration, routing, and presentation in single modules or functions. This makes narrow changes difficult to reason about, raises regression risk, and forces coding agents and maintainers to load unrelated invariants before editing safely.

The initial audit identified these priority areas:

• agent terminal outcomes, reply execution, and embedded attempt lifecycle
• plugin registration rollback and startup activation planning
• Gateway WebSocket handshake and request dispatch
• changed-file classification and test routing
• Workboard runtime ownership
• legacy-store static analysis
• generated locale and protocol model pipelines
• scripts/pr internals and cohesive acceptance scenarios
• iOS application state ownership

Proposed solution

Land a sequence of small internal refactor PRs. Each PR must:

• preserve config, SDK, CLI option, protocol, schema, and public type shapes
• preserve generated artifact contents unless regeneration is mechanically required
• keep public exports and runtime behavior unchanged
• introduce focused tests or invariant matrices for the extracted boundary
• pass focused remote proof, check:changed, and autoreview before landing
• avoid compatibility shims or parallel old/new implementations

The first wave will cover terminal outcome normalization, plugin registration transactions, shared change-impact facts, Workboard runtime ownership, and legacy-store analyzer decomposition. Later waves will cover the remaining named surfaces.

Alternatives considered

• Splitting files by size alone: rejected because it redistributes hidden coupling without defining ownership.
• One repository-wide refactor PR: rejected because review and rollback would be unsafe.
• Leaving generated and safety-critical tooling untouched: rejected; their generators and internal seams still need the same ownership audit, while preserving exact outputs and contracts.

Impact

Affected: maintainers, contributors, coding agents, CI/release operators.

Severity: ongoing engineering drag and elevated regression risk on frequently edited paths.

Frequency: every change touching these orchestration surfaces.

Consequence: slower review, broader test requirements, duplicated policy, and lower confidence in automated edits.

Evidence/examples

A full codebase-memory index on current main produced 302,664 nodes and 1,244,792 edges. Representative hotspots include a 5,391-line embedded attempt function, a 2,245-line Gateway WebSocket handler, a plugin loader with 47 inbound and 117 outbound graph edges, and multiple validation-routing modules that independently classify the same changed paths.

Additional information

This is maintainer-requested refactor work. No PR in this program may add or change config keys, SDK surfaces, protocol/schema shapes, CLI options, or user-visible behavior.