@ritualai/cli 0.11.0 → 0.24.0

package/skills/gemini/ritual/references/build-flow.md

@@ -51,7 +51,7 @@ Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must c
 
 ### CLI and async guardrails
 
-Follow `references/cli-output-contract.md` for terminal output, dense-list formatting, user-facing vocabulary, and the no-internal-step-label rule. Follow `references/async-polling.md` for every long-running server operation.
+Follow `references/cli-output-contract.md` for terminal output, dense-list formatting, user-facing vocabulary, and the no-internal-step-label rule. Follow `references/async-polling.md` for every long-running server operation. Whenever the user asks to **change or add** something via free text (refine sub-problems, reframe scope, add an anti-goal), follow `references/change-preflight.md` — restate the request and show the exact instruction before calling the mutating tool, and wait for confirmation. It is a hard pause even in auto-mode.
 
 #### Step 0 — Auto-mode heads-up (informational, NOT a pause)
 
@@ -107,6 +107,17 @@ Persist `auditMode` to `Exploration.metadata.auditMode` at `create_exploration`
 
 #### Step 1 — Pick a workspace
 
+<!-- skill-options:no-gate-change: connection-freshness ping check is a non-interactive warn, adds no user-facing gate or option -->
+**Connection freshness check (one-time, warn-only) — fire on your FIRST MCP call this session.** Alongside the first `list_workspaces` call below, call `mcp__ritual__ping` **once** and inspect the returned identity:
+
+- If the response is **missing `gitSha` or `toolContractHash`**, or reports **`version: "1.0.0"`** (the legacy hardcoded value), the user is connected to an **outdated / legacy Ritual MCP** — emit exactly ONE line, then continue normally (warn-only, never block):
+
+  `⚠ Connected to an outdated Ritual MCP (no build identity) — some build features may be unavailable. Run \`ritual doctor\` to check, then \`ritual init\` if it flags a refresh.`
+
+- Otherwise (identity present and not legacy), say nothing and proceed.
+
+Do this **at most once per session** — don't re-ping on later steps.
+
 Resolution order:
 
 1. **Project-bound workspace (preferred).** Check for a `.ritual/config.json` at the project root (you can use the Read tool — the file is a small JSON with `workspaceId` + `workspaceName`). If it exists, that's the workspace this repo is bound to. Use it without pausing.
@@ -278,7 +289,7 @@ Steps:
    - Use the state badge to decide which step to jump to (see "Suggested next action" column above).
    - Skip ahead in this skill — don't re-run Steps 2-9 for an exploration that already has them done.
    - For `ready` or `in_flight` states, jump directly to Step 10 (build brief generation).
