@ritualai/cli 0.7.8 → 0.7.10

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
@@ -39,13 +45,63 @@ When **not** to use:
 
 Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must choose among options, approve creation or acceptance, resolve ambiguity, authorize implementation, accept cost/time, or provide missing non-code context. Do **not** pause for status-only steps, safe defaults, internal recon, or silent checks.
 
+**Pauses are not optional even in auto-mode.** See Step 0 below — when the host agent has auto-accept / bypass-permissions enabled, the SKILL must still honor every `[USER PAUSE]` as a hard stop. Inferring an answer from context, choosing a default, or pressing on without an actual user reply defeats the build flow's value: Ritual is producing aligned recommendations because the human shaped the inputs, not because the agent guessed plausibly.
+
 ---
 
 ### 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.
 
-#### Step 1
+#### Step 0 — Permission mode check (pre-flight)
+
+Before any tool call on a fresh `/ritual build` invocation, check whether the host coding agent is running in **auto-accept** or **bypass-permissions** mode. Different agents call this different things, but the behavioral signature is the same: the agent has been told it can skip per-action confirmations and keep moving.
+
+Why this matters: `/ritual build` is built around ~5 real human decisions (workspace, scope, discovery question picks, recommendation acceptance, implementation approval). Each is a `[USER PAUSE]` later in this flow. Auto-mode collapses those gates — the agent defaults each answer and races through. The resulting exploration looks normal but doesn't reflect the user's judgment, which is the entire reason `/ritual build` exists rather than going straight to code.
+
+How to detect (per-agent):
+
+| Agent | Indicator |
+|---|---|
+| **Claude Code** | TUI footer shows `auto-accept edits` or `bypass permissions`. Toggled with **Shift+Tab**. |
+| **Cursor** | "Auto" / "Yolo" toggle in the Composer/Agent panel. |
+| **Codex** | `--full-auto` CLI flag or the equivalent setting in the IDE extension. |
+| **Kiro** | Per-server `autoApprove[]` arrays in `mcp.json`, plus any global "auto" toggle in the Agent panel. |
+| **Windsurf / VS Code Copilot / Gemini CLI** | Each has its own auto-accept mode in settings. |
+
+If the agent cannot detect this with confidence (the indicator surface differs by version), default to **asking the user** at the start of every `/ritual build`. The check is cheap; a wasted build is not.
+
+**If auto-mode is on (or you're uncertain), surface this before Step 1:**
+
+```text
+Heads up — looks like your coding agent is in auto-mode for this session.
+
+Ritual's build flow needs ~5 real decisions from you across the next
+20–30 minutes:
+  · which workspace to use
+  · how to scope the problem
+  · which discovery questions matter for your case
+  · which recommendations to accept
+  · whether the build brief is ready to implement
+
+Auto-mode tends to speed past these. The output will look like a
+normal Ritual exploration but won't actually reflect your input —
+the recommendations will be plausible-but-not-yours.
+
+──────────────────────────────────────────────────────────────────
+Recommended: turn off auto-mode before continuing.
+  · Claude Code: Shift+Tab to cycle back to "default"
+  · Other agents: see your agent's settings or CLI flag
+──────────────────────────────────────────────────────────────────
+
+1. Pause — I'll turn off auto-mode, then say "go"
+2. Continue anyway (I want speed over alignment for this run)
+```
+
+**[USER PAUSE — required, do not auto-answer]** Wait for an actual user message before proceeding.
+
+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 — Pick a workspace
 
 Resolution order:
@@ -102,7 +158,7 @@ If there are **zero existing explorations** and `raw_input = null`, do not say "
 
 ```text
 Ritual build
-● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation
+● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Using workspace: {workspaceName}.
 
@@ -137,7 +193,7 @@ Steps:
    >
    > **{state_glyph} {state_label}**
    > - **{name}** — {short scope summary, first 80 chars of problemStatement}
-   >   - {recommendationCount} rec{s} ({accepted}/{total} approved), {decisionsCount} decision{s} logged, {openDeferralsCount} open deferral{s}
+   >   - {recommendationCount} rec{s} ({accepted}/{total} approved{implementationSegment}), {openDeferralsCount} open deferral{s}
    >   - {state-specific call-to-action — see table below}
    >
    > Recommended: resume one if it matches this work.
@@ -149,7 +205,7 @@ Steps:
    >
    > **{state_glyph} {state_label}**
    > - **{name}** — {short scope summary, first 80 chars of problemStatement}
-   >   - {recommendationCount} rec{s} ({accepted}/{total} approved), {decisionsCount} decision{s} logged, {openDeferralsCount} open deferral{s}
+   >   - {recommendationCount} rec{s} ({accepted}/{total} approved{implementationSegment}), {openDeferralsCount} open deferral{s}
    >   - {state-specific call-to-action — see table below}
    >
    > Reply with:
@@ -158,6 +214,20 @@ Steps:
    > - a feature/problem description to start fresh
    > - `none` to exit
 
+   **`{implementationSegment}` resolution rule** — derive from `implementationStatus.implementationRecord` on the listing response:
+
+   | Condition | Render |
+   |---|---|
+   | No `ImplementationRecord` | `` (empty — drop the segment) |
+   | Has record but `prUrl` is null | ` · synced (no PR linked)` |
+   | `prStatus = merged` | ` · implemented in PR #{prNumber}` |
+   | `prStatus = open` or `draft` | ` · implementing in PR #{prNumber} [{prStatus}]` |
+   | `prStatus = closed` (not merged) | ` · abandoned (PR #{prNumber} closed)` |
+
+   In markdown-rendering agents, hyperlink `PR #{prNumber}` to `prUrl` so users can click through. In plaintext agents, append `prUrl` on the next line.
+
+   **Rationale** — promotes recommendations to the visible noun and folds the previously-separate "decisions logged" count into the recommendation lifecycle. `Implemented` means "this exploration's approved recs shipped as code, here's the PR" — a stronger user-facing signal than a raw decision count. Decisions still exist as the underlying KG primitive (and are still surfaced explicitly by `/ritual lineage`), but they're no longer a headline concept in the build/resume status line.
+
    State badge → user-facing label + call-to-action:
 
    | Glyph | State | User-facing label | Suggested next action |
@@ -416,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.
@@ -427,7 +508,7 @@ If a `CONTEXT-<slug>.md` is found AND its `## The ask` section close-matches the
 - **Surface a compact note**:
   > Code recon
   > Found `CONTEXT-<slug>.md` from `/ritual context-pulse`.
-  > Using {N} candidate files + {M} prior KG decisions as the recon base. Override with `recon: refresh`.
+  > Using {N} candidate files + {M} related prior exploration{s} as the recon base. Override with `recon: refresh`.
 - Proceed directly to 3.2.
 
 If no seed file is found, OR the seed's `## The ask` doesn't match the current `raw_input`, do fresh recon. For mismatch, mention the ignored seed in one line and do not delete it.
@@ -519,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.
@@ -535,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.
 
@@ -581,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:
 
@@ -691,22 +885,24 @@ LLM call, ~5–10s. Returns 5–6 sub-problems — different framing axes the sy
 
 The coding agent's packet is context, not authority. Do not pre-rank or collapse the generated sub-problems based only on the agent hypotheses. Let MCP/template/KG output determine the candidate considerations; use the packet to make them specific, evidenced, and grounded.
 
-**If the response includes `kg_context_used` with `implementationCount > 0`:** surface this to the user BEFORE presenting the considerations. It's the visible signal that prior team decisions shaped this draft.
+**If the response includes `kg_context_used` with `implementationCount > 0`:** surface this to the user BEFORE presenting the considerations. It's the visible signal that prior shipped work shaped this draft.
 
 > Reading the codebase I overlapped with 3 prior Ritual explorations on these files:
->  - **"Anonymous checkout opt-in"** (shipped 2026-04-12) — 2 decisions, 1 deferral
->  - **"Payment-method routing"** (shipped 2026-03-22) — 4 decisions
->  - **"Session-data persistence"** (shipped 2026-02-08) — 1 decision
+>  - **"Anonymous checkout opt-in"** (shipped 2026-04-12) · 1 open deferral
+>  - **"Payment-method routing"** (shipped 2026-03-22)
+>  - **"Session-data persistence"** (shipped 2026-02-08)
 >
 > I factored those into the sub-problems below.
 
+(Drop the per-exploration decision count from this listing — recommendations + ship status are the user-facing signals, not decision counts. Keep `· N open deferral{s}` when `deferrals > 0` since open deferrals are scope-warning notes the user cares about. If `deferrals === 0`, just show `(shipped {date})` with no trailing segment.)
+
 If `implementationCount === 0`: don't mention the KG check (silent — would just be noise on a cold KG).
 
 **[USER PAUSE]** Present as `Problems to solve for`, never as versioned sub-problem headings:
 
 ```text
 Ritual build
-✓ Context  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation
+✓ Context  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Problems to solve for
 
@@ -730,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"):
@@ -788,7 +986,7 @@ References:
   Source: {exploration title or id}{ optional ': https://dev.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`.
 ```
 
@@ -796,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
 
@@ -815,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:
 
@@ -839,7 +1038,7 @@ Store `exploration_id`. Move the progress header from Scope to Discovery:
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation
+✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Exploration created. Track progress at https://dev.ritualapp.cloud/e/{exploration_id}
 
@@ -892,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
 
@@ -907,33 +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.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.
+
+**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).
 
-##### 7.3 — Present matters and collect picks
+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.
 
-The state contains `matters[]`, each with `id`, `name`, and `questions[]`. Walk through them **one matter at a time**:
+###### 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)
 
-Pick the questions Ritual should answer before recommendations.
-Choose `all`, numbers like `1,3`, or `skip`.
+Question picking
 
-1. {question 1}
-2. {question 2}
-...
+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.
 ```
 
-**[USER PAUSE]** Wait per matter.
+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`:**
+
+- "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.
+```
+
+`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}
+
+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`.
+```
+
+###### 7.3.3 — Return to Areas index with status markers
+
+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
+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 with another Area number, or `done` to investigate the {total picked}
+picked questions. Reply `pause` to stop here.
+```
 
-##### 7.4 — Commit picks per-matter
+When EVERY Area has been resolved (picked or skipped), shift the CTA from "another Area number" to:
 
-For each matter where the user picked at least one question, call `mcp__ritual__accept_discovery_questions` with:
+```text
+All Areas reviewed. Reply `done` to investigate the {total picked}
+picked questions. Reply `pause` to stop here.
+```
+
+###### 7.3.4 — Power paths from the index
+
+- **`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.
+
+###### 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 (one call per Area, dispatched in parallel)
+
+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),
+  ),
+);
+```
 
-This MUST be one call per matter — the API enforces per-matter atomicity. Don't bundle across matters.
+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
 
@@ -946,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.
@@ -989,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'`
@@ -1004,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)
+
+Run discovery
 
-1. Stop after answers — review and refine the generated answers before recommendations.
-2. Run through recommendations — fastest path to a recommendation set.
+How do you want to run discovery?
 
-Pick 1 or 2.
+  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}
 
@@ -1025,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
 
-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.
+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.
 
-**The agent walks the user through each question one at a time.** For each question:
+────────────────────────────────────────────────────────────────────
+
+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}
+
+v1 answer:
+{...}
+
+My follow-up: {...}
+
+Reply `submit` or reply with text to iterate.
+```
+
+For each question's loop:
 
 1. **Fetch the state.** Call `mcp__ritual__get_answer_state({ question_id })`. Returns:
    - The question text
@@ -1037,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:**
 
@@ -1072,55 +1486,211 @@ 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. Each rec includes:
 
-Call `mcp__ritual__get_recommendations(exploration_id)`. Response is an array of recommendations with id, title, status, content, reasoning.
+- 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. Two design rules:
+
+1. **Group by `metadata.category.name`.** NEVER show a flat numbered 1..N list. The category is the organizing unit; recommendations are stable `R1..RN` IDs assigned in order of appearance ACROSS categories (top-to-bottom, NOT per-category — so a user can say `detail R7` unambiguously without naming the category).
+2. **Compact scope reference at top.** Show a single-line compressed version of the problem statement so the user can read recommendations against what they were optimized for. Support `show scope` to expand to full.
+
+Full rail at the landing (Recommendations stage opens):
 
 ```text
