@ritualai/cli 0.7.5 → 0.7.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ritualai/cli",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "Ritual CLI — scaffold AI coding agent skills + register MCP servers. Connects Claude Code, Cursor, Windsurf, Kiro, Gemini CLI, VS Code/Copilot, and Codex to Ritual Cloud.",
   "private": false,
   "license": "Apache-2.0",

package/skills/claude-code/ritual/manifest.json

@@ -0,0 +1,57 @@
+[
+  {
+    "path": "DESIGN.md",
+    "lines": 36,
+    "bytes": 2226
+  },
+  {
+    "path": "SKILL.md",
+    "lines": 72,
+    "bytes": 5915
+  },
+  {
+    "path": "agents/openai.yaml",
+    "lines": 6,
+    "bytes": 213
+  },
+  {
+    "path": "references/async-polling.md",
+    "lines": 27,
+    "bytes": 1197
+  },
+  {
+    "path": "references/build-flow.md",
+    "lines": 1519,
+    "bytes": 88142
+  },
+  {
+    "path": "references/cli-output-contract.md",
+    "lines": 225,
+    "bytes": 11559
+  },
+  {
+    "path": "references/context-pulse-flow.md",
+    "lines": 357,
+    "bytes": 25358
+  },
+  {
+    "path": "references/discovery-classification.md",
+    "lines": 176,
+    "bytes": 10275
+  },
+  {
+    "path": "references/lineage-flow.md",
+    "lines": 154,
+    "bytes": 8774
+  },
+  {
+    "path": "references/resume-flow.md",
+    "lines": 157,
+    "bytes": 9950
+  },
+  {
+    "path": "references/scoring-fallback.md",
+    "lines": 126,
+    "bytes": 6494
+  }
+]

package/skills/claude-code/ritual/references/build-flow.md

@@ -101,12 +101,20 @@ Reply with:
 If there are **zero existing explorations** and `raw_input = null`, do not say "starting fresh" and do not advance to template selection yet. Ask for the feature/problem first:
 
 ```text
-No existing explorations in this workspace yet.
+Ritual build
+● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation
 
-What would you like to build or explore? Describe the feature/problem, or run
-`/ritual context-pulse <ask>` first if you want a readiness check before planning.
+Using workspace: {workspaceName}.
+
+No Ritual history here yet.
+
+Next: start with a feature, or let Ritual suggest high-leverage work from the repo.
+
+Reply with a feature/problem description, `suggest`, `pulse <ask>`, or `none`.
 ```
 
+For `pulse <ask>`, route to `/ritual context-pulse <ask>`. Keep it as an optional side path; do not make context-pulse feel like the required first move for `/ritual build`.
+
 If the user replies `suggest` but the workspace has no prior explorations, explain that suggestions need prior workspace signal and ask for a feature/problem instead.
 
 #### Step 1.5 — Resume vs start (cognitive-debt check)
@@ -156,9 +164,9 @@ Steps:
    |---|---|---|---|
    | 📍 | `in_progress` | "still in discovery" | "Continue discovery" |
    | 💬 | `awaiting_admin` | "waiting on admin to accept recommendations" | "Show recommendations for admin review" |
-   | ✅ | `ready` | "ready to implement" | "Generate the build brief and start coding" |
+   | ✅ | `ready` | "ready for build brief" | "Generate the build brief and continue to implementation" |
    | 🛠 | `in_flight` | "implementation in progress" | "Resume — generate or refresh the build brief on remaining work" |
-   | ✓ | `done` | "fully shipped" | "Nothing to do here — start a new exploration if this is new scope" |
+   | ✓ | `done` | "shipped with follow-ups" if open deferrals exist; otherwise "shipped context" | "Address follow-ups or use `/ritual lineage` if relevant. Hide fully complete shipped work by default." |
    | ⚠ | `implemented_ahead` | "code shipped before admin acceptance" | "Surface to user — ask admin to review the implementation against the un-accepted recs, or update the recs to match what shipped" |
 
    The `implemented_ahead` callout is load-bearing: it means a collaborator implemented a recommendation while it was still in `draft` or `pending_review`, and the snapshot column froze that timeline. The user (typically an admin) should know about this BEFORE you do anything else.
@@ -244,27 +252,27 @@ Steps:
 
       1. {candidate.title}
 
-      {candidate.summary}
+         {candidate.summary}
 
