Skip to content

docs: update phase4-plan.md to reflect Phase 3 closure + discoveries#25

Merged
rafael5 merged 1 commit into
mainfrom
phase4-plan-update
May 11, 2026
Merged

docs: update phase4-plan.md to reflect Phase 3 closure + discoveries#25
rafael5 merged 1 commit into
mainfrom
phase4-plan-update

Conversation

@rafael5
Copy link
Copy Markdown
Contributor

@rafael5 rafael5 commented May 11, 2026

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 into docs/phase4-plan.md.

What changed

  • §0 dependency table — Phase 3 row flipped 🟡 In flight → ✅ CLOSED. Captures the importable helper list (match_intent, parse_typed_id, resolve_module_manifest_url, find_module_entry, entry_has_signature_and_example, fetch). Verification snippet rewritten to invoke make handshake / make recipes-check (now real Make targets).
  • §0 narrative — drop "Phase 4 may start at Phase 3 C2"; all three upstream phases are closed and 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 5-row table of the concrete artifacts Track B / Track E pull from .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.
  • §3 B1 — fixtures point at Phase 3's bundled set under profile/build/fixtures/ instead of "a frozen snapshot".
  • §3 B2route_intent reshapes to vendor-and-fallback (Phase 3's match_intent handles exact matches; only the fuzzy-rank fallback is genuinely new code).
  • §3 B3describe("recipe:new-app-tdd-ci") is no longer hypothetical; cites the real recipe + the task_index.json recipes category.
  • §3 B4 — spell out which helpers describe reuses vs which path is new (the recipe: ID lookup).
  • §6 Track E — collapses to one evidence doc following Phase 1 + Phase 3 convention. Drop phase4-status.md; fold the stage roll-up into phase4-evidence.md. Rename .txt.md for parity.
  • §7 Stage Matrix — B1 simplified; E2 (status doc) removed; E1 verification rewritten; E3 → E2.
  • §9 Risk Notes — replace "Phase 3 dependency timing" (historical) with "Vendored Phase 3 helper drift" — the new ongoing risk + TDD-based mitigation.
  • §10 Gantt — phase 3 lane shows ✅ CLOSED 2026-05-11.
  • §11 Done definition — 10 → 9 criteria (status doc removed); evidence file renamed; "every §11 done-criterion cited green" added.

What did NOT change

Scope, exit criterion (canonical-query round-trip from a fresh uvx --from git+...@v0.1.0 install), GitHub-Release-over-PyPI distribution decision, and the 5-track layout (A / B / C / D / E) all stand.

Test plan

  • Markdown-only change; no CI surface touched
  • Internal cross-refs (phase3-evidence.md, profile/build/fixtures/, recipe.schema.json, the 4 shipped recipes) verified to exist on main
  • CI green

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).
@rafael5 rafael5 merged commit 5a9efe5 into main May 11, 2026
2 checks passed
@rafael5 rafael5 deleted the phase4-plan-update branch May 11, 2026 10:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant