@ritualai/cli 0.8.2 → 0.9.3

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

@@ -45,7 +45,7 @@ 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.
+**Pauses are not optional even in auto-mode** (load-bearing). 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. The auto-mode reminder in Step 0 below is informational only — it does not relax this rule; it's a heads-up to the user, not permission to bypass pauses.
 
 ---
 
@@ -53,15 +53,29 @@ Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must c
 
 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 0 — Permission mode check (pre-flight)
+#### Step 0 — Auto-mode heads-up (informational, NOT a pause)
 
-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.
+> **Changed 2026-05-21.** Pre-0.8.3 this was a blocking pause: the agent asked the user to confirm they were not in auto-mode and waited for a `1`/`2` reply before proceeding. That broke FTUE: a brand-new user running their first `/ritual build` hit a meta-question about a Claude Code TUI setting before they had any context for what Ritual does. Friction without value. Worse, no reliable programmatic signal exists for "is the agent in auto-mode" — every coding agent represents the state differently, the MCP request carries no mode flag, and the SKILL itself admitted "I can't read your Claude Code TUI footer from here." So the pause was theatre: it forced the user to assert something the agent had no way to verify.
+>
+> The new shape: one informational line in the FIRST user-visible message of the flow. No pause. No `[USER PAUSE]` here. If the user IS in auto-mode, the next genuine decision pause (workspace pick, scope pick, etc.) is the natural place they'll notice it racing past. The line below gives them the right cue + remediation.
+
+The SKILL MUST include the following one-line heads-up at the top of the **first** user-visible message in a `/ritual build` flow (typically the workspace summary in Step 1, or the no-args prompt in Step 1.1). Include it once per flow only:
+
+```text
+Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
+scope, discovery picks, rec acceptance, implementation approval). If your
+agent is in auto-accept / bypass-permissions mode, those pauses won't
+actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
+back to "default").
+```
+
+That's it. No menu. No required reply. Just inform.
 
-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.
+Pausing discipline is still load-bearing — every `[USER PAUSE]` later in the flow is a hard stop regardless of whether the user reads or ignores this heads-up. The agent's contract is unchanged from the preamble: never infer an answer, never pick a default, never press on without an actual user reply. Auto-mode collapsing those pauses is the user's risk to accept; the SKILL's job is just to surface that risk visibly once, then enforce the gates regardless.
 
-How to detect (per-agent):
+**Per-agent indicators** (informational, for the SKILL's own awareness — NOT to gate behavior):
 
-| Agent | Indicator |
+| Agent | Where the mode shows up |
 |---|---|
 | **Claude Code** | TUI footer shows `auto-accept edits` or `bypass permissions`. Toggled with **Shift+Tab**. |
 | **Cursor** | "Auto" / "Yolo" toggle in the Composer/Agent panel. |
@@ -69,38 +83,7 @@ How to detect (per-agent):
 | **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.
+The table is here so future contributors understand WHY the heads-up mentions Claude Code's Shift+Tab specifically — that's the dominant target client. If we add an elicitation-based picker (see `documents/architecture/selection-cursor-pattern.md` §"Future — MCP elicitation"), the auto-mode concern reduces further because elicitation form-mode requires actual user input regardless of agent mode.
 
 #### Step 1 — Pick a workspace
 
@@ -108,12 +91,19 @@ Resolution order:
 
 1. **Project-bound workspace (preferred).** Check for a `.ritual/config.json` at the project root (you can use the Read tool — the file is a small JSON with `workspaceId` + `workspaceName`). If it exists, that's the workspace this repo is bound to. Use it without pausing.
 
-   User-visible:
+   **Validate the binding + get exploration count in one call.** Call `mcp__ritual__list_workspaces()` (no args). Each row in the response carries `_count.explorations` — the authoritative count, server-side, including any explorations created via web UI / other agents / out-of-band API calls. Find the row matching the bound `workspaceId`:
+
+   - **Not found** (deleted, access revoked, wrong id in config): pause with a clear error and offer `workspace: list` to re-bind. Don't fall through to `list_explorations` later — it errors with a less actionable message.
+   - **Found:** store `workspace.explorationCount` for Step 1.5. The SKILL never maintains a local "empty workspace" cache because that goes stale against anything that mutates the workspace outside this CLI's view.
+
+   User-visible (per Step 0, prepend the one-line auto-mode heads-up — once per flow):
 
+   > Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace, scope, discovery picks, rec acceptance, implementation approval). If your agent is in auto-accept / bypass-permissions mode, those pauses won't actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle back to "default").
+   >
    > Using workspace: **{workspaceName}** from `.ritual/config.json`.
    > Override with `workspace: list`.
 