-      Why high-leverage:
-      {candidate.rationale — cite the specific RB, deferral, prior decision, shipped PR, or file-level signal.}
+         Why high-leverage:
+         {candidate.rationale — cite the specific RB, deferral, prior decision, shipped PR, or file-level signal.}
 
-      Touches:
-      {referencesPriorWork — list exploration names/ids, PRs, RB ids, or deferrals. Wrap if long.}
+         Touches:
+         {referencesPriorWork — list exploration names/ids, PRs, RB ids, or deferrals. Wrap if long.}
 
 
       2. {candidate.title}
 
-      {candidate.summary}
+         {candidate.summary}
 
-      Why high-leverage:
-      {candidate.rationale}
+         Why high-leverage:
+         {candidate.rationale}
 
-      Touches:
-      {referencesPriorWork}
+         Touches:
+         {referencesPriorWork}
 
 
-      Pick 1, 2, 3, or 4. Or say none and describe what you want directly.
+      Reply with a number to lock that scope, `suggest` to regenerate candidates, or describe a different problem to start fresh.
       ```
 
       If one candidate would resume an existing in-flight exploration rather than create a duplicate, add a short note after the picker:
@@ -344,7 +352,8 @@ Resolution order:
    User-visible:
 
    > Template
-   > Using **{templateName}** from `.ritual/config.json`.
+   > Using **{templateName}**, pinned in `.ritual/config.json`.
+   > Ritual will use this to turn the candidate into implementation-ready sub-problems, recommendations, and a build brief for the coding agent.
    > Override anytime with `template: list` or `template: {name}`.
 
 2. **Pick a recommended default + offer alternatives.** If no `.ritual/config.json` pin exists, call `mcp__ritual__list_templates`. From the response, pick the first template matching this fallback chain:
@@ -366,16 +375,16 @@ Resolution order:
 
 5. **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.
 
-6. **Track role silently; surface only the operational default.** Infer `role` from the selected template and carry it forward for:
+6. **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** explain the inference or ask for role confirmation by default. Do not print a happy-path line like "Defaulting to engineering flow."
 
-   User-visible after the template is selected:
+   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:
 
-   > Defaulting to **{role}** flow. Override with `role: product`, `role: design`, etc.
+   > 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
@@ -572,11 +581,21 @@ 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, surface a single ask (CLI Tenet #2 — one recommended action with a cheap escape):
+When triggered, frame references as an optional booster, not a mandatory phase. The happy path is to continue. Render this prompt:
+
+```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.
 
-> Any PRDs, tickets, designs, transcripts, or chat excerpts that should shape this? Paste paths / URLs now, or say `skip`.
+Press Enter or type `g` to generate the list.
+Or paste files/text/URLs to attach context first.
+Type `pause` to stop here.
+```
 
-Wait for the user to either provide refs or skip.
+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`.
 
 If none of the triggers apply, do **not** block. Print a non-blocking line and proceed:
 
@@ -683,15 +702,33 @@ 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 a numbered list and ask which to include:
+**[USER PAUSE]** Present as `Problems to solve for`, never as versioned sub-problem headings:
 
-> Sub-problems the system identified (v1):
->
-> 1. {sub-problem 1}
-> 2. {sub-problem 2}
-> ...
->
-> Which should we factor into the scope? Pick any subset, "all", or ask for a different framing (e.g. "make them more technical", "drop the measurement angle", "focus on enterprise").
+```text
+Ritual build
+✓ Context  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation
+
+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.
+
+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
+```
+
+Only the title line gets the number. Put a blank line between candidates. Do not show version labels like `(v1)` in CLI output.
 
 ##### 4.2 Iteration loop
 
@@ -712,7 +749,7 @@ Loop until the user says "these are good" or picks a subset.
 
 Store the final picked sub-problems for Step 5 — they go into `considerations[]`.
 
-#### Step 5 — Generate scope
+#### Step 5 — Generate problem frame
 
 ##### 5.1 First draft
 
@@ -723,19 +760,43 @@ Call `mcp__ritual__generate_problem_statement` with:
 - `template_id` (same as Step 4 — the one picked in Step 2)
 - `sources` (the same file-path list passed to generate_considerations — keeps the KG anchor consistent)
 
