@ritualai/cli 0.7.9 → 0.7.11

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

@@ -12,17 +12,23 @@ The Ritual data model uses product-research terminology. This skill translates t
 |---|---|
 | **scope** | `problemStatement` |
 | **sub-problem** | `consideration` |
-| **matter** | `matter` (no rename — already the right word) |
+| **Area** (NOT "matter") | `matter` |
 | **discovery question** | `question` |
 | **recommendation** | `recommendation` |
 
 When the user says "tighten the scope," call `generate_problem_statement(...)` with their refinement. When you tell the user "I picked these sub-problems," you mean the items you put in `considerations[]`. The tools don't change; only the language to the user does.
 
+**On "Area" vs "matter":** the API field is `matter` for historical reasons. The user-facing label is **Area** because it's plainer and reads less research-y in a developer flow. NEVER surface "matter" or "matter.name" in user-facing copy — use "Area" / "Area name" instead.
+
 
 ### Runtime contracts
 
 Before running this flow, apply `references/cli-output-contract.md` and `references/async-polling.md`. Keep raw recon internal, pass the `codebase_context_packet` downstream, and show the user only the compact `recon_digest`.
 
+**Build rail is load-bearing.** Every top-level user-facing message below MUST begin with the 6-stage build rail per `references/cli-output-contract.md` § Build progress anchor. Examples in this file show the rail in context; the canonical stage table + `progressHeader(stage)` spec lives in the output contract. Do not drop the rail to save space.
+
+For narrow/mobile chat surfaces, use the **compact progress anchor** defined in `references/cli-output-contract.md` § Build progress anchor (the `Ritual build · 2/6 Scope` chip) instead of forcing the full six-stage rail to wrap. Same contract, different rendering.
+
 ### When to use
 
 - The user describes a new feature, refactor, migration, or implementation-heavy change that needs planning before coding
@@ -96,7 +102,6 @@ Recommended: turn off auto-mode before continuing.
 
 Regardless of which option the user picks, treat every subsequent `[USER PAUSE]` in this flow as a hard stop. Do not infer answers from context, do not pick a "reasonable default," do not press on without an actual user reply. The user picking option 2 means *they accept the trade-off* — it does NOT grant you permission to auto-answer the gates that come next.
 
-#### Step 1
 #### Step 1 — Pick a workspace
 
 Resolution order:
@@ -392,7 +397,7 @@ Steps:
      > **{candidate.name}** *(LLM confidence: {Math.round(candidate.llmConfidence * 100)}%)*
      > - *"{candidate.problemStatement first 120 chars, no ellipsis padding}..."*
      > - Why I think it overlaps: {candidate.llmRationale}
-     > - URL: `https://dev.ritualapp.cloud/e/{candidate.explorationId}`
+     > - URL: `https://app.ritualapp.cloud/e/{candidate.explorationId}`
      > {endfor}
      >
      > **Choose:**
@@ -481,6 +486,17 @@ Proceed to Step 3 once a template is selected. No extra confirmation is required
 
 Before generating considerations, gather codebase context so the sub-problems land specific to *this* code, not generic. The goal is not to show the user every fact you found; the goal is to ground downstream MCP calls and expose only decision-relevant findings in the CLI.
 
+**Capability Boundary Check (load-bearing):** If recon detects a mismatch between the user's ask and what THIS repo can actually implement — typically because the feature spans systems (backend service, mobile app, billing provider, email worker, schema migrations) that aren't present in the current checkout — DO NOT invent the missing systems and DO NOT continue as if the repo is complete. Run the boundary-check pause described in § 3.2 below before proceeding to scope. Frame the missing half as a normal architecture boundary, not a failure: *"This repo looks like the frontend side of a larger feature,"* not *"I could not find backend dependencies."* The user has not done anything wrong; the agent is asking how to scope the work.
+
+Common boundary mismatches to detect:
+
+- Full-stack feature ask + frontend-only repo (UI present, no API/service code)
+- Mobile feature ask + no API client contract or backend
+- Billing/payments feature + no payment service / subscription code
+- Email/notification feature + no worker / job / email-provider integration
+- Auth/session feature + no user mutation / session backend
+- Data/analytics feature + no schema, migration, or storage layer
+
 ##### 3.0 — Check for a pre-build context seed
 
 Before doing fresh recon, check whether the user already seeded one via `/ritual context-pulse`. Glob for `CONTEXT-*.md` at the repo root.
@@ -584,12 +600,12 @@ If no seed file is found, OR the seed's `## The ask` doesn't match the current `
    - No `guest_session_id` column was found in the inspected conversion models; scope may need to use the actual guest attribution identifiers.
    ```
 
-   Example `recon_digest`:
+   Example `recon_digest` — single-path case (low ambiguity):
 
    ```text
-   Code recon complete
+   Code recon
 
-   Key surfaces:
+   Repo signals:
    - `apps/conversions/abstract_models.py` — append-only conversion events.
    - `apps/conversions/outbox.py` — async publish/retry lifecycle.
    - `apps/order/models.py` — raw guest email surface.
@@ -600,16 +616,128 @@ If no seed file is found, OR the seed's `## The ask` doesn't match the current `
    Scope correction:
    - I did not find `guest_session_id` in the inspected models.
 
