paseo-epic: lock requirements early and gate on them

Adds a pre-start preferences step (onboards users with no
orchestration-preferences.json), a capture-intent step that runs
even under --autopilot, an immutable Requirements block in the plan
that includes acceptance criteria, and a final lightweight check
that audits every requirement before deliver. Drops --no-grill.

skills/paseo-epic/SKILL.md

@@ -2,13 +2,15 @@
 name: paseo-epic
 description: Heavy-ceremony orchestration for big work — research, planning, adversarial review, phased implementation, audit, delivery. Use when the user says "epic", "long task", "build this end to end", or wants a feature that runs all night.
 user-invocable: true
-argument-hint: "[--autopilot] [--worktree] [--no-grill] <task>"
+argument-hint: "[--autopilot] [--worktree] <task>"
 ---
 
 # Paseo Epic
 
 Heavy-ceremony orchestrator. Runs research → plan → implement → deliver as one resumable flow. The plan file at `~/.paseo/plans/<slug>.md` is the source of truth and survives compaction.
 
+This usually runs for hours, often overnight. By the time agents are working, you cannot re-litigate intent with the user. Capture the requirements they have already given you in conversation — behaviors, the "why," UX rules, constraints — and write them into the plan as immutable before any planning agent spins up. Everything downstream (planner, adversarial reviewer, implementers) optimizes around those requirements; it does not relitigate them.
+
 **User's request:** $ARGUMENTS
 
 ## Prerequisites
@@ -22,12 +24,13 @@ The role and phase-type vocabulary lives in the roles reference shipped with thi
 - **Default**: conversational. Grills, gates between phases, ask before deliver.
 - `--autopilot`: no grills, no gates, run through deliver. For all-night work.
 - `--worktree`: isolate the work in a new worktree.
-- `--no-grill`: skip clarifying questions; keep gates.
 
 ## Hard rules
 
 - **The plan file is the source of truth.** Re-read before every phase.
 - **You are the only writer to the plan file.** Agents don't touch it.
+- **Requirements are immutable.** What the user has stated about behavior, UX, "why it works this way," and acceptance criteria goes into the plan's Requirements block before any planner runs and does not change after. The technical plan (phases, ordering, approach) flexes around them. Planner and reviewer challenge HOW, never WHAT or WHY.
+- **The epic is not done until every Requirement is met.** The plan ends with a lightweight check that audits every bullet in the Requirements block against the delivered code. If anything is unmet, the orchestrator loops back and fixes it before deliver — under `--autopilot` too.
 - **Provider for every agent comes from orchestration preferences** — match the role's category.
 - **Worktrees only via Paseo.** Never run `git worktree add` yourself.
 - **Agents do not commit.** Delivery happens in the deliver phase.
@@ -38,13 +41,31 @@ The role and phase-type vocabulary lives in the roles reference shipped with thi
 ## Flow
 
 ```
-[Worktree] → Research → [Grill] → Plan → Adversarial review → [Confirm] → Implement → Deliver
-                        ^^^^^^^                                ^^^^^^^^^
-                        default mode                           default mode
+Preferences → [Worktree] → Research → Capture intent → [Grill] → Plan → Adversarial review → [Confirm] → Implement → Deliver
+onboard if                            always           ^^^^^^^                               ^^^^^^^^^
+missing                                                default mode                          default mode
 ```
 
 ---
 
+## 0. Preferences (pre-start)
+
+Read `~/.paseo/orchestration-preferences.json`. /epic dispatches across these provider categories:
+
+- `planning` — drafts and reviews the technical plan
+- `research` — surveys the code before planning
+- `impl` — writes code (refactor, implement)
+- `ui` — implements styling/layout passes
+- `audit` — read-only verification, including the final lightweight requirements check
+
+If the file is missing or any of these categories is unset, walk the user through it once. Use `list_providers` and `list_models` to surface candidates, explain each category in one line, and use `AskUserQuestion` to collect a provider per category. Persist their choices straight to `~/.paseo/orchestration-preferences.json`.
+
+Do not proceed past this step until every category /epic will use is set. This applies under `--autopilot` too — autopilot cannot start without known providers.
+
+If the file is complete, say nothing and continue.
+
+---
+
 ## 1. Research yourself
 
 Read the code first. Grep the relevant area, read 2–4 key files, understand the current shape.