-Returns a polished "How might we ..." style scope (typically <800 chars) plus optional follow-up questions and quality scores. Treat this as **v1** of the problem statement.
+Returns a candidate problem statement plus optional follow-up questions and quality scores. For engineering / agentic-coding templates, translate the returned statement into a developer-oriented **problem frame** before showing it. Do not default to "How might we…" unless the selected template is product/design oriented or the user asks for HMW phrasing.
 
-If the response includes `kg_context_used` with `implementationCount > 0`, prepend a note to the scope presentation:
+Engineering style:
+- `Problem frame: {verb/outcome} while preserving {constraints}.`
+- `Build/enable {capability} without {key failure modes}.`
+- `Scope: {implementation objective} across {surfaces}.`
 
-> *(Grounded in {N} prior implementation{s}: {top match name}, …)*
+Keep RB IDs, recommendation IDs, prior exploration IDs, and source links out of the main frame sentence. Put provenance underneath in `References:`.
 
-**[USER PAUSE]** Present and ask:
+If the response includes `kg_context_used` with `implementationCount > 0`, include that signal in the `References:` block rather than as a parenthetical in the frame.
 
-> Here's the scope (v1):
->
-> > **{generated scope}**
->
-> Looks good? Want to tighten / broaden / change the audience / focus on a specific tier? Or "ship it" to lock it in.
+**[USER PAUSE]** Present like this:
+
+```text
+Problem frame
+
+{developer-oriented problem frame}
+
+Optimize for:
+- {load-bearing constraint}
+- {load-bearing constraint}
+- {load-bearing constraint}
+
+References:
+- {RB/decision/exploration label} — {one-line meaning}
+  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.
+Or reply with edits, e.g. `tighten`, `broaden`, `focus on outbox`, `drop dashboard`, or `pause`.
+```
+
+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.
 
 ##### 5.2 Iteration loop
 
@@ -743,24 +804,30 @@ If the user asks for a refinement:
 
 Call `mcp__ritual__refine_problem_statement` with:
 - `workspace_id`, `raw_input`, `considerations`, `template_id`, `sources` — unchanged. (Same `sources` as the original generate call — keeps the KG anchor stable.)
-- `previous_problem_statement`: the FULL TEXT of the current best draft (the v1 you just showed)
-- `change_prompt`: the user's request verbatim ("tighten and drop the audience clause")
-- `version`: optional label like `"v2"` — purely for telemetry
+- `previous_problem_statement`: the FULL TEXT of the current best draft
+- `change_prompt`: the user's request verbatim
+- `version`: optional telemetry only; do not show version labels to the user
 - `session_id`: omitted on the first refinement; chain on subsequent ones
 
-The returned text becomes `v2`. Show it. The user can iterate v2 → v3 → ... by calling refine again with `previous_problem_statement` set to the latest draft.
+The returned text becomes the new current draft. Show it using the same `Problem frame` format above, still without version labels.
 
-**Critical**: each refinement's `previous_problem_statement` is the LATEST draft, not the original v1. Otherwise the LLM keeps refining the same starting point and the user can't compose multiple refinements ("tighter, AND drop the audience clause, AND make it past-tense").
+**Critical**: each refinement's `previous_problem_statement` is the LATEST draft, not the original. Otherwise the LLM keeps refining the same starting point and the user can't compose multiple refinements.
 
-When the user accepts ("ship it" / "looks good"), store the final text as `problem_statement` for Step 6.
+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 (problem statement accepted; actor / behavior / acceptance signals are now scorable). Compute per `/ritual context-pulse` § Step CP3. Render full if this crosses Raw ask → Under-specified, else compact.
+**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`).
 
 #### 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)`.
 
-**[USER PAUSE]** "I'll create the exploration as **T2 churn reduction (Q3)**. Proceed?"
+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.
+
+User-visible before the call, if needed:
+
+```text
+Creating exploration: **T2 churn reduction (Q3)**
+```
 
 Call `mcp__ritual__create_exploration` with:
 - `workspace_id`
@@ -768,9 +835,16 @@ Call `mcp__ritual__create_exploration` with:
 - `problem_statement` (the scope from Step 5)
 - `agentic: false` — **do NOT** pass `agentic: true`. We want explicit per-step control so the user gets to pick discovery questions in Step 7. Auto-agentic skips that.
 
