RFC 000: deprecate before removing, in line with INVARIANTS.md

[sergiopaniego]

Summary

RFC 000 says "we will not put soft deprecation in place until 1.0", but the Deprecations policy added to .claude/docs/INVARIANTS.md in #1277 (and first used in #1276) requires deprecating before removing. Cursor's alignment review on #1277 flagged this. This updates the "breaking changes" paragraph of RFC 000 to match: removals of APIs, CLI flags and environments get a FutureWarning naming the removal release and the replacement, for at least two minor releases, with a pointer to INVARIANTS.md. It also adds an amendment history entry. The post-1.0 sentence stays as it was.

cc @Darktex, since you're one of the RFC's authors.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• New environment
• Refactoring

Alignment Checklist

Before submitting, verify:

• I have read .claude/docs/PRINCIPLES.md and this PR aligns with our principles
• I have checked .claude/docs/INVARIANTS.md and no invariants are violated
• I have run /pre-submit-pr (or bash .claude/hooks/lint.sh and tests) and addressed all issues

RFC Status

• Not required (bug fix, docs, minor refactoring)
• RFC exists: RFC 000 (rfcs/000-project-phases.md), amended here
• RFC needed (will create before merge)

Test Plan

Docs only. RFC 000 and INVARIANTS.md now describe the same rule.

Claude Code Review

N/A. This PR was written with AI assistance (Claude Code) and reviewed by me.

---

Note

Low Risk
Documentation-only RFC amendment; no runtime or API behavior changes.

Overview
RFC 000 is amended so its pre-1.0 breaking-changes stance matches Deprecations in .claude/docs/INVARIANTS.md, instead of saying soft deprecation would not happen until 1.0.

The Our approach towards breaking changes section now states that removing APIs, CLI flags, or environments requires a deprecation period: the old surface keeps working with a FutureWarning that names the removal release and the replacement, for at least two minor releases, with a pointer to INVARIANTS.md. Breaking changes remain acceptable pre-1.0 and are still documented in release notes; the post-1.0 guarantees sentence is unchanged.

An amendment history entry (October 1, 2026) and an updated Amended date document this change.

^{Reviewed by Cursor Bugbot for commit 743a12c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[bot-ci-comment]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[cursor]

Alignment Review Report

Automated Checks

• Lint: N/A — the diff touches only rfcs/000-project-phases.md (Markdown, no Python), so usort/ruff (.claude/hooks/lint.sh) don't apply. uv wasn't available in this execution environment to confirm, but there is nothing lintable in this change regardless.
• Debug code: CLEAN — .claude/hooks/check-debug.sh only surfaces pre-existing print/TODO occurrences elsewhere in src/; none originate from this diff.

Open RFCs Context

• RFC 000 (rfcs/000-project-phases.md, Status: In Review) is the only RFC touched. The edit amends its "Our approach towards breaking changes" section and adds an Amendment History entry.
• No other open RFCs (001–012) reference deprecation or are otherwise affected by this docs-only change.

Tier 1: Fixes Required

None. This is a 6-line, Markdown-only amendment (2 insertions, swap of one sentence, one amendment-history bullet, and an updated Amended date). No syntax errors, no debug code, no lint surface.

Tier 2: Alignment Discussion

Principle Conflicts

None identified. The change doesn't touch the Gymnasium API, client/server boundary, reward placement, or the WebSocket/MCP dual-API model from PRINCIPLES.md — it's purely about release/removal process.

RFC Conflicts

None identified — and worth calling out explicitly why: this PR is itself the resolution of a previously-flagged conflict, not a new one. RFC 000 used to say "we will not put soft deprecation in place until 1.0", which contradicted the Deprecations policy merged into .claude/docs/INVARIANTS.md in #1277 (same author). That exact contradiction was flagged by this automation's review on #1277, and the PR description here explicitly references that flag and cc's @Darktex (RFC 000's author of this section, confirmed via git blame). The new RFC 000 text now matches INVARIANTS.md on every substantive point: FutureWarning, naming the removal release + replacement, and "at least two minor releases" pre-1.0 — the post-1.0 sentence is left untouched. I verified the two documents are now textually consistent, so no residual conflict remains.

One light process note rather than a blocking flag: RFC 000 lists four authors (@Darktex, @pankit-eng, @jspisak, @zkwentz) and is still "In Review" — the author has already looped in @Darktex, which covers the substantive sign-off; no further action needed from my side.

Summary

• 0 mechanical issues to fix
• 0 principle-alignment points for human review
• 0 open RFC conflicts — this PR resolves the one previously flagged on #1277

Small, well-scoped docs fix that reconciles RFC 000 with the already-merged INVARIANTS.md deprecation policy. No concerns blocking merge.

  

_{Sent by Cursor Automation: Pre-review}