Conversation
Phase 3 Track A — recipe schema and directory scaffold. Foundation for Phase 3 Tracks B/C/D (B authors recipes; C TDDs the handshake test; D wires Make + CI). Per phase3-plan.md §2. Four parts in one coherent PR: 1. profile/recipe.schema.json (new) — JSON Schema 2020-12 for the YAML frontmatter at the top of every docs/recipes/<slug>.md. Required: id (typedID, recipe:* prefix), title (≤70 char), intent (matches a task_index entry), touches (≥1 typedID), verified_on (ISO date), ci_verifiable (bool). Optional: prereqs, manual_checklist_url, tier (tier-1|2|3), notes. allOf rule: ci_verifiable=false REQUIRES manual_checklist_url. typedID grammar duplicated in $defs so the schema validates standalone — same regex as tools.schema.json + task_index.schema.json. 2. docs/recipes/README.md (new) — describes the recipe contract, frontmatter table, the seven priority recipes (gating/buffer/ post-exit), the CI gate that Track D will implement, authoring guide, and what the directory is NOT. ~95 lines of prose. 3. profile/task_index.json — new top-level "recipes" category with one row per priority recipe mapping intent → recipe:<slug> typed ID + see_also pointers to the tools / cmds / modules each recipe touches. 7 rows. Total intent count 59 → 66. 4. (audit-only) A1 findings captured in this PR body — no existing recipe content anywhere in the org; only references in planning prose, and one adjacent surface (tools.json workflow block: tdd_inner_loop + minimal_application_recipe) that recipes do not replace. Verification, all green: - recipe.schema.json valid JSON Schema 2020-12; synthetic positive + two negative fixtures (missing manual_checklist_url when ci_verifiable=false; malformed typedID) both rejected as expected. - task_index.json validates against task_index.schema.json (now 6 categories, 66 intents). - profile/tools.json + task_index.json schema-strict via validate-catalog.py: OK. - make catalog byte-idempotent. - pytest profile/build/: 26/26. - make check-docs-prose green (docs/recipes/README.md is .md). - make phase0-smoke: PASS. Phase 3 launch state: - Track A this PR — foundation for everything else. - Tracks B/C/D ready to start in parallel once this lands. - recipes 1–4 are gating for Phase-3 exit (Track B); #5 is buffer; #6 (tier-2) + #7 (tier-3) are post-exit follow-ups.
3 tasks
rafael5
added a commit
that referenced
this pull request
May 11, 2026
…25) 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
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
Phase 3 Track A — recipe schema + directory scaffold. Foundation for Tracks B/C/D per `phase3-plan.md` §2.
A1 audit (captured here so future readers don't have to re-grep)
What lands
Verification (all green)
Phase 3 launch state after this lands
Tracks B (recipes 1–4), C (TDD handshake test), D (Make + CI) can all run in parallel — different files, no overlap per phase3-plan.md §1. Recipes 5/6/7 are post-exit follow-ups.
Test plan