-Store `exploration_id`. Show the URL:
+Store `exploration_id`. Move the progress header from Scope to Discovery:
+
+```text
+Ritual build
+✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation
 
-> Exploration created. Track progress at https://dev.ritualapp.cloud/e/{exploration_id}
+Exploration created. Track progress at https://dev.ritualapp.cloud/e/{exploration_id}
+
+Next: generate discovery questions to resolve the implementation trade-offs.
+```
 
 ##### 6.1 — Promote the pre-build seed (if one was consumed in Step 3.0)
 
@@ -824,7 +898,7 @@ Longest phase because generation is async + the user picks per-matter.
 
 Call `mcp__ritual__suggest_discovery_questions(exploration_id)`. Returns immediately with `task_id`. Tell the user:
 
-> Generating discovery questions for each matter… 30-120 seconds.
+> Generating discovery questions for each area…
 
 ##### 7.2 — Poll until ready
 
@@ -839,13 +913,16 @@ Don't poll faster than every 5 seconds. Follow the global polling rule above: si
 
 The state contains `matters[]`, each with `id`, `name`, and `questions[]`. Walk through them **one matter at a time**:
 
-> **{matter.name}** — {matter.questions.length} discovery questions:
->
-> 1. {question 1}
-> 2. {question 2}
-> ...
->
-> Which should the agent investigate? Pick any subset, "all", or "skip" to skip this matter.
+```text
+Discovery area: {matter.name}
+
+Pick the questions Ritual should answer before recommendations.
+Choose `all`, numbers like `1,3`, or `skip`.
+
+1. {question 1}
+2. {question 2}
+...
+```
 
 **[USER PAUSE]** Wait per matter.
 
@@ -905,61 +982,50 @@ Skip silently if no anti-goals were mentioned.
 
 **Pulse (Step 7.4 done — and again after 7.5 if anti-goals were set):** Emit a pulse — decision resolution and (if 7.5 ran) assumption safety just moved. Compact format unless this crosses Under-specified → Exploration-safe.
 
-#### Step 8 — Run the agentic pipeline (role-aware pause point)
-
-The agentic pipeline runs sourcing → answers → recommendations. Two run modes are supported (2026-05-12, PR 4):
+#### Step 8 — Run discovery through recommendations
 
-**Mode A — Full agentic to recommendations (DEFAULT for engineering / delivery / operations / marketing roles, and the **skip** path):**
+The agentic pipeline runs sourcing → answers → recommendations. For engineering / agentic-coding flows, do **not** offer an answers-only mode; the happy path is to run through recommendations.
 
-Call `mcp__ritual__start_agentic_run` with:
-- `scope_type: 'exploration'`
-- `exploration_id`
+For `engineering`, `delivery`, and `operations` roles, show:
 
-Runs through sourcing → answers → recommendations end-to-end. Typical runtime: 3-8 minutes. Poll, show progress, proceed to Step 9 when COMPLETED.
+```text
+Next: run discovery through recommendations.
 
-**Mode B — Stop after answers (RECOMMENDED DEFAULT for product / PRD / design roles):**
+Press Enter or type `run` to continue.
+Type `pause` to stop here.
+```
 
-For PRD-style flows the user often wants to iterate on the v1 answers before recommendations are synthesized — the answers ARE the substance of the PRD; refining them lifts rec quality dramatically.
+Accept empty input, `run`, `r`, `go`, `continue`, or `next` as proceed.
 
 Call `mcp__ritual__start_agentic_run` with:
 - `scope_type: 'exploration'`
 - `exploration_id`
-- `stop_after: 'answers'`
-
-The pipeline halts after Phase 3 (answering). Run lands in `PAUSED_FOR_REVIEW`. Continue with Step 8.5 instead of Step 9.
 
-**Which mode to offer:**
+For `product`, `design`, or explicitly PRD-style flows, answer review may be useful. Offer two choices without time estimates:
 
-Use the **role** inferred at Step 2 step 6b:
-- `engineering`, `delivery`, `operations` → default Mode A; offer Mode B as opt-in
-- `product`, `design`, `marketing` → default Mode B; offer Mode A as opt-in
-- Otherwise → ask the user
-
-Phrase the offer plainly. For product roles:
+```text
+Next: run discovery.
 
-> I'll start the agentic pipeline. Two options:
->
-> 1. **Stop after answers** *(recommended for PRD)* — I'll generate v1 answers for each matter (~3-5 min). You review and refine each one before I run recommendations. Highest-quality PRD output but takes longer overall.
-> 2. **Skip the pause — run all the way to recommendations** — fastest end-to-end (~3-8 min). You can still edit answers later in the web UI, but recs will already exist.
->
-> 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.
 
-For engineering roles, flip the order — Mode A first.
+Pick 1 or 2.
+```
 
