docs: update phase4-plan.md to reflect Phase 3 closure + discoveries#25
Merged
Conversation
Phase 3 closed 2026-05-11 (PRs #19/#20/#22/#23/#24, see phase3-evidence.md). The Phase 4 plan was written before Phase 3 shipped and assumed Track B would block on it. This commit folds Phase 3's actual landings back into the plan: * §0 dependency table: Phase 3 row flipped 🟡 In flight → ✅ CLOSED, with the PR wave + importable helper list. Verification snippet rewritten to invoke `make handshake` / `make recipes-check` (now real Make targets, not aspirational). * §0 narrative: drop "Phase 4 may start at Phase 3 C2" — all three upstream phases are now closed, Track B is fully unblocked. * §1 Track Index: Track B's `Blocked by` simplifies to `A7` (was `A7 ∧ Phase 3 C2`). * §1 new subsection "What Phase 3 already shipped that Phase 4 consumes" — a table of the 5 concrete artifacts Track B / Track E pull from `.github/main` (discovery helpers, offline fixtures, recipe schema + 4 recipes, the two Make targets, the recipe runner pattern) plus a note on the two out-of-scope follow-ups (YAML parser limitations + orphan fixtures). * §3 B1: fixtures now reference Phase 3's bundled offline set instead of "a frozen snapshot of tools.json + task_index.json". * §3 B2: route_intent example reshaped to vendor-and-fallback — `match_intent` from Phase 3 handles exact matches; Phase 4's only new code is the fuzzy-rank fallback. * §3 B3: `describe("recipe:new-app-tdd-ci")` is no longer a hypothetical — point at the real recipe shipped in PR #23 and the task_index category shipped in PR #20. * §3 B4: spell out which helpers `describe` reuses (`parse_typed_id`, `resolve_module_manifest_url`) and which path is genuinely new code (`recipe:` lookup — Phase 3 didn't cover recipes in the routing trail). * §6 Track E: collapse to one evidence doc following Phase 1 + Phase 3 convention. Drop `phase4-status.md`; fold the stage-status roll-up into `phase4-evidence.md`. Rename `phase4-evidence.txt` → `.md` for parity with phase1/3 (already-rendered Markdown on GitHub). * §7 Stage Matrix: B1 `Blocked by` simplified; E2 (status doc) removed; E1 verification updated; E3 → E2. * §9 Risk Notes: replace "Phase 3 dependency timing" (now historical) with "Vendored Phase 3 helper drift" — the new ongoing risk, with a TDD-based mitigation. * §10 Gantt: phase 3 lane shows ✅ CLOSED instead of "unblocked; sequence as planned". * §11 Done definition: 10 → 9 criteria (phase4-status.md removed); evidence file renamed to .md; "every §11 done-criterion cited green" added to the evidence requirement (same pattern phase3-evidence.md follows).
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
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
Phase 3 closed 2026-05-11 (PRs #19 / #20 / #22 / #23 / #24 — see
docs/phase3-evidence.md). The Phase 4 plan was written before Phase 3 shipped and assumed Track B would block on it. This PR folds Phase 3's actual landings back intodocs/phase4-plan.md.What changed
match_intent,parse_typed_id,resolve_module_manifest_url,find_module_entry,entry_has_signature_and_example,fetch). Verification snippet rewritten to invokemake handshake/make recipes-check(now real Make targets).Blocked bysimplifies toA7(wasA7 ∧ Phase 3 C2)..github/main(helpers, offline fixtures, recipe schema + 4 recipes, the two Make targets, recipe runner pattern), plus the two known out-of-scope follow-ups (YAML parser limitations, orphan fixtures) noted as non-blocking.profile/build/fixtures/instead of "a frozen snapshot".route_intentreshapes to vendor-and-fallback (Phase 3'smatch_intenthandles exact matches; only the fuzzy-rank fallback is genuinely new code).describe("recipe:new-app-tdd-ci")is no longer hypothetical; cites the real recipe + thetask_index.jsonrecipes category.describereuses vs which path is new (therecipe:ID lookup).phase4-status.md; fold the stage roll-up intophase4-evidence.md. Rename.txt→.mdfor parity.What did NOT change
Scope, exit criterion (canonical-query round-trip from a fresh
uvx --from git+...@v0.1.0install), GitHub-Release-over-PyPI distribution decision, and the 5-track layout (A / B / C / D / E) all stand.Test plan
phase3-evidence.md,profile/build/fixtures/,recipe.schema.json, the 4 shipped recipes) verified to exist onmain