-   Next: attach PRDs/tickets if they should shape scope, or proceed.
+   Pulse: Reasoning Readiness ~55% · Context Debt 45% (initial ask + code recon)
+
+   Next: attach PRDs/tickets if they should shape scope, or `proceed` to continue.
+   ```
+
+   Example `recon_digest` — ambiguity case (multiple plausible interpretations):
+
+   When recon surfaces two materially different product/implementation paths for the same ask, name them both, **mark one as recommended with a one-line reason**, and pause with a concrete reply syntax. Do not expose raw tier labels (use the translations from `references/cli-output-contract.md`).
+
+   ```text
+   Code recon
+
+   Repo signals:
+   - `GatewayForm` already supports "create account before checkout," but
+     redirects away from checkout to `customer:register`. There is no inline
+     or post-order account path today.
+   - Guest checkout is already wired through order placement:
+     `CheckoutSessionData.set_guest_email()`, `AbstractOrder.guest_email`, and
+     `build_submission()` preserve guest identity.
+   - `RegisterUserMixin` is the reusable account-creation surface:
+     user creation, `user_registered`, login, and registration email.
+   - `OrderPlacementMixin` and `post_checkout` are the clean hooks for
+     creating or claiming an account at order placement.
+
+   Constraint:
+   - Oscar's dynamic class loading via `get_class()` is the extension
+     pattern here. Implement with subclass-overridable views/mixins, not
+     monkey-patches.
+
+   Ambiguity to resolve:
+   "Join while booking" maps to two plausible features.
+
+     1. Inline registration at checkout
+        Let new customers register on the checkout page itself instead of
+        being redirected to `/accounts/register/`.
+
+     2. Post-order account creation — recommended
+        Let guests place the order as today, then claim the order by
+        setting a password on the thank-you page. Preserves guest checkout
+        and fits Oscar's `OrderPlacementMixin` / `post_checkout` hooks.
+
+   Pulse: Reasoning Readiness ~35% · Context Debt 65% (scope not locked yet)
+
+   Next: reply `2` for the recommended post-order path, `1` for inline
+   registration, or describe a different intent. Reply `pause` to stop here.
+   ```
+
+   Notes on the ambiguity-case shape:
+   - **"Repo signals"** (not "Found" or "Key surfaces") signals these are the evidence behind the recommendation.
+   - **Recommendation goes after the option name on the SAME line**, with a single concise reason on the line below. This keeps the options scannable in a decision moment.
+   - **`Next:` is a single line** ending in a concrete reply syntax (`reply N`), not an open-ended question. Lead with the recommended default; the escape hatch comes last.
+   - **The pulse line uses the user-facing label**, never the raw tier identifier.
+
+   Example `recon_digest` — Capability Boundary Check (feature spans systems not in this repo):
+
+   When the user's ask requires capabilities that aren't present in this repo (frontend-only repo asked for full-stack feature, mobile repo with no API contract, etc.), surface the boundary as a normal architecture fact and give the user three concrete scoping options. NEVER continue as if the repo can implement the missing half; NEVER invent the missing systems.
+
+   ```text
+   Code recon
+
+   Action needed
+
+     This feature likely spans another repo or service.
+     Add the backend/API context, or choose a narrower scope.
+
+   Repo boundary:
+   - This repo contains the checkout UI and guest checkout flow.
+   - I found no backend account-creation endpoint, user/order linking
+     mutation, email job, or migration layer.
+   - So the full "join while booking" feature likely spans this repo plus
+     an API/backend service.
+
+   Can build here:
+   - Checkout/thank-you page UI
+   - Password capture or account-claim form
+   - API client integration point
+   - Mocked frontend tests
+   - Empty/error/success states
+
+   Needs outside context:
+   - Endpoint that creates or claims the account
+   - Contract for linking a guest order to a user
+   - Auth/session behavior after claim
+   - Email/verification behavior, if required
+
+   How should I scope this?
+
+     1. Frontend-only
+        Build the UI against an existing API. I'll ask for the endpoint/
+        contract next.
+
+     2. Contract-first — recommended if the API is not settled
+        Define the API contract and frontend integration here, then produce
+        a backend build brief for the missing service work.
+
+     3. Add backend repo/context
+        Pause here while you point me at the backend repo or docs, then I'll
+        recon the full path.
+
+   Pulse: Reasoning Readiness ~30% · Context Debt 70% (repo boundary unresolved)
+
+   Next: reply `2` for contract-first, `1` for frontend-only, or `3` to add
+   backend context. If you already know the API, paste the endpoint or
+   contract and I'll continue.
    ```
 
+   Notes on the boundary-check shape:
+   - **Lead with an "Action needed" callout block** that names the boundary in one sentence + the user's choice in one sentence. This is a load-bearing decision gate — leading with the callout (rather than the data) makes the gate pop in scrollback. Use this callout style only for boundary checks and other high-importance gates; ordinary recon stays in the standard `recon_digest` shape.
+   - **"Repo boundary:" not "I couldn't find…"** — frame the missing half as an architecture fact, not as a failure or as something the user did wrong. The agent is asking how to scope, not reporting an error.
+   - **"Can build here:" + "Needs outside context:"** are paired sections — they tell the user the explicit IN/OUT split for THIS repo so they can make an informed scoping decision. Don't merge them into one bullet list.
+   - **Three scoping options, recommendation on option 2 by default** — frontend-only / contract-first / add-context covers the realistic decision space. Mark "Contract-first" as recommended when the API surface is not yet defined; mark "Frontend-only" recommended when the user signaled they already have a stable API.
+   - **The pulse line stays parenthetical** with a user-facing reason (`repo boundary unresolved`), per the Pulse tier labels rule in `references/cli-output-contract.md`.
+   - **Internal classification (not user-facing):** track each candidate piece against the boundary as `in_repo_buildable`, `external_dependency_known`, `external_dependency_unknown`, `needs_additional_repo`, or `contract_first_candidate`. These shape how downstream scoring + build-brief generation handle the missing half once the user picks an option. None of these labels should appear in user-facing copy.
+
 ##### 3.2 — Surface the digest and continue
 
 Surface only `recon_digest` by default. Do **not** dump `raw_recon_notes` or the full `codebase_context_packet` to the CLI unless the user asks for detail.
 
 Pause only if:
 - recon contradicts the user's stated scope,
-- there are multiple plausible implementation areas and choosing wrong would waste work,
+- there are multiple plausible implementation areas and choosing wrong would waste work (use the ambiguity-case `recon_digest` shape above),
+- **recon shows the feature spans systems not in this repo** (use the Capability Boundary Check `recon_digest` shape above — frontend-only repo, missing API/service, etc.),
 - a legal/product/business constraint is required before generation,
 - the user explicitly asked to review recon before continuing.
 
@@ -646,21 +774,22 @@ Knowledge sources are a feature multiplier, not a mandatory gate. Ask for PRDs/t
 - the feature has legal, privacy, billing, permissions, enterprise, analytics, migration, or compliance constraints,
 - code recon found implementation surfaces but not product intent.
 
-When triggered, frame references as an optional booster, not a mandatory phase. The happy path is to continue. Render this prompt:
+When triggered, frame references as an optional booster, not a mandatory phase. The happy path is to continue. Keep the prompt tight — the user's decision here is simply "attach context or continue":
 
 ```text
 Optional: add non-code context before scope generation.
 