-   - For `awaiting_admin`, jump to Step 9 (review + accept). Only an admin can move it forward; collaborators see the recs and proceed only if they're explicitly authorized to implement ahead.
+   - For `awaiting_admin`, jump to Step 9 (review + `proceed`). Only an admin can move it forward; collaborators see the recs and proceed only if they're explicitly authorized to implement ahead.
    - For `implemented_ahead`, surface the situation to the user and ask what to do — typically the admin reconciles by either approving the recs post-hoc (no code change needed) or updating the recs to match shipped reality.
    - **For `done` or `in_flight` — branch-existence sanity check FIRST.** *(CLI Tenet #9 — sanity-check the world before trusting the database.)* The state badge is computed from `ImplementationRecord` rows in the KG. If the KG was seeded from synthetic/bootstrap data (a common state in early pilot deployments), the record can assert a PR/branch that doesn't exist in this repo. Before treating the exploration as ✓ shipped, verify:
 
@@ -885,6 +896,55 @@ If the user says "skip" / "none" / "later", proceed silently to Step 4. Do NOT p
 
 The user can always come back later with `/ritual context-pulse <exploration>` to see the current Reference Grounding score, OR drag refs in mid-flow (e.g. at Step 8 if the agentic run surfaces a question that a PRD would have answered).
 
+#### Step 3.9 — Classify the work item + pick the lead persona
+
+Before generating sub-problems, settle **what job this is** and **whose lens leads it** — both shape
+everything downstream, so they come first. **You** classify the job (you have the repo open — you're the
+best-informed classifier, and doing it here saves a backend LLM call); the server returns the lenses.
+
+1. **Classify the request** into ONE development work-item slug, using the user's raw ask + your code
+   recon:
+
+   ```text
+   understand-codebase-area · design-technical-approach · create-implementation-plan ·
+   build-frontend-feature · build-backend-service · integrate-api · create-docs-site ·
+   refactor-code · debug-production-issue · improve-performance · add-tests · prepare-release
+   ```
+
+   (Use `build-feature` only when the ask is a generic build that none of the specific jobs fit.) Pick the
+   single best match — e.g. "add OAuth to the dashboard" → `build-backend-service`; "the checkout page is
+   slow" → `improve-performance`; "clean up the payments module" → `refactor-code`.
+
+2. **Call `mcp__ritual__work_item`** with that `jtbd` (and `entry_use_case` if known). It returns
+   `{ workItemLabel, deliverableTemplate, recommended, options: [{ persona, label, whenToChoose }] }` —
+   deterministic, no LLM, already biased by the user's `ritual init` persona.
+
+3. **Present the work item + lens options** as a `(label + description)` bottom-drawer choice picker
+   (same shape as discovery picks, per `references/cli-output-contract.md`), recommended lens first and
+   marked:
+
+   ```text
+   This looks like: Build backend service / API → Service Build Brief
+   Who's leading it? (recommended: Backend Developer)
+
+   1. Backend Developer — Best when you care about API contracts, data, transactions, scaling.  ← recommended
+   2. Developer — Best when you care about feasibility, implementation correctness, shippability.
+   3. Eng Lead — Best when you care about technical approach, risk, sequencing, review.
+
+   Reply `use` to lead as Backend Developer, a number to switch, or name a lens.
+   ```
+
+4. **Default = the recommended lens.** An ambiguous reply (`use`/`ok`/`go`) accepts it. If the user says
+   the *work item* is wrong ("no, this is a refactor"), re-classify and call `work_item` again. If they
+   switch the *lens*, that's a change → run the change pre-flight (`references/change-preflight.md`) to
+   confirm before adopting it.
+
+5. **Remember the chosen `persona` slug** — you pass it through to `create_exploration` as `lead_persona`
+   at Step 6. (It also carries into the generation prompts once persona-aware generation ships; for now
+   it's persisted + surfaced.)
+
+Keep this light — one drawer, recommended pre-selected; most users accept. Don't belabour it.
+
 #### Step 4 — Generate sub-problems
 
 ##### 4.1 First draft
@@ -938,6 +998,8 @@ Only the title line gets the number. Put a blank line between candidates. Do not
 
 The user may, at the Step 5 problem-statement gate, say something like "rethink the sub-problems" or "the framing is off — show me other angles." When that happens, call `mcp__ritual__refine_considerations` and re-render the sub-problem set + a fresh problem statement. In the default flow this path is unreachable; it exists for the explicit "rethink scope" escape hatch.
 
+**Pre-flight (mandatory):** before calling `refine_considerations`, run the change pre-flight in `references/change-preflight.md` — restate the change in the user's terms, show the exact `change_prompt` you're about to send, and wait for `yes`. This is a hard pause (even in auto-mode) and fires on every such request, including one-word ones. Do not call the tool until the user confirms.
+
 Call `mcp__ritual__refine_considerations` with:
 - `workspace_id`, `raw_input`, `sources` — unchanged from the generate call. Critical: pass the SAME `sources` array each iteration so the KG-injected priorContext stays consistent.
 - `template_id` — same rule as Step 4: omit unless the user explicitly overrode it. If you passed `template_id` to the original `generate_considerations` call, pass the same value here for symmetry; otherwise leave it off and let server-side resolution stay consistent across iterations.
@@ -1006,6 +1068,8 @@ Rules:
 
 If the user asks for a refinement:
 
+**Pre-flight (mandatory):** before calling `refine_problem_statement`, run the change pre-flight in `references/change-preflight.md` — restate the change in the user's terms, show the exact `change_prompt` you're about to send, and wait for `yes`. This is a hard pause (even in auto-mode) and fires on every refinement request, including a one-word `tighten`/`broaden`. Do not call the tool until the user confirms.
+
 Call `mcp__ritual__refine_problem_statement` with:
 - `workspace_id`, `raw_input`, `considerations`, `sources` — unchanged. (Same `sources` as the original generate call — keeps the KG anchor stable.)
 - `template_id` — same rule as Step 4 / Step 5.1: omit unless the user explicitly overrode; if you passed it to the original `generate_problem_statement` call, pass the same value here for symmetry.
@@ -1026,7 +1090,7 @@ When the user locks the frame, store the final text as `problem_statement` for S
 
 Generate a short name (≤60 chars) from the scope — typically the noun phrase, not the full HMW. E.g. "Reduce T2 customer churn in Q3" → name `T2 churn reduction (Q3)`.
 
-Do not add another confirmation if the user just accepted the problem frame. Create the exploration immediately after the user replies `use`/`proceed`. If a name is ambiguous, **choose the shortest clear noun phrase and continue without pausing** — the name is editable later and shouldn't become a decision gate. Do NOT rely on "proceed on Enter" or empty input in agent chat (see `references/cli-output-contract.md` § Surface-aware continuation prompts).
+Create the exploration immediately once the frame is locked — the work item + lead persona were already settled at Step 3.9, so do not add a *further* confirmation here. If a name is ambiguous, **choose the shortest clear noun phrase and continue without pausing** — the name is editable later and shouldn't become a decision gate. Do NOT rely on "proceed on Enter" or empty input in agent chat (see `references/cli-output-contract.md` § Surface-aware continuation prompts).
 
 User-visible before the call, if needed:
 
@@ -1040,6 +1104,8 @@ Call `mcp__ritual__create_exploration` with:
 - `problem_statement` (the scope from Step 5)
 - `template_id` — **OPTIONAL.** Per Step 2, omit by default. The server resolves from `explicit dto.templateId → workspace.defaultTemplateId → user.persona → first SYSTEM template`, then forks the resolved template into a per-exploration Template row atomically inside this same `create_exploration` request. Pass `template_id` ONLY when the user explicitly overrides on the CLI (`/ritual build --template-id <id>`). If you passed `template_id` to Step 4's `generate_considerations`, pass the same value here so the LLM prompt context the considerations were generated under matches the exploration's stamped template. Do NOT read `.ritual/config.json` or invent a `template_id` from persona — the server does the resolution.
 - `agentic: false` — **do NOT** pass `agentic: true`. We want explicit per-step control so the user gets to pick discovery questions in Step 7. Auto-agentic skips that.
+- `jtbd` — **REQUIRED for `/ritual build`.** The work-item slug you classified at **Step 3.9** (e.g. `'build-backend-service'`, `'refactor-code'`, or `'build-feature'` for a generic build). Tags the exploration's job-to-be-done so the workflow surfaces the build-brief → code-plan → implement → PR deliverable phase across every surface (the Spark panel, etc.), not the generic produce-deliverable flow. Omit only if this is a non-build exploration (defaults to `produce-deliverable`).
+- `lead_persona` — the lens slug the user chose at **Step 3.9** (e.g. `'backend-developer'`). Pass the chosen `persona` from `work_item`. Omit only if Step 3.9 was skipped — the server then resolves the jtbd's canonical lens. Unknown slugs are ignored server-side.
 
 Store `exploration_id`. Move the progress header from Scope to Discovery:
 
@@ -1097,6 +1163,7 @@ Surface a single compact summary after all registrations resolve:
 
 **Why this lives at 6.2, not inside `create_exploration`:** sources are deliberately decoupled from the exploration row so a partial source-registration failure doesn't block exploration creation. Step 6 must always succeed if the underlying validation passes; Step 6.2 is best-effort on top.
 
+<!-- lite:skip-start reason="unpicked-consideration preservation is not part of lite" -->
 #### Step 6.5 — Preserve unpicked considerations without cluttering the workspace
 
 Unpicked or dismissed considerations are useful signal, but automatically creating sibling explorations can clutter the workspace. Do **not** fork sibling explorations by default.
@@ -1123,6 +1190,7 @@ If sibling creation is confirmed, call:
 
 Then summarize the created siblings in the dense-list format. Do not pause after creation; return to the primary build flow.
 
+<!-- lite:skip-end -->
 #### Step 7 — Discovery questions
 
 Longest phase because generation is async + the user picks per-Area. (Internally the API field is `matter_id`; user-facing copy always says Area.)
@@ -1131,16 +1199,22 @@ Longest phase because generation is async + the user picks per-Area. (Internally
 
 1. Call `mcp__ritual__suggest_discovery_questions(exploration_id)` (Step 7.1) — no user input needed; just kick it off.
 2. Poll `mcp__ritual__get_discovery_state(exploration_id)` until `ready: true` (Step 7.2).
-3. Render the Areas index per § 7.3.1 (NOT a free-form list — see § 7.3.1 rendering anti-pattern below).
-4. `[USER PAUSE]` — the user picks Areas + questions, or types `accept shortlist` / `skip discovery`.
-5. Call `mcp__ritual__accept_discovery_questions` for each picked Area (Step 7.4).
-6. Evaluate Step 7.4.5 triggers; render the scope-classification gate if any fire.
-7. ONLY THEN proceed to Step 8 and render the *"Reply `run` to continue"* CTA.
+3. Render the **Area rail + Area 1's questions together** and walk Area-by-Area per § 7.3.1 (the rail orients; a rail with NO questions under it — a bare index — is the failure mode).
+4. `[USER PAUSE]` — the user picks questions across Areas (**floor: 6 to run; aim for 15–20; no cap**), or types `accept shortlist`.
+5. Commit all picked Areas in ONE `mcp__ritual__accept_discovery_questions_batch` call (Step 7.4) — never one parallel call per Area.
+6. Optionally capture anti-goals (Step 7.5), then proceed to Step 8 and render the *"Reply `run` to continue"* CTA.
+
+**Picking is a deliberate step-through, not a bulk action (load-bearing):** the user going Area by Area and choosing the questions that matter IS the value of discovery — that per-question judgment shapes the whole downstream chain. So **nudge the user to step through and pick**; don't lead with bulk shortcuts.
+- **Nudge to step through.** Walk the user Area-by-Area (drop into Area 1, `next`/`prev`) and invite deliberate picks per Area, with `show more` to expand an Area. The framing is "which of these should we dig into?", not "want all of them?".
+- **Floor (HARD): at least 6 questions** across any Areas — below this, do NOT commit or proceed (tell them how many more to pick and keep them in the picker). There is NO "skip discovery" path — the agentic run needs a real question set to develop answers against. **Good coverage (SOFT): 15–20 questions** — nudge toward it on the Summary, but never block once ≥6. **No upper cap** — picking many (or all) is a legitimate explicit choice, never a default or fallback. (Uncovered scope is handled downstream when recommendations + requirements are generated and audited, so a thin set is the failure mode to prevent.)
+- **The default is the shortlist, never "all."** For a user who doesn't want to step through every Area, **`accept shortlist` (the 6–10 highest-leverage questions)** is the convenience default. An ambiguous reply (`proceed`, `go`, `ok`) at this gate means **accept the shortlist** — never silently accept everything.
+- **Taking all IS allowed — but only as an explicit user choice, never the default or a fallback.** If the user genuinely says "take all" / "all of them", honor it and commit them; that's a legitimate choice, not an error. Just never *offer* "I'll take all" as the default, and never auto-fall-back to it. (Worth mentioning once, not as a gate: every accepted question is answered individually in the agentic run, so accepting all of them across every Area means many more questions to answer and a much longer run — but it's the user's call.)
 
 **Forbidden behaviors:**
 
-- Calling `start_agentic_run` before `accept_discovery_questions` has been called at least once for this exploration. (`skip discovery` is the explicit exception — it intentionally takes the no-picks path through 7.4.5.)
+- Calling `start_agentic_run` before at least 6 discovery picks have been committed for this exploration (via `accept_discovery_questions_batch`, or `accept_discovery_questions`). There is no skip-discovery exception.
 - Silently auto-picking all generated questions and proceeding to Step 8 — observed in agent output 2026-05-15 as "the engineering-mode default is to run, which skips the per-question picker." There is no such default; the picker is mandatory.
+- **Offering "or I'll default to taking all of them" (or any accept-all fallback), then committing the full set on an ambiguous reply** — observed 2026-06-05 (a `proceed` at this gate → `accept_discovery_questions_batch` with all 68 questions → a ~25-min run the user never chose). Accept-all is a legitimate choice **only when the user explicitly asks for it** — it is NEVER the default you offer, and NEVER the fallback. The default you offer + fall back to is always **`accept shortlist`** (6–10). An ambiguous reply (`proceed`/`go`/`ok`) at the pick gate means **accept the shortlist**, not the full set. Lead by nudging the user to step through Areas and pick deliberately.
 - Rendering "Next: run discovery through recommendations / Reply `run` to continue" anywhere in the chat before Step 7.4 has completed.
 
 The picker is **not** a UI suggestion — it's the load-bearing decision gate where the user expresses what to investigate. Skipping it converts the agentic run into an automated "answer everything" pass and erases the user's judgment.
@@ -1160,29 +1234,40 @@ Generating discovery questions for each area…
 
 Loop:
 - Call `mcp__ritual__get_discovery_state(exploration_id)`
-- If `ready: false`, wait 5 seconds, poll again
+- If `ready: false`, wait 10 seconds, poll again
 - If `ready: true`, exit loop
 
-Don't poll faster than every 5 seconds. Follow the global polling rule above: single `Bash sleep 5` per iteration and a one-line update every ~3 polls (~15s). Polling heartbeats are exempt from the Build rail rule per `references/cli-output-contract.md` § Build progress anchor — does NOT apply to.
+Don't poll faster than every 10 seconds (matches the Spark UI's 10s discovery cadence). Follow the global polling rule above: single `Bash sleep 10` per iteration and a one-line update every ~2 polls (~20s). Polling heartbeats are exempt from the Build rail rule per `references/cli-output-contract.md` § Build progress anchor — does NOT apply to.
 
-##### 7.3 — Area-first picker (Areas index → drill into an Area → return to index)
+##### 7.3 — Matter-walk picker (Area rail + selected Area's questions → walk with `next`/`prev` → Summary)
 
 The state contains `matters[]`, each with `id`, `name`, and `questions[]`. Internally these are `matter`s; user-facing copy ALWAYS calls them **Areas**.
 
-DO NOT lead with a curated cross-area question list. It reads as the agent having pre-selected the answer and asking the user to rubber-stamp; the user's job at this moment is scanning the space and picking where to spend investigation. Use a two-level picker: Areas index first, then per-Area question detail, then back to the index with status markers.
+This MIRRORS the Spark `/discover` picker exactly: Spark shows a **tab bar of all Areas with one tab selected AND that tab's questions already rendered below it**. The CLI does the same in text — every render shows a compact **Area rail** (all Areas, the current one marked, with running picked counts) **and, directly beneath it, the current Area's questions**. The user picks questions, then moves between Areas with `next`/`prev`, and finally lands on a **Summary** grouped by Area before committing. Seeing each Area's questions and choosing deliberately IS the value of discovery.
+
+The two failure modes this contract prevents:
+- **A bare Area index** — the rail (or a "pick an Area" menu) with **no questions under it**. The rail without its current Area's questions is exactly the removed model; always render the questions inline. (This is the failure d3 caught on 2026-06-07: the agent rendered the Area list alone.)
+- **A full dump** — every Area's questions in one message. Only the **current** Area's questions render per turn.
+
+**Turn boundaries (load-bearing — this is a multi-turn walk, not a one-shot render).** Render the rail + **exactly ONE Area's questions per turn**. After rendering, **STOP and end your turn** — wait for the user's reply (`numbers` / `next` / `prev` / `skip` / `done`). Each of `next` / `prev` / `done` produces the **next render in a NEW turn**, never appended to the current message. You already hold every Area's questions from `get_discovery_state` — that is NOT license to render the whole walk or multiple Areas' questions in a single message. The rail lists Area *names + counts* (cheap orientation); only the current Area's *questions* render. One Area → STOP → reply → next Area. The Summary (§ 7.3.3) is likewise its own turn.
 
 ###### 7.3.0 — Compute per-Area recommendations + the global shortlist (internal, not user-facing)
 
-Two computations happen before the index renders. Both stay internal — they show up as counts on the index, not as auto-applied picks.
+Three things surface, **none auto-applied**:
+- **(a) The Area rail** — every Area's name + its running picked count. Cheap orientation (names + counts, NOT their questions), shown above the current Area's questions from the very first render. This is the legitimate, always-visible "tab bar" — it is NOT the forbidden bare index, *because the current Area's questions always render beneath it*.
+- **(b) The per-Area ★ recommended set** (3–4 questions) — computed for the Area you are currently showing.
+- **(c) The global shortlist** (6–10 across all Areas) — computed only when the user types `accept shortlist`.
+
+The user always picks; nothing is auto-committed.
 
-**Per-Area recommended counts** (what to suggest when the user drills into an Area):
+**Per-Area recommended set** (the ★ set, for the Area currently shown):
 
 - Pick the top 3–4 questions per Area most likely to shape the recommendations, based on the problem statement, locked sub-problems from Step 4, and the codebase recon context from Step 3. Bias toward questions whose absence would force later stages to invent consequential facts.
 - Area has **< 4 questions**: all are recommended.
 - Area has **4–7 questions**: top 3 are recommended.
 - Area has **8+ questions**: top 4 are recommended.
 
-**Global shortlist** (what `accept shortlist` accepts when used from the index):
+**Global shortlist** (what `accept shortlist` accepts — available from any Area or the Summary):
 
 - Pick **6–10 questions TOTAL across all Areas**, biased toward questions most likely to change recommendations.
 - Preserve Area diversity by default — at least one question from each Area where the per-Area recommended set was non-empty, unless the scope is clearly concentrated (e.g. one Area dominates the recon evidence).
@@ -1191,246 +1276,197 @@ Two computations happen before the index renders. Both stay internal — they sh
 
 Neither set is auto-applied. The user still picks per Area, or uses `accept shortlist` as a power path that bypasses the area-by-area drill.
 
-###### 7.3.1 — Areas index (landing)
+###### 7.3.1 — First render: Area rail + Area 1's questions (the walk begins)
 
-Full rail + intro + numbered Areas list with `{recommended} recommended · {total} total` per Area. NO question text on this screen — just the surface map. This is the first message of the picker; the rail has already been emitted, so subsequent area-detail messages use the in-phase chip.
+Open ON Area 1 with the **rail above and Area 1's questions below it** — never the rail alone. The rail lists every Area (current one marked, picked count per Area); the questions are Area 1's ★ recommended set. Full phase rail on this first message (we just entered Discovery); subsequent Area messages use the in-phase chip.
 
 ```text
 Ritual build
 ✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
-Question picking
-
-Ritual generated questions across {N} areas for the {M} locked sub-problems:
-{first sub-problem name} + {second sub-problem name}.
-
-Pick an Area to review. I'll show the 3–4 questions most likely to change
-the implementation plan.
-
-Areas:
-
-  1. {Area name 1}                   {N} recommended · {N} total
-  2. {Area name 2}                   {N} recommended · {N} total
-  3. {Area name 3}                   {N} recommended · {N} total
-  ...
-
-Reply with an Area number, `accept shortlist`, or `skip discovery`.
-Inside an Area, use `show more` to see the rest.
-```
-
-Number alignment: right-pad the Area name to a consistent column so the counts line up vertically. Drop the `accept shortlist` token when no Area has recommendations (rare; just show the area-number + `skip discovery` CTAs).
-
-**Rendering anti-pattern (load-bearing) — the Areas index renders ONLY area names + counts. Observed violations 2026-05-15:**
+Question picking · Area 1 of {N} · {Area name}          picked so far: 0
 
-- ❌ Question previews under each area:
-  ```text
-  1. Wishlist Visibility Contract (10 qs)
+Areas   ● {Area name 1}   ○ {Area name 2}   ○ {Area name 3}   ○ {Area name 4}   ○ {Area name 5}
+        ● current · ✓N after a name = picked in that Area · move with `next` / `prev`
 
-     1. How PUBLIC/SHARED behave across owner controls...
-  2. Shared Wishlist Surfaces (8 qs)
+Ritual generated questions across {N} areas for {M} locked sub-problems.
+I'll walk you through each — aim for 15–20 total (6 minimum to run, no cap).
 
-     2. Which entry points light up first...
-  ```
-  No. This invents question previews the SKILL never asked for, AND uses overlapping numbering (`1. {area}` and `1. {question preview}`) that creates ambiguity — when the user replies `5`, neither side can tell what they meant. Single numbering stream: areas only.
-
-- ❌ Free-form bullet lists, "for your convenience" question summaries, or any text under the area line beyond `{N} recommended · {N} total`.
-
-- ❌ Adding a "TL;DR" / "highlights" section above or below the Areas list.
+Showing the {k} most likely to change the plan ({total} in this Area):
 
-**The correct shape is exactly** (no exceptions):
+  1. {recommended question 1, wrapped readably}
+  2. {recommended question 2, wrapped readably}
+  3. {recommended question 3, wrapped readably}
 
+pick   numbers (e.g. `1,3`)  ·  `suggested` (these ★)  ·  `add <your question>`  ·  `show more` ({total−k} more)
+walk   `next`  ·  `prev`  ·  `skip`  ·  `done` (≥6)  ·  `accept shortlist`
 ```
-Areas:
-
-  1. {Area name}                     {N} recommended · {N} total
-  2. {Area name}                     {N} recommended · {N} total
-  ...
-```
-
-If the user wants to see questions, they pick an Area number — that's what § 7.3.2 (Area detail) is for. **Do not pre-empt their drill choice with question previews.** Same rule as Step 9.1's "use server preview verbatim, do not free-form-summarize on top."
-
-**Why `accept shortlist`, not `accept recommended`:**
-
-- "Recommended" is ambiguous (recommended per Area? globally? by category? recommended *recs* later in the flow?). The discovery picker uses **shortlist** explicitly because the shortlist is global (6–10 questions across all Areas, computed in § 7.3.0) — distinct from per-Area recommended counts shown alongside each Area, and distinct from the later `accept recommended` action that accepts implementation themes in Step 9.
-- This creates a clean vocabulary split: **discovery = `accept shortlist`** (questions), **recommendations = `accept recommended`** (themes).
-
-**Don't advertise global `show all` at the index.** Showing every question across every Area can be a screen-flooding wall. The escape hatch the user actually needs is **`show more` inside an Area** (lazy expansion per Area), not a global dump. Accept `show all` as a reply but don't list it as a visible CTA on the index.
-
-###### 7.3.2 — Area detail (one Area's questions)
-
-When the user picks an Area number, show that Area's **top recommended questions** by default. Hold the rest behind `show more`. In-phase chip, NOT full rail (rail was emitted on the index).
 
-```text
-Question picking · {Area name}
-
-Showing {N} recommended questions out of {total}.
+**Single numbering stream — number the QUESTIONS only; the rail Areas are NOT numbered.** The 2026-05-15 failure numbered Areas AND question previews in one view, so a reply of `5` was ambiguous. Here the rail uses `●`/`○` markers + names (no numbers) and you move it with `next`/`prev` — the only numbered list is the current Area's questions, so a bare number is never ambiguous. Wrap long question text readably. The `picked so far` count, the rail markers/`✓N` counts, and the `Area i of N` breadcrumb all update on every render of the walk.
 
-  1. {question 1, wrapped readably}
+**Why `accept shortlist`, not `accept recommended`:** "recommended" is ambiguous (per-Area? global?). The picker uses **shortlist** for the global 6–10 power path (§ 7.3.0), keeping a clean vocabulary split: **discovery = `accept shortlist`** (questions), **recommendation review = `proceed`** (Step 9). The ★ marks the per-Area recommended set; `suggested` picks it.
 
-  2. {question 2, wrapped readably}
+###### 7.3.2 — Within an Area (pick, then move)
 
-  3. {question 3, wrapped readably}
-
-Reply with numbers like `1,2` to pick, `show more` to see all {total},
-or `skip` to leave this Area without picks.
-```
+**Every render in this section keeps the `Areas …` rail line on top** (current Area marked, `✓N` counts updated) — it's omitted from the snippets below only for brevity. Never re-render an Area's questions without the rail above them.
 
-`show more` reveals the rest of the questions, formatted in two groups (Recommended / More):
+- **`numbers`** (e.g. `1,3` or `1,2,5`): add those questions to the picked set, re-render this Area (rail + questions) with `✓` on the picked rows + the updated `picked so far`, then prompt `next` / `prev` / `done`.
+- **`suggested`**: pick this Area's recommended (★) set in one go.
+- **`show more`**: reveal the rest, grouped Recommended / More (lazy per-Area expansion — never a global dump):
 
 ```text
-Question picking · {Area name}
+Question picking · {Area name}                          picked so far: {T}
 
 Recommended:
-
-  1. {recommended question 1}
+  1. {recommended question 1}      ✓
   2. {recommended question 2}
   3. {recommended question 3}
 
 More questions:
-
   4. {non-recommended question 1}
   5. {non-recommended question 2}
-  6. {non-recommended question 3}
-  7. {non-recommended question 4}
   ...
 
-Reply with numbers like `1,2,5`, or `skip`.
+Reply numbers (e.g. `1,4`), `next`, `prev`, or `skip`.
 ```
 
-###### 7.3.3 — Return to Areas index with status markers
+- **`next` / `prev`**: move to the next / previous Area (picks preserved). At the last Area, `next` goes to the Summary (§ 7.3.3).
+- **`skip`**: leave this Area with no picks, advance to `next`.
+- **`done`**: jump straight to the Summary (allowed from any Area).
+- **`pause`**: stop here — state is saved, nothing committed.
+- **`show all`**: accepted as a reply (expands every Area's questions into one long list) but NOT advertised on the CTA line — per-Area `show more` is the default, not a global wall.
+- **`add <your question>`** (e.g. `add How should we handle partial refunds?`): add a USER-AUTHORED question to THIS Area. **Pre-flight format-validate it locally first:** it must read as a single, clear question (non-empty, interrogative or ends with `?`, ≤ ~200 chars). If it's malformed (a statement, a fragment, multiple questions, too long), say what's off and ask them to rephrase — do NOT hold a malformed one. When valid, **hold it locally** for this Area and re-render the Area (rail + questions) with it shown as `＋ (your)  {text}` beneath the questions, `picked so far` incremented. It counts toward the floor/target like any pick. It is NOT written to the server yet — every custom question is persisted in ONE batch at `commit` (§ 7.4).
 
-After the user picks for an Area (or skips), return to the Areas index with status markers reflecting what's been resolved. Use `✓` for picked, `–` for skipped, `□` for not-yet-touched. NEVER use strikethrough — it renders inconsistently across terminals.
+###### 7.3.3 — Summary (after the last Area, or on `done`) — the review-before-commit gate
 
-```text
-Question picking
+Render all picks grouped by Area. This MIRRORS Spark's Summary tab and is the gate where the user confirms before the run. Use `✓` picked / `—` none / `□` untouched. NEVER strikethrough (renders inconsistently across terminals).
 
-Areas:
-
-  ✓ 1. {Area name 1}                   {N} picked
-  □ 2. {Area name 2}                   {N} recommended · {N} total
-  □ 3. {Area name 3}                   {N} recommended · {N} total
-  – 4. {Area name 4}                   skipped
+```text
+Question picking · Summary                              {T} picked
+
+  ✓ 1. {Area name 1}        {n} picked
+        – {picked question}
+        – {picked question}
+  — 2. {Area name 2}        none picked
+  ✓ 3. {Area name 3}        {n} picked
+        – {picked question}
   ...
 
-Reply with another Area number, or `done` to investigate the {total picked}
-picked questions. Reply `pause` to stop here.
+{if T < 15}   A good set is usually 15–20 — you've picked {T}. Reply an Area
+              number to add more, `more` to suggest new Areas, or `commit`.
+{if T ≥ 15}   Reply `commit` to run discovery on these {T} questions, an Area
+              number to adjust, `more` for new Areas, or `pause` to stop.
 ```
 
-When EVERY Area has been resolved (picked or skipped), shift the CTA from "another Area number" to:
+**The minimum model — floor 6 HARD, good 15–20 SOFT, no cap:**
 
-```text
-All Areas reviewed. Reply `done` to investigate the {total picked}
-picked questions. Reply `pause` to stop here.
-```
+- **`commit` with T < 6** → REFUSE (hard floor). *"Pick at least 6 to run discovery — you have {T}, choose {6−T} more,"* then return to the Summary (or the Area they were on). No skip path; do NOT call `accept_discovery_questions_batch` or `start_agentic_run`.
+- **`commit` with 6 ≤ T < 15** → allowed. Proceed to § 7.4 after the one-line "good is 15–20" nudge — do NOT re-nag or block.
+- **`commit` with T ≥ 15** → proceed to § 7.4.
+- **An Area number** at the Summary → re-open that Area's questions (picks preserved), then return here.
+
+**Held custom questions + pending new Areas render in the Summary** so the user reviews everything before `commit`: a held custom question shows under its Area as `＋ (your) {text}`; a pending agent-suggested new Area shows at the bottom as `＋ (new) {name}  {n} questions`. They count toward `{T}`. All are persisted at `commit` (§ 7.4).
+
+- **`more`** at the Summary → the user wants broader coverage. **Suggest 2–3 NEW candidate Areas inline yourself** — each a short name + 3–4 questions — authored from the problem statement, the locked scope, and the Areas already shown, chosen to fill **gaps** the current Areas miss. Label the candidates with **LETTERS (`A`, `B`, `C`) — not numbers** — to avoid colliding with the question-number stream, and ask which to add (`letters`, e.g. `A` or `A,C`, or `none`). Picked candidates become **pending new Areas held locally** (persisted at `commit`). Do NOT call a server "generate-more" endpoint — you have the context, so propose directly (it's faster). **Never auto-add — the user picks.**
 
-###### 7.3.4 — Power paths from the index
+###### 7.3.4 — Power paths (available from any Area or the Summary)
 
-- **`accept shortlist`** (from the index, before picking any Area): accept the 6–10-question global shortlist computed in § 7.3.0. Group those by their owning Area, then call `accept_discovery_questions` once per Area (in parallel per § 7.4) with the shortlisted IDs for that Area. Skip straight to Step 7.4 commit + Step 7.4.5 classification. This is intentionally NOT "top 3–4 of every Area" — that would scale to 24–32 picks on a wide exploration and reintroduce the "no triage signal" problem the area-first picker exists to fix.
-- `show all` (from the index): accepted as a reply but NOT advertised on the CTA line. Expands into a single long list view across all Areas. Use only when the user explicitly asks — the area-first index is the default.
-- `skip discovery` (from the index, before any picks): treat ALL Areas as skipped. The classification check in Step 7.4.5 will surface this as a deliberate choice.
+- **`accept shortlist`**: accept the 6–10-question global shortlist computed in § 7.3.0 — the fast path for a user who doesn't want to walk every Area. Group those by their owning Area, commit them in ONE `accept_discovery_questions_batch` call (§ 7.4 — one entry per Area), and proceed to Step 7.5. Intentionally NOT "top 3–4 of every Area" (which would scale to 24–32 picks and reintroduce the "no triage signal" problem). The shortlist is the quick minimal set; the walk is how a user reaches the 15–20 good-coverage range.
+- **`show all`**: accepted as a reply but NOT advertised on the CTA line. Expands every Area's questions into one long list. Use only when the user explicitly asks — the per-Area `show more` is the default.
+- **`done`**: jump to the Summary from any Area to review + `commit`.
+- **Below the floor** (fewer than 6 picked on `commit`): do NOT proceed. Reply with how many more are needed and return to the Summary — e.g. *"Pick at least 6 to run discovery — you've picked 3, choose 3 more."* There is no skip path. (6–14 is allowed with the soft nudge; ≥15 is the good-coverage target — see § 7.3.3.)
 
 ###### 7.3.5 — What NOT to say
 
 - DO NOT add machinery copy like *"The answer engine will then investigate them via codebase recon and surface clarifying questions for you to review."* The user only needs to know that picking them triggers investigation.
 - DO NOT use `Press Enter` anywhere in this picker (see § Surface-aware continuation prompts).
-- DO NOT say `lock` for the picking confirmation; use `done` from the index.
-- DO NOT show full question text in the index — only Area names + counts.
+- DO NOT say `lock` for the picking confirmation; use `done` (to the Summary) then `commit`.
+- DO NOT number Areas and questions in the same view — one numbering stream (the current Area's questions). The breadcrumb `Area i of N` carries position; it is not a pickable number.
 
 ###### Legacy alias notes
 
-- `suggest` (legacy per-Area shortcut) is now the implicit per-Area recommendation — the index already shows recommended counts and `accept shortlist` is the global power path. If a user still types `suggest` inside an Area, treat it as "pick the recommended set for this Area."
-- `accept recommended` (legacy global shortcut): if a user types this, treat it as `accept shortlist`. Surface a one-line note that the discovery-stage token is `accept shortlist` (questions); `accept recommended` is reserved for Step 9's theme acceptance.
+- `suggest` (legacy per-Area shortcut) is now spelled **`suggested`** — picks the current Area's recommended (★) set. If a user types `suggest` inside an Area, treat it the same.
+- `accept recommended` (legacy global shortcut): at the DISCOVERY stage, if a user types this, treat it as `accept shortlist` and surface a one-line note that the discovery-stage token is `accept shortlist` (questions). (At Step 9 the recommendation-review CTA is `proceed`, not `accept recommended`.)
 - `all` (legacy fourth option) remains removed (see § Removed below).
 
 ###### Removed: `all` (the old fourth option)
 
 The legacy `all` shortcut was removed because in practice it produced low-signal selections — picking everything is indistinguishable from not discriminating, which makes Reasoning Readiness scoring less meaningful at the boundary and pushes recommendation generation against a noisy answer set. Users who really did mean "everything" can still type the full number list (e.g. `1,2,3,4,5`) — but that requires conscious intent rather than a one-keystroke default. If you see a SKILL or external reference still mentioning `all`, it's stale.
 
-##### 7.4 — Commit picks (one call per Area, dispatched in parallel)
+##### 7.4 — Commit picks (ONE batch call across all Areas)
 
-For each Area where the user picked at least one question, call `mcp__ritual__accept_discovery_questions` with:
-- `state_id` (from the discovery state)
-- `matter_id` (the API field; user-facing this is the Area)
-- `question_ids[]` (the picks for THIS Area)
+**load-bearing — forbidden behavior:** do NOT fan out one
+`accept_discovery_questions` call per Area in parallel. Each per-Area call
+does several DB round-trips; firing them concurrently exhausts the server's
+connection pool and returns 503s on the later Areas (observed in prod). The
+batch endpoint exists precisely to avoid this — use it.
 
-The API enforces per-matter atomicity — there is no cross-matter batch endpoint today (filed as backlog: `accept_discovery_questions_batch`). To minimize wall-clock latency when the user picked across many Areas, **dispatch the per-Area calls in parallel** with `Promise.all` rather than awaiting each one sequentially:
+Call `mcp__ritual__accept_discovery_questions_batch` **once** with every
+Area's picks in a single atomic request:
+- `state_id` (from the discovery state)
+- `picks[]` — one entry per Area the user picked in, each `{ matter_id, question_ids[] }`
 
 ```ts
-// Parallel, NOT sequential.
-await Promise.all(
-  pickedAreas.map((area) =>
-    accept_discovery_questions(state_id, area.matter_id, area.question_ids),
-  ),
-);
+// ONE call. All Areas, one atomic transaction, one successor state.
+await accept_discovery_questions_batch(state_id, [
+  { matter_id: areaA.matter_id, question_ids: areaA.question_ids },
+  { matter_id: areaB.matter_id, question_ids: areaB.question_ids },
+  // …one entry per Area with at least one pick
+]);
 ```
 
+Use the single-Area `accept_discovery_questions` ONLY when the user picked in
+exactly one Area. If for some reason you must use it across several Areas
+(e.g. the batch tool is unavailable), call it **sequentially** (`await` each
+in turn) — never in parallel.
+
 User-facing: emit ONE status line for the whole commit, not one per Area:
 
 ```text
 Saving picks across {N} Areas…
 ```
 
-If any individual call fails, log the Area name + error inline and continue with the rest — partial success is acceptable here. The next step's classification check will surface anything that didn't land.
-
-##### 7.4.5 — Classify unpicked areas when the signal warrants it
-
-After question picking, check for scope mismatch only when one of these triggers fires:
-
-- Pick-rate < 40%
-- Matter coverage <= 50%
-- Pick-rate = 100%
-- Picks concentrate heavily in one matter while the scope spans several concerns
+The batch call is all-or-nothing — validation fails the whole request if any
+pick is malformed, so there's no partial-success state to reconcile. Areas the
+user chose not to pick from are simply left unpicked.
 
-If no trigger fires, proceed silently to anti-goals.
+**If there are NO held custom questions or pending new Areas, proceed to anti-goals.**
 
-**Fire-on-trigger anti-pattern (load-bearing):** after `accept_discovery_questions` returns, you MUST evaluate the four trigger conditions before proceeding to Step 8. If ANY trigger matches, you MUST render the scope-classification gate. Skipping the gate when a trigger fires — including the "the picks look reasonable to me" / "the user seems decisive" / "they probably know what they're doing" judgment call — is a SKILL violation. The decision signal is the user's **actual pick distribution**, not the agent's confidence in it.
+###### 7.4.1 — Persist held custom questions + new Areas (only if any were held)
 
-Concretely: at 5 picks out of 70 total questions = 7.1% pick-rate, the < 40% trigger fires. The gate MUST be rendered. Observed violation 2026-05-15: agent proceeded directly to Step 8 after a 5/70 acceptance, never showed the scope-classification gate — silently locking the user into a broad scope while their actual investigation was tightly focused on 5 questions.
+Custom questions (`add`, § 7.3.2) and pending new Areas (`more`, § 7.3.3) were held
+LOCALLY during the walk because `add_discovery_question` needs a **workspace** matter id,
+which only exists after the batch above materialized the picked Areas. Persist them now,
+AFTER the batch call:
 
-This is the same gap as the Step 9 "freelance dedupe action" anti-pattern: the SKILL specifies the behavior; the agent must not override based on its own assessment of whether the gate "feels needed."
+1. **Resolve workspace matter ids.** Call `mcp__ritual__get_exploration(exploration_id)` and
+   map each Area **name** → its workspace `matters[i].id`. (The batch only materialized Areas
+   the user picked AI questions in.)
+2. **For each Area that has held custom questions:**
+   - if a workspace matter for that name exists → use its id;
+   - if not (a custom-only Area, or a pending new Area) → `mcp__ritual__create_discovery_matter(exploration_id, name)` first, use the returned id.
+   - then call `mcp__ritual__add_discovery_question(exploration_id, matter_id, text)` for each held question — **SEQUENTIALLY** (`await` each), never in parallel (same connection-pool caution as the batch).
+3. **For each pending new Area** (from `more`): `create_discovery_matter(...)` then `add_discovery_question(...)` per its questions, sequentially.
 
-If a trigger fires, summarize the pattern in plain language and ask the user to classify unpicked areas. This is a top-level decision gate that closes the picker sub-views, so the full rail returns:
+One status line for the whole persist step (not one per question):
 
 ```text
-Ritual build
-✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
-
-Scope check
-
-{One-line summary of which pattern fired — e.g. "You picked 4 of 32 questions, mostly in retention."}
-
-How should I treat the unpicked areas?
-
-  1. Out of scope — tighten the current scope around what you picked.
-  2. Later phase — keep the broad scope, but mark unpicked areas as phase-later candidates.
-  3. Open questions — keep the broad scope and treat unpicked areas as context debt.
-  4. Pick more — return to question picking before continuing.
-
-Reply with `1`, `2`, `3`, or `4`. Reply `pause` to stop here.
-```
-
-Use `references/discovery-classification.md` for the branch handlers, pulse templates, and no-discrimination case. Do not preview score deltas in the question-picking menu; let the pulse explain the consequence after the user chooses.
-
-For Branch 2, append an exact block to `recon_context` before build brief generation:
-
-```markdown
-## Explicit phase-later candidates
-
-These were intentionally deferred by the user during discovery. They are not context debt. Include them in the Build Brief under "Phase Candidates / Deferrable Items."
-
-- {matter/question}
-  Reason: {user choice or inferred dependency}
-  Related RB/source: {optional}
+Adding your {M} question(s) across {K} Area(s)…
 ```
 
+Only after all holds are persisted, proceed to anti-goals. The floor (≥6) counts
+custom + AI questions together — never `start_agentic_run` before the held questions are
+written.
 
 ##### 7.5 — Optional: capture out-of-scope items
 
 If the user mentioned things they DON'T want investigated ("don't touch enterprise SSO", "skip pricing"), capture them as anti-goals.
 
+**Pre-flight (mandatory):** before calling `set_anti_goals`, run the change pre-flight in `references/change-preflight.md` — restate the out-of-scope items you heard and show the exact anti-goal `text` array you're about to send, then wait for `yes`. A misread anti-goal poisons rec-gen and the R4 audit downstream, so this hard pause (even in auto-mode) applies even when the user's phrasing seemed clear. Do not call the tool until the user confirms.
+
 Call `mcp__ritual__set_anti_goals(exploration_id, [{ text, reason? }, ...])`.
 
-Skip silently if no anti-goals were mentioned.
+Skip silently if no anti-goals were mentioned. (No mention = nothing to confirm; the pre-flight only runs when the user actually states out-of-scope items.)
 
 **Pulse (Step 7.4 done — and again after 7.5 if anti-goals were set):** Emit a pulse — decision resolution and (if 7.5 ran) assumption safety just moved. Compact format unless this crosses Under-specified → Exploration-safe.
 
@@ -1530,7 +1566,7 @@ Pick whichever fits the user's flow — they're equivalent in content. Do not in
 
 ##### 8.1 — Polling loop
 
-Poll `mcp__ritual__get_agentic_run(run_id)` using `references/async-polling.md`: **`Bash sleep 5` (always 5 — never escalate to 15/20/25)** per iteration, then a fresh status call. Even if the run takes 2+ minutes, the sleep value stays 5; the harness blocks chained-shorter-sleeps-at-increasing-N just like it blocks `sleep ≥ 30`. Agentic runs CAN exceed 5 min for large explorations — if you see status still running past ~5 min of polling, switch to the `Monitor` + `until <check>; do sleep 2; done` pattern from `references/async-polling.md` § Long waits.
+Poll `mcp__ritual__get_agentic_run(run_id)` using `references/async-polling.md`: **`Bash sleep 20` (constant 20 — matches Spark's 20s agentic cadence; never escalate)** per iteration, then a fresh status call. Even if the run takes 2+ minutes, the sleep value stays a constant 20; the harness blocks chained-shorter-sleeps-at-increasing-N just like it blocks `sleep ≥ 30`, but a fixed `20` is non-escalating and under 30 → guard-safe. Agentic runs CAN exceed 5 min for large explorations — if you see status still running past ~5 min of polling, switch to the `Monitor` + `until <check>; do sleep 2; done` pattern from `references/async-polling.md` § Long waits.
 
 **On the FIRST poll only** (not every poll), prepend one line that locks the "background execution is default" mental model:
 
@@ -1631,356 +1667,146 @@ For each question's loop:
 
 **Pulse (Step 8 done):** Emit a pulse — decision resolution moved significantly (answers complete, draft recommendations now exist). Render full if this crosses Under-specified → Exploration-safe, else compact.
 
-#### Step 9 — Review and accept recommendations (grouped, role-aware)
-
-**Use `mcp__ritual__get_recommendations_preview(exploration_id)` for the Step 9.1 landing screen.** It returns a server-rendered preview with `previewText` (terminal-formatted, hard-wrapped at 78 cols — print verbatim), `idMap` (`R1..RN` → uuid lookup for resolving `accept R3` / `detail R7`), `actions` (role-aware structured command list), `categoryGroups` (structured grouped list for non-terminal surfaces), `actionHint`, `scopeLine`, and `totalCount`. The server already handles role detection (admin vs collaborator) and filters out `approved`/`rejected` recs.
-
-Use `mcp__ritual__get_recommendations(exploration_id)` (the raw array) only when you need fields not in the preview — full `metadata.acceptance_criteria[]`, `metadata.explainability` rationale chain, `metadata.labels[]`, etc. The detail card in 9.3 (`detail R{N}`) loads from the raw tool keyed by the uuid you got from `idMap`.
-
-Each raw rec includes:
+<!-- lite:keep-start -->
 
-- top-level: `id`, `title`, `content` (summary), `status`, `priority`, `points`, `confidence`
-- `metadata.category.name` — **the load-bearing grouping key** (one rec → one category)
-- `metadata.acceptance_criteria[]` — concrete pass conditions
-- `metadata.explainability` — `rationale` (chained `→` arrow string), `faq_references[]`, `problem_alignment`, `inferred_elements`, optional `initial_input_analysis`
-- `metadata.labels[]` — secondary tags
-
-**Role model — load-bearing**: only **admins** can accept recommendations (call `accept_recommendations`). **Collaborators** can read, comment, and proceed to implement, but they cannot move recs from `draft`/`pending_review` to `approved`. The preview API handles this automatically — the `actions` list and `actionHint` are gated on the caller's workspace role; admins see `accept recommended` while everyone else sees `request admin review` plus the optional `continue` (implement-ahead) path. Respect what the preview returns; don't substitute it.
-
-If you don't already know the user's role on this workspace, prefer the workspace member endpoint or cached role from `/ritual init`. When unavailable, ask plainly: *"Are you the workspace admin or a collaborator?"* Do not attempt acceptance blindly unless the user explicitly says to accept.
-
-**Vocabulary**: do NOT use "Reasoning chain" or "reasoning_chain" in user-facing copy. The user-visible label is **"Why this"** — a 4-line Problem / Discovery / Tradeoff / Recommendation breakdown derived from the rationale field. "Reasoning chain" sounds like internal model chain-of-thought; "Why this" is product-native.
-
-**Vocabulary anti-pattern — load-bearing**: recommendations are grouped by **category** (`metadata.category.name`). They are **NEVER** grouped by `matter` or by `Area`. Those are **discovery-phase concepts** — the matter / Area is where DISCOVERY QUESTIONS live; recommendations are synthesized across all matters and grouped by the category the LLM assigns (themes like "Token security & replay", "Atomicity & architecture", etc.). The internal DB field `matter_id` does not appear in the recommendation surface and **must never appear in user-facing copy** at this step. Anti-pattern observed in agent output: *"44 recs grouped by matter"* — the right framing is *"44 recs grouped by category"* (with categoryGroups returned by the preview API doing the work). If you find yourself referring to recommendation groups as "Areas" or "matters," stop and re-read this paragraph.
-
-**Action-menu anti-pattern — load-bearing**: the **blessed action set at the Step 9 acceptance gate** is exactly:
+#### Step 9 — Review recommendations (category walk)
 
-- `accept recommended` — admin path, accepts all on-screen recs
-- `request admin review` — collaborator path, notifies workspace admin
-- `drop R{N}` — remove one rec from the set before accepting
-- `drill R{N}` — show one rec's full detail card
-- `comment R{N}` — leave feedback on a specific rec
-- `pause` — stop here; user can resume via `/ritual resume`
+This is the most-read screen in the build flow, and — as of 2026-06-08 — a **non-blocking review**. Recommendations are **auto-accepted at generation** (created `approved`); the artifacts that depend on them (requirements, the deliverable doc, and — for developer-function jobs — the build brief) are **already being generated** the moment rec-gen completes. Step 9 is the user's chance to **read and refine** the set, not an accept-or-reject gate. Replying `proceed` records that a human reviewed it (stamps `reviewedAt` / `reviewedBy`) and continues to the build brief — it never blocks, and there is **no reject path here**.
 
-Plus the `continue` (implement-ahead) escape hatch for collaborators with explicit authorization.
+The review is a **category walk**, mirroring Spark's recommendation drawer: the user moves through one **category** at a time, sees each recommendation in that category in full (title, description, and the "Why this" reasoning), and can refine any one of them in place before continuing.
 
-**Do NOT freelance other actions.** Anti-patterns observed in agent output:
+**Data source.** Use `mcp__ritual__get_recommendations(exploration_id)` (the raw array) — the walk shows full per-rec content, so you need the fields a titles-only preview omits:
 
-- ❌ `dedupe` — there is no de-dupe action. The system produces a non-duplicated rec set by design (single-flight rec-generation, V5 cap-enforcer, Stage A.2 quality audit). If duplicates appear, that's a system regression — file a bug, don't offer a workaround.
-- ❌ `open the admin` / "open the admin UI to reject one pass" — there is no admin UI surface invoked from `/ritual build`. The CLI is the surface; the action set above is the contract.
-- ❌ `reject one pass` / `accept the survivors` — assumes a duplicate-pass shape that should not exist post-PR #345.
-- ❌ Any invented compound action (`accept and dedupe`, `merge similar`, etc.) — drives the user into a workflow the system doesn't support.
-
-If the rec set looks wrong, the right responses are: surface the anomaly explicitly, ask the user how to proceed, and consult `mcp__ritual__get_recommendation_attestation` for the quality audit's `duplicateTitlePrefixes` signal. Don't paper over with an invented action.
-
-##### 9.1 — Landing screen: server-rendered preview (primary path)
+- top-level: `id`, `title`, `content` (the description / summary), `status`, `priority`, `points`, `confidence`
+- `metadata.category.name` — **the load-bearing grouping key** (one rec → one category)
+- `metadata.explainability` — `rationale` (chained `→` arrow string), `faq_references[]`, `problem_alignment`, `inferred_elements`
+- `metadata.acceptance_criteria[]` — concrete pass conditions (optional to surface; see § 9.1)
 
-The recommendations review is the most-read screen in the whole build flow.
+Assign stable `R1..RN` IDs **globally across all categories** in page order (NOT restarting per-category), and remember the `R{N}` → `id` map so you can resolve `edit R{N}` to the rec UUID for the MCP calls.
 
-**Primary path — print the server preview verbatim:**
+**Vocabulary — load-bearing:**
 
-```text
-1. Call mcp__ritual__get_recommendations_preview(exploration_id).
-
-2. Response shape:
-     {
-       terminalPreviewText: "...",   // present for surface=terminal (default)
-       uiPreview: {                   // always present
-         stage: "recommendations",
-         stageIndex: 4, stageCount: 6,
-         scopeLine, stats, categoryGroups,
-         idMap, actions
-       }
-     }
-
-3. Print response.terminalPreviewText VERBATIM. Do not re-render,
-   re-wrap, re-number, or add a leading "Here are your recommendations..."
-   line. The server already laid out the build rail, scope, grouped recs,
-   and role-aware action hint at 78-col wrap.
-
-4. Remember response.uiPreview.idMap so you can resolve user input — when
-   they reply `accept R3` or `detail R7`, look up `R{N}` → uuid in
-   idMap and use that uuid in the follow-up MCP call (accept_recommendations,
-   get_recommendations).
-
-5. response.uiPreview.actions is for mobile/web button rendering — terminal
-   flow ignores it (action hint copy is already inside terminalPreviewText).
-   Each action carries `style: "primary" | "secondary"` so a non-terminal
-   UI knows which is the call-to-action.
-```
+- Recommendations are grouped by **category** (`metadata.category.name`). They are **NEVER** grouped by `matter` or by `Area` — those are discovery-phase concepts. `matter_id` must never appear in user-facing copy. Anti-pattern observed in agent output: *"44 recs grouped by matter"* — the right framing is *"44 recs across K categories."*
+- Do NOT use "Reasoning chain" / "reasoning_chain" in user-facing copy. The user-visible label is **"Why this"** — a short Problem / Discovery / Tradeoff distillation derived from the `rationale` field, NOT the literal `→` arrow chain (that's the model's internal scratchpad shape).
 
-The server controls the rendering shape (category numbering, R-IDs, titles-only, 78-col wrap, role-aware action hint). Your job is to print and look up — not to invent labels, re-group, or add commentary.
+**Action set — load-bearing (exactly three, no freelancing):**
 
-**Rendering anti-pattern — DO NOT DO THIS:** the most-seen Step 9 regression is the agent printing the preview AND THEN free-form-listing the recs themselves as a bulleted summary "for the user's convenience." This is wrong on three axes:
+- `edit R{N} <your change>` — refine one recommendation: regenerate its title / description / reasoning from a plain-language ask, **preview** the change, then **apply** it. (§ 9.2)
+- `next` — move to the next category. (§ 9.3)
+- `proceed` — mark the set reviewed and continue to the build brief, from any category. (§ 9.3)
 
-1. **Doubles the content** — preview already has titles + R-IDs + action hint at 78-col wrap. A second free-form list is redundant and pushes the action hint off-screen on small terminals.
-2. **Drops the R-IDs** — a free-form bullet list erases the stable `R{N}` references the user needs to reply with `accept R3` / `drill R7` / `comment R12`. The user then types `view 10` (positional) thinking that's stable; it's not.
-3. **Invents grouping labels** — free-form rendering tempts the agent to label groups as "Areas" or "matters" (already covered by the vocabulary anti-pattern above).
+**Do NOT freelance other actions.** There is **no `drop` / reject** (recs are auto-accepted and the review is non-blocking — a rec the user dislikes is refined with `edit`, or simply left as-is), **no `comment`**, and **no separate `drill` / `detail`** (full content is already on screen). Reject none of these by inventing compounds either (`dedupe`, `accept the survivors`, `merge similar`, `open the admin UI` — all forbidden). If the rec set itself looks wrong (e.g. apparent duplicates), surface the anomaly explicitly and consult `mcp__ritual__get_recommendation_attestation` (`duplicateTitlePrefixes`) — don't paper over it with an invented action.
 
-If the user wants more detail than the preview shows, they use `drill R{N}` — that's what the action menu is for. Do not pre-empt their drill choice with a wall of free-form bullets.
+##### 9.1 — The walk: one category per turn
 
-**"Many recs" rule — load-bearing for high-count sets**: when `response.uiPreview.stats.totalCount > 20`, the preview is **especially** the right surface to use; do NOT compensate by dumping the rec content inline. The server preview keeps high-count sets navigable (R-IDs + titles + compact category groups). If a 40+ rec set ever lands, the right reaction is to investigate WHY (single-flight regression? cap-enforcer bypass?) — see Stage A.2 audit signals via `get_recommendation_attestation` — not to add helpful free-form rendering on top.
+**[USER PAUSE]** Render the **current category only**, then stop and wait for the user's reply. One category per turn — never dump every category's full content in a single message (that's the wall-of-text failure mode; the walk is what keeps a 13-rec set readable). The first render opens with the full rail; subsequent categories use the in-phase chip.
 
-**Fallback path — if the preview tool is unavailable or returns a non-200**: render per the contract block below. The contract is the same shape the server uses, so a mismatch between server-rendered and agent-rendered output is unlikely. The fallback exists for older MCP servers that haven't deployed the preview endpoint yet.
-
-```text
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-STEP 9.1 RENDERING CONTRACT (FALLBACK) — non-negotiable
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Use this contract ONLY if get_recommendations_preview is unavailable
-(older MCP server) or returns an error. Otherwise, print the preview
-verbatim per the Primary path above.
-
-
-Landing view is for SELECTION, not reading. Full prose belongs in 9.3.
-
-✓ DO:
-- Number categories `1.`, `2.`, `3.` … `K.` in page order
-- Assign recommendations stable `R1`, `R2`, … `RN` IDs GLOBALLY across
-  all categories (NOT restart per-category — so `detail R7` is
-  unambiguous without naming the category)
-- Show recommendation TITLES ONLY at the landing
-- Indent recs 3 spaces under their category
-- One blank line between categories
-- Include compact scope line above the list
-- End with the action block (`accept recommended` etc.)
-
-✗ DO NOT:
-- Do NOT render recs as a flat `1..N` list with no category structure
-- Do NOT use raw numeric rec IDs like `1.`, `2.`, `3.` — use `R1`, `R2`, `R3`
-- Do NOT show recommendation `content` / summary text at the landing
-- Do NOT show acceptance criteria, rationale, tactics, or references at
-  the landing — those are 9.3 detail-card content
-- Do NOT omit category numbering (the prefix is what separates this
-  from a wall-of-text grouped list)
-- Do NOT invent a "raw / deduped" framing line — the API does not return
-  pre-dedup counts. Use `{N} recommendations across {K} categories.`
-
-OBSERVED FAILURE — never render this:
-
-  Recommendations (13)
-
-  1. Backfill legacy data to fail-closed PRIVATE visibility
-     Add a constrained `visibility` field with DB default PRIVATE...
-
-  2. Codify actor-state rights around owner-only mutation
-     Define a single permission matrix across PRIVATE/SHARED/PUBLIC...
-
-  3. Centralize object permissions across storefront and dashboard
-     Reusable `can_view_wishlist` / `can_edit_wishlist` methods...
-
-Why wrong:
-  - Looks grouped only implicitly; categories not visible as headers
-  - Uses `1..N` numeric IDs (should be `R1..RN`)
-  - Dumps `content` summaries — defeats the purpose of a landing view
-  - `detail R7` no longer maps to a stable ID
-
-PREFLIGHT — before printing 9.1 output, self-check:
-  □ Did I group by `metadata.category.name`?
-  □ Did I prefix each category with `1.`, `2.`, … `K.`?
-  □ Did I assign global `R1..RN` IDs across categories?
-  □ Did I show titles only (no summaries / no rationale)?
-  □ Is there a compact scope line above the list?
-  □ Does my action block use `R{N}` references that match the IDs above?
-
-If any answer is no, FIX BEFORE PRINTING.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-Full rail at the landing (Recommendations stage opens):
+First category (rail shown):
 
 ```text
 Ritual build
 ✓ Context  ✓ Scope  ✓ Discovery  ● Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Scope:
-{one-line compressed scope — ~80-120 chars; truncate the full problem
-statement at a natural clause boundary, no ellipsis}
-
-Recommendations ready
+{one-line compressed scope — ~80-120 chars; truncate at a clause boundary, no ellipsis}
 
-{N} recommendations across {K} categories.
+{N} recommendations across {K} categories. They're accepted by default —
+review and refine any, or proceed anytime.
 
-1. {Category 1 name}
-   R1 {title}
-   R2 {title}
+Category 1/{K} — {category name}
 
-2. {Category 2 name}
-   R3 {title}
-   R4 {title}
-   R5 {title}
+  R1  {title}
+      {content — the description, wrapped at terminal width, 1-3 lines}
+      Why this: {one-line Problem→Discovery→Tradeoff distillation, plain prose}
 
-3. {Category 3 name}
-   R6 {title}
+  R2  {title}
+      {description}
+      Why this: {...}
 
-...
+Pulse: Reasoning Readiness ~88% · Context Debt 12% (implementation-ready)
 
-Pulse: Reasoning Readiness ~88% · Context Debt 12% · +26% (implementation-ready)
-
-Recommended: reply `accept recommended` to approve these {N} and generate
-the build brief.
-
-Or reply:
-- `detail R7` to inspect one recommendation
-- `drop R8` to remove one before accepting
-- `change R3: <edit>` to revise one
-- `hold` to stop here
+Reply  edit R{N} <your change>   ·   next (Category 2/{K})   ·   proceed (build brief)
 ```
 
-Notes:
-
-- **Categories are numbered `1..K`** (their position on the page). **Recommendations get stable `R1..RN` IDs** across the whole set. The numbering is for reading orientation; the user references recs by `R{N}`, not by category number.
-- **One blank line between categories**; titles indent at 3 spaces (so the eye lands on the category name first, then the R-IDs scan down).
-- **Pulse uses full labels** per `references/cli-output-contract.md` § Pulse tier labels.
-- **`accept recommended`** is the visible CTA — NOT `accept all`. "Recommended" frames the action as "the curated set you see on screen"; "all" sounds like a bulk operation over deduped/hidden/raw recs.
-- **Surface 4 actions at first render — not more.** The four above (`detail R{N}`, `drop R{N}`, `change R{N}: <edit>`, `hold`) cover the decisive cases. Less-frequent actions stay discoverable but off-screen at the landing:
-  - **`add <topic>`** lets the user request an additional recommendation on the fly (e.g. `add telemetry` → agent calls `regenerate_recommendation` with a new rec hint, or asks the user to clarify what's missing). Surface it in `help` or on the 9.3 detail card, NOT in the landing action line — too many actions at once weakens the selection screen. If the backing API doesn't yet support targeted single-rec addition, prompt the user with: "I can add a rec for `{topic}` by regenerating the full set with that pinned — that takes ~30s. Or hold the current set and add manually via the web UI."
-  - **`show scope`** to expand the full problem statement (covered in 9.2).
-
-##### 9.2 — `show scope` handling
-
-When the user replies `show scope`, expand to the full problem statement (no rail repetition — this is a sub-view inside the same phase, use the in-phase chip):
+Subsequent categories (in-phase chip, no full rail):
 
 ```text
-Recommendations · Scope (full)
+Recommendations · Category 2/{K} — {category name}
 
-{full problemStatement, wrapped at terminal width}
+  R3  {title}
+      {description}
+      Why this: {...}
 
-Reply `back` to return to the recommendations list, or any of the regular
-recommendation actions.
-```
+  ...
 
-##### 9.3 — Detail card (when user replies `detail R{N}`)
+Reply  edit R{N} <your change>   ·   next (Category 3/{K})   ·   proceed (build brief)
+```
 
-In-phase chip + focused single-rec card. Use the LABELED-BLOCK shape per `references/cli-output-contract.md` § Dense list format. The "Why this" block REPLACES the `rationale` chained-arrow string — render it as 4 named lines, not the literal `Problem → Discovery → Tradeoff → Recommendation` arrow chain (which is the LLM's internal scratchpad shape, not user-facing).
+Notes:
 
-```text
-Recommendations — R7
+- **Global `R{N}` IDs** continue across categories (Category 2 starts at R3 if Category 1 held R1–R2). The R-ID is how the user references a rec in `edit R{N}`; never restart numbering per category.
+- **`content` (the description) and "Why this" ARE shown** at the walk — unlike the old titles-only landing. That's deliberate: the user reads and refines in place. Keep each rec to title + 1–3 description lines + one "Why this" line. If a rec's `acceptance_criteria` are short and genuinely useful you may add a single `Pass: {...}` line, but don't pad — the walk must stay scannable.
+- **One blank line between recs**; indent rec bodies under their `R{N}` so the eye lands on the title first.
+- **`proceed` is the primary CTA** and is offered on every category — the user never has to walk all categories to continue.
+- **On the last category**, the action line drops `next`; if the user types `next` there, reply: "That was the last category — reply `proceed` to continue, or `edit R{N}` to refine one."
 
-R7. {title}
+##### 9.2 — `edit R{N} <ask>`: preview, then apply
 
-Category:
-{metadata.category.name}
+This mirrors Spark's "Revise → Preview Revision → Apply revision" exactly: the change is **previewed before anything persists**.
 
-Recommendation:
-{content — direct, actionable summary; 2-4 sentences}
+1. Resolve `R{N}` → rec UUID from the walk's ID map.
+2. Call `mcp__ritual__suggest_recommendation_edit({ recommendation_id, instruction: "<the user's ask, verbatim>" })`. This runs an LLM and returns a **transient proposal** — nothing is mutated yet. It carries `id` (the proposal id), `summary` ("what changed"), and `diff[]` of `{ field, before, after }` where `field` is `title`, `description`, or `chain.<idx>`.
+3. **[USER PAUSE]** Render the preview and wait:
 
-Why this:
-- Problem: {one-line distillation from metadata.explainability.problem_alignment}
-- Discovery: {one-line distillation from metadata.explainability.faq_references[0].insight}
-- Tradeoff: {one-line distillation from rationale's "Tradeoffs (...)" segment}
-- Recommendation: {one-line distillation from rationale's "Recommendation (...)" segment}
+```text
+Recommendations · R{N} — proposed revision
 
-Tactics:
-- {short imperative — derived from metadata.acceptance_criteria where actionable}
-- {short imperative}
-- {short imperative}
+What changed: {proposal.summary}
 
-Acceptance criteria:
-- {metadata.acceptance_criteria[0]}
-- {metadata.acceptance_criteria[1]}
-- {metadata.acceptance_criteria[N]}
+Title
+- {before}
++ {after}
 
-References:
-- {file path or RB id from metadata.explainability.faq_references / referenced_faq_ids}
-- {reference}
+Description
+- {before}
++ {after}
 
-Reply `drop R7`, `change R7: <edit>`, or `back`.
+Why this — step {i}
+- {before}
++ {after}
 
-To move forward, reply `accept recommended` from the summary.
-If you only want a subset, `drop` the recs you don't want first, then `accept recommended`.
+Reply  apply (save this revision)   ·   discard (keep the original)
 ```
 
-Notes on the detail card:
-
-- **Per-rec and subset accept are first-class CTAs as of cli 0.9.6.** The MCP `accept_recommendations` tool now takes an optional `recommendation_ids: string[]` param: omit it to bulk-accept everything (legacy), or pass a subset to promote only those rec IDs. Surface `accept R7` (single from detail), `accept R5,R8,R12` (subset from landing), and `accept recommended` (all) as the three accept-shaped CTAs. The agent accumulates the approved subset across the one-by-one walk-through and submits ONE batch call at the end — not N individual calls.
-- The 4-line "Why this" block is a transformation of the chained-arrow `rationale` string. The arrow chain is fine as a one-line summary at the very bottom if helpful, but the 4-named-line form is the primary readable shape.
-- `Tactics` and `Acceptance criteria` are related but distinct: tactics are SHORT IMPERATIVE STEPS ("Call Django authenticate() / login() through configured backends"); acceptance criteria are PASS CONDITIONS ("Valid inline registration creates exactly one user and authenticates the session").
-- `References` come from `metadata.explainability.faq_references` (subject + question text) AND `referenced_faq_ids` (which the agent can resolve back to the underlying source files / RBs if known).
-- `back` returns to the landing summary, NOT to a new fetch — the agent should cache the recs from the landing call and re-render.
+   - Render ONLY the `diff` fields that are present. Map `field: "title"` → `Title`, `"description"` → `Description`, `"chain.<idx>"` → `Why this — step {idx+1}`.
+   - If the proposal's `diff` is empty (the LLM found no meaningful change), say so plainly and return to the category view unchanged — don't fabricate a diff.
 
-##### 9.4 — Action handling
+4. On `apply`: call `mcp__ritual__apply_recommendation_proposal({ recommendation_id, proposal_id })`. It persists a new version, replays the reasoning chain, and returns the applied proposal. Re-fetch the rec (`get_recommendations`) and **re-render the current category with R{N} updated in place**, then continue the walk (action line `edit R{N} <change> · next · proceed`).
+   On `discard`: return to the current category unchanged — nothing was persisted.
 
-Visible CTAs in 9.1 / 9.3 map to MCP/API actions. Some are direct, some require interpretation. The agent maps free-text replies to these actions:
+Editing is non-destructive and does not advance the flow — the user can `edit` several recs, across categories, before `proceed`.
 
-| User reply | Action | Backing call |
-|---|---|---|
-| `accept recommended` | Accept ALL recs currently on screen | `mcp__ritual__accept_recommendations({ exploration_id })` (omit `recommendation_ids` — admin only, see Branch B) |
-| `accept R{N}` (from detail) | Mark that single rec approved (batch of 1) | `mcp__ritual__accept_recommendations({ exploration_id, recommendation_ids: [rec_uuid_for_R{N}] })`. Exploration stays in REVIEWING_RECOMMENDATIONS if other recs remain in draft/pending; transitions to COMPLETE once nothing remains. |
-| `accept R{N},R{M},R{P}` (subset from landing) | Mark that subset approved (batch of N) | `mcp__ritual__accept_recommendations({ exploration_id, recommendation_ids: [rec_uuids…] })`. Single round-trip — don't loop N calls. |
-| `detail R{N}` | Render the detail card for that rec | None (in-memory) |
-| `change R{N}: <edit>` | Regenerate that single rec with the user's hint | `mcp__ritual__regenerate_recommendation(recommendation_id, hint)` if available; else queue as a comment + ask the user to wait for re-gen |
-| `drop R{N}` | Mark that rec rejected | `update_recommendation` with status=rejected, OR add a "deliberately excluded" note for the brief generator |
-| `add <topic>` | Request a new rec on the topic | See § 9.1 note — typically requires full regenerate with the new topic pinned; SKILL surfaces the choice to the user before triggering |
-| `show scope` | Expand the scope reference | None (in-memory) |
-| `hold` | Stop here without accepting | None (exits the flow; user can resume later) |
-
-Don't display all aliases. Display the most-likely-needed: `accept recommended`, `accept R{N}` (single), `detail R{N}`, `drop R{N}`, `hold`. Show `accept R{N},R{M}` (subset), `change R{N}: <edit>`, and `add <topic>` in the detail card or as a one-line hint when the landing screen is presented for the second time (the user knows the basics by then).
-
-**Subset-accept agent behavior — one call, not N:** when the user types `accept R5,R8,R12` (or accumulates approvals across the one-by-one walkthrough), the agent collects the rec UUIDs in memory and submits a SINGLE `accept_recommendations({ exploration_id, recommendation_ids })` call. Do not loop and call the tool once per rec — the API + downstream artifact-trigger is designed for one batch per "user is done with this set" event. Multiple calls inflate latency, multiply the triage-complete event emission, and cause duplicate auto-artifact queueing.
+##### 9.3 — `next` and `proceed`
 
-**Backlog notes** (referenced for the agent so it doesn't over-promise):
-- `add <topic>` requires a regenerate with a pinned topic — that's a forthcoming `regenerate_recommendation` improvement; until then it's a full regeneration cycle.
-- Per-rec MCP `reject` (status=rejected) doesn't have a dedicated MCP tool yet. For now, `drop R{N}` is handled via the web's per-rec PATCH OR by the user simply not including it in the batch-accept call (it stays in draft/pending until the user explicitly accepts or rejects it). Adding `reject_recommendation` MCP tool is on the backlog.
-
-##### 9.A — Branch A: admin replies `accept recommended`
-
-Call `mcp__ritual__accept_recommendations(exploration_id)`. Response includes counts (`promoted`, `alreadyApproved`, `skipped`, `transitionedToComplete`). Show the full rail at this completion state — Recommendations is done, Build brief comes next:
+- **`next`** → render the next category per § 9.1 (in-phase chip). After the last category, prompt `proceed`.
+- **`proceed`** (from any category) → call `mcp__ritual__accept_recommendations({ exploration_id })`. Under the non-blocking model this **records the human review** (stamps `reviewedAt` / `reviewedBy`) and advances; it is NOT a draft→approved promotion (the recs are already `approved`). The downstream artifacts were queued at rec-gen time, so this returns fast. Then show the completion rail and continue to Step 9.5:
 
 ```text
 Ritual build
 ✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
 
-Accepted {N} recommendations.
+Reviewed {N} recommendations.
 
 View: https://app.ritualapp.cloud/e/{exploration_id}
 
-Next: generating the build brief…
+Next: preparing the build brief…
 ```
 
-**Pulse (recommendations accepted):** Emit a pulse — this is almost always a state-tier crossing into **Recommendation-ready**. Render full.
+**Pulse (recommendations reviewed):** emit a pulse — this is almost always a state-tier crossing into **Recommendation-ready**. Render full.
 
 Continue to Step 9.5 (`Wait for requirements`).
 
-##### 9.B — Branch B: user is a collaborator (no admin acceptance available)
-
-Same landing screen as 9.1, but the action block changes — collaborators can request admin review instead of accepting directly:
-
-```text
-Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ● Recommendations  ○ Build brief  ○ Implementation (Your agent)
-
-Scope:
-{compact scope}
-
-Admin acceptance pending
-
-These recommendations are in {status — draft / pending_review}. Only an
-admin can formally accept them.
-
-1. {Category 1}
-   R1 {title}
-   R2 {title}
-
-...
-
-Recommended: reply `request admin review` to send these for approval.
-Or reply `detail R7`, `change R3: <edit>`, `drop R8`, or `hold`.
-
-(If your team allows it, you can continue to implementation before admin
-acceptance — Ritual will mark the exploration as `implemented_ahead` so
-the admin can reconcile later. Reply `continue` to take that path.)
-```
-
-Note the THREE-tier CTA structure for collaborators:
-1. `request admin review` — the recommended path (notifies admin, no implementation yet)
-2. `continue` — implement-ahead-of-acceptance (logs as `implemented_ahead`; admin can reconcile later)
-3. `hold` — stop entirely
-
-The `request admin review` action maps to the workspace notification endpoint (or falls back to a Slack/email DM the agent surfaces as a copyable message). The `implemented_ahead` path is documented in Step 11 / 12.
-
-If the user picks `continue`, proceed to Step 9.5. The `sync_implementation` call in Step 12 will automatically snapshot the rec status via the A1.5 column.
+<!-- lite:keep-end -->
 
 #### Step 9.5 — Wait for requirements (auto-triggered by Step 9)
 
@@ -2012,11 +1838,11 @@ Steps:
    | Response | Action |
    |---|---|
    | `status === 'READY'` | Proceed to Step 10 |
-   | `exists === false` (still null) for 3+ polls | The fire-and-forget hasn't reached the DB yet, OR Branch B was just hit (no LLM call yet). After several polls either keep polling OR proceed to Step 10 — the API auto-triggers generation inline if the set is still missing when the brief is requested (adds ~30s to the brief call but never hard-fails). |
+   | `exists === false` (still null) for 3+ polls | The fire-and-forget hasn't reached the DB yet, OR `proceed` (accept_recommendations) hasn't run yet (no LLM call yet). After several polls either keep polling OR proceed to Step 10 — the API auto-triggers generation inline if the set is still missing when the brief is requested (adds ~30s to the brief call but never hard-fails). |
    | `status === 'GENERATING'` | Keep polling |
    | `status === 'FAILED'` | Surface `errorMessage` to the user; offer to retry by calling `generate_build_brief` directly (which will auto-trigger a fresh generation), OR by hitting `POST /requirements?force=true` via the web UI |
 
-4. **Special case — Branch B from Step 9 (collaborator did NOT call accept_recommendations):** there's no fire-and-forget auto-trigger because accept never ran. Skip the polling entirely and let Step 10's auto-trigger handle requirement generation inline. The brief call will take ~30s longer than it otherwise would.
+4. **Special case — `proceed` not yet called (accept_recommendations hasn't run):** if the user jumped ahead without the rec-review `proceed`, there's no fire-and-forget auto-trigger from that path. Skip the polling entirely and let Step 10's auto-trigger handle requirement generation inline. The brief call will take ~30s longer than it otherwise would. (Note: auto-finalize at rec-gen completion usually already queued requirements, so this case is rare.)
 
 5. When `status === 'READY'`, tell the user one line ("Requirements ready…") and continue to Step 9.6 (if anti-goals exist) OR directly to Step 10 (if no anti-goals, audit step is skipped silently).
 
@@ -2210,15 +2036,15 @@ Call `mcp__ritual__generate_build_brief` with:
 - `recon_context` — the Step 3 `codebase_context_packet` plus any explicit phase/later candidates from discovery. Do not pass raw recon notes. This grounds "Codebase Anchors" in real file paths while keeping agent hypotheses auditable and non-authoritative.
 - `sources` — the **same** file-path array passed to `generate_considerations` and `generate_problem_statement` in Steps 4–5. Critical for KG consistency: the brief's "Previously Deferred" section only populates when overlapping prior implementations exist on these files.
 
-Returns the brief markdown + an `id` + `kgContextUsed` block. The brief is **idempotent on (exploration, icp)** — same recommendation+requirement hashes return the cached READY row. Pass `force: true` only when a prompt-version update requires re-generation.
+Returns **immediately** with `status: 'GENERATING'` (synthesis runs in the background — poll per Step 10b) UNLESS it's a cache hit, which returns `status: 'READY'` with the brief markdown directly. The brief is **idempotent on (exploration, icp)** — same recommendation+requirement hashes return the cached READY row. Pass `force: true` only when a prompt-version update requires re-generation (also returns `GENERATING` → poll).
 
-##### 10b — Timeout-recovery polling (CLI Tenet #8)
+##### 10b — Status polling (CLI Tenet #8)
 
-`generate_build_brief` can outlive the local MCP request timeout, especially when the API auto-triggers RequirementSet generation inline. You may see a local-timeout error while server-side work is still running.
+`generate_build_brief` is **fire-and-poll**: it returns almost immediately with `status: 'GENERATING'` (the synthesis runs server-side in the background) — NOT the finished brief. A cache hit returns `status: 'READY'` directly; treat that as done. So you no longer wait on a local timeout — you poll the status from the start.
 
-**Don't give up and don't blindly regenerate.** Instead, fall back to status polling:
+**Don't treat the GENERATING response as the brief, and don't re-call generate to "check".** Poll the status:
 
-1. On timeout/error from `generate_build_brief`, call `mcp__ritual__get_build_brief_status(exploration_id, icp)` immediately.
+1. After `generate_build_brief` returns `GENERATING` (or on the rare local timeout), call `mcp__ritual__get_build_brief_status(exploration_id, icp)`.
 2. Poll using the standard async polling rule: one `Bash sleep 5` per poll iteration, then a fresh status call. Print a brief "still generating…" update every ~3 polls when the status is unchanged.
 3. Exit conditions:
 
@@ -2394,6 +2220,7 @@ Branch by user response. The CTA on screen is `go`, but accept these as synonyms
 
 **Pulse (Step 10 done):** Emit a pulse — this often crosses into **Implementation-ready** (90%+). Render full when that crossing happens. Use the build-brief celebration line: `✓ Build brief ready — discovery has become an implementation path.` If still below 90% (e.g. brief flagged residual debt), surface that in the pulse line itself and propose addressing it before coding.
 
+<!-- lite:skip-start reason="optional UX brief review is not part of lite" -->
 #### Step 10.5 — Optional UX brief review (entered ONLY when the user picks `ux-review` at Step 10d)
 
 This step is opt-in. If the user picked `go` at Step 10d, skip directly to Step 11. The `ux-review` path is reached only when the user explicitly asks for it at the Step 10d gate — there is no auto-gating in this MVP (later iterations may use Stage E's UI-surface classifier to suggest the path automatically; see `backlog_design_recon_stage_e.md`).
@@ -2487,6 +2314,8 @@ Steps:
 
 **Pulse (Step 10.5 done):** Re-emit the Step 10 pulse if the review surfaced material gaps or mismatches — Readiness can dip back below 90% when significant UX work is flagged that the brief didn't capture. If the review came back clean (zero mismatches, zero gaps, zero new-work), keep the existing pulse — the brief was already implementation-ready.
 
+<!-- lite:skip-end -->
+<!-- lite:keep-start -->
 #### Step 11 — Implement
 
 This step happens **inside** the same `/ritual build` chat if the agent is also the coding agent (Claude Code / Cursor / etc.), or hand-off if the user is implementing themselves.
@@ -2577,9 +2406,23 @@ The user is now in plan mode (from Step 11.0.5). The agent must:
 
 1. **Load `BUILD-BRIEF.md`** as the first input. If `BUILD-BRIEF-VERIFICATION.md` exists, load it too — every `contradicted` and `not_found` entry becomes an explicit constraint in the plan ("the brief claimed X but the code does Y; the plan must reconcile / not assume X"). If `UX-REVIEW.md` exists alongside `BUILD-BRIEF.md` (the user opted into Step 10.5), use the "Plan Mode Prompt" block at its bottom as the FIRST input — its numbered list of mismatches / gaps / new-work surfaces is the tailored agenda. The generic plan-mode template is the fallback for when only the brief exists.
 
-2. **Produce a numbered implementation plan** whose top entries are: (1) the RBs from the brief, (2) any contradictions surfaced by verification, (3) any "new work" surfaces from UX review. The plan should name the specific files / functions / new modules each plan step will touch — concrete enough that the user can spot a mistake before any edit happens.
+2. **Load the SCOPE CONTRACT as hard constraints (the load-bearing step — prevention, not just detection).** The brief read (`get_build_brief_status` → `scopeContractResolved`, or the `generate_build_brief` response) carries the SAME typed contract Ritual will audit your plan against at Step 11.1.6. Treat it as binding and put it at the TOP of the plan-mode prompt verbatim:
+
+   > **Scope contract — your plan must honour this (it will be audited):**
+   > - **MUST cover** (one or more plan steps each, and cite the requirement): {each `scopeContractResolved.inScope[].text`}
+   > - **Do NOT implement — deferred to a LATER PR** (out of scope for this change): {each `deferred[].text`}
+   > - **Do NOT cross — non-goals**: {each `antiGoals[].text`}
+   > - **Open questions — do NOT silently implement; flag if you must touch**: {each `discoveryGates[].text`}
+
+   This is what makes plan mode deliver on the promise of the brief (which delivers on the recs). Feeding the contract in UP FRONT prevents the divergences Step 11.1.6 would otherwise have to catch and send back.
 
-3. **Stay in plan mode until the user accepts the plan.** Do NOT switch to edit/auto-accept mode until the user explicitly approves the plan in plan mode (Claude Code's "accept plan" affordance, or the user typing `accept` / `looks good` / `go`).
+3. **Produce a numbered implementation plan** that:
+   - has **one or more steps covering EVERY in-scope requirement** above (map each step to the requirement id it implements — this is the coverage the audit checks),
+   - implements **none** of the deferred items and crosses **none** of the non-goals,
+   - puts the RBs, any verification contradictions, and any UX "new work" surfaces at the top,
+   - names the specific files / functions / new modules each step touches — concrete enough that the user can spot a mistake before any edit.
+
+4. **Stay in plan mode until the user accepts the plan.** Do NOT switch to edit/auto-accept mode until the user explicitly approves the plan in plan mode (Claude Code's "accept plan" affordance, or the user typing `accept` / `looks good` / `go`).
 
 ##### 11.1.5 — Optional: save the implementation plan as a markdown artifact
 
@@ -2622,6 +2465,87 @@ Save this plan to `IMPLEMENTATION-PLAN.md` before coding? (y/N)
 
 **Why this matters:** `BUILD-BRIEF.md` is the Ritual requirements artifact (what + why). `IMPLEMENTATION-PLAN.md` is the agent's concrete execution strategy (how). For non-trivial implementations, saving both gives reviewers a useful bridge from requirement to code — and gives `/ritual lineage` queries a richer trail to surface on future builds touching the same files.
 
+<!-- lite:skip-start reason="optional plan-fidelity audit is not part of lite" -->
+##### 11.1.6 — Optional: audit the plan against the brief (Audit 3 / plan-fidelity)
+
+After plan mode produces the plan and **before any code edits**, you can audit the plan against the build brief's frozen **scope contract** (its in-scope requirements, discovery-gate requirements, and anti-goals). This is **Audit 3 / R6** — the downstream bookend to the Step 9.6 recs audit. It's non-circular by construction: the contract derives from discovery/recs, never the plan, so a flagged divergence is a real drift, not a tautology.
+
+**Gate behavior by build mode** (from Step 0.1's `auditMode`):
+
+- **`normal` (default):** offer it; default is to skip (most plans are faithful).
+- **`audited`:** recommend it (default yes).
+- **`strict`:** run it automatically (no prompt), and treat an `anti_goal_violation` as blocking.
+
+**Rendering contract — verbatim (normal / audited modes):**
+
+```text
+Plan ready — audit it against the brief before coding?
+
+Ritual can check this plan against BUILD-BRIEF.md's scope contract — flagging
+anything the plan drops (a brief requirement no step covers), sneaks in
+(out-of-scope work), or that crosses a non-goal — before you write code.
+
+Reply `audit-plan` to run it, or `proceed` to start implementing.
+```
+
+[USER PAUSE] Branch on response:
+
+- **`audit-plan`** (or auto, in `strict` mode): call
+  `mcp__ritual__audit_plan(exploration_id, plan_content)` where `plan_content`
+  is the implementation plan plan mode just produced (the same text you'd save to
+  `IMPLEMENTATION-PLAN.md`). The server normalizes it to plan operations and runs
+  R6 against the brief's scope contract. It's async — the tool polls to
+  completion and returns a thin payload:
+  - `audit_status: "ok"` (no divergences) → tell the user the plan is faithful to
+    the brief and continue to Step 11.2.
+  - `audit_status: "needs_attention"` → render each divergence (`divergence_kind`
+    + the `plan_op` and/or `brief_reference` it concerns + `rationale`). Group by
+    kind: **missing_brief_decision** ("the brief asked for X; no plan step covers
+    it" — computed deterministically from coverage), **out_of_scope_addition**
+    ("step N does X, which maps to nothing in the brief"), **premature_implementation**
+    ("step N implements X, which the brief deferred to a LATER phase/PR — not this
+    one"), **scope_creep** ("step N covers X but does substantially more"). Then
+    pause: *"Revise the plan to address these (back to plan mode), or proceed and
+    accept the divergences? Reply `revise` or `proceed`."*
+  - `audit_status: "blocked"` (an `anti_goal_violation`) → surface it prominently:
+    *"⚠ The plan advances something the brief explicitly forbids: {evidence}. This
+    crosses a non-goal you set during discovery."* In `strict` mode this blocks —
+    require `revise` or an explicit `override` with a one-line justification. In
+    other modes, strongly recommend `revise`.
+  - On `revise`: the audit response carries a ready-to-paste **`revision_directive`**
+    (assembled from the structured `revisions[]`, blockers first — each is a
+    `request_plan_revision` repair keyed to a specific divergence). Feed that
+    directive **verbatim** back into plan mode as the revision agenda (back to
+    Step 11.1, keeping the scope contract from 11.1's step 2 in force), let plan
+    mode produce a revised plan, then **re-run `audit_plan` on the revised plan**.
+    This is the runtime repair loop: `audit_plan` → `revise` → `audit_plan`.
+    - **Cap it at 2 revision rounds.** If divergences remain after the 2nd
+      revision, stop looping and surface the residual divergences to the user with
+      a decision: *"These divergences persist after 2 revisions — accept them
+      (they'll be logged), or stop here? Reply `accept` or `pause`."* Don't churn.
+  - On `proceed` / `override` / `accept`: continue to Step 11.2. Treat each
+    accepted divergence as a **`confirm_intentional_divergence`** — record it as a
+    Step 12 `sync_implementation` decision (`area` = the requirement/anti-goal,
+    `choice` = "intentionally diverged: {why}", `source_recommendation_id` = the
+    `brief_reference.id`) so the override is captured in lineage rather than lost.
+    A persistent *anti-goal violation* the user keeps overriding is a signal the
+    BRIEF (or its anti-goals) is wrong — surface that, don't just bury it.
+- **`proceed`** (or anything else): skip the audit and continue to Step 11.2. Do
+  not re-prompt.
+
+**Rules:**
+
+- **Requires a READY BuildBrief with a scope contract.** Briefs synthesized before
+  the scope-contract feature lack one; if `audit_plan` returns a 400 about a
+  missing contract, regenerate the brief (`generate_build_brief force:true`) or
+  skip the audit — don't block the build on it.
+- **Advisory, not auto-repair.** R6 surfaces divergences; the fix is always a
+  human-in-the-loop plan revision or an explicit accept. Never silently rewrite
+  the plan.
+- **Don't dump the raw normalized plan ops** into the chat — surface the
+  divergences (the signal), not the methodology.
+
+<!-- lite:skip-end -->
 ##### 11.2 — Implement
 
 1. Use the standard coding-loop tools (Edit/Write/Bash/etc.) to execute the accepted plan.
@@ -2669,40 +2593,55 @@ If the user says "y" / "push" / "open PR":
 3. `gh pr create --base <default-branch> --title <…> --body <…>`.
 4. Surface the PR URL to the user.
 
+**Write the PR body for a maintainer who has never heard of Ritual.** Lead with what changed, *where to look* (in review order), *why*, and *how to verify* — so a reviewer can move fast and trust the change. Ritual lineage goes at the bottom, not the top. Fill every section from real artifacts (brief decisions, the diff, the test files); never leave a `<placeholder>` in the posted body.
+
 **PR body template:**
 
 ```markdown
-## Summary
+## What this PR does
 
-<2-3 lines max, derived from the build brief's Goal section>
+<2-3 plain sentences: the change + the problem it solves, derived from the build brief's Goal>
 
-## RBs satisfied
+## Where to look (review order)
 
-| RB | Title | Where |
-|---|---|---|
-| RB-1 | <title from brief> | <key file/module> |
-| RB-2 | <title from brief> | <…> |
-| … | | |
+1. `<path>` — <the load-bearing change; start here>
+2. `<path>` — <how it integrates>
+3. `<path>` — <schema/data changes, if any>
+   <ordered load-bearing → plumbing, so review time goes where it matters>
 
-## Test plan
+## Why / key decisions
 
-- <one bullet per test file / suite added>
-- <coverage notes if non-trivial>
+- <decision + the trade-off / alternative rejected — the 1-3 calls a reviewer might second-guess, taken from the brief's decisions>
 
-## Exploration
+## How to verify
 
-- Exploration: [<exploration name>](https://app.ritualapp.cloud/e/<exploration_id>)
-- Build brief: see `BUILD-BRIEF.md` (committed in this PR for reviewer reference)
-- Implementation plan: see `IMPLEMENTATION-PLAN.md` *(only include this line if Step 11.1.5 actually wrote the file — agent execution strategy alongside the brief)*
-- Deferrals intentionally punted: <count, with one-line each>
+- Automated: <test files + how to run them>
+- Manual: <steps a reviewer runs locally to see it work>
 
----
+## Scope & follow-ups
+
+- In scope: <what this PR delivers>
+- Out of scope / deferred: <intentional punts, one line each — so reviewers don't flag them as gaps>
+
+## Risk / blast radius
+
+- <backward-compat, migration ordering, perf — what could break in prod>
+
+## Ritual lineage
+
+- Exploration: [<exploration name>](<EXPLORATION_URL>) · Build brief: `BUILD-BRIEF.md` (committed for reviewer reference) · Requirements satisfied: <N/M>
+- Implementation plan: see `IMPLEMENTATION-PLAN.md` *(only if Step 11.1.5 wrote it)*
+
+Ritual-Exploration: <exploration_id>
 
 🪷 Generated via [Ritual](https://ritual.work) — closing the loop with `sync_implementation` after merge.
 ```
 
+> **`<EXPLORATION_URL>` MUST be environment-correct — never hardcode `app.ritualapp.cloud`.** Use the server-resolved exploration URL the MCP returns (built from the server's `WEB_URL`). Hardcoding production breaks the link for **dev** builds (the exploration lives in the dev DB) and for **self-hosted / single-tenant enterprise** deployments (the exploration lives on the customer's own Ritual instance, not Ritual's SaaS). If the MCP response does not carry a URL, derive the base from your Ritual auth issuer rather than assuming production. Same rule for the `Ritual-Exploration-Url` commit trailer.
+
 If the user is implementing manually: hand off the brief + the branch-strategy note ("create a feature branch off `main` — don't commit to trunk"), tell them you'll be ready to run `sync_implementation` when they're done.
 
+<!-- lite:keep-end -->
 #### Step 12 — Close the loop with `sync_implementation`
 
 ##### 12.0 — What this step does (in product terms)
@@ -2741,7 +2680,7 @@ Call `mcp__ritual__sync_implementation` with:
 - `deferrals[]` — for things you intentionally punted (`rb_id`, `description`, `reason`, `severity`, `related_files[]`, `related_modules[]`)
 - `gate_verdict`, `adherence_rate` — your own self-reported quality signals
 
-The A1.5 snapshot column auto-captures each linked recommendation's status at the moment of sync — so if you implemented while the rec was still `draft` (Branch B in Step 9), the timeline is preserved automatically.
+The A1.5 snapshot column auto-captures each linked recommendation's status at the moment of sync — so if you implemented before the rec review's `proceed` (while the rec was still un-reviewed), the timeline is preserved automatically.
 
 When sync_implementation succeeds, the response includes:
 
@@ -2773,7 +2712,7 @@ any touched file to trace this back later.
 
 The `Implemented:` line surfaces a representative slice of WHAT got implemented (concrete area:choice pairs from the underlying `decisions[]` payload) rather than a labeled count. Per the vocabulary rule in `cli-output-contract.md`: the word "decisions" is not surfaced as a user-facing label; the artifacts ARE the signal.
 
-If any anchor's `recommendationStatusAtImplementation` is NOT `approved` (i.e. the Branch B path), add a callout — still frame in implementation/recommendation terms. Append this block BELOW the completion message (no separate rail; the rail is already rendered at the top):
+If any anchor's `recommendationStatusAtImplementation` is NOT `approved` (i.e. implemented before the rec review's `proceed`), add a callout — still frame in implementation/recommendation terms. Append this block BELOW the completion message (no separate rail; the rail is already rendered at the top):
 
 ```text
 ⚠ {M} of the recommendations were implemented while still in {status}
@@ -2850,7 +2789,85 @@ Reply `1`, `2`, or `3`. Reply `pause` to stop here.
 
 If the saved payload's `commits[]` matches current git state, proceed silently to the retry.
 
-#### Step 13 — Optional follow-up
+<!-- lite:keep-start -->
+#### Step 13 — Suggest the next job to be done
+
+The loop just closed (Step 12). Rather than stop cold and make the user
+re-bootstrap context for whatever they do next, offer the **next best job to be
+done** — a NEW discovery exploration in THIS workspace, so the knowledge graph,
+deferrals, and prior explorations you just built keep compounding. This is
+forward motion, never required work.
+
+##### 13.1 — Generate the suggestion set
+
+Call `mcp__ritual__suggest_next_job` with `{ exploration_id }` (the
+just-finished exploration). It returns 1 primary + up to 2 alternatives. Each is
+a NEW exploration that runs its own discovery — it is **never** "go implement the
+recommendations you already have" (that's the coding agent's job — `/ritual
+resume` on this same exploration). Each suggestion carries:
+
+- `jtbd` + `label` — the job, already picked
+- `reasoning` — the concrete signal it cites (a deferral, an unaddressed recommendation, or the natural lifecycle continuation)
+- `descriptionSeed` — a first-person "what to explore" framing to pre-fill the next exploration's problem box
+- `recommendedPersona`, `sourceRecommendationId`, `id`
+
+Also returned: `recommendationsAddressed` (false ⇒ this exploration still has
+clear-to-implement work that ships via `resume`, not a next job).
+
+- **If `suggestions` is empty** (or the call errors) → say nothing about next jobs; drop straight to 13.3. Never block the closed-loop completion on this.
+
+##### 13.2 — Present the picker
+
+**[USER PAUSE]** Render the standard list-picker (primary first, marked ★):
+
+```text
+Next job to be done
+
+{exploration name} is shipped and logged. To keep building on what this
+workspace now knows, here's the next discovery worth running:
+
+★ 1. {primary label}
+     {primary reasoning}
+
+  2. {alt1 label}
+     {alt1 reasoning}
+
+  3. {alt2 label}
+     {alt2 reasoning}
+
+Reply `1`, `2`, or `3` to start it — the job's already picked, so you'll go
+straight to framing what to explore. Reply `skip` to stop here.
+```
+
+Only render lines for the suggestions actually returned (there may be just a
+primary, or a primary + 1). If `recommendationsAddressed` is `false`, add ONE
+line below the picker — lean on the coding agent, don't turn Ritual into a
+backlog manager:
+
+```text
+({N} item{s} from this exploration are clear to implement — say `resume` to continue shipping them here.)
+```
+
+**[USER PAUSE — required, do not auto-answer]** Wait for the user's reply.
+
+##### 13.2.1 — On pick (`1` / `2` / `3`)
+
+The picked suggestion is a NEW exploration in the SAME workspace with the job
+already chosen — so **advance, don't re-bootstrap**:
+
+1. Skip the work-item / job pick entirely (Steps 0–4) — `jtbd` is already set by the suggestion.
+2. Go to **Step 5 (problem frame)** using the suggestion's `descriptionSeed` as the DRAFT "what are you trying to explore?" — present it as an editable starting point, not a blank box. Let the user refine it.
+3. At **Step 6 (`create_exploration`)**, pass `from_next_job_suggestion_id` = the picked suggestion's `id`. The server links the new exploration to its parent + source recommendation, defaults the `jtbd` from the suggestion, and marks the suggestion started (it stops showing as an open next job, and the originating recommendation now reads as handed off).
+   - If `create_exploration` returns **409** (this next job was already started), don't create a duplicate — tell the user it's already in progress and offer to open that exploration instead.
+4. Continue the normal flow from **Step 7 (discovery)**.
+
+##### 13.2.2 — On `skip`
+
+Acknowledge and drop to 13.3. The suggestion set is persisted — a later `ritual
+graph status` or re-run of `/ritual build` in this workspace can surface it
+again; nothing is lost.
+
+##### 13.3 — Follow-up pointer
 
 If they want to check the state at any time, point them at:
 
@@ -2858,9 +2875,10 @@ If they want to check the state at any time, point them at:
 
 Or: re-run `/ritual build` in this workspace later — the existing-work check will surface this exploration with its new `done` state badge, and any future build whose `sources` overlap will pull in the decisions + deferrals you just logged as priorContext.
 
+<!-- lite:keep-end -->
 ### Failure modes & recovery
 
-**Discovery generation hangs (>5 min polling without `ready: true`)**: ask the user — wait longer? retry (`suggest_discovery_questions` again, new task)? or skip discovery entirely (proceed to Step 8 without picked questions)?
+**Discovery generation hangs (>5 min polling without `ready: true`)**: ask the user — wait longer, or retry (`suggest_discovery_questions` again, new task)? Discovery questions are required (the user must pick at least 6 to run), so there is no skip-and-proceed option; if generation can't produce questions, surface the failure rather than running with none.
 
 **Agentic run fails or stalls**: surface the error, offer retry or stop.
 
@@ -2908,8 +2926,9 @@ This subcommand exclusively uses Ritual MCP tools, in the order they appear:
 24f. `mcp__ritual__apply_repair` (Step 9.6 — apply or waive a structured repair instruction returned by an audit iteration; cli 0.10.0+)
 24g. `mcp__ritual__get_audit_chain` (Step 9.6 — fetch the full chain trail for review/lineage; cli 0.10.0+)
 25. `mcp__ritual__sync_implementation` (Step 12)
+26. `mcp__ritual__suggest_next_job` (Step 13.1 — propose the next discovery job after the loop closes; `create_exploration` at Step 13.2.1 takes `from_next_job_suggestion_id` to record the handoff)
 
-35 of the 46 Ritual MCP tools (cli 0.10.0+: the 3 new audit tools — `audit_recommendations`, `apply_repair`, `get_audit_chain` — joined the linear flow at Step 9.6 (audit-suite.md § Audit 1)). The other 11 (`ping`, `get_exploration`, `list_agentic_runs`, `add_collaborator`, `check_anti_goals`, `query_knowledge_graph`, `get_workspace_overview`, `get_knowledge_source`, `remove_knowledge_source`, `get_recommendation_attestation`, `score_context_pulse`) are situational, not part of the linear build flow.
+36 of the 48 Ritual MCP tools (cli 0.10.0+: the 3 audit tools — `audit_recommendations`, `apply_repair`, `get_audit_chain` — joined the linear flow at Step 9.6 (audit-suite.md § Audit 1); cli 0.22.0+: `suggest_next_job` joined at Step 13 to close-then-continue the loop). The other 12 (`ping`, `get_exploration`, `list_agentic_runs`, `add_collaborator`, `check_anti_goals`, `query_knowledge_graph`, `get_workspace_overview`, `get_knowledge_source`, `remove_knowledge_source`, `get_recommendation_attestation`, `score_context_pulse`, `get_next_job`) are situational, not part of the linear build flow (`get_next_job` re-reads a persisted next-job set; the flow itself only needs `suggest_next_job`).
 
 **Note on `check_anti_goals` vs `audit_recommendations`:** these are distinct tools. `check_anti_goals` is the older, single-shot validation tool (read-tier; one LLM call, no chain rows) used ad-hoc to validate a proposal against an exploration's current anti-goal set. `audit_recommendations` (cli 0.10.0+, write-tier) starts a stateful `AuditChain` that runs R4 (constraint-perturbation) against a brief, produces structured `SurvivalReport` + `RepairInstruction` rows, and supports the apply/waive repair loop. Use `check_anti_goals` for one-shot proposal validation; use `audit_recommendations` for chain-tracked constraint-survival audits of a brief.
 
@@ -2918,8 +2937,8 @@ This subcommand exclusively uses Ritual MCP tools, in the order they appear:
 When `/ritual build` completes, the exploration is in COMPLETE state with accepted recommendations AND a build brief has been generated AND (if the agent implemented in-chat) `sync_implementation` has been called. The full close-the-loop cycle now lives inside this skill — there's no separate downstream `/ritual-builder-spec` step required.
 
 Variants:
-- Admin runs the whole flow: Steps 1 → 13, no handoff.
-- Collaborator runs the build flow: Steps 1 → 13 with Step 9 Branch B (no admin acceptance available); the resulting exploration shows `⚠ implemented_ahead` until an admin reconciles.
+- One person runs the whole flow: Steps 1 → 13, no handoff. Step 9 is a uniform non-blocking review (recs are auto-accepted; `proceed` records the review and continues).
+- Implementation lands before the rec review/`proceed`: the `sync_implementation` snapshot freezes that timeline and the exploration shows `⚠ implemented_ahead` until reconciled (see Step 12).
 - Resume mid-flow: the existing-work check surfaces explorations with state badges and jumps directly to the right phase. (Or, for the "I just want to pick up" intent, see `/ritual resume` below.)
 
 ---