refactor(e2e): demand-load phase routing

e2e/README.md

@@ -40,6 +40,13 @@ graph TD
 | Publish | `/publish` | Push branch, create draft PR | `06-pr-description.md` |
 | Respond | `/respond` | Address reviewer comments | `07-review-responses.md` |
 
+Each phase command invokes `skills/dispatch.md` with the requested phase. The
+dispatcher resolves any project override, loads only that phase, and passes
+along the command context. After the phase reports its result,
+`skills/completion.md` supplies the shared next-step guidance without loading
+the full controller. The controller remains the entry point for workflow
+discovery and ambiguous requests.
+
 ## Typical Flow
 
 ```text
@@ -143,7 +150,9 @@ e2e/
 ├── guidelines.md               # Behavioral rules and guardrails
 ├── README.md                   # This file
 ├── skills/
-│   ├── controller.md           # Phase dispatcher and transitions
+│   ├── controller.md           # Discovery and ambiguous-input router
+│   ├── dispatch.md             # Explicit-phase dispatcher
+│   ├── completion.md           # Shared next-step guidance
 │   ├── ingest.md               # Fetch story, explore e2e infrastructure
 │   ├── plan.md                 # Map ACs to test scenarios
 │   ├── revise.md               # Incorporate plan feedback

e2e/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: e2e
-version: 0.6.1
+version: 0.7.0
 description: >-
   Story-to-e2e-test workflow that takes a Jira [QE] Story, discovers the
   project's e2e testing infrastructure, plans test scenarios, writes e2e

e2e/commands/code.md

@@ -4,8 +4,8 @@ description: "Write e2e test code following discovered patterns, committing incr
 ---
 # /code
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=code`.
 
-Dispatch the **code** phase. Context:
+Context:
 
 $ARGUMENTS

e2e/commands/ingest.md

@@ -4,8 +4,8 @@ description: "Fetch [QE] story, verify dependencies, explore e2e infrastructure,
 ---
 # /ingest
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=ingest`.
 
-Dispatch the **ingest** phase. Context:
+Context:
 
 $ARGUMENTS

e2e/commands/plan.md

@@ -4,8 +4,8 @@ description: "Map acceptance criteria to e2e test scenarios, select reference su
 ---
 # /plan
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=plan`.
 
-Dispatch the **plan** phase. Context:
+Context:
 
 $ARGUMENTS

e2e/commands/publish.md

@@ -4,8 +4,8 @@ description: "Push feature branch and create draft PR for e2e tests"
 ---
 # /publish
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=publish`.
 
-Dispatch the **publish** phase. Context:
+Context:
 
 $ARGUMENTS

e2e/commands/respond.md

@@ -4,8 +4,8 @@ description: "Fetch and address PR reviewer comments on e2e test code"
 ---
 # /respond
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=respond`.
 
-Dispatch the **respond** phase. Context:
+Context:
 
 $ARGUMENTS

e2e/commands/revise.md

