docs: align contract docs with canonical events and stable source references

[michaeljabbour]

Summary

• Removed phantom event names and aligned all contract docs to the canonical execution:start/execution:end + llm:request/llm:response event vocabulary
• Updated contract references away from fragile line-number anchors to stable symbol/section references
• Orchestrator contract signature and docs now reflect the **kwargs coordinator injection model
• Fixed related_files frontmatter paths so scripts/check_related_files.py passes cleanly
• Docstring-only updates in python/amplifier_core/interfaces.py (no runtime changes)

Files changed

File	Scope
CONTRACTS.md	Event name alignment, reference updates
docs/HOOKS_API.md	Event name fix
docs/contracts/ORCHESTRATOR_CONTRACT.md	**kwargs injection model, event alignment
docs/contracts/PROVIDER_CONTRACT.md	Event name + reference fixes
docs/contracts/TOOL_CONTRACT.md	Event name + reference fixes
docs/contracts/HOOK_CONTRACT.md	Event name + reference fixes
docs/contracts/CONTEXT_CONTRACT.md	Reference + path fixes
python/amplifier_core/interfaces.py	Docstring-only updates

Verification evidence

$ python scripts/check_related_files.py
Files checked: 34
Files with frontmatter: 11
Errors: 0
Warnings: 0

Passed: All references valid

Test plan

• scripts/check_related_files.py passes with 0 errors, 0 warnings
• Changes are docs/docstrings only — no runtime behavior affected
• All 8 files reviewed for event name consistency

🤖 Generated with Amplifier

[bkrabach]

Thorough Review — PR #40

Thanks for this work, @michaeljabbour — the core intent is solid and addresses real doc-code drift. We verified every claim against the live codebase (LSP, grep, script execution) and the fundamental changes are correct. However, we found several issues that need a follow-up pass before merge.

What we verified ✅

• Phantom events confirmed: turn:start, turn:end, llm:pre, llm:post — grep across entire codebase returns zero hits outside CONTRACTS.md. These genuinely do not exist in events.rs, any Python source, or any test.
• Canonical events confirmed: execution:start at events.rs:119, execution:end at events.rs:121, llm:request at events.rs:74, llm:response at events.rs:76 — all present in ALL_EVENTS slice and test-verified.
• Orchestrator **kwargs confirmed: LSP hover on interfaces.py:37 shows **kwargs: Any. The contract doc on main incorrectly shows coordinator: ModuleCoordinator | None = None. Your fix is correct.
• All 18 broken paths confirmed: check_related_files.py currently exits 1 with 18 errors on main. Every related_files path using amplifier_core/... is broken. Your ../../python/amplifier_core/... fixes all resolve to existing files.
• interfaces.py change is docstring-only: LSP documentSymbol confirms all 8 class definitions start at line 33+. The diff touches only lines 3–10 inside the module docstring. Zero runtime impact.

Issues to address

1. "41+" should be "41" (factual error)
CONTRACTS.md now says "The full set contains 41+ events." There is a Rust test at events.rs:342 that asserts ALL_EVENTS.len() == 41. The count is exactly 41, not "41+". Please change to "41 events" or "41 canonical events."

2. ai_context/DOCUMENTATION_LINKING.md has 3 broken path templates — MISSED (high priority)
This is the AI-agent guidance document that templates new contract files. It still has amplifier_core/interfaces.py (without python/) at lines 28, 113, and 167. Any AI (or human) following this template will generate files with the same broken related_files paths this PR is fixing. The check_related_files.py script only validates frontmatter, not body text, so it won't catch these. Please fix these 3 references.

3. docs/HOOKS_API.md still has lines: 205-220 (inconsistency)
The PR removes lines: annotations from every contract file but leaves lines: 205-220 in docs/HOOKS_API.md — making it the only surviving line-number anchor after this PR. For consistency with your own stated rationale, please remove this too.

4. docs/specs/PROVIDER_SPECIFICATION.md has a broken path (medium)
Line 20 references amplifier_core/interfaces.py in a table without the python/ prefix. Body text so the script won't catch it, but worth fixing in the same pass.

Non-blocking observations (no changes needed)

• ScriptedOrchestrator in testing.py:145 is missing **kwargs: It would crash with TypeError if called through AmplifierSession (which always passes coordinator=). Not this PR's problem, but we'll track it separately.
• Event table lists context:compaction but not context:pre_compact/context:post_compact: Developers writing hooks more commonly need the pre/post events. Consider adding them to the "commonly referenced" table in a follow-up.
• Hardcoded event strings: hooks.py:44-51 and bindings/python/src/lib.rs:1104-1118 define independent string literals rather than importing from events.rs/events.py. The new "always use constants" guidance is good aspirational direction, but the codebase has ~20 existing violations. Not blocking for this PR.

Summary

The core work is valuable and we want it merged. The 4 actionable items above are all straightforward fixes in the same vein as the existing changes. Once addressed, this is ready to go. 🙏