refactor(core)!: trim the plugin protocol and standardize on register_handlers (#487 part 2, #451)

[mlieberman85]

Summary

Part 2 of #487, plus #451. Both change the same plugin classes, the darnit-hello template and the plugin-author docs, so they're in one PR as separate commits. Spec first.

#487: trim ComplianceImplementation. Five protocol methods had no production caller:

• get_all_controls and get_controls_by_level: only called by the implementations themselves;
• get_rules_catalog and get_remediation_registry: no callers;
• register_controls: called behind hasattr, and a no-op in every implementation.

Controls, SARIF rules and remediations come from the framework TOML. This PR removes the methods from:

• the Protocol;
• all six in-tree plugins (baseline, csl, example, gittuf, hello, reproducibility);
• the three hasattr call sites;
• the unguarded calls in gittuf, reproducibility and example.

The Protocol is @runtime_checkable and discovery checks it with isinstance, so dropping members only loosens that check. A third-party plugin that still defines the old methods is still discovered. A new test covers both a plugin with the legacy methods and one without them. The protocol is now name, display_name, version, spec_version and get_framework_config_path, plus the optional register_handlers().

#451: one handler-registration hook.

• register_handlers() is the protocol hook. gittuf and reproducibility rename register_sieve_handlers, and darnit-example drops its duplicate. Their register() functions no longer register handlers as a side effect of discovery; the framework calls the hook itself.
• darnit-csl used to register at module import. It now uses register_handlers(), so a registry reset no longer loses its step type (new test).
• darnit-hello gets a documented no-op register_handlers() to show the shape.
• Compatibility: core/discovery.py still calls register_sieve_handlers for out-of-tree plugins, with a comment that it's kept for compatibility and isn't a supported choice. A new test checks that a plugin with only register_sieve_handlers still registers.

Spec:

• framework-design.md §6 has the trimmed protocol, and §6.4 names the hook. Appendix C gets a "Removed" entry. Version 1.0.0-alpha.16.
• CLAUDE.md and the plugin-author guides are updated to match.
• The CHANGELOG lists each removed method as BREAKING, for code that called these methods on a discovered implementation.

Closes #451
Refs #487

Type of Change

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update
• Refactoring (no functional changes)

Framework Changes Checklist

• Updated framework spec (docs/architecture/framework-design.md) if behavior changed
• Ran uv run python scripts/validate_sync.py --verbose and it passes

Testing

• Tests pass locally (uv run pytest tests/ -v): 5150 passed, 26 skipped (main: 5148)
• Added tests for new functionality (if applicable)
• Linting passes (uv run ruff check .)

Also run:

• integration tests with GitHub Actions environment variables set: 334 passed;
• darnit audit . with -f reproducibility, -f gittuf and -f community-spec: each plugin's own step types run, and none is reported as unregistered;
• one MCP server per framework (reproducibility, gittuf, community-spec), each built in a fresh process with create_server: each registers its plugin's step types;
• the plugin_discovery_smoke checks from CI, run locally against darnit-hello: pass.

AI assistance

• No AI assistance was used
• AI assistance was used

Claude (Claude Code, claude-opus-5-5) made this change: spec, code, tests and docs. This description was also drafted with Claude. Commits carry an Assisted-by: Claude:claude-opus-5-5 trailer.

Additional Notes

Left for later:

• server/factory.py has its own copy of the handler-registration helper, which calls only register_handlers. Audits register through register_implementation_handlers, so this has no effect in practice, but the factory could delegate to it.
• The core/plugin.py comment block lists get_check_handlers, get_context_handlers and get_remediation_handlers, which nothing calls.
• darnit-hello and some guide snippets still use Path(__file__) rather than importlib.resources (feature 021). The CLAUDE.md example now uses importlib.resources.
• Part 3 of Remove dead adapter system, legacy storage backend, unused protocol methods, and other unreachable code (~3,500 lines) #487 (fold darnit-example into darnit-testchecks) is next.

🤖 Generated with Claude Code