@ritualai/cli 0.8.3 → 0.9.4

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

@@ -91,6 +91,11 @@ 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.
 
+   **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").
@@ -98,7 +103,7 @@ Resolution order:
    > 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]**
 
@@ -166,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:
+
+> No prior work in this workspace — starting fresh.
 
-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.
+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:
 
@@ -431,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:
+> **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.
 
-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.
+**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.
 
-   **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.
+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.
 
-   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.
-
-   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).
-
-   **`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`):
-
-   | 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 |
-
-   **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.
+**What still happens inside `create_exploration`** (server-side, agent doesn't see it):
 
-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
 
@@ -727,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
@@ -757,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
 
@@ -793,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.
@@ -954,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.
@@ -995,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
 
@@ -2168,13 +2094,14 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
    - **Same exploration** (recommendationsHash matches the cached row): silent overwrite + one-line note in the summary that you refreshed it.
    - **Different exploration**: surface a confirm: *"A `BUILD-BRIEF.md` already exists from exploration `{previous_exploration_name}`. Overwrite with brief for `{this_exploration_name}`? (y/N, or save-to-`BUILD-BRIEF-{slug}.md`)"*. (CLI Tenet #11 — confirm before destructive.)
 
-2. **Print a compact CLI summary** — the top-of-mind information plus a single line pointing at the file:
+2. **Print a compact CLI summary** — the top-of-mind information, the verification result, plus a single line pointing at the file:
 
    ```
    ✓ Build brief ready — discovery has become an implementation path.
 
    Signal: {N} accepted recommendations were converted into {M} code-time requirements.
    File: BUILD-BRIEF.md ({line_count} lines, {file_kb_size} KB)
+   Verification: {V} verified · {C} contradicted · {NF} not found  (from Step 10b.5; see BUILD-BRIEF-VERIFICATION.md)
 
    Goal: {first line of Goal section, ≤ 100 chars}
 
@@ -2193,8 +2120,9 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
    ```
 
    Rules for the summary (CLI Tenets #3, #6):
+   - **The `Verification:` line is mandatory** — render the actual numbers from Step 10b.5. If 10b.5 was legitimately skipped (brief made zero specific code citations), render `Verification: n/a — brief made no code citations to verify` instead of omitting the line. The line existing-but-zero is fine; the line being MISSING is a structural signal that 10b.5 was skipped without justification. Reviewing this summary should let the user (and a future SKILL self-check) catch a skipped-verification regression by spotting the missing line. The 2026-05-21 demo regression was Step 10b.5 silently skipped on a brief that cited `AbstractCommunicationEventType`, `utils.py Dispatcher`, `notify_user()`, and `oscar_send_alerts.py` — exactly the case 10b.5 is supposed to verify.
    - **Cap RBs and anchors at top 3 each.** Engineers don't read 12-row tables in terminals.
-   - **Omit any section that's empty.** No "Previously Deferred: none" lines — just don't render that line.
+   - **Omit any section that's empty.** No "Previously Deferred: none" lines — just don't render that line. (The `Verification:` line is exempt — it's always rendered, see above.)
    - If `kgContextUsed.implementationCount > 0`, append one line above the goal: *"Grounded in {N} prior implementation{s}: {top match name}, …"* (CLI Tenet #4 — cite the specific signal).
 
 3. **Offer to open the file** (CLI Tenet #10 — OS-aware affordances, available not mandatory):
@@ -2211,7 +2139,9 @@ 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. Full rail (this is a decision gate that closes the Build brief phase):
+End Step 10 with a single recommended action plus a cheap escape hatch — never a 3-way option bloom.
+
+**Rendering contract (load-bearing — see SKILL.md § Contract strength):** the user-facing block below is **verbatim**. Render the text inside the fenced block exactly as written — same option names (`go`, `drill {N}`, `ux-review`, `pause`), same one-line descriptions, same order, same connector word ("Before `go`, you can run `ux-review`…"). Do NOT paraphrase to "implement", "sync", "hold", "ship", or any other reworded synonyms. Do NOT collapse the option list. Do NOT add or omit options. The 2026-05-21 demo regression was an agent rendering `Reply implement / sync / hold` instead of this block — three different options, two with different semantics than the SKILL intends (`sync` ≠ `pause`). The contract-strength rule in SKILL.md is the backstop; this notice is the local reminder.
 
 ```text
 Ritual build
@@ -2227,12 +2157,12 @@ Build brief ready
 Before `go`, you can run `ux-review` for a design-quality pass on the brief (recommended for UI/UX features — produces `UX-REVIEW.md` and a tailored plan-mode prompt so plan mode stops asking you the same UX questions it always does). Reply `pause` to stop here.
 ```
 
-Branch by user response. Accept `go`, `y`, `yes`, `proceed`, `continue`, `next` as the visible-CTA path (do not display all aliases):
+Branch by user response. The CTA on screen is `go`, but accept these as synonyms so a user typing the obvious intent doesn't get penalized for word choice:
 
-- **`go` / proceed / yes / y**: continue to Step 11. Plan mode will read `BUILD-BRIEF.md` + any synced reviews (verify-brief from Step 10b.5; UX review from Step 10.5 if it ran) via KG `priorContext`. If verify-brief produced contradictions, plan mode picks them up there — the brief content itself stays as Ritual's historical artifact.
-- **`ux-review` / review / `ux`**: continue to Step 10.5 (writes `UX-REVIEW.md`, syncs it to KG via `sync_brief_review`, then continues to Step 11 with the tailored plan-mode prompt). Opt-in; absence is the existing path.
+- **`go` / `y` / `yes` / `proceed` / `continue` / `next` / `implement` / `ship`**: continue to Step 11. Plan mode will read `BUILD-BRIEF.md` + any synced reviews (verify-brief from Step 10b.5; UX review from Step 10.5 if it ran) via KG `priorContext`. If verify-brief produced contradictions, plan mode picks them up there — the brief content itself stays as Ritual's historical artifact. (Synonyms accepted because the agent's drift to "Reply `implement`" trained users to type that word; until the verbatim rendering enforcement is fully reliable, treat user input charitably.)
+- **`ux-review` / `review` / `ux`**: continue to Step 10.5 (writes `UX-REVIEW.md`, syncs it to KG via `sync_brief_review`, then continues to Step 11 with the tailored plan-mode prompt). Opt-in; absence is the existing path.
 - **`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`.
+- **`pause`** / `hold` / `stop`: stop here. The brief is on disk; the user can resume with `/ritual resume`.
 
 **No `refine` action at Step 10d.** The brief is read-only after generation. Two reasons:
 
@@ -2350,7 +2280,9 @@ 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.
+Next: I'll do a quick branch / dirty-worktree safety check, then hand
+off to your agent's plan mode so the first pass is a plan grounded
+in BUILD-BRIEF.md — not file edits.
 ```
 
 ##### 11.0 — Branch strategy (CLI Tenet #13)
@@ -2382,16 +2314,100 @@ Next: I'll create a feature branch, then start on RB-1.
 
 **Never offer "commit to `main` directly" as an option in any user prompt.**
 
-##### 11.1 — Implement
+##### 11.0.5 — Plan-mode handoff (load-bearing — [USER PAUSE])
+
+**Branch is created, working tree is safe — now hand off to plan mode.** Plan mode is user-invoked (the agent can't toggle it programmatically in Claude Code / Cursor / etc.), so without an explicit prompt the implementation phase starts with the agent improvising file edits instead of producing a reviewable plan grounded in `BUILD-BRIEF.md`. This step happens AFTER branch creation (Step 11.0) because plan mode in Claude Code blocks Bash, so branch creation has to happen first.
+
+**Rendering contract — verbatim:**
+
+```text
+Branch ready. Switch your agent into plan mode so the first pass is
+a plan grounded in BUILD-BRIEF.md, not file edits.
+
+  · Claude Code: press Shift+Tab to cycle to "plan mode" (footer shows
+    "plan mode" instead of "default" or "auto-accept edits")
+  · Cursor: open Composer → toggle to "Plan" mode
+  · Other agents: equivalent "plan / propose-only" mode if available;
+    otherwise reply `skip` and I'll continue without
+
+Reply `ready` once you're in plan mode (or `skip` if your agent has no
+plan-mode equivalent). I'll load BUILD-BRIEF.md (and BUILD-BRIEF-
+VERIFICATION.md / UX-REVIEW.md if present) as the FIRST inputs and
+produce a numbered plan you can review before any file is edited.
+```
+
+[USER PAUSE] Branch on response:
+
+- **`ready`**: continue to Step 11.1 (plan generation).
+- **`skip`**: log a one-line note ("Plan mode skipped — agent has no plan-mode equivalent or user opted out. Proceeding directly to implement; risk: less reviewable first pass.") and skip Step 11.1 + 11.1.5, jumping straight to Step 11.2 (implement). This is an escape hatch, not the default.
+- Any other response: re-render the prompt once. If still not `ready` / `skip` after two tries, default to `skip` with the warning line.
+
+**Why this is load-bearing:**
+
+1. Plan mode is the only mechanism that produces a reviewable plan BEFORE file edits. Skipping it means the user is reviewing a diff, not a plan — a more expensive correction loop.
+2. `BUILD-BRIEF-VERIFICATION.md` contradictions are most valuable when they become explicit plan constraints, not when they're discovered during implementation.
+3. Without an explicit prompt, the agent typically goes straight from "build brief ready" to file edits — observed regression during 2026-05-21 demo testing.
+
+##### 11.1 — Plan mode generates the implementation plan
+
+The user is now in plan mode (from Step 11.0.5). The agent must:
+
+1. **Load `BUILD-BRIEF.md`** as the first input. If `BUILD-BRIEF-VERIFICATION.md` exists, load it too — every `contradicted` and `not_found` entry becomes an explicit constraint in the plan ("the brief claimed X but the code does Y; the plan must reconcile / not assume X"). If `UX-REVIEW.md` exists alongside `BUILD-BRIEF.md` (the user opted into Step 10.5), use the "Plan Mode Prompt" block at its bottom as the FIRST input — its numbered list of mismatches / gaps / new-work surfaces is the tailored agenda. The generic plan-mode template is the fallback for when only the brief exists.
+
+2. **Produce a numbered implementation plan** whose top entries are: (1) the RBs from the brief, (2) any contradictions surfaced by verification, (3) any "new work" surfaces from UX review. The plan should name the specific files / functions / new modules each plan step will touch — concrete enough that the user can spot a mistake before any edit happens.
+
+3. **Stay in plan mode until the user accepts the plan.** Do NOT switch to edit/auto-accept mode until the user explicitly approves the plan in plan mode (Claude Code's "accept plan" affordance, or the user typing `accept` / `looks good` / `go`).
+
+##### 11.1.5 — Optional: save the implementation plan as a markdown artifact
+
+After plan mode produces the implementation plan, **but before any code edits**, ask whether to save it.
+
+**Rendering contract — verbatim:**
+
+```text
+Plan ready
+
+Your agent generated an implementation plan from BUILD-BRIEF.md
+{and BUILD-BRIEF-VERIFICATION.md / UX-REVIEW.md if those exist}.
+
+Save this plan to `IMPLEMENTATION-PLAN.md` before coding? (y/N)
+```
+
+[USER PAUSE] Branch on response (default is no — not every plan is worth committing):
+
+- **`y` / `yes` / `save`**: write `IMPLEMENTATION-PLAN.md` alongside `BUILD-BRIEF.md` in the repo root (or `.ritual/IMPLEMENTATION-PLAN.md` if the repo prefers tooling artifacts out of the top level — check `.gitignore` first). Prepend the Ritual attribution header:
+
+  ```markdown
+  <!--
+  Generated by Ritual via plan mode
+  Exploration: https://app.ritualapp.cloud/e/{exploration_id}
+  Build brief: BUILD-BRIEF.md (Ritual requirements)
+  This file: agent's concrete execution strategy
+  Do not remove this header; it preserves implementation lineage.
+  -->
+  ```
+
+  Then continue to Step 11.2.
+- anything else (`n` / `no` / empty / any other text): continue to Step 11.2 without writing the file. Do not re-prompt.
+
+**Rules:**
+
+- **Do not ask this before plan mode has produced the plan.** The question is for the assembled plan, not "do you want me to write a plan in advance."
+- **Do not dump the full plan into the chat when saving.** The plan markdown belongs in the file the user can open, search, share, and revisit — same pattern as `BUILD-BRIEF.md` and `BUILD-BRIEF-VERIFICATION.md` (CLI Tenet #1 — files for detail, CLI for decisions).
+- **Default is `no`** — explicit `y` is required. Most quick implementations don't need a committed plan; saving by default would clutter the repo.
+- If the user later opens the PR (Step 11.5), include `IMPLEMENTATION-PLAN.md` in the PR body's Exploration section if it was saved (see Step 11.5 template).
+
+**Why this matters:** `BUILD-BRIEF.md` is the Ritual requirements artifact (what + why). `IMPLEMENTATION-PLAN.md` is the agent's concrete execution strategy (how). For non-trivial implementations, saving both gives reviewers a useful bridge from requirement to code — and gives `/ritual lineage` queries a richer trail to surface on future builds touching the same files.
+
+##### 11.2 — Implement
 
-1. Take the build brief as input. **If `UX-REVIEW.md` also exists alongside `BUILD-BRIEF.md` (the user opted into Step 10.5), read it too.** When both files are present, use the "Plan Mode Prompt" block at the bottom of `UX-REVIEW.md` as the FIRST input to plan mode — its numbered list of mismatches / gaps / new-work surfaces is the tailored agenda. The generic plan-mode template is the fallback for when only the brief exists.
-2. Use the standard coding-loop tools (Edit/Write/Bash/etc.) to make the code change.
-3. Run tests, lint, build per the repo's conventions.
-4. Track each architectural decision as you go — the input to Step 12's `sync_implementation` call. Per decision, write down: `area`, `choice`, `alternatives_considered`, `rationale`, `source_recommendation_id` (the RB-N or recommendation id the decision implements). This is what makes lineage queryable later — don't skip it.
+1. Use the standard coding-loop tools (Edit/Write/Bash/etc.) to execute the accepted plan.
+2. Run tests, lint, build per the repo's conventions.
+3. Track each architectural decision as you go — the input to Step 12's `sync_implementation` call. Per decision, write down: `area`, `choice`, `alternatives_considered`, `rationale`, `source_recommendation_id` (the RB-N or recommendation id the decision implements). This is what makes lineage queryable later — don't skip it.
 
-##### 11.2 — Commit (CLI Tenet #14 — Ritual attribution)
+##### 11.3 — Commit (CLI Tenet #14 — Ritual attribution)
 
-Commit on the feature branch from 11.0. One-or-many commits is fine; conventional-commit prefixes preferred (`feat:`, `fix:`, `test:`, etc.). Include a Ritual footer on the FINAL commit of the implementation so the trace from code → exploration is visible in `git log`:
+Commit on the feature branch from Step 11.0. One-or-many commits is fine; conventional-commit prefixes preferred (`feat:`, `fix:`, `test:`, etc.). Include a Ritual footer on the FINAL commit of the implementation so the trace from code → exploration is visible in `git log`:
 
 ```
 feat(<area>): <one-line headline>
@@ -2405,7 +2421,7 @@ Ritual-RBs-Satisfied: RB-1, RB-2, RB-7
 
 Intermediate commits can skip the footer. The final commit IS the linkage anchor.
 
-##### 11.3 — Post-implementation summary (CLI Tenet #1 — files for detail, CLI for decisions)
+##### 11.4 — Post-implementation summary (CLI Tenet #1 — files for detail, CLI for decisions)
 
 **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:
 
@@ -2421,7 +2437,7 @@ Next: push + open PR? (y / show me what changed / abort)
 
 If the user picks "show me what changed", THEN run `git diff --stat HEAD~N..HEAD` or open per-file diffs interactively — on request, not by default.
 
-##### 11.4 — Push + PR (single recommended action)
+##### 11.5 — Push + PR (single recommended action)
 
 If the user says "y" / "push" / "open PR":
 
@@ -2454,6 +2470,7 @@ If the user says "y" / "push" / "open PR":
 
 - Exploration: [<exploration name>](https://app.ritualapp.cloud/e/<exploration_id>)
 - Build brief: see `BUILD-BRIEF.md` (committed in this PR for reviewer reference)
+- Implementation plan: see `IMPLEMENTATION-PLAN.md` *(only include this line if Step 11.1.5 actually wrote the file — agent execution strategy alongside the brief)*
 - Deferrals intentionally punted: <count, with one-line each>
 
 ---