@@ -4,8 +4,8 @@ description: "Incorporate user feedback into the e2e test plan"
 ---
 # /revise
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=revise`.
 
-Dispatch the **revise** phase. Context:
+Context:
 
 $ARGUMENTS

e2e/commands/validate.md

@@ -4,8 +4,8 @@ description: "Run e2e tests, check for anti-patterns, verify scenario coverage,
 ---
 # /validate
 
-Read `../skills/controller.md` and follow it.
+Read `../skills/dispatch.md` and follow it with `PHASE=validate`.
 
-Dispatch the **validate** phase. Context:
+Context:
 
 $ARGUMENTS

e2e/skills/code.md

@@ -516,4 +516,4 @@ Report your results:
 - Any discoveries (especially feature defects)
 - Overall implementation status
 
-Then **re-read the controller** (`controller.md`) for next-step guidance.
+Then return to the invoking workflow router for completion guidance.

e2e/skills/completion.md

@@ -0,0 +1,36 @@
+---
+name: completion
+description: Recommend next steps after one attended e2e phase.
+---
+
+# E2E Phase Completion
+
+After the completed `PHASE` reports its results, recommend the best next step
+for the actual outcome, mention relevant alternatives briefly, and stop for the
+user.
+
+- **ingest:** Recommend `/plan` unless the story context, [DEV] dependencies,
+  or test infrastructure has blocking gaps. Recommend clarification or waiting
+  for dependencies when planning cannot proceed safely.
+- **plan:** Recommend `/revise` for user-requested changes, or `/code` when the
+  user has already reviewed and accepted the plan.
+- **revise:** Recommend `/code` when the user is satisfied, or another
+  `/revise` round when further changes remain.
+- **code:** Recommend `/validate`. If implementation exposed a plan gap, note
+  the inline plan update or offer `/plan` when user review is needed. For a
+  feature defect, report it without recommending an out-of-scope product-code
+  fix. For missing test infrastructure, present the documented deviation
+  options for user choice.
+- **validate:** Recommend `/publish` only when validation passed. When failures
+  or anti-patterns remain, recommend fixing them and rerunning `/validate`.
+  Add missing scenarios when an acceptance-criteria gap is fixable; escalate
+  ambiguous or non-e2e-testable criteria to the user.
+- **publish:** Recommend `/respond` when review comments arrive; otherwise the
+  workflow is complete for now.
+- **respond:** Recommend `/validate` after code changes, another `/respond`
+  round while comments remain, or note completion when the PR is approved and
+  no work remains.
+
+The user may start at `/code` with an existing plan or partial test
+implementation, and may skip `/publish` and `/respond` when working locally.
+Never auto-advance between attended phases.

e2e/skills/controller.md

@@ -1,16 +1,19 @@
 ---
 name: controller
-description: Top-level workflow controller that manages phase transitions for e2e test implementation.
+description: Discover and route ambiguous e2e test implementation requests.
 ---
 
 # E2E Test Workflow Controller
 
-You are the workflow controller. Your job is to manage the e2e test
-implementation workflow by executing phases and handling transitions
-between them.
+Use this controller for workflow discovery and ambiguous-input routing. Once a
+phase is selected, delegate its execution and completion guidance to the
+lightweight dispatcher.
 
 ## Phases
 
+Keep this phase list synchronized with the command wrappers, phase files,
+dispatcher filename mapping, and per-phase completion guidance.
+
 1. **Ingest** (`/ingest`) — `ingest.md`
    Fetch the [QE] Jira story, verify [DEV] dependencies are merged, explore
    the project's e2e test infrastructure, and build a test-execution profile.
@@ -59,95 +62,36 @@ the source repo:
 
 ## How to Execute a Phase
 
-1. **Announce** the phase to the user: *"Starting /plan."*
-2. **Locate** the skill file — read and follow
-   `../../_shared/recipes/phase-override-resolution.md` with
-   WORKFLOW=`e2e`, PHASE_FILE=`{phase}.md`.
-3. **Read** the resolved skill file
-4. **Execute** the skill's steps — the user should see your progress
-5. When the skill is done, it will tell you to report findings and
-   re-read this controller. Do that — then use "Recommending Next Steps"
-   below to offer options.
-6. Present the skill's results and your recommendations to the user
-7. **Stop and wait** for the user to tell you what to do next.
-
-## Recommending Next Steps
-
-After each phase completes, present the user with **options** — not just one
-next step. Use the typical flow as a baseline, but adapt to what actually
-happened.
-
-### Typical Flow
-
-```text
-ingest → plan → [revise loop] → code → validate → publish → [respond loop]
-```
-
-### What to Recommend
-
-**Continuing forward:**
-
-- `/ingest` completed → recommend `/plan` (almost always the right next step)
-- `/plan` completed → recommend `/revise` for user review of the plan, or `/code` if the user has already reviewed inline
-- `/revise` completed (user satisfied) → recommend `/code`, or another `/revise` round
-- `/code` completed → recommend `/validate` (always — never skip validation)
-- `/validate` completed (all passing) → recommend `/publish`
-- `/validate` completed (failures remain) → recommend fixing issues, then re-running `/validate`
-- `/publish` completed → recommend `/respond` when review comments arrive
-- `/respond` completed → recommend another `/respond` round, or note that the workflow is done when the PR is approved and merged
-
-**Looping back:**
-
-- `/plan` reveals story gaps or contradictions → suggest the user clarify with the story author or update the story
-- `/code` reveals plan gaps → the plan is updated inline during implementation; offer `/validate` when implementation is complete
-- `/code` discovers a feature defect (test reveals a bug in the [DEV] implementation) → note it in the implementation report; the test may need to xfail or skip. Do NOT recommend fixing the feature — that is out of scope
-- `/code` discovers a missing test infrastructure method (plan referenced a method that doesn't exist) → see deviation rules in `code.md`; a local helper may suffice, or the user decides whether to adjust the plan or add test infrastructure support outside this workflow
-- `/validate` reveals test failures → offer to diagnose and fix, then re-run `/validate`
-- `/validate` reveals anti-patterns → fix them during validation, then re-run the affected checks
-- `/validate` reveals unsatisfied acceptance criteria → if fixable (missing test scenarios), write them during validation; if the criterion is ambiguous or not e2e-testable, escalate to the user
-- `/respond` requires code changes → apply changes, re-run `/validate`, then continue responding
-
-**Skipping:**
-
-- If the user already has a plan or partial test implementation, they may start at `/code`
-- If the user wants to skip PR creation (e.g., working locally), `/publish` and `/respond` may be skipped
-
-### How to Present Options
-
-Lead with your top recommendation, then list alternatives briefly:
-
-```text
-Recommended next step: /code — begin writing e2e test code following the
-approved plan.
-
-Other options:
-- /revise — if you want to adjust the plan first
-- /validate — if you've already written test code and want to check it
-```
+Set `PHASE` to the selected phase, then read `dispatch.md` and follow it. The
+dispatcher owns phase announcement, override resolution, execution, and
+completion routing for both built-in phases and project overrides.
 
 ## Starting the Workflow
 
-Before dispatching any phase, check if the project has its own `AGENTS.md`
-or `CLAUDE.md`. If so, read it — it may contain project-specific conventions,
-testing standards, or other guidance that affects how the workflow operates.
-
 When the user provides a Jira issue key or URL:
-1. Execute the **ingest** phase
-2. After ingestion, present results and wait
+1. Set `PHASE=ingest`.
+2. Read `dispatch.md` and follow it.
+
+If the user invokes a specific command (e.g., `/code`), set `PHASE` to that
+command's phase, then read `dispatch.md` and follow it. Do not force the user
+through earlier phases.
 
-If the user invokes a specific command (e.g., `/code`), execute that phase
-directly — don't force them through earlier phases.
+For any other input, summarize the available phases, ask the user for a Jira
+issue key or URL or a specific phase command, and stop without reading
+`dispatch.md`.
 
 ## Error Handling
 
-If any phase fails (Jira MCP errors, test failures, git errors):
+If a phase cannot complete because of an operational error (for example, a
+Jira MCP or git error):
 
 1. **Stop immediately.** Do not advance to the next phase.
 2. **Report the error** to the user with the specific error message.
 3. **Offer options:** retry the failed step, skip the phase (if optional), or escalate.
 
 Do not fabricate results when a tool call fails. Do not silently continue
-past errors.
+past errors. A completed validation report with a failing verdict is a valid
+phase outcome; route it through `completion.md` for fix-and-rerun guidance.
 
 ## Context Management
 
@@ -164,7 +108,8 @@ subagent spawning.
 ## Rules
 
 - **Never auto-advance.** Always wait for the user between phases.
-- **Recommendations come from this file, not from skills.** Skills report findings; this controller decides what to recommend next.
+- **Recommendations come from `completion.md`.** Phase skills report findings;
+  the completion guide provides the authoritative next-step model.
 - **Jira is read-only.** The `/ingest` phase reads from Jira but never modifies it. No phase in this workflow writes to Jira.
 - **Plan evolves during implementation.** `/code` updates `02-plan.md` as tasks are completed. This is expected, not a sign of plan failure.
 - **Validation is mandatory before publishing.** Never recommend `/publish` unless `/validate` has passed.

e2e/skills/dispatch.md

@@ -0,0 +1,33 @@
+---
+name: dispatch
+description: Resolve and execute one explicitly requested e2e phase.
+---
+
+# E2E Phase Dispatch
+
+E2E phase filenames follow the `{PHASE}.md` convention. If a phase uses a
+different filename, define its mapping here before resolving overrides.
+
+Before dispatching, read the project's `AGENTS.md` or `CLAUDE.md` only if
+neither is already in the session. Then, given `PHASE`, initialize
+`COMPLETION_CONSUMED=false`, announce `Starting /{PHASE}.`, and read and follow
+`../../_shared/recipes/phase-override-resolution.md` with `WORKFLOW=e2e` and
+`PHASE_FILE={PHASE}.md`. Read and execute the resolved phase file, passing
+through the command context unchanged.
+
+The built-in fallback is the phase file beside this dispatcher. Follow the
+phase through its reporting step. Treat any supported phase exit—returning to
+the invoking router, requesting completion guidance, or re-reading the
+controller—as a return to this dispatcher. If the returned
+`COMPLETION_HANDOFF` executes `completion.md`, set `COMPLETION_CONSUMED=true`
+before executing that handoff. When the phase returns, read the guide once and
+follow its guidance for `PHASE` only when `COMPLETION_CONSUMED=false`; the
+dispatcher is the only component that reads the completion guide.
+
+If the recipe rejects a project override, continue with its built-in fallback.
+If that fallback cannot be resolved, an operational error prevents the phase
+from completing, or the phase has no completion behavior compatible with this
+workflow, report the failure and stop without reading `completion.md`. A
+completed phase report with a failing verdict, including `validate.md` reporting
+`FAIL`, is a valid outcome: read `completion.md` so it can provide fix-and-rerun
+guidance.

e2e/skills/ingest.md

@@ -744,4 +744,4 @@ Report your findings:
 - Story test plan status (test cases found / expected zero / anomalous zero / no testplan)
 - Assessment of readiness for `/plan`
 
-Then **re-read the controller** (`controller.md`) for next-step guidance.
+Then return to the invoking workflow router for completion guidance.

e2e/skills/plan.md

@@ -349,4 +349,4 @@ Report your results:
 - Note any risks or open questions
 - Assessment of plan completeness
 
-Then **re-read the controller** (`controller.md`) for next-step guidance.
+Then return to the invoking workflow router for completion guidance.

e2e/skills/publish.md

@@ -230,7 +230,6 @@ Present:
 - PR URL (the full `https://github.com/...` link, not just `owner/repo#number`)
 - Branch name and base
 - Number of commits included
-- Next steps (share with reviewers, wait for comments, then use `/respond`)
 
 ## Output
 
@@ -244,6 +243,5 @@ Present:
 Report your results:
 - PR URL and branch name
 - Commits included
-- Suggested next steps
 
-Then **re-read the controller** (`controller.md`) for next-step guidance.
+Then return to the invoking workflow router for completion guidance.

e2e/skills/respond.md

@@ -231,4 +231,4 @@ Report your results:
 - Re-validation recommendation
 - Outstanding items
 
-Then **re-read the controller** (`controller.md`) for next-step guidance.
+Then return to the invoking workflow router for completion guidance.

e2e/skills/revise.md

@@ -134,4 +134,4 @@ Report your results:
 - Any consistency updates made as a side effect
 - Assessment of plan readiness for `/code`
 
-Then **re-read the controller** (`controller.md`) for next-step guidance.
+Then return to the invoking workflow router for completion guidance.

e2e/skills/validate.md

@@ -394,4 +394,4 @@ Report your results:
 - Regression status
 - Overall verdict
 
-Then **re-read the controller** (`controller.md`) for next-step guidance.
+Then return to the invoking workflow router for completion guidance.