docs(compatibility): add Phase 4A policy

[solomonneas]

Summary

• Record the Phase 4A compatibility policy and its planned v0.25.0 release anchor.
• Define T0 as the actual GitHub release publication date and require both the v0.27.0 version gate and the T0 + 90-day calendar gate.
• Preserve the standalone mirror histories, define the GraphTrail crate policy, and document shim replacement blockers.
• Add a 15-item Phase 4B checklist with every item unchecked and both archive actions explicitly prohibited during Phase 4A.
• Lock the release clock, no-rewrite rule, replacement paths, scope exclusions, and unchecked checklist in a tracked policy test.

Release status

v0.25.0 is planned but is not yet published. This change does not start the compatibility clock. T0 remains the actual publication date shown on the Brigade release page. If v0.25.0 publishes on a date other than 2026-07-20, the calendar gate must be recomputed as T0 + 90 days.

This PR does not archive a repository, execute a Phase 4B checklist item, or change Agent Pantry or agent-notify/#366.

Verification

• ./scripts/verify: 3,488 passed, 3 skipped, 82.41% coverage
• Brigade verification receipt: 20260720-202728-work-verify-d390e6
• Final independent review: no blocking findings

Refs #352
Refs #365

Summary by CodeRabbit

• Documentation
  • Added tracking for the Phase 4A compatibility and archive policy.
  • Documented archival rules, shim retention/disposition guidance, command naming/invocation mappings, and planned publication timing.
  • Included a “90-day calendar gate” and updated the policy checklist to reflect remaining work.
• Tests
  • Added a release-metadata validation test to ensure the policy document contains the required tracked text and checklist state.

[solomonneas]

@coderabbitai review

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: escoffier-labs/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 1b758722-3aad-42ac-88bf-bfeb2a56fa45

📥 Commits

Reviewing files that changed from the base of the PR and between a5b1000 and ef96324.

⛔ Files ignored due to path filters (1)

• docs/phase-4a-compatibility-and-archive.md is excluded by !docs/**, !**/docs/**

📒 Files selected for processing (1)

• tests/test_release_metadata.py

---

📝 Walkthrough

Walkthrough

Adds a release metadata test that verifies the Phase 4A compatibility and archive policy document contains required policy text, date-gate details, and exactly 15 unchecked checklist items with no completed items.

Changes

Phase 4A policy validation

Layer / File(s)	Summary
Archive policy document test tests/test_release_metadata.py	Adds timedelta date arithmetic and validates required policy fragments, the planned 2026-07-20 publication date, the conditional 90-day calendar gate, and checklist state.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change: adding Phase 4A compatibility policy documentation and related tracking.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/issue-365-compatibility-checklist

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[solomonneas]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.