-   Pause only if the file is missing/malformed, the workspace cannot be accessed, or the user explicitly asks to switch.
+   Pause only if the file is missing/malformed, the workspace cannot be accessed (validation failed above), or the user explicitly asks to switch.
 2. **List existing project workspaces.** If no `.ritual/config.json`, call `mcp__ritual__list_workspaces` — this returns project-type workspaces (the General workspace is excluded by default; agents never use it). Present as a numbered list (id, name). **[USER PAUSE]** for selection.
 3. **Create a new one if none exist or user wants a fresh one.** Call `mcp__ritual__create_workspace` with a name — convention is to name it after the repo (basename of cwd, or origin remote). Confirm the name with the user first. **[USER PAUSE]**
 
@@ -160,6 +150,12 @@ If there are **zero existing explorations** and `raw_input = null`, do not say "
 Ritual build
 ● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
+Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
+scope, discovery picks, rec acceptance, implementation approval). If your
+agent is in auto-accept / bypass-permissions mode, those pauses won't
+actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
+back to "default").
+
 Using workspace: {workspaceName}.
 
 No Ritual history here yet.
@@ -175,9 +171,18 @@ If the user replies `suggest` but the workspace has no prior explorations, expla
 
 #### Step 1.5 — Resume vs start (cognitive-debt check)
 
-**Skip this step ONLY if you just created the workspace in Step 1 (no explorations possible yet).** Otherwise: before generating new sub-problems, check whether the user's intent might already be covered — partially or fully — by an existing exploration in this workspace.
+**Skip the `list_explorations` call when the workspace is provably empty.** Two signals count as proof:
+
+1. You just created the workspace in Step 1 (in-session creation — there are no explorations possible yet).
+2. The bound workspace's `_count.explorations === 0` (server-side, read from the `list_workspaces` call in Step 1). This is authoritative against any source of mutation — web UI, other agents, out-of-band API calls.
+
+If either fires, emit a single line and proceed straight to Step 2:
 
-The cost of skipping this step is high: an engineer mid-loop on a feature ends up with two parallel explorations on the same problem, the build brief grounds on the wrong one, and the knowledge graph gets diluted with near-duplicate decisions.
+> No prior work in this workspace — starting fresh.
+
+Otherwise: before generating new sub-problems, check whether the user's intent might already be covered — partially or fully — by an existing exploration in this workspace.
+
+The cost of skipping this step inappropriately is high: an engineer mid-loop on a feature ends up with two parallel explorations on the same problem, the build brief grounds on the wrong one, and the knowledge graph gets diluted with near-duplicate decisions. That's why the skip is gated on a positive server-side empty signal (in-session creation OR `_count.explorations === 0`), never on a client-side cache or heuristic.
 
 Steps:
 
@@ -440,110 +445,39 @@ Steps:
 
    **Calibration:** the threshold for surfacing is conservative — the agent is biased toward "miss not false-flag" (you'd rather silently skip a real overlap than noisily prompt the user when there isn't one). If you DO see this prompt, take it seriously — it's likely there's real overlap.
 
-#### Step 2 — Template selection
-
-Templates shape the structure of considerations, the problem statement, and the final deliverable artifact (PRD, spec, brief, etc.). A `/ritual build` flow from inside a coding agent usually wants an engineering-flavored template, but the user must retain an easy override path.
+#### Step 2 — Template selection (server-side, silent)
 