-**Common behavior for both modes:**
+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 the standard async polling rule: one `Bash sleep 5` per iteration, then a fresh status call. Print progress only when `progress_pct` or `current_step` changes, or every ~15 seconds if the status is unchanged:
+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:
 
 > Agentic run: {progress_pct}% — {current_step}
 
 When `status` is `COMPLETED`: continue to Step 9.
 When `status` is `COMPLETED_WITH_ERRORS`: tell the user, but proceed — partial recommendations may still be useful.
 When `status` is `FAILED`: surface the error message, ask if they want to retry (`start_agentic_run` again with same exploration_id) or stop.
-When `status` is `PAUSED_FOR_REVIEW` (Mode B only): continue to Step 8.5.
+When `status` is `PAUSED_FOR_REVIEW` (product/design answer-review mode only): continue to Step 8.5.
 
 If user wants to abort mid-flight: `mcp__ritual__cancel_agentic_run(run_id)`.
 
-#### Step 8.5 — Agent-driven per-answer iteration (Mode B only)
+#### Step 8.5 — Agent-driven per-answer iteration (product/design answer-review mode only)
 
 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.
 
@@ -1003,7 +1069,6 @@ When the pipeline pauses at `PAUSED_FOR_REVIEW`, the exploration is at step `REV
 
 **Abandon:** `cancel_agentic_run(run_id)`. The exploration stays at `REVIEWING_ANSWERS` — the user can come back later and either resume or start fresh.
 
-**Performance note:** each iteration is 1 LLM call (~3-5s). For 20 questions × 2 iterations average × 1 call = 40 LLM calls (~$0.04). The skip path is ~$0. Bounded by user choice per-question.
 
 **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.
 
@@ -1018,7 +1083,10 @@ If you don't already know the user's role on this workspace, prefer the workspac
 Present recommendations in a compact, scannable form and give one recommended action:
 
 ```text
-Recommendations ready: {N}
+Ritual recommendations are ready.
+
+Next: accept them to generate an implementation-ready build brief.
+Signal: discovery has completed and recommendations now exist for this scope.
 
 1. {title}
 
@@ -1028,7 +1096,6 @@ Recommendations ready: {N}
 
 {one-line summary}
 
