feat(planning): scaffold phases 9/10/11 backlog + forward-facing .planning/

[ayhammouda]

Summary

PR #4 of 6 in the v0.1.5 launch wave (per CHANGE-REQUEST-v0.1.5-launch.md, §D).

Adds three on-disk phase skeletons for the post-v0.1.5 backlog plus a tracked .planning/ROADMAP.md, and updates AGENTS.md to acknowledge the new forward-facing role of .planning/.

What's in

• .planning/phases/09-compare-versions/09-CONTEXT.md — new MCP tool: compare_versions(symbol, v1, v2) returns a structured diff of a stdlib symbol's signature/docstring/deprecation between two Python versions.
• .planning/phases/10-whatsnew/10-CONTEXT.md — new MCP tool: whatsnew_for_version(version) returns the official "What's New" page sliced into MCP-friendly sections with kind enum and pagination.
• .planning/phases/11-detect-venv/11-CONTEXT.md — enhancement: detect_python_version v2 reads VIRTUAL_ENV / pyvenv.cfg / .venv directories before falling back to v1's .python-version / python3 / sys.version_info chain. Backfills tests/test_detection.py (v1 has none).
• .planning/ROADMAP.md — new file. Documents v0.1.4 (shipped), v0.1.5 (in progress per CR), and the post-v0.1.5 backlog with links to each phase CONTEXT. Issue numbers will be backfilled after this PR merges.
• AGENTS.md — "Context Hygiene" section rewritten. Old framing said .planning/ was archival-only; new framing distinguishes live forward-looking specs (.planning/ROADMAP.md + .planning/phases/0X-…/) from archival history.

Out of scope (separate work)

• D5 — open GitHub issues for phases 09/10/11 with phase-plan label. Deferred until this PR merges so the issue bodies can link the merged CONTEXT.md URLs and so the ROADMAP table's #TBD placeholders can be backfilled in a follow-up commit.
• Phase implementations themselves are out of scope — these are spec skeletons only. Each phase will get its own /gsd-plan-phase cycle when prioritized.

Notes

• .planning/ was previously listed in .git/info/exclude (local, not tracked) as part of an old "archival artifacts kept out of public repo" policy. With this PR's locked decision (CR §9 Workstream D), .planning/ becomes a tracked forward-facing surface. The local exclude has been updated with a dated note explaining the policy shift; the line for .planning/ is commented out so new files in .planning/ are no longer ignored. Pre-2026-05-14 archival content remains untracked in maintainers' worktrees per the prior policy.

Test plan

• .planning/ROADMAP.md renders cleanly on GitHub with the three phase rows and links to their CONTEXTs
• Each phase CONTEXT.md follows the same shape (Goal / Depends on / Requirements / Success criteria / Plans / UI hint / Out of scope)
• AGENTS.md Context Hygiene section parses on GitHub
• CI green (ci.yml, security.yml, codeql.yml)

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a public ROADMAP documenting v0.1.4 as shipped and v0.1.5 in progress (five coordinated workstreams) and a post-v0.1.5 backlog.
  • Added phase-planning docs for three upcoming MCP tools: version comparison, “What’s New” extraction, and venv-aware Python detection (v2).
  • Updated contributor guidance to treat planning as the forward-facing surface and clarified current sources of truth.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a31a6e78-f1f1-4481-9d87-f1582810690b

📥 Commits

Reviewing files that changed from the base of the PR and between 786ab16 and 2b0d2ca.

📒 Files selected for processing (3)

• .planning/ROADMAP.md
• .planning/phases/10-whatsnew/10-CONTEXT.md
• .planning/phases/11-detect-venv/11-CONTEXT.md

✅ Files skipped from review due to trivial changes (3)

• .planning/ROADMAP.md
• .planning/phases/10-whatsnew/10-CONTEXT.md
• .planning/phases/11-detect-venv/11-CONTEXT.md

---

📝 Walkthrough

Walkthrough

Adds a tracked ROADMAP and three new phase CONTEXT documents, and updates AGENTS.md to treat .planning/ as the forward-facing planning surface; defines Phase 09 (compare_versions), Phase 10 (whatsnew_for_version), and Phase 11 (venv-aware detect_python_version v2).

Changes

Project Planning Framework and Phase Roadmap

Layer / File(s)	Summary
Planning governance framework AGENTS.md, .planning/ROADMAP.md	ROADMAP.md documents current release status (v0.1.4 shipped; v0.1.5 in progress) and the post-v0.1.5 backlog of planned phases. AGENTS.md redefines context hygiene guidance to treat live phase CONTEXTs in .planning/phases/*/ as forward-facing and other .planning/ contents as archival, and updates the "source of truth" checklist to point to README.md, CONTRIBUTING.md, .github/INTEGRATION-TEST.md, and tests/.
Phase 09: compare_versions(symbol, v1, v2) tool .planning/phases/09-compare-versions/09-CONTEXT.md	Phase 09 specifies a new MCP tool that produces a structured JSON-serializable diff of a Python stdlib symbol's signature, behavior, and docstring across two indexed versions, with detailed requirements for input shape, error handling, token constraints, and success criteria for changed/unchanged/missing symbol cases.
Phase 10: whatsnew_for_version(version) tool .planning/phases/10-whatsnew/10-CONTEXT.md	Phase 10 defines a tool that returns official Python "What's New" content as structured sections with title, anchor, body, and kind fields, specifying schema, token/cost constraints with pagination, and success criteria for section counts, stable anchors, kind filtering, and error handling for missing versions.
Phase 11: detect_python_version v2 (venv-aware) .planning/phases/11-detect-venv/11-CONTEXT.md	Phase 11 enhances the existing detect_python_version tool with venv awareness: check VIRTUAL_ENV environment variable and pyvenv.cfg, discover .venv or venv directories up the directory tree, support uv/poetry patterns, preserve v1 fallback chain, and return (major_minor, source) tuple discriminating among venv:VIRTUAL_ENV, venv:.venv, .python-version file, python3 in PATH, and server runtime, with success criteria and required tests for all cases.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I sketched a roadmap by moonlit code,
Phases queued where future work will go,
Compare, whatsnew, and venv-aware light,
A planning path to guide the night,
Hop forward — careful, steady, slow.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: introducing scaffolded planning documentation for future phases 9/10/11 and establishing .planning/ as a tracked forward-facing roadmap surface.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/phase-backlog

---

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