-Ritual recommendations are ready.
+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
 
-Next: accept them to generate an implementation-ready build brief.
-Signal: discovery has completed and recommendations now exist for this scope.
+{N} recommendations across {K} categories.
 
-1. {title}
+1. {Category 1 name}
+   R1 {title}
+   R2 {title}
 
-{one-line summary}
+2. {Category 2 name}
+   R3 {title}
+   R4 {title}
+   R5 {title}
 
-2. {title}
+3. {Category 3 name}
+   R6 {title}
 
-{one-line summary}
+...
+
+Pulse: Reasoning Readiness ~88% · Context Debt 12% · +26% (implementation-ready)
+
+Recommended: reply `accept recommended` to approve these {N} and generate
+the build brief.
 
-Reply `accept`, `detail 2`, or `hold`.
+Or reply `detail R7`, `change R3: <edit>`, `drop R8`, `add <topic>`, or `hold`.
 ```
 
-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:
+
+- **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.
+- **`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). 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."
+
+##### 9.2 — `show scope` handling
 
-**Branch A — user IS an admin and says `accept`:**
+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):
 
-Call `mcp__ritual__accept_recommendations(exploration_id)`. Response includes counts (`promoted`, `alreadyApproved`, `skipped`, `transitionedToComplete`). Show:
+```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.
+```
 
