Define an integration-neutral contract for native event configuration #5052

Problem

Shared event orchestration currently contains agent-specific format branches and knowledge of native configuration layouts. Moving native rendering and cleanup into integration packages improves ownership, but agent-specific branches and method names in shared code leave that boundary incomplete.

The Vibe preservation fix in #4646 illustrates this distinction: native TOML handling can live in VibeIntegration while shared events still explicitly selects Vibe-specific methods.

This is architectural follow-up work, not a prerequisite for accepting that bug fix.

Proposed improvement

Define a small, typed contract on IntegrationBase for merging and removing native event hooks. Possible method names are merge_native_event_hooks() and remove_native_event_hooks(); finalize their signatures against the requirements of existing event-capable integrations.

Shared orchestration should own canonical event filtering, shared dispatcher creation and reference-counted cleanup, and manifest bookkeeping. Integrations should own native event-name mapping, configuration rendering and merging, managed-entry recognition, and cleanup.

The contract should provide access to shared dispatcher-command construction and safe, journal-aware filesystem operations without requiring integrations to reproduce shared lifecycle behavior.

Acceptance criteria

• Shared orchestration delegates native configuration updates and cleanup through declared, integration-neutral methods, without Vibe-specific branches or dynamic discovery of Vibe-named methods.
• Validate the contract against Vibe and at least one other existing native-event format. Existing format implementations may remain behind base-class defaults; migrating every integration is not required.
• Integrations without native-event support retain their existing behavior.
• The update result distinguishes files actually updated from untouched or skipped files. Failures and skipped updates produce explicit diagnostics.
• Merged user configuration retains partial ownership; untouched files do not acquire new ownership claims.
• Disabling events and uninstalling remove only Spec Kit-managed entries, preserve unowned content, and retain the dispatcher while another integration references it.
• Preserve symlink protections and lifecycle-journal participation.
• Add positive and negative contract coverage, including no-op preservation and multi-integration dispatcher lifecycle. Any bug fixes include before-and-after regression evidence.
• Document the contract and ownership boundary in design/integration.md.

Out of scope

• Changes to native hook schemas or supported events.
• Changes to core command templates.
• A new event plugin framework.
• Wholesale migration of every integration’s native event implementation.

AI disclosure

GitHub Copilot, powered by GPT-6.1 Sol (gpt-6.1-sol), drafted this issue under human supervision. The user reviewed the draft and authorized filing it upstream. AI assistance covered PR inspection, architectural analysis, and issue drafting; no implementation changes were made.