docs: ROADMAP.md + NEW_SESSION_PROMPT.md + 2 pin tests - #33
Merged
Conversation
Adds the v2.2.0→v3.0 implementation plan (`docs/ROADMAP.md`, 476 lines covering 7 phases) and a self-contained copy-pasteable starter prompt (`docs/NEW_SESSION_PROMPT.md`, 224 lines) that bootstraps a fresh agent session on Phase 0. Both files are explicitly exempted from the `/docs/*.md` deny-list in .gitignore — they're source-of-truth artifacts, not transient session reports, so they ship with the public repo alongside MANUAL.md and CHUNK_SCHEMA.md. Two pin tests in `tests/test_release_critical_names.py` keep both files honest: - `test_roadmap_md_exists_and_covers_all_phases` — file exists and contains all 7 `## Phase N` headings (N=0..6) plus cross-links to NEW_SESSION_PROMPT.md, AGENTS.md, CHANGELOG.md. Renaming a phase or stripping a cross-link fails CI. - `test_new_session_prompt_md_exists_with_required_invariants` — file exists, has the `==== BEGIN PROMPT ====` / `==== END PROMPT ====` markers (load-bearing for copy-paste UX), and inlines the 6 worst footguns (package name, thinking-blocks rule, tox-freshness, 7-manifest lockstep, `gh release create`, comp.storage). A future agent that skips AGENTS.md still gets the protection. AGENTS.md updated: TL;DR now points at NEW_SESSION_PROMPT.md + ROADMAP.md as the bootstrap chain, and the Cross-references section lists both files with their purpose. No version bump — docs+tests only, same shape as PR #31 and PR #32. Full local sweep green: 1700 pytest, ruff format+check, all 3 freshness/version gates. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…_ROOT> CI lint job on PR #33 caught two hardcoded personal-path references in docs/NEW_SESSION_PROMPT.md (lines 26 and 149): /Users/visansilviugeorge/Desktop/DREAM AI/TDPilot_deepseekv4 This slipped through the local sweep because `scripts/check_no_personal_paths.sh` scans only `git ls-files` output — the file was still untracked when I ran the pre-commit check. CI runs the check post-merge so it scans the committed tree. The fix uses `<REPO_ROOT>` as a portable placeholder (matching the script's documented suggestion) and clarifies the prose: anyone copy-pasting the prompt will `cd` into their own clone path, so a hardcoded $HOME path was just wrong regardless of the lint check. Verified locally with files now staged: - `bash scripts/check_no_personal_paths.sh` — clean - `uv run pytest tests/test_release_critical_names.py` — 12/12 pass - `uv run --extra dev ruff format --check ...` — clean Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 78f112b3e4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ```bash | ||
| cd "/Users/visansilviugeorge/Desktop/DREAM AI/TDPilot_deepseekv4" | ||
| git fetch origin && git checkout -b claude/v2.2.0-phase-0-foundation origin/main | ||
| git log --oneline -5 # confirm 93c9a30 AGENTS.md is the tip |
There was a problem hiding this comment.
The starter prompt hard-codes git log --oneline -5 # confirm 93c9a30 AGENTS.md is the tip, but this file is meant for future sessions and main will advance after this commit. Because the very next instruction says to stop if any baseline step fails, following this prompt on a healthy newer main can create a false failure and block Phase 0 work. Replace the fixed SHA check with a stable invariant (e.g., verify required files/sections exist) so the bootstrap remains valid across commits.
Useful? React with 👍 / 👎.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/ROADMAP.md(~470 lines) — full v2.2.0→v3.0 implementation plan. 7 phases (0–6), per-phase file-level inventory, cross-cutting concerns (testing strategy, feature-flag pattern, release flow, doc discipline, backward-compat), release-cadence summary, risk register, quick-start for next session.docs/NEW_SESSION_PROMPT.md(224 lines) — copy-pasteable starter prompt for a fresh agent session picking up Phase 0. Self-contained: inlines the 6 worst footguns (package name, DeepSeek thinking-blocks, .tox freshness, 7-manifest lockstep,gh release create,comp.storage) so an agent that skips AGENTS.md is still protected.tests/test_release_critical_names.py:test_roadmap_md_exists_and_covers_all_phases— file exists, all 7## Phase Nheadings present, cross-links to NEW_SESSION_PROMPT/AGENTS/CHANGELOG intact.test_new_session_prompt_md_exists_with_required_invariants— file exists, BEGIN/END markers present (copy-paste UX), worst footguns inlined, bootstrap chain (AGENTS.md + ROADMAP.md) referenced.AGENTS.mdupdated — TL;DR points at the new bootstrap chain; Cross-references section lists both new docs with purpose..gitignore— explicit!/docs/ROADMAP.mdand!/docs/NEW_SESSION_PROMPT.mdexceptions to the existing/docs/*.mddeny-list.No version bump. Docs + tests only — same shape as PR #31 (post-v2.1.5 hygiene) and PR #32 (AGENTS.md addition).
Why
After v2.1.5 stabilized the API .tox (FIFO inbox, safety timer, idle-suffix predicate), the next stretch is feature work — but spread across 6 months and 6+ releases. A fresh session needs:
docs/ROADMAP.md(source of truth).docs/NEW_SESSION_PROMPT.md.test_release_critical_names.py.Test plan
uv run pytest tests/ --ignore=tests/agent_evals -q— 1700 pass (1698 prior baseline + 2 new pin tests)uv run --extra dev ruff format --check src tests scripts td_component— cleanuv run --extra dev ruff check src tests scripts td_component— cleanuv run python scripts/check_versions.py— v2.1.5 in sync (no drift)uv run python scripts/check_tox_freshness.py— both .tox freshuv run python scripts/check_tox_api_freshness.py— both .tox freshbash scripts/check_no_personal_paths.sh— clean🤖 Generated with Claude Code