-Because this touches {legal/privacy/billing/permissions/analytics/migration/etc.}, PRDs, tickets, designs, chat excerpts, prior incidents, or customer requests may change what we prioritize.
-
-Next: we'll generate a list of suggested problems to pick from.
+Because this touches {constraint}, PRDs, tickets, designs, incidents, or
+customer requests may change what we prioritize.
 
-Press Enter or type `g` to generate the list.
+Reply `go` to continue with code context only.
 Or paste files/text/URLs to attach context first.
-Type `pause` to stop here.
+Reply `pause` to stop here.
 ```
 
-Accept empty input, `g`, `go`, `generate`, `continue`, `skip`, or `none` as proceed. Wait only if the user provides refs, asks a question, or types `pause` / `stop`.
+Accept (alias) `go`, `g`, `generate`, `continue`, `skip`, `next`, or `none` as proceed. Per `references/cli-output-contract.md` § Surface-aware continuation prompts, do NOT treat empty input as proceed inside agent chat — chat surfaces can't reliably observe an empty message. Wait only if the user provides refs, asks a question, or types `pause` / `stop`.
+
+Process language like *"Next: we'll generate a list of suggested problems to pick from"* used to live here — removed because the decision at this moment is "attach context or continue," not a preview of what comes next. The follow-up step's framing belongs in the follow-up step, not stacked on this prompt.
 
 If none of the triggers apply, do **not** block. Print a non-blocking line and proceed:
 
@@ -797,6 +926,8 @@ Reply with:
 
 Only the title line gets the number. Put a blank line between candidates. Do not show version labels like `(v1)` in CLI output.
 
+**Why `all` is allowed here but NOT in discovery question picking:** sub-problem selection is a SCOPE-LOCKING decision — picking `all` means "the full surfaced scope is what we're solving for," which is a legitimate, declarative choice (often the right one when the agent has surfaced a tight 3-5 sub-problem set). Discovery question picking is INVESTIGATION TRIAGE — picking `all` there is a low-signal "I haven't discriminated yet" answer that pollutes the answer set and weakens readiness scoring. The removal of `all` in Step 7.3 is discovery-specific; don't propagate it backwards to Step 4.
+
 ##### 4.2 Iteration loop
 
 If the user asks for a refinement (anything that isn't "all" / specific picks / "these are good"):
@@ -852,10 +983,10 @@ Optimize for:
 
 References:
 - {RB/decision/exploration label} — {one-line meaning}
-  Source: {exploration title or id}{ optional ': https://dev.ritualapp.cloud/e/{exploration_id}' if available}
+  Source: {exploration title or id}{ optional ': https://app.ritualapp.cloud/e/{exploration_id}' if available}
 - {reference}
 
-Press Enter or type `lock` to use this frame and review discovery questions.
+Reply `use` to use this frame and review discovery questions.
 Or reply with edits, e.g. `tighten`, `broaden`, `focus on outbox`, `drop dashboard`, or `pause`.
 ```
 
@@ -863,7 +994,8 @@ Rules:
 - Do not show the old versioned scope heading.
 - Do not show `Engineering problem:` as the heading; use `Problem frame`.
 - Do not say `ship it` unless the user used that language first.
-- Accept empty input, `lock`, `l`, `go`, `continue`, or `next` as lock/proceed.
+- Visible CTA is `use`. Accept `lock`, `l`, `go`, `continue`, or `next` as aliases for backwards-compat — do NOT display them. Per `references/cli-output-contract.md` § Surface-aware continuation prompts, do NOT treat empty input as proceed inside agent chat.
+- `lock` is demoted to alias only: "lock" sounded final/irrevocable for a frame that's very much iterable; `use` carries the right tone.
 
 ##### 5.2 Iteration loop
 
@@ -882,13 +1014,13 @@ The returned text becomes the new current draft. Show it using the same `Problem
 
 When the user locks the frame, store the final text as `problem_statement` for Step 6.
 
-**Pulse (Step 5 done):** Emit a pulse — feature clarity just jumped. Compute per `/ritual context-pulse` § Step CP3. Render full if this crosses Raw ask → Under-specified, else compact. In inline build output, translate raw tier labels into user-friendly labels (for example, `Initial ask + code recon` instead of `RAW_ASK`).
+**Pulse (Step 5 done):** Emit a pulse — feature clarity just jumped. Compute per `/ritual context-pulse` § Step CP3. Render full if this crosses Raw ask → Under-specified, else compact. Translate raw tier labels into user-facing copy per `references/cli-output-contract.md` § Pulse tier labels — never expose `RAW_ASK` / `UNDER_SPECIFIED` / etc. directly.
 
 #### Step 6 — Create the exploration
 
 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 locked the problem frame. Create the exploration immediately after lock/proceed. If a name is ambiguous, use one compact proposal and proceed on Enter.
+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).
 
 User-visible before the call, if needed:
 
@@ -908,7 +1040,7 @@ Store `exploration_id`. Move the progress header from Scope to Discovery:
 Ritual build
 ✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
-Exploration created. Track progress at https://dev.ritualapp.cloud/e/{exploration_id}
+Exploration created. Track progress at https://app.ritualapp.cloud/e/{exploration_id}
 
 Next: generate discovery questions to resolve the implementation trade-offs.
 ```
@@ -959,13 +1091,18 @@ Then summarize the created siblings in the dense-list format. Do not pause after
 
 #### Step 7 — Discovery questions
 