-Recommended: accept all and generate the build brief.
 Reply `accept`, `detail 2`, or `hold`.
 ```
 
@@ -1065,7 +1132,7 @@ Steps:
 
 1. **Tell the user once** that requirements are being generated:
 
-   > Generating requirements for the build brief… usually 20-60s.
+   > Generating requirements for the build brief…
 
 2. **Poll `mcp__ritual__get_requirement_set_status(exploration_id)` every ~5s.** The response shape:
 
@@ -1079,14 +1146,14 @@ 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.
-   - **Update the user every ~3 polls (~15s)** with a "still generating…" line so they know you haven't stalled.
+   - **Update the user every ~3 polls** with a "still generating…" line so they know you haven't stalled.
 
 3. **Exit conditions:**
 
    | Response | Action |
    |---|---|
    | `status === 'READY'` | Proceed to Step 10 |
-   | `exists === false` (still null) for 3+ polls (~15s) | The fire-and-forget hasn't reached the DB yet, OR Branch B was just hit (no LLM call yet). After ~15s either keep polling OR proceed to Step 10 — the API auto-triggers generation inline if the set is still missing when the brief is requested (adds ~30s to the brief call but never hard-fails). |
+   | `exists === false` (still null) for 3+ polls | The fire-and-forget hasn't reached the DB yet, OR Branch B was just hit (no LLM call yet). After several polls either keep polling OR proceed to Step 10 — the API auto-triggers generation inline if the set is still missing when the brief is requested (adds ~30s to the brief call but never hard-fails). |
    | `status === 'GENERATING'` | Keep polling |
    | `status === 'FAILED'` | Surface `errorMessage` to the user; offer to retry by calling `generate_build_brief` directly (which will auto-trigger a fresh generation), OR by hitting `POST /requirements?force=true` via the web UI |
 
@@ -1119,17 +1186,17 @@ Returns the brief markdown + an `id` + `kgContextUsed` block. The brief is **ide
 
 ##### 10b — Timeout-recovery polling (CLI Tenet #8)
 
-`generate_build_brief` can take **30–90s** in the cold-start case: the API auto-triggers RequirementSet generation inline (~30s) if one doesn't exist, then synthesizes the brief on top (~20-60s). MCP clients enforce a hard **30s timeout** on the request — you will sometimes see a local-timeout error while the server-side work is still running.
+`generate_build_brief` can outlive the local MCP request timeout, especially when the API auto-triggers RequirementSet generation inline. You may see a local-timeout error while server-side work is still running.
 
 **Don't give up and don't blindly regenerate.** Instead, fall back to status polling:
 
 1. On timeout/error from `generate_build_brief`, call `mcp__ritual__get_build_brief_status(exploration_id, icp)` immediately.
-2. Poll every **~5s** for up to **2min** total. Polling rule (CLI Tenet #7): a single `Bash sleep 5` call per turn — the harness blocks chained sleeps and `sleep ≥ 30`. Update the user with a "still generating…" line every ~3 polls (~15s).
+2. Poll using the standard async polling rule: one `Bash sleep 5` per poll iteration, then a fresh status call. Print a brief "still generating…" update every ~3 polls when the status is unchanged.
 3. Exit conditions:
 
    | Response | Action |
    |---|---|
-   | `exists === false` for 3+ polls (~15s) | The fire-and-forget never landed — try calling `generate_build_brief` once more (it will likely succeed now that requirements are ready). |
+   | `exists === false` for 3+ polls | The fire-and-forget never landed — try calling `generate_build_brief` once more (it will likely succeed now that requirements are ready). |
    | `status === 'GENERATING'` | Keep polling. |
    | `status === 'READY'` | Read `content` field — proceed to Step 10c as if generate had completed. |
    | `status === 'FAILED'` | Surface `errorMessage` to the user. Propose a single action (CLI Tenet #2): *"The brief failed: {errorMessage}. Retry with a fresh generation? (y/N)"*. On yes: call `generate_build_brief` again with `force: true`. |
@@ -1158,8 +1225,10 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
 2. **Print a compact CLI summary** — the top-of-mind information plus a single line pointing at the file:
 
    ```
-   ✓ Build brief ready — {exploration_name} ({N} recs accepted, {M} requirements)
-     BUILD-BRIEF.md ({line_count} lines, {file_kb_size} KB)
+   ✓ 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)
 
    Goal: {first line of Goal section, ≤ 100 chars}
 
@@ -1206,7 +1275,7 @@ Branch by user response:
 - **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?".
 
-**Pulse (Step 10 done):** Emit a pulse — this often crosses into **Implementation-ready** (90%+). Render full when that crossing happens — *"safe to code"* is the celebration line. If still below 90% (e.g. brief flagged residual debt), surface that in the pulse line itself and propose addressing it before coding.
+**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.
 
 #### Step 11 — Implement
 
@@ -1419,10 +1488,10 @@ This subcommand exclusively uses vNext MCP tools, in the order they appear:
 14. `mcp__ritual__get_discovery_state` (Step 7.2)
 15. `mcp__ritual__accept_discovery_questions` (Step 7.4)
 16. `mcp__ritual__set_anti_goals` (Step 7.5, optional)
-17. `mcp__ritual__start_agentic_run` (Step 8 — accepts `stop_after='answers'` for PRD/product flows)
+17. `mcp__ritual__start_agentic_run` (Step 8 — engineering runs through recommendations; product/design may use `stop_after='answers'`)
 18. `mcp__ritual__get_agentic_run` (Step 8 / Step 8.5 polling)
 19. `mcp__ritual__cancel_agentic_run` (Step 8, only on user abort)
-20. `mcp__ritual__resume_agentic_run` (Step 8.5, only when stop_after='answers' was used)
+20. `mcp__ritual__resume_agentic_run` (Step 8.5, only when product/design answer-review mode was used)
 20a. `mcp__ritual__get_answer_state` (Step 8.5 per-question read)
 20b. `mcp__ritual__iterate_answer` (Step 8.5 — user picked "iterate")
 20c. `mcp__ritual__submit_answer` (Step 8.5 — user picked "submit")