docs: refresh stale phase/MVP prose and add doc-surface drift guards#93
Merged
Conversation
Fix truth-in-docs drift and lock it out: - EVIDENCE.md lifecycle diagram: replace non-command 'archive' leaf node with 'replay'; the three leaf boxes are now replay/inspect/diff, matching the three operations in section 9. - render.py / protocol.py: drop MVP/Week-2/Week-3 framing; describe the shipped surface (render covers run/replay/diff/verify/export; store surface is save/load/query/close with history/timeline/matrix/diff as consumer-side layers). - 9 test files: rewrite RED-phase 'does not exist yet' docstrings to present tense. Guards (all behind the decision surface): - test_evidence_doc_freshness.py: new check asserts every lifecycle-diagram leaf box is a real CLI command (locks out 'archive' drift; prose 'archive' still allowed). - test_readme_command_surface.py: every build_parser subcommand is referenced in README. - test_release_gate_coverage_sync.py: release_gate COVERAGE_FLOOR equals CI --cov-fail-under. - test_cli_store_lifecycle.py: clarify minimize opens no ReplayStore.
ericckzhou
added a commit
that referenced
this pull request
Jun 8, 2026
…93) (#94) Fix truth-in-docs drift and lock it out: - EVIDENCE.md lifecycle diagram: replace non-command 'archive' leaf node with 'replay'; the three leaf boxes are now replay/inspect/diff, matching the three operations in section 9. - render.py / protocol.py: drop MVP/Week-2/Week-3 framing; describe the shipped surface (render covers run/replay/diff/verify/export; store surface is save/load/query/close with history/timeline/matrix/diff as consumer-side layers). - 9 test files: rewrite RED-phase 'does not exist yet' docstrings to present tense. Guards (all behind the decision surface): - test_evidence_doc_freshness.py: new check asserts every lifecycle-diagram leaf box is a real CLI command (locks out 'archive' drift; prose 'archive' still allowed). - test_readme_command_surface.py: every build_parser subcommand is referenced in README. - test_release_gate_coverage_sync.py: release_gate COVERAGE_FLOOR equals CI --cov-fail-under. - test_cli_store_lifecycle.py: clarify minimize opens no ReplayStore.
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.
What
Truth-in-docs hygiene pass plus cheap drift guards that lock the fixes in. Documentation- and test-only — no runtime code paths change.
Fixes (stale → shipped reality)
│ archive │box, which is not a command. Replaced withreplay; the three leaf boxes are now replay / inspect / diff, matching the three operations in §9. Prose updated to name the full consumer surface.falsifyai/cli/render.py: dropped "MVP scope" + "Rich/colored output and--jsonland in Week 3" (never shipped). Now describes the actual surface it renders (run/replay,diff,verify,export).falsifyai/replay/protocol.py: dropped "MVP surface only —case_history/diff_sessionsdeferred to Week 2". Describes the real store contract (save/load/query/close) and that history/timeline/matrix/diff are consumer-side layers, not store methods.# RED:comments) to present tense.Guards (all behind the decision surface)
test_evidence_doc_freshness.py: new check parses the §3 lifecycle diagram and asserts every leaf box is a real CLI command — locks out thearchivedrift permanently. The prose word "archive" (retention discussion) is still allowed; only diagram boxes are checked.test_readme_command_surface.py(new): every subcommand registered inbuild_parser()must be referenced inREADME.md.test_release_gate_coverage_sync.py(new):scripts/release_gate.pyCOVERAGE_FLOORmust equal CI's--cov-fail-under— the "keep in sync" comment was the only thing holding them together.Nit
test_cli_store_lifecycle.pydocstring clarified:minimizeopens noReplayStore(in-memory search, persists nothing), so it has no store lifecycle to pin — distinct fromrun, which does.Out of scope (intentionally deferred)
validate_groq.ps1: self-declares "DO NOT COMMIT", requires.env.localwith real keys — correctly stays gitignored, no action..claude/settings.json: left unstaged per established workflow convention.Verification
uv run pytest: 788 passed (including 23 meta-tests; the new diagram guard correctly fails on a non-command leaf node, verified during development).uv run ruff check .: clean.ruff format --check: clean.