[Docs] Publish ROADMAP.md and an API stability / deprecation policy toward 1.0

[dgenio]

Summary

Add a public ROADMAP.md that organizes open issues into themes and milestones on the path to 1.0, plus an explicit API stability and deprecation policy: what is stable today, what may change before 1.0, and how breaking changes are communicated.

Why this matters

The project ships fast (ten minor releases, one already-handled breaking rename) and has a rich issue backlog — but an evaluator can't currently tell where it's going or how risky it is to depend on. A roadmap converts the backlog into a story ("audit durability → protocol coverage → hardening → 1.0"), and a written stability contract is precisely what turns "interesting Alpha" into "we can build on this". The 0.10.0 import rename was handled well; codifying that practice multiplies its trust value.

Proposed scope

• ROADMAP.md: 3–5 named themes mapping to existing open issues (e.g., durable verifiable audit; protocol coverage MCP/A2A; production hardening per security: production-hardening roadmap + ship the first piece (token signing/encryption, pluggable secrets/auth) #103; ecosystem contracts per coherence: adopt the canonical Frame seam (producer side) — resolve "two firewalls" with contextweaver#352 / weaver-spec#84 #110/coherence: consume the shared Policy + safety-class contract (weaver-spec#78 / agentfence#76) — write once, enforce embedded + at the edge #111/Add shared policy contract roadmap with AgentFence #120; DX & docs), each with motivating one-liners and issue links — explicitly marked as direction, not commitment.
• A "Stability" section (in ROADMAP.md or docs/versioning.md): SemVer interpretation pre-1.0 (what minor bumps may break), the public-API definition (the __all__ surface), deprecation mechanics (warning period, DeprecationWarning, CHANGELOG entries), and the criteria for declaring 1.0.
• README links the roadmap; CONTRIBUTING points issue authors at it.
• GitHub milestones created to mirror the themes, with existing issues assigned.

Implementation notes

• Keep it one page; a roadmap nobody maintains is worse than none — add a "last reviewed" date and a note that issues are the source of truth.
• 1.0 criteria should be concrete and checkable (e.g., stability policy enforced for N releases, hardening roadmap items from security: production-hardening roadmap + ship the first piece (token signing/encryption, pluggable secrets/auth) #103 shipped, weaver-spec conformance suite running in CI rather than the current placeholder).
• The deprecation policy should reference the existing practice from the 0.10.0 rename (parallel naming window, CHANGELOG breaking entry) as the template.

Acceptance criteria

• ROADMAP.md published with themed, issue-linked direction and a last-reviewed date.
• Stability/deprecation policy defines the public API surface and breaking-change mechanics.
• 1.0 criteria stated concretely.
• Milestones created and populated; README/CONTRIBUTING link the roadmap.

Out of scope

• Committing to dates.
• Reorganizing or closing existing issues (triage is separate maintenance).
• The production-hardening content itself (security: production-hardening roadmap + ship the first piece (token signing/encryption, pluggable secrets/auth) #103 owns it; the roadmap links it).

References

• Ecosystem precedents for pre-1.0 stability policies in typed Python libraries (e.g., documented SemVer-with-caveats approaches).
• In-repo: CHANGELOG 0.10.0 breaking-change handling, tests/test_public_api.py (public surface is already test-pinned), security: production-hardening roadmap + ship the first piece (token signing/encryption, pluggable secrets/auth) #103, coherence: adopt the canonical Frame seam (producer side) — resolve "two firewalls" with contextweaver#352 / weaver-spec#84 #110, coherence: consume the shared Policy + safety-class contract (weaver-spec#78 / agentfence#76) — write once, enforce embedded + at the edge #111, Add shared policy contract roadmap with AgentFence #120.

---

Priority: P1 · Effort: S · Impact: High