-> Accepted {N} recommendations. Exploration is COMPLETE.
-> View: https://dev.ritualapp.cloud/e/{exploration_id}
+##### 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
+Recommendations — R7
+
+R7. {title}
+
+Category:
+{metadata.category.name}
+
+Recommendation:
+{content — direct, actionable summary; 2-4 sentences}
+
+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}
+
+Reply `drop R7`, `change R7: <edit>`, or `back`.
+
+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`.
+```
+
+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.
+
+##### 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:
+
+```text
+Ritual build
+✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
+
+Accepted {N} recommendations.
+
+View: https://dev.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.
 
@@ -1145,8 +1715,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:**
 
@@ -1265,15 +1836,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)
 
-> Open `BUILD-BRIEF.md` and skim the RBs + anchors. **Ready to implement?** (y / refine the brief / drill into one item)
+Build brief ready
+
+`BUILD-BRIEF.md` is on disk. Skim the RBs + anchors, then decide:
+
+  · `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
+
+Reply `pause` to stop here.
+```
 
-Branch by user response:
+Branch by user response. Accept `go`, `y`, `yes`, `proceed`, `continue`, `next` as the visible-CTA path (do not display all aliases):
 
-- **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?".
+- **`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.
 
@@ -1281,6 +1866,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:
@@ -1338,7 +1938,7 @@ Intermediate commits can skip the footer. The final commit IS the linkage anchor
 **Don't dump a per-file changelog into the chat.** The full diff lives in `git diff <branch>..HEAD` and the eventual PR body. The CLI summary should be **≤ 8 lines** and surface only what's load-bearing for the user's next decision:
 
 ```
-✓ Implementation done — {exploration name}
+✓ Implementation done (your agent) — {exploration name}
   Branch: {branch}, {N} commits, {M} files changed
   Tests: {tests_added} added, all passing
   RBs satisfied: {comma-joined list of RB-N from the brief, ALL or a count}
@@ -1395,16 +1995,29 @@ 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 {N} architectural decisions you made get linked back to the recommendations that motivated them — so future `/ritual build` calls touching `{first 2 files}` will see your decisions 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 decision list first)**
+```text
+Ritual build
+✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
+
+Log implementation
 
-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).
+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.
 
 ##### 12.1 — Make the call
 
@@ -1425,30 +2038,105 @@ 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}**
->   - {decisionsCount} decision{s} registered: {first 2 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.
+```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}
 
-If any decision's `recommendationStatusAtImplementation` is NOT `approved` (i.e. the Branch B path), add a callout:
+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.
+```
 
-> ⚠ {M} decision{s} implemented while their source recommendation was still in **{status}** — the exploration now shows `implemented_ahead`. An admin should review + accept the recs to close the gap.
+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):
+
+```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):
+
+```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):
+
+```bash
+mkdir -p .ritual/pending-sync
+[ -f .ritual/pending-sync/.gitignore ] || echo '*' > .ritual/pending-sync/.gitignore
+[ -f .ritual/pending-sync/.gitignore ] && ! grep -q '^!\.gitignore$' .ritual/pending-sync/.gitignore && echo '!.gitignore' >> .ritual/pending-sync/.gitignore
+```
+
+That two-line `.gitignore` (`*` then `!.gitignore`) follows the standard pattern: ignore everything in this directory EXCEPT the gitignore file itself. Most teams already use this idiom for `.cache/`, `node_modules/`, etc.
+
+##### 12.2 — Staleness check before retry
+
+When retrying a pending sync from `.ritual/pending-sync/<id>.json`, the user may have committed more code since the failure. The saved payload's `commits[]` is a frozen snapshot — re-uploading it after additional commits land would mis-attribute the new work as "not part of this exploration."
+
+Before re-invoking `sync_implementation` on a saved payload:
+
+1. Read the payload's `commits[]` (each has a `sha`).
+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 with the full rail (top-level decision gate):
+
+```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.
+```
 
-> `sync_implementation` failed: {error summary}
-> Saved the intended sync payload to `.ritual/pending-sync/<exploration-id>.json`.
-> Retry later with the same payload; no implementation decisions were lost.
+**[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.
 
-Create `.ritual/pending-sync/` if needed. Keep the pending-sync file git-tracked unless the repo has a different convention for generated workflow state.
+If the saved payload's `commits[]` matches current git state, proceed silently to the retry.
 
 #### Step 13 — Optional follow-up