-Longest phase because generation is async + the user picks per-matter.
+Longest phase because generation is async + the user picks per-Area. (Internally the API field is `matter_id`; user-facing copy always says Area.)
 
 ##### 7.1 — Kick off
 
-Call `mcp__ritual__suggest_discovery_questions(exploration_id)`. Returns immediately with `task_id`. Tell the user:
+Call `mcp__ritual__suggest_discovery_questions(exploration_id)`. Returns immediately with `task_id`. Tell the user with the full rail (we just entered the Discovery phase):
 
-> Generating discovery questions for each area…
+```text
+Ritual build
+✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+
+Generating discovery questions for each area…
+```
 
 ##### 7.2 — Poll until ready
 
@@ -974,66 +1111,185 @@ Loop:
 - If `ready: false`, wait 5 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).
+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.
+
+##### 7.3 — Area-first picker (Areas index → drill into an Area → return to index)
+
+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.
 
-##### 7.3 — Present matters and collect picks
+###### 7.3.0 — Compute per-Area recommendations + the global shortlist (internal, not user-facing)
 
-The state contains `matters[]`, each with `id`, `name`, and `questions[]`. Walk through them **one matter at a time**:
+Two computations happen before the index renders. Both stay internal — they show up as counts on the index, not as auto-applied picks.
+
+**Per-Area recommended counts** (what to suggest when the user drills into an Area):
+
+- 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):
+
+- 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).
+- Cap at 10 even when the per-Area recommended sets sum to more. The point of the shortlist is to give the user a clean "the highest-signal triage set across the whole space" — picking 24–32 questions because 8 Areas each have 3–4 recommended brings back the "no triage signal" problem under a new name.
+- If the per-Area recommended sets sum to ≤10, the shortlist IS just the union (no further trimming).
+
+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)
+
+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.
 
 ```text
-Discovery area: {matter.name}
+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.
 
-  1. {question 1}
-  2. {question 2}
+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
   ...
 
-Pick the questions Ritual should answer for this area. Reply with:
+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).
+
+**Why `accept shortlist`, not `accept recommended`:**
 
-  ·  `suggest` — help me pick the top 3–4 highest-leverage questions for this area
-  ·  numbers like `1,3,5` — pick specifically
-  ·  `skip` — this area isn't relevant to the current scope
+- "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}.
+
+  1. {question 1, wrapped readably}
+
+  2. {question 2, wrapped readably}
+
+  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.
 ```
 
-**[USER PAUSE]** Wait per matter.
+`show more` reveals the rest of the questions, formatted in two groups (Recommended / More):
+
+```text
+Question picking · {Area name}
+
+Recommended:
+
+  1. {recommended question 1}
+  2. {recommended question 2}
+  3. {recommended question 3}
 
-###### "suggest" handling
+More questions:
+
+  4. {non-recommended question 1}
+  5. {non-recommended question 2}
+  6. {non-recommended question 3}
+  7. {non-recommended question 4}
+  ...
 
-When the user replies `suggest` for a matter, propose which questions to send to `accept_discovery_questions` rather than asking again. Selection rule:
+Reply with numbers like `1,2,5`, or `skip`.
+```
 
-- **Pick the top 3–4 questions most likely to shape the recommendations** based on the problem statement, the 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.
-- If the matter has **fewer than 4 questions**, pick all of them.
-- If the matter has **4 to 7 questions**, pick 3.
-- If the matter has **8+ questions**, pick 4.
+###### 7.3.3 — Return to Areas index with status markers
 
-After picking, tell the user which ones were suggested so they can see and override:
+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.
 
 ```text
-Suggested picks for "{matter.name}":
-  ✓ {question N} — {one-line why this matters}
-  ✓ {question M} — {one-line why this matters}
-  ✓ {question P} — {one-line why this matters}
+Question picking
+
+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
+  ...
 
-Reply `redo` to suggest a different set, `numbers` to override (e.g. `2,5,7`), or `next` to continue.
+Reply with another Area number, or `done` to investigate the {total picked}
+picked questions. Reply `pause` to stop here.
+```
+
+When EVERY Area has been resolved (picked or skipped), shift the CTA from "another Area number" to:
+
+```text
+All Areas reviewed. Reply `done` to investigate the {total picked}
+picked questions. Reply `pause` to stop here.
 ```
 
-`next` is the default — if the user just hits enter or says "looks good," proceed. Do not pause for explicit confirmation if the user already said `suggest`; the assist is the action, not a preview the user has to re-approve.
+###### 7.3.4 — Power paths from the index
 
-###### "skip" handling
+- **`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.
 
-Treat the matter as not requiring questions. Don't call `accept_discovery_questions` for it. The unpicked questions feed Step 7.4.5's classification check.
+###### 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.
+
+###### 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.
+- `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 per-matter
+##### 7.4 — Commit picks (one call per Area, dispatched in parallel)
 
-For each matter where the user picked at least one question, call `mcp__ritual__accept_discovery_questions` with:
+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`
-- `question_ids[]` (the picks for THIS matter)
+- `matter_id` (the API field; user-facing this is the Area)
+- `question_ids[]` (the picks for THIS Area)
+
+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:
+
+```ts
+// Parallel, NOT sequential.
+await Promise.all(
+  pickedAreas.map((area) =>
+    accept_discovery_questions(state_id, area.matter_id, area.question_ids),
+  ),
+);
+```
+
+User-facing: emit ONE status line for the whole commit, not one per Area:
+
+```text
+Saving picks across {N} Areas…
+```
 
-This MUST be one call per matter — the API enforces per-matter atomicity. Don't bundle across matters.
+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
 
@@ -1046,15 +1302,24 @@ After question picking, check for scope mismatch only when one of these triggers
 
 If no trigger fires, proceed silently to anti-goals.
 
-If a trigger fires, summarize the pattern in plain language and ask the user to classify unpicked areas:
+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:
 
 ```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.