-Resolution order:
-
-1. **Persona-pinned default (preferred — FTUE-set).** Check `.ritual/config.json` for a `personaSlug` field. If present, that slug **is the template id** (Engineering template families are seeded with `schema.id === <slug>` — see `apps/cli/src/lib/persona-samples.ts`). Use it directly as `template_id` without calling `mcp__ritual__list_templates` and without pausing. This is the common case: the user picked a persona during `ritual init`'s FTUE, the slug was persisted to `.ritual/config.json`, and `/ritual build` should respect that pick.
-
-   **Frame this as a persona + scope-of-work confirmation, not a template confirmation.** "Template" is an internal noun the user hasn't seen — they picked a *persona* during FTUE and what they care about now is "is the persona right + what does that mean for this feature?" Use the `PERSONA_DISPLAY` table below to look up the friendly label from the slug.
-
-   User-visible (one short pause that confirms persona + lists the scope sections, NOT a tool-call prompt):
-
-   > You're set up as **{personaLabel}**.
-   >
-   > For this feature, we'll work through: scope · non-goals · requirements · acceptance criteria · dependencies · metrics · open questions.
-   >
-   > Sound right? Reply `go` to continue, or `change role` to pick a different persona.
+> **Rewritten 2026-05-21 (CLI 0.9.0+).** Previously this section had three branches (persona-pinned / legacy-pinned / list-and-pick) that the SKILL had to navigate, and could optionally call `mcp__ritual__list_templates`. That tool is gone from the agent-facing MCP surface as of CLI 0.9.0. Template selection is now entirely server-side: when `create_exploration` is called without an explicit `template_id`, the server resolves the right SYSTEM template from `user.persona` (set by `ritual init` FTUE) → `workspace.defaultTemplateId` (team override) → system default, then forks it into a per-exploration Template atomically inside the same `create_exploration` request.
 
