M4 AP-5: public-API contract lock + as-built reconciliation (closes Milestone M4)

[STiFLeR7]

Summary

Final slice of Milestone M4 (BYOM recovery library). Locks the public surface and reconciles the documentation-first record with what actually shipped in AP-1–AP-4. No src/ behavior change — one new test + docs/trackers only.

• Public-API contract test (tests/test_public_api_contract.py): pins the exact 20-name cairn.__all__, fails on drift (both missing and extra), asserts every name imports, and guards __version__ at 0.x (blocks an accidental/unapproved v1.0 bump).
• Design-spec §12 (append-only): records the as-built deviations honestly — recover() has no goal (carried in the checkpoint), the Agent outcome is AgentRun (not RunResult), Observation/Model/MockModel aren't top-level exports, and CodeHarness.resume/observe_world were not force-migrated onto recover() (the harness interleaves Task-specific env setup — churning the validated benchmark was rejected). Sections 1–11 preserved verbatim.
• Milestone M4 tracker README (project/phases/milestone-4-byom-library/README.md): mirrors M1–M3; summarizes the 5 slices, what shipped, deviations, honest scope.
• Trackers + CHANGELOG: M4 now visible in the phase board, ap-index (slices AP-1…AP-5), and a ## [Unreleased] CHANGELOG entry (no version bump — ships nothing outward).

Governance

• 0.x, no publish/release/announce, no tag — CHANGELOG is [Unreleased]; the contract test guards the version at 0.x.
• Honest scope (ADR-0009): C1 is not confirmed by M4; the library lets a user reproduce the evidence on their own model. Every deviation is recorded, not hidden.
• ADR-0007 untouched (no src/ change at all).

Test Plan

• Full suite green: 141 passed (137 + 4 contract tests).
• Contract test's EXPECTED equals live cairn.__all__ exactly; catches both added and removed names; __version__ == 0.2.0.
• Deviation claims verified true against src/cairn/recovery.py (no goal) and src/cairn/agent.py (AgentRun).
• Spec §12 append-only; §1–11 untouched. All doc links resolve.
• Independent holistic review: READY TO MERGE (9/9 axes PASS).
• Maintainer review + merge (yours). Merging this closes Milestone M4.

🤖 Generated with Claude Code

[STiFLeR7]

Maintainer review — APPROVED for merge ✅

Reviewed from my side. Clean close-out of Milestone M4.

• 141 passed. No src/ behavior change — one new contract test + docs/trackers only.
• Surface lock works: EXPECTED equals the live 20-name cairn.__all__, catches both added and removed names, guards __version__ at 0.x.
• Honest reconciliation: every recorded deviation (recover() no-goal, AgentRun, harness not force-migrated) verified true against the code; consistent across spec §12 (append-only), milestone README, trackers, and the [Unreleased] CHANGELOG.
• Governance intact: no version bump/tag, 0.x, v1.0 hold, C1 not confirmed / user-reproducible.

MERGEABLE / CLEAN. Merging — this closes Milestone M4.