+  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.
@@ -1089,13 +1354,19 @@ The agentic pipeline runs sourcing → answers → recommendations. For engineer
 For `engineering`, `delivery`, and `operations` roles, show:
 
 ```text
-Next: run discovery through recommendations.
+Ritual build
+✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
-Press Enter or type `run` to continue.
-Type `pause` to stop here.
+Run discovery
+
+Ritual will source answers for the picked questions, then generate
+recommendations. This usually takes a few minutes.
+
+Reply `run` to continue.
+Reply `pause` to stop here.
 ```
 
-Accept empty input, `run`, `r`, `go`, `continue`, or `next` as proceed.
+Visible CTA is `run`. Accept `r`, `go`, `continue`, or `next` as aliases. Per `references/cli-output-contract.md` § Surface-aware continuation prompts, do NOT treat empty input as proceed inside agent chat.
 
 Call `mcp__ritual__start_agentic_run` with:
 - `scope_type: 'exploration'`
@@ -1104,17 +1375,23 @@ Call `mcp__ritual__start_agentic_run` with:
 For `product`, `design`, or explicitly PRD-style flows, answer review may be useful. Offer two choices without time estimates:
 
 ```text
-Next: run discovery.
+Ritual build
+✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
-1. Stop after answers — review and refine the generated answers before recommendations.
-2. Run through recommendations — fastest path to a recommendation set.
+Run discovery
 
-Pick 1 or 2.
+How do you want to run discovery?
+
+  1. Stop after answers — review and refine the generated answers
+     before recommendations.
+  2. Run through recommendations — fastest path to a recommendation set.
+
+Reply `1` or `2`. Reply `pause` to stop here.
 ```
 
 If they pick 1, call `start_agentic_run` with `stop_after: 'answers'` and continue to Step 8.5 when it pauses. If they pick 2, call without `stop_after` and continue to Step 9 when complete.
 
-Poll `mcp__ritual__get_agentic_run(run_id)` using `references/async-polling.md`: one `Bash sleep 5` per iteration, then a fresh status call. Print progress only when `progress_pct` or `current_step` changes, or every ~3 polls if unchanged:
+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. Print progress only when `progress_pct` or `current_step` changes, or every ~3 polls if unchanged:
 
 > Agentic run: {progress_pct}% — {current_step}
 
@@ -1125,11 +1402,58 @@ When `status` is `PAUSED_FOR_REVIEW` (product/design answer-review mode only): c
 
 If user wants to abort mid-flight: `mcp__ritual__cancel_agentic_run(run_id)`.
 
-#### Step 8.5 — Agent-driven per-answer iteration (product/design answer-review mode only)
+#### Step 8.5 — Run Agentic Exploration (product/design answer-review mode only)
+
+When the pipeline pauses at `PAUSED_FOR_REVIEW`, the exploration is at step `REVIEWING_ANSWERS`. Every Area's questions have v1 answers + at least one clarifying question per consideration, but nothing has been committed for recommendation generation yet.
+
+**The agent walks the user through each question one at a time as part of the running agentic exploration.** Render the full rail at the **landing** (the first answer-review message), then use the in-phase chip on subsequent per-question views.
+
+**On naming:** this step is **Run Agentic Exploration** in user-facing copy and section headings — NOT "Per-answer iteration" (the old internal label). The phase the user is in is "the agentic exploration is running and pausing for your input on each answer before recommendations generate." That's what the heading should say.
+
+Landing (first question, full rail + intro):
+
+```text
+Ritual build
+✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+
+Run Agentic Exploration
+
+Ritual drafted answers for {totalQuestions} questions across {N} Areas.
+For each question, you can submit the v1 answer or iterate with a
+follow-up. When all questions are submitted, Ritual generates
+recommendations.
+
+────────────────────────────────────────────────────────────────────
+
+Discovery — question 1 of {total}: {Area name}
+
+Q: {question.text}
+
+v1 answer:
+{currentDraft, first 400 chars …}
+
+My follow-up: {first consideration's latest assistant message}
+
+Reply `submit` to lock in v1, or reply with text to iterate.
+Reply `pause` to stop here.
+```
+
+Each subsequent per-question view uses the in-phase chip only (no full rail):
+
+```text
+Discovery — question 2 of {total}: {Area name}
+
+Q: {question.text}
 
-When the pipeline pauses at `PAUSED_FOR_REVIEW`, the exploration is at step `REVIEWING_ANSWERS`. Every matter's questions have v1 answers + at least one clarifying question per consideration, but nothing has been committed for recommendation generation yet.
+v1 answer:
+{...}
+
+My follow-up: {...}
+
+Reply `submit` or reply with text to iterate.
+```
 
-**The agent walks the user through each question one at a time.** For each question:
+For each question's loop:
 
 1. **Fetch the state.** Call `mcp__ritual__get_answer_state({ question_id })`. Returns:
    - The question text
@@ -1137,20 +1461,10 @@ When the pipeline pauses at `PAUSED_FOR_REVIEW`, the exploration is at step `REV
    - The considerations (sub-aspects) with their chat sessions
    - The latest assistant message per consideration — this is the **first clarifying question** the answer engine already generated during Phase 3
 
-2. **Present to the user.** Two choices, that's it (no "skip"):
+2. **Present using the landing-or-chip shape above.** Two choices, that's it (no "skip"):
 
-   > **Question {N} of {total}** — *{matter.name}*
-   >
-   > **Q:** {question.text}
-   >
-   > **v1 answer:**
-   > {currentDraft, first 400 chars …}
-   >
-   > **My follow-up:** {first consideration's latest assistant message}
-   >
-   > Two options:
-   > 1. **submit** — you're happy with v1; lock it in and move to the next question
-   > 2. **iterate** — answer my follow-up OR tell me what's wrong with v1 (free-text). I'll regenerate.
+   - **submit** — happy with v1; lock it in and move to the next question
+   - **iterate** (any free-text reply) — answers the follow-up OR explains what's wrong with v1; the answer engine regenerates
 
 3. **Branch on user's choice:**
 
@@ -1172,55 +1486,274 @@ When the pipeline pauses at `PAUSED_FOR_REVIEW`, the exploration is at step `REV
 
 **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 (role-aware)