@@ -57,13 +78,25 @@ State your own understanding to the user in 2–3 sentences.
 
 Create a worktree via Paseo. Record the returned path and branch — they go into the plan frontmatter.
 
-## 3. Grill (unless `--no-grill` or `--autopilot`)
+## 3. Capture intent (always)
+
+Before any planning agent runs, distill what the user has already told you into a concrete Requirements list. This step runs even under `--autopilot` — it is the floor that grilling extends, not replaces.
+
+Pull from the conversation that led to this skill being invoked: described behaviors, UX rules, the "why this works this way," constraints, what must not change, what the user explicitly accepted or rejected, and the **acceptance criteria** (concrete, testable conditions that say "the work is done"). Write each as a short imperative bullet. Lean inclusive — if the user mentioned it as a behavior, constraint, or success condition, it goes in.
+
+Drop these bullets straight into the plan's `## Requirements (immutable)` block when you write the file in step 6. They become the input every downstream agent reads as fixed, and the bar the final check audits against.
+
+If the user has only given product/UX requirements and no technical direction, that is fine. Capture the product requirements and acceptance criteria as immutable. The technical plan is what the planner gets to design and the reviewer gets to challenge.
+
+## 4. Grill (unless `--autopilot`)
 
 Use `AskUserQuestion`. One at a time, recommended option stated, branches resolved depth-first. Never ask code-answerable questions. Every 3–4 questions, summarize resolved decisions.
 
+Anything the user resolves here becomes a Requirement and gets added to the immutable block.
+
 Stop when branches are resolved or the user says "go".
 
-## 4. Plan with adversarial review
+## 5. Plan with adversarial review
 
 ### Spawn a planner
 
@@ -72,21 +105,22 @@ Persistent — keep iterating, do not archive after the first response. Provider
 Prompt it to:
 
 - Read the roles reference for vocabulary.
-- Take the objective and resolved decisions from grill as input.
+- Take the Objective and the Requirements (immutable) block as fixed input. The technical plan optimizes around them; it does not redesign them. If a requirement looks wrong, flag it in chat — do not silently work around it.
 - Think refactor-first: if existing code doesn't accommodate the change, plan the reshape before the feature. Phases like "wire up", "glue", "integrate" usually mean an upstream refactor was missed.
 - Reply terse, one line per phase, in chat — not to disk.
 
 ### Challenge it
 
-Send follow-ups. Push on edge cases, alternative orderings, smallest shippable slice, bolt-on phases that should be a refactor instead. Iterate until the plan is sharp.
+Send follow-ups. Push on edge cases, alternative orderings, smallest shippable slice, bolt-on phases that should be a refactor instead. Keep the challenge on HOW — phases, ordering, technical approach. The Requirements block is not on the table here. Iterate until the plan is sharp.
 
 ### Spawn a plan-reviewer
 
 Provider from the `planning` preference. Prompt it to:
 
 - Read the roles reference.
-- Read the planner's draft.
-- Challenge it: bolt-ons, missing edge cases, over-engineering, wrong ordering, hidden dependencies. Push for alternatives. Force tradeoffs.
+- Read the planner's draft and the Requirements block.
+- Challenge the technical plan: bolt-ons, missing edge cases, over-engineering, wrong ordering, hidden dependencies. Push for alternatives. Force tradeoffs.
+- Treat the Requirements block as fixed. If a requirement seems off, surface it as a flag for the orchestrator — do not propose an alternative plan that quietly drops or weakens it.
 
 ### Surface tradeoffs to the user
 
@@ -100,7 +134,7 @@ Use `AskUserQuestion`. Iterate the planner if the user picks differently.
 
 Archive the planner and plan-reviewer once the plan is locked.
 
-## 5. Write the plan
+## 6. Write the plan
 
 Persist to `~/.paseo/plans/<slug>.md`:
 
@@ -121,6 +155,17 @@ updated: <ISO>
 
 <one paragraph>
 