-   Do **NOT** call `mcp__ritual__list_templates` in this branch. It's wasted ceremony — both for latency (round-trip + LLM context bloat) and for UX (pre-FTUE this step was a real decision; with `personaSlug` already pinned it's a confirmation prompt the user can't meaningfully act on).
+**For the agent: there is no template-selection step. Skip this Step entirely and go to Step 3.** Don't read `.ritual/config.json` for persona, don't try to call `list_templates` (it's not registered), don't render a "Using persona X" confirmation.
 
-   **`PERSONA_DISPLAY` lookup table** (slug → label, mirrors `apps/cli/src/lib/persona-samples.ts#PERSONA_SAMPLES`). If the slug isn't here (a custom or future persona), fall back to humanizing the slug (e.g. `frontend-web` → `Frontend Web`):
+Why no user-visible confirmation: a "do you want to continue with your persona?" prompt without a real way to customize sections is theatre. If the user wants to change persona, they re-run `ritual init`. If they want to customize the template's section structure for one exploration, that's a separate not-yet-shipped capability (tracked on the FTUE backlog as "agent-side template customization via `template_schema` parameter on `create_exploration`"). Until that ships, no per-build confirmation has anything actionable to offer.
 
-   | slug | label |
-   | --- | --- |
-   | backend-services | Backend Services |
-   | frontend-web | Frontend Web |
-   | data-engineering | Data Engineering |
-   | ml-engineering | ML Engineering |
-   | platform-engineering | Platform Engineering |
-   | security-engineering | Security Engineering |
-   | developer-tooling | Developer Tooling |
-   | embedded-firmware | Embedded / Firmware |
-   | game-development | Game Development |
-   | smart-contracts | Smart Contracts |
-   | desktop-apps | Desktop Apps |
-   | qa-engineering | QA Engineering |
+**What still happens inside `create_exploration`** (server-side, agent doesn't see it):
 
-   **If user replies `change role`** (or `template: list`, retained as a power-user alias): fall through to Branch 3 (`list_templates`). Otherwise treat any non-empty reply that isn't a recognized override command as `go`.
-
-2. **Legacy template pin.** If `personaSlug` is missing but `.ritual/config.json` has the legacy `defaultTemplateId` field (older inits before FTUE), use that as `template_id` without pausing. Same confirmation shape as Branch 1, but the role name comes from the template — call `mcp__ritual__list_templates` ONCE to resolve the display name (the legacy pin gave us an id, not a label), then show:
-
-   > You're set up with **{templateName}**.
-   >
-   > For this feature, we'll work through: scope · non-goals · requirements · acceptance criteria · dependencies · metrics · open questions.
-   >
-   > Sound right? Reply `go` to continue, or `change role` to pick a different persona.
-
-3. **No pin — pick a recommended default + offer alternatives.** Only when neither `personaSlug` nor `defaultTemplateId` is set, call `mcp__ritual__list_templates`. From the response, pick the first template matching this fallback chain:
-   - Name matches `/Feature Specification.*Agentic Coding/i` — canonical default for code-aware builds
-   - Name matches `/Technical Detail PRD/i`
-   - Name matches `/Engineering Spec|Technical (Detail|Spec)/i`
-   - First SYSTEM-type template in the list (last resort)
-
-   User-visible as a **[USER PAUSE]**:
-
-   > Template
-   > Recommended: **{templateName}** — {short description}
-   >
-   > Reply `go`, `list`, or `template: {name}`.
-
-4. **If the user types `list`** (in any branch, override path): call `mcp__ritual__list_templates` if you haven't yet, then present a numbered menu of all SYSTEM-type templates. Skip CUSTOM templates by default to avoid menu sprawl unless the user gives a specific custom id/name. Each line: `{N}. {name} — {short description}`. Wait for a number selection.
-
-5. **If the user types `template: {name}` or picks one by name:** call `mcp__ritual__list_templates` if you haven't yet, then find the case-insensitive partial match. If ambiguous, show only the matching options and ask which one. If no match, show the SYSTEM template menu.
-
-6. **Remember `template_id`.** It passes through every subsequent phase — `generate_considerations`, `refine_considerations`, `generate_problem_statement`, `refine_problem_statement`, and ultimately `create_exploration`. The API uses it to load template-specific anti-patterns + focus keywords into the LLM prompt, so it materially shapes output quality.
-
-7. **Track role silently.** Infer `role` from the selected template and carry it forward for:
-   - recommendation tone
-   - sibling exploration cap
-   - Step 8 run-mode default
-
-   Do **not** explain the inference or ask for role confirmation by default. Do not print a happy-path line like "Defaulting to engineering flow."
-
-   Only surface role when the template or task is ambiguous, or when the user asks how the flow is being biased. If needed, use one compact line:
-
-   > Using **{role}** defaults. Override with `role: product` if needed.
-
-   Recognized roles (use the role keyword the API returns, not a paraphrase):
-   - `engineering` — code-aware, technical depth
-   - `product` — PRDs, product briefs, market positioning
-   - `design` — UX research, design briefs
-   - `marketing` — campaigns, launch plans, GTM
-   - `delivery` — sprint plans, release plans
-   - `operations` — SOWs, ops planning
-
-   Pause only if:
-   - the template name is ambiguous,
-   - the user explicitly questions the role,
-   - the chosen role changes a costly or irreversible path,
-   - or no pinned/recommended default exists.
-
-   If the user corrects the role (e.g. "actually I'm building a PRD"), update internal role tracking. Do **not** re-pick the template unless the user explicitly asks to change it.
+```
+1. Resolve PARENT template from the chain:
+     explicit dto.templateId
+     → workspace.defaultTemplateId
+     → user.persona via schema.id-matching SYSTEM template
+     → first SYSTEM template by createdAt
+2. FORK the parent into a per-exploration Template row
+   (type='EXPLORATION', parentTemplateId set, schema copied)
+3. CREATE the Exploration pointing at the forked template
+4. Return { id, ... } to the agent
+```
 
-8. **Suggest persistence only when useful.** If you got here via Branch 3 (no pinned default, you picked one from the list), AND the user accepted with `go` rather than picking a different one, suggest:
+All atomic in one HTTP request. See `apps/api/src/modules/explorations/explorations.service.ts#create` for the exact code path.
 
-   > Want me to pin this template for future `/ritual build` runs in this repo? I can add `"defaultTemplateId": "{id}"` to `.ritual/config.json`.
+**Role inference (still applicable):** the resolved template's primary ICP / role still drives recommendation tone, sibling exploration cap, and Step 8 run-mode default. The agent doesn't need to compute or display role — server-side resolution does the right thing per the persona's mapped ICP (e.g., `frontend-web` → ENGINEER → engineering-flavored recs). Only surface role when the user explicitly asks how the flow is being biased:
 
-   If the user says yes, write the field while preserving existing keys. Use the `defaultTemplateId` field (not `personaSlug`) when the user picked a template directly — `personaSlug` is reserved for the FTUE persona pick (where the slug semantically maps to one of the 12 Engineering personas). The SKILL reads `personaSlug` first, then `defaultTemplateId`, so either field works as a pin; the distinction is provenance.
+> Using **{role}** defaults. Override with `role: product` if needed.
 
-   This is a TEAM pin — `.ritual/config.json` is committed to the repo per Step 1, so the whole team picks up the same default.
+Recognized roles (use the role keyword the API returns, not a paraphrase): `engineering`, `product`, `design`, `marketing`, `delivery`, `operations`.
 
-   **Do NOT suggest persistence in Branches 1 or 2** (persona-pinned or legacy-pinned). The pin already exists; offering to write it would be confusing.
+If the user corrects the role mid-flow ("actually I'm building a PRD"), update internal role tracking. **Do not** re-pick the template — that requires re-creating the exploration, which is bigger than a mid-flow correction warrants. If the user genuinely wants a different template for this exploration, ask them to start over: `/ritual build` again, or `ritual init --persona <slug>` to change their default first.
 
-Proceed to Step 3 once a template is selected. No extra confirmation is required after a pinned template or an accepted default.
+Proceed to Step 3.
 
 #### Step 3 — Code reconnaissance
 
@@ -736,7 +670,7 @@ If no seed file is found, OR the seed's `## The ask` doesn't match the current `
 
    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.
+   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 name the three scoping options as **informational** context. **Do not pause on this.** The boundary information is folded into the `codebase_context_packet` so the downstream `generate_considerations` call produces boundary-aware sub-problems against the repo's actual capability surface. The user's first real gate is the problem statement in Step 5 — they can reshape scope there if the default narrowing was wrong. NEVER continue as if the repo can implement the missing half; NEVER invent the missing systems.
 
    ```text
    Code recon
@@ -766,34 +700,26 @@ If no seed file is found, OR the seed's `## The ask` doesn't match the current `
    - 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.
+   Scoping inferred: contract-first (default for unsettled API)
 
-     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.
+     This repo can build: UI integration, API client surface, mocked tests
+     This repo cannot build: account-creation endpoint, order-linking, email job
+     Considerations will be scoped to what this repo can ship.
 
    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.
+   Continuing to problem statement. You can reshape scope there in plain
+   English (e.g. "frontend-only", "add the backend service contract",
+   or paste API docs to widen the recon).
    ```
 
    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.
+   - **No pause.** Surface the boundary as compact info inside the recon digest, then proceed to `generate_considerations`. The user's first gate is the problem statement (Step 5) where they can reshape scope in plain English. Pausing here was load-bearing in the old SKILL, but it gated FTUE users behind a 1/2/3 menu before they'd seen any product output. The boundary information is preserved — both in user-facing recon (the "Scoping inferred:" block) and in the `codebase_context_packet` that feeds downstream MCP calls.
+   - **"Scoping inferred:" not "How should I scope this?"** — the agent makes the default narrowing (contract-first when API unsettled; repo-side-only when the missing half is clearly out-of-tree) and names what it picked. The user corrects at Step 5 if it was wrong.
+   - **"This repo can build:" + "This repo cannot build:"** are paired one-liners — they document the IN/OUT split so the inferred scoping is auditable. Keep them compact (one line each); the full lists live in `codebase_context_packet`.
+   - **Default narrowing logic:** if the user's ask names a backend/API endpoint, choose **contract-first**. If the user's ask is clearly UI/UX-shaped or the missing systems are obviously out-of-tree (mobile app, separate billing service), choose **repo-side only**. If ambiguous, default to **contract-first** — it preserves more of the user's intent in the downstream artifacts than narrowing to repo-side does.
    - **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.
+   - **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. Stamp the inferred default scope as `inferred_scope` in the packet so `generate_considerations` / `generate_problem_statement` see it. None of these labels should appear in user-facing copy.
 
 ##### 3.2 — Surface the digest and continue
 
@@ -802,10 +728,11 @@ Surface only `recon_digest` by default. Do **not** dump `raw_recon_notes` or the
 Pause only if:
 - recon contradicts the user's stated scope,
 - 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.
 
+**Capability boundary detection does NOT pause.** When recon shows the feature spans systems not in this repo, render the Capability Boundary Check digest from § 3.1 (it's informational), pick the default scope per the "Default narrowing logic" rule, and proceed to Step 3.5. The user reshapes scope at Step 5 (problem-statement gate) if the default narrowing was wrong.
+
 If no pause is needed, proceed to Step 3.5. The user still has a cheap escape hatch: `recon: detail`, `recon: refresh`, or a correction in plain English.
 
 **Pulse (Step 3 done):** Emit a pulse line — repo grounding just moved meaningfully (sources collected, agent inspected files, possibly KG hits). Compute per `/ritual context-pulse` § Step CP3 and render compact unless this is the FIRST pulse of the build flow, in which case use full.
@@ -963,39 +890,31 @@ The coding agent's packet is context, not authority. Do not pre-rank or collapse
 
 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:
+**No pause — auto-accept all generated sub-problems** as `considerations[]` and proceed to Step 5. Render them as compact info so the user sees the framing the system will optimize for, but do NOT prompt for input:
 
 ```text
 Ritual build
 ✓ Context  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
-Problems to solve for
-
-Pick which problems should shape the scope.
-Ritual will turn your selection into a tight problem frame that tells the coding agent what to optimize for.
+Solving for these sub-problems
 
 1. {Title}
-
    {Short explanation, wrapped for terminal width.}
 
 2. {Title}
-
    {Short explanation, wrapped for terminal width.}
 
-Reply with:
-- `all` to solve for everything listed
-- numbers like `1,2,5`
-- a different framing, e.g. `more technical`, `add fraud angle`, `drop observability`
-- `pause` to stop here
+(Refine scope at the problem-frame step — say "drop {N}", "add {angle}",
+or "focus on {N},{M}" when you see the problem statement.)
 ```
 
-Only the title line gets the number. Put a blank line between candidates. Do not show version labels like `(v1)` in CLI output.
+Only the title line gets the number. Put a blank line between candidates. Do not show version labels like `(v1)` in CLI output. Do NOT include a "Reply with…" prompt or a `[USER PAUSE]` here — the next user-facing gate is the problem statement (Step 5).
 
-**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.
+**Rationale for auto-accept:** sub-problem selection is a SCOPE-LOCKING decision, and per the SKILL's own rule "`all` is a legitimate declarative choice — often the right one when the agent has surfaced a tight 3-5 sub-problem set." Asking the user to pick before they've seen the problem frame is theater — the problem statement is the assembled artifact where scope is meaningfully visible, and the refine_problem_statement loop at Step 5 accepts arbitrary change prompts ("drop the observability angle", "make this contract-first") that round-trip through the same sub-problem refinement under the hood. Surfacing the sub-problems as info preserves visibility; dropping the pause preserves FTUE flow.
 
-##### 4.2 Iteration loop
+##### 4.2 Sub-problem refinement (only when user explicitly asks)
 
-If the user asks for a refinement (anything that isn't "all" / specific picks / "these are good"):
+The user may, at the Step 5 problem-statement gate, say something like "rethink the sub-problems" or "the framing is off — show me other angles." When that happens, call `mcp__ritual__refine_considerations` and re-render the sub-problem set + a fresh problem statement. In the default flow this path is unreachable; it exists for the explicit "rethink scope" escape hatch.
 
 Call `mcp__ritual__refine_considerations` with:
 - `workspace_id`, `raw_input`, `template_id`, `sources` — unchanged from the generate call. Critical: pass the SAME `sources` array each iteration so the KG-injected priorContext stays consistent.
@@ -1004,13 +923,11 @@ Call `mcp__ritual__refine_considerations` with:
 - `dismissed`: items the user explicitly rejected
 - `session_id`: omitted on the first refinement; pass the `session_id` from the previous refine response on subsequent ones to chain context
 
-Track the new items as `{ text, version: N+1 }`. Present **alongside** the prior versions, not replacing them — the user can mix selections across versions.
-
-Loop until the user says "these are good" or picks a subset.
+Track the new items as `{ text, version: N+1 }`. After the refinement, regenerate the problem statement and present it. The user's next pause is again the problem-statement gate.
 
 **Critical**: never re-call `generate_considerations` for a refinement. That endpoint is stateless and re-rolls a fresh seed; you'll lose what the user just told you. The whole point of `refine_*` is the LLM sees the iteration context.
 
-Store the final picked sub-problems for Step 5 — they go into `considerations[]`.
+Store the final sub-problems for Step 5 — they go into `considerations[]`.
 
 #### Step 5 — Generate problem frame