+#### Step 9 — Review and accept recommendations (grouped, role-aware)
 
-Call `mcp__ritual__get_recommendations(exploration_id)`. Response is an array of recommendations with id, title, status, content, reasoning.
+Call `mcp__ritual__get_recommendations(exploration_id)`. Response is an array of recommendations. Each rec includes:
+
+- 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`. Respect this so a collaborator running `/ritual build` doesn't hit a 403 mid-flow and lose context.
 
 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.
 
-Present recommendations in a compact, scannable form and give one recommended action:
+**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.
+
+##### 9.1 — Landing screen: grouped category summary + compact scope
+
+The recommendations review is the most-read screen in the whole build flow.
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STEP 9.1 RENDERING CONTRACT — non-negotiable
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+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):
+
+```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
+
+{N} recommendations across {K} categories.
+
+1. {Category 1 name}
+   R1 {title}
+   R2 {title}
+
+2. {Category 2 name}
+   R3 {title}
+   R4 {title}
+   R5 {title}
+
+3. {Category 3 name}
+   R6 {title}
+
+...
+
+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
+```
+
+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):
+
+```text
+Recommendations · Scope (full)
+
+{full problemStatement, wrapped at terminal width}
+
+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}`)
+
+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).
 
 ```text
-Ritual recommendations are ready.
+Recommendations — R7
 
-Next: accept them to generate an implementation-ready build brief.
-Signal: discovery has completed and recommendations now exist for this scope.
+R7. {title}
 
-1. {title}
+Category:
+{metadata.category.name}
 
-{one-line summary}
+Recommendation:
+{content — direct, actionable summary; 2-4 sentences}
 
-2. {title}
+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}
+
+Tactics:
+- {short imperative — derived from metadata.acceptance_criteria where actionable}
+- {short imperative}
+- {short imperative}
+
+Acceptance criteria:
+- {metadata.acceptance_criteria[0]}
+- {metadata.acceptance_criteria[1]}
+- {metadata.acceptance_criteria[N]}
+
+References:
+- {file path or RB id from metadata.explainability.faq_references / referenced_faq_ids}
+- {reference}
 
-{one-line summary}
+Reply `drop R7`, `change R7: <edit>`, or `back`.
 
-Reply `accept`, `detail 2`, or `hold`.
+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`.
 ```
 