+## Requirements (immutable)
+
+What the user has stated. Behaviors, UX rules, the "why," constraints,
+and acceptance criteria (testable conditions for "done").
+Captured in step 3 (and extended by the grill in step 4).
+This block does not change during planning, review, or implementation.
+The final check before deliver audits every bullet here.
+
+- <bullet>
+- <bullet>
+
 ## Notes
 
 - <ISO> orchestrator: <freeform>
@@ -130,16 +175,16 @@ updated: <ISO>
 - [ ] **Phase 1** · <type> · <short name>
       Acceptance: <one line>
 
-- [ ] **Phase N** · gate · user smoke test
-
-- [ ] **Phase N+1** · deliver · <commit | PR + merge | cherry-pick>
+- [ ] **Phase N** · verify · requirements + acceptance audit
+- [ ] **Phase N+1** · gate · user smoke test
+- [ ] **Phase N+2** · deliver · <commit | PR + merge | cherry-pick>
 ```
 
 Phase types: `refactor`, `implement`, `verify`, `gate`, `deliver`. Verify variants written inline: `verify · unslop`, `verify · qa`, `verify · spec`, `verify · review`. See the roles reference.
 
 Status markers: `[ ]` not started, `[~]` in progress, `[x]` done, `[!]` blocked.
 
-## 6. Confirm (default mode)
+## 7. Confirm (default mode)
 
 Show the phase list (not the file contents — they'll read it). 2–3 sentences. Wait.
 
@@ -147,7 +192,7 @@ If `--autopilot`: skip.
 
 ---
 
-## 7. Implement
+## 8. Implement
 
 Loop: find next undone phase → mark `[~]` → dispatch by type → wait → verify → mark `[x]` → repeat.
 
@@ -160,7 +205,7 @@ Stop when: a `gate` phase is reached, all phases `[x]`, or a phase is `[!]` bloc
 Spawn a refactorer. Provider from `impl` (or `ui` for styling-only reshapes). cwd = the worktree path if set. Tell it to:
 
 - Read the roles reference and load the skills it names.
-- Read the plan file. Scope is Phase N; acceptance is pinned there.
+- Read the plan file, including the Requirements (immutable) block. Scope is Phase N; acceptance is pinned there.
 - Reshape, not feature: behavior identical before and after. Existing tests stay green. Add a parity test if missing.
 - When done: typecheck pass + relevant tests green. Do not commit. Do not update the plan.
 
@@ -169,7 +214,7 @@ Spawn a refactorer. Provider from `impl` (or `ui` for styling-only reshapes). cw
 Spawn an impl agent. Provider from `impl` (or `ui` for styling-only). cwd = the worktree path if set. Tell it to:
 
 - Read the roles reference and load the skills it names.
-- Read the plan file. Scope is Phase N.
+- Read the plan file, including the Requirements (immutable) block. Scope is Phase N. Requirements are constraints, not suggestions — implement to them.
 - Read any plan-relevant repo docs by path.
 - TDD: failing test first, then make it pass.
 - If the existing shape doesn't accommodate the change, push back instead of bolting on — a refactor phase should have come first.
@@ -189,7 +234,7 @@ No agent. Yield to the user.
 
 #### deliver
 
-Inline — see Section 8.
+Inline — see Section 9.
 
 ### Verifying agent output
 
@@ -216,7 +261,7 @@ The plan file lets a fresh orchestrator pick up if the user kills you and reinvo
 
 ---
 
-## 8. Deliver
+## 9. Deliver
 
 Read frontmatter to choose mode:
 
@@ -276,6 +321,8 @@ Mid-deliver resumption:
 
 ## Failure modes
 
+- Skipping capture-intent because grilling was skipped. The Requirements block is the floor; grilling extends it.
+- Letting adversarial review erode requirements the user already locked. Reviewer sharpens the technical plan; it does not relitigate intent.
 - Treating phases as a checklist to grind through. They're gates. Verify before advancing.
 - Forgetting to set the agent's cwd to the worktree path in worktree mode.
 - Re-explaining the plan to the user. They wrote it with you. Reference phases by number.