Breaking changes follow semver

Renaming a hook, changing its payload shape, or removing a plugin context method without a major version bump breaks every plugin in the ecosystem instantly and silently. Plugin authors discover the change when their code crashes, not from a deprecation warning or migration guide. ISO 25010 maintainability.modifiability requires that the scope of a change be predictable; semver applied to the plugin API is the mechanism that communicates scope. Without it, every minor host release carries hidden risk for the plugin ecosystem.

Apply semver discipline to the plugin API independently of the host application version: hook renames or payload changes = major bump; new hooks = minor; behavioral bug fixes = patch. Forward deprecated hook names to their replacements and emit a warning.

on(hook: string, handler: Function) {
  if (DEPRECATED_HOOKS[hook]) {
    console.warn(
      `[PluginAPI] Hook "${hook}" is deprecated and will be removed in API v${
        DEPRECATED_HOOKS[hook].removeInVersion
      }. Use "${DEPRECATED_HOOKS[hook].replacement}" instead.`
    );
    hook = DEPRECATED_HOOKS[hook].replacement;
  }
  // ... register handler
}