-If the user asks for detail, show the requested recommendation's `content` and `reasoning_chain` if present, then return to the same `accept / detail / hold` prompt. Do not ask a second confirmation after the user says `accept` unless statuses are mixed, rejected, or the user is not an admin.
+Notes on the detail card:
+
+- **Single-rec accept is NOT a visible CTA here** — the SKILL deliberately omits `accept R7`. The backing API only supports accept-all (`accept_recommendations`) today; surfacing `accept R7` would teach the user a command the system can't fulfill. When a single-rec accept endpoint lands (see backlog), re-introduce it here.
+- 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.
+
+##### 9.4 — Action handling
+
+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:
+
+| User reply | Action | Backing call |
+|---|---|---|
+| `accept recommended` | Accept ALL recs currently on screen | `mcp__ritual__accept_recommendations(exploration_id)` (admin only — see Branch B) |
+| `detail R{N}` | Render the detail card for that rec | None (in-memory) |
+| `accept R{N}` (from detail) | Mark that single rec approved | **No direct single-rec API today — NOT shown as a visible CTA.** If user types it anyway, explain: "I can accept all 11 now via `accept recommended`, or you can `drop` the ones you don't want first." See backlog. |
+| `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 four most-likely-needed: `accept recommended`, `detail R{N}`, `drop R{N}`, `hold`. Show `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).
+
+**Backlog notes** (referenced for the agent so it doesn't over-promise):
+- Single-rec `accept R7` from the detail card doesn't have a direct API endpoint — today the user can either accept ALL or none. Surface this honestly: "I can accept all 11 now, or you can drop the ones you don't want and then accept the rest."
+- `add <topic>` requires a regenerate with a pinned topic — that's a forthcoming `regenerate_recommendation` improvement; until then it's a full regeneration cycle.
 
-**Branch A — user IS an admin and says `accept`:**
+##### 9.A — Branch A: admin replies `accept recommended`
 
-Call `mcp__ritual__accept_recommendations(exploration_id)`. Response includes counts (`promoted`, `alreadyApproved`, `skipped`, `transitionedToComplete`). Show:
+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:
 
-> Accepted {N} recommendations. Exploration is COMPLETE.
-> View: https://dev.ritualapp.cloud/e/{exploration_id}
+```text
+Ritual build
+✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
+
+Accepted {N} recommendations.
+
+View: https://app.ritualapp.cloud/e/{exploration_id}
+
+Next: generating the build brief…
+```
 
 **Pulse (recommendations accepted):** Emit a pulse — this is almost always a state-tier crossing into **Recommendation-ready**. Render full.
 
-Continue to Step 9.5.
+Continue to Step 9.5 (`Wait for requirements`).
 
-**Branch B — user is a collaborator (no admin acceptance available):**
+##### 9.B — Branch B: user is a collaborator (no admin acceptance available)
 
-Tell the user explicitly:
+Same landing screen as 9.1, but the action block changes — collaborators can request admin review instead of accepting directly:
 
-> These recommendations are still in **{status — draft / pending_review}**. Only an admin can formally accept them.
->
-> Recommended: keep going and generate the build brief. When we sync implementation later, Ritual will record that it shipped ahead of admin acceptance. An admin can reconcile later.
->
-> Reply `continue`, `hold for admin`, or `detail {N}`.
+```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.
 
@@ -1245,8 +1778,9 @@ Steps:
    ```
 
    Polling rules in this harness:
-   - Use a **single `Bash sleep 5`** call per poll iteration — don't chain sleeps or use `sleep ≥30`. The harness blocks chained sleeps; one short sleep per turn dodges that AND keeps the user-facing progress feel live.
+   - **`Bash sleep 5` per poll. Always 5. Never escalate to 15/20/25.** The harness blocks chained sleeps, `sleep ≥ 30`, AND successive `sleep N` calls across turns at increasing N. One short sleep per turn dodges all three guards AND keeps the user-facing progress feel live.
    - **Update the user every ~3 polls** with a "still generating…" line so they know you haven't stalled.
+   - If polling crosses ~5 minutes, switch to the `Monitor` + `until <check>; do sleep 2; done` pattern from `references/async-polling.md` § Long waits.
 
 3. **Exit conditions:**
 
@@ -1312,7 +1846,7 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
    ```markdown
    <!--
    Generated by Ritual
-   Exploration: https://dev.ritualapp.cloud/e/{exploration_id}
+   Exploration: https://app.ritualapp.cloud/e/{exploration_id}
    Build brief id: {brief_id}
    Do not remove this header; it preserves implementation lineage.
    -->
@@ -1365,15 +1899,29 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
 
 ##### 10d — Confirm and proceed (CLI Tenet #2, #12)
 
-End Step 10 with a single recommended action plus a cheap escape hatch — never a 3-way option bloom.
+End Step 10 with a single recommended action plus a cheap escape hatch — never a 3-way option bloom. Full rail (this is a decision gate that closes the Build brief phase):
+
+```text
+Ritual build
+✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
+
+Build brief ready
 
-> Open `BUILD-BRIEF.md` and skim the RBs + anchors. **Ready to implement?** (y / refine the brief / drill into one item)
+`BUILD-BRIEF.md` is on disk. Skim the RBs + anchors, then decide:
 
-Branch by user response:
+  · `go` — ready to implement; move to coding
+  · `refine` — something's off; tell me what and I'll regenerate
+  · `drill {N}` — drill into RB-{N} before deciding
 
-- **y / proceed / yes**: continue to Step 11.
-- **refine**: ask what's off, then call `generate_build_brief` with `force: true` after applying their feedback to the exploration (typically a recommendation re-accept or a requirement adjustment via the web UI).
-- **drill into X**: open the specific section in the markdown, discuss inline, then loop back to "Ready to implement?".
+Reply `pause` to stop here.
+```
+
+Branch by user response. Accept `go`, `y`, `yes`, `proceed`, `continue`, `next` as the visible-CTA path (do not display all aliases):
+
+- **`go` / proceed / yes / y**: continue to Step 11.
+- **`refine`**: ask what's off, then call `generate_build_brief` with `force: true` after applying their feedback to the exploration (typically a recommendation re-accept or a requirement adjustment via the web UI).
+- **`drill {N}`**: open RB-{N} in the markdown, discuss inline, then loop back to the gate above.
+- **`pause`**: stop here. The brief is on disk; the user can resume with `/ritual resume`.
 
 **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.
 
@@ -1381,6 +1929,21 @@ Branch by user response:
 
 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.
 
+The Implementation phase landing — full rail (the rail moves to Implementation for the first time):
+
+```text
+Ritual build
+✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
+
+Implementation (Your agent)
+
+The build brief is on disk. From here, your agent codes against the
+RB list. Ritual will track commits via the `Ritual-Exploration:` trailer
+so they link back to this exploration when you sync.
+
+Next: I'll create a feature branch, then start on RB-1.
+```
+
 ##### 11.0 — Branch strategy (CLI Tenet #13)
 
 **Never commit to `main` / `master` from an agent workflow.** Before writing a single line of code:
@@ -1427,7 +1990,7 @@ feat(<area>): <one-line headline>
 <short body — what changed, why, key trade-off>
 
 Ritual-Exploration: <exploration_id>
-Ritual-Exploration-Url: https://dev.ritualapp.cloud/e/<exploration_id>
+Ritual-Exploration-Url: https://app.ritualapp.cloud/e/<exploration_id>
 Ritual-RBs-Satisfied: RB-1, RB-2, RB-7
 ```
 
@@ -1480,7 +2043,7 @@ If the user says "y" / "push" / "open PR":
 
 ## Exploration
 
-- Exploration: [<exploration name>](https://dev.ritualapp.cloud/e/<exploration_id>)
+- Exploration: [<exploration name>](https://app.ritualapp.cloud/e/<exploration_id>)
 - Build brief: see `BUILD-BRIEF.md` (committed in this PR for reviewer reference)
 - Deferrals intentionally punted: <count, with one-line each>
 
@@ -1495,14 +2058,27 @@ If the user is implementing manually: hand off the brief + the branch-strategy n
 
 ##### 12.0 — What this step does (in product terms)
 
-Before asking for permission, frame the call in language the user can act on. `sync_implementation` is not just an API call — it's the moment the workspace's knowledge graph absorbs what you just shipped. From the user's POV:
+Before asking for permission, frame the call in language the user can act on. `sync_implementation` is not just an API call — it's the moment the workspace's knowledge graph absorbs what you just shipped. Full rail (this is a top-level decision gate that ends the build flow):
 
-> I'm about to log this implementation into the workspace's knowledge graph. After this:
-> - The exploration's state flips to ✓ done (or ⚠ implemented-ahead if any recs weren't approved when shipped).
-> - The implementation gets linked back to the recommendations it implements — so future `/ritual build` calls touching `{first 2 files}` will see this implementation as priorContext.
-> - The {M} open deferrals you intentionally punted get logged with their reasons — peers can see them in `/ritual lineage` on these files later.
->
-> **OK to log? (y / hold off / let me adjust the list first)**
+```text
+Ritual build
+✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
+
+Log implementation
+
+I'm about to log this implementation into the workspace's knowledge graph. After this:
+
+  · The exploration's state flips to ✓ done (or ⚠ implemented-ahead if
+    any recs weren't approved when shipped).
+  · The implementation gets linked back to the recommendations it
+    implements — so future `/ritual build` calls touching
+    `{first 2 of filesChanged}` will see this implementation as priorContext.
+  · The {M} open deferrals you intentionally punted get logged with
+    their reasons — peers can see them in `/ritual lineage` on these
+    files later.
+
+Reply `log` to confirm, `hold off`, or `adjust` to edit the list first.
+```
 
 This framing replaces "I need to call sync_implementation, OK?" — which is jargon. The user should know what they're approving in product terms (CLI Tenet #4 — cite the specific signal). Note the vocabulary rule in `cli-output-contract.md` — do not surface "decisions" / "{N} decisions" as a user-facing label here; frame the moment as logging the **implementation** itself.
 
@@ -1525,32 +2101,58 @@ When sync_implementation succeeds, the response includes:
 - `decisionsCount`, `deferralsCount` — totals for the summary line
 - `webUrl` — clickable link to the exploration's implementation record in the web UI
 
-**Surface ALL of this to the user**, not just "ok logged." This is the visible signal that the loop closed. Format:
+**Surface ALL of this to the user**, not just "ok logged." This is the visible signal that the loop closed. Full rail (this is the completion state for the whole `/ritual build` flow):
 
-> ✓ Logged implementation for **{exploration name}**
->   - Implemented: {first 2 area:choice pairs from the `decisions[]` payload, e.g. "auth: OAuth not SAML; data-model: tenant-scoped indexes"}
->   - {deferralsCount} deferral{s} registered: {first 1, e.g. "[major] Rate-limit per-tenant — out of scope for v1"}
->   - View: {webUrl}
->
-> Future `/ritual build` calls touching `{first 2 of filesChanged}` will now see this implementation in their priorContext block.
+```text
+Ritual build
+✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ✓ Implementation (Your agent)
+
+✓ Logged implementation for {exploration name}
+
+  · Implemented: {first 2 area:choice pairs from decisions[],
+    e.g. "auth: OAuth not SAML; data-model: tenant-scoped indexes"}
+  · {deferralsCount} deferral{s} registered: {first 1, e.g. "[major]
+    Rate-limit per-tenant — out of scope for v1"}
+  · View: {webUrl}
+
+Future `/ritual build` calls touching `{first 2 of filesChanged}` will
+now see this implementation in their priorContext block.
+
+Next: nothing required — the loop is closed. Run `/ritual lineage` on
+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:
+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):
 
-> ⚠ {M} of the recommendations were implemented while still in **{status}** state — the exploration now shows `implemented_ahead`. An admin should review + accept the recs to close the gap.
+```text
+⚠ {M} of the recommendations were implemented while still in {status}
+state — the exploration now shows `implemented_ahead`. An admin should
+review + accept the recs to close the gap.
+```
 
 The closing sentence is the most important one: it tells the user **what just happened in the system** in product-level terms. Without it, sync_implementation feels like a write-only black hole. With it, the user understands they just contributed to the workspace's memory.
 
 **If `sync_implementation` fails:** do not drop the structured implementation data. Write the intended payload to `.ritual/pending-sync/<exploration-id>.json` and tell the user exactly what was not logged.
 
-User-visible:
+User-visible (full rail — sync failure is a top-level state):
 
-> `sync_implementation` failed: {error summary}
-> Saved the intended sync payload to `.ritual/pending-sync/<exploration-id>.json`.
-> Retry later with the same payload; nothing about your implementation was lost.
->
-> (Run `/ritual resume` later to see + retry pending syncs.)
+```text
+Ritual build
+✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
+
+Sync failed (recoverable)
+
+`sync_implementation` failed: {error summary}
+
+Saved the intended sync payload to `.ritual/pending-sync/<exploration-id>.json`.
+Nothing about your implementation was lost — the failure is on the
+logging side, not the code side.
+
+Next: run `/ritual resume` later to see + retry pending syncs, or
+re-run `sync_implementation` now if the cause was transient.
+```
 
 Create `.ritual/pending-sync/` if needed. **Ensure the directory is gitignored** — the saved payload contains `decisions[].rationale` text the user typed and commit-level data that shouldn't end up in shared repo history. On the first failed sync, also write `.ritual/pending-sync/.gitignore` with `*` so the directory itself is committed but its contents aren't (gives teammates the breadcrumb that pending syncs exist without leaking contents):
 
@@ -1572,16 +2174,28 @@ Before re-invoking `sync_implementation` on a saved payload:
 2. Run `git log --pretty=format:%H` against the payload's `branch`.
 3. Compare: if there are commit SHAs in `git log` that AREN'T in the payload's `commits[]`, the payload is stale.
 
-If stale, surface to the user:
+If stale, surface to the user with the full rail (top-level decision gate):
 
-> ⚠ This pending sync was saved {N} day(s) ago. Since then you've added {M} more commit(s) to `{branch}` that aren't in the saved payload.
->
-> Retrying as-is would log a partial picture (decisions from when the failure happened, but missing the {M} new commits).
->
-> Options:
->   1. **Retry as-is** — log what was saved; you can sync the new commits in a follow-up.
->   2. **Regenerate** — re-run Step 12 from scratch with the current state; discards the saved payload.
->   3. **Show me** — print the {M} new commits so I can decide.
+```text
+Ritual build
+✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
+
+Pending sync is stale
+
+This pending sync was saved {N} day(s) ago. Since then you've added
+{M} more commit(s) to `{branch}` that aren't in the saved payload.
+Retrying as-is would log a partial picture — the work done since the
+failure would NOT be attributed to this exploration.
+
+Options:
+
+  1. Retry as-is — log what was saved; you can sync the new commits later.
+  2. Regenerate — re-run from scratch with the current state. This is
+     usually right when there's been substantive work since the failure.
+  3. Show me — print the {M} new commits so I can decide.
+
+Reply `1`, `2`, or `3`. Reply `pause` to stop here.
+```
 
 **[USER PAUSE — required, do not auto-answer]** Wait for response. Option 2 is usually right when there's been substantive work; option 1 is fine for small follow-up commits the user wants attributed to the next sync.