@ritualai/cli 0.36.28 → 0.36.36

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

@@ -1,5 +1,5 @@
 <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
-<!-- source-sha: 890b590159dbb59d -->
+<!-- source-sha: d34e2df8a4177dbe -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -165,6 +165,41 @@ Pausing discipline is still load-bearing — every `**[LITE AUTO — no pause; a
 
 Every message should be the prescribed gate copy (rail + content + CTA) — terse, plain, no preamble, no sign-off commentary.
 
+<!-- skill-options:no-gate-change: 2026-06-16 voice/copy polish — adds the Copy rules block, plainer overlap/workspace/verification/discovery render copy, and a causal pulse gloss. No tracked pause gate, option token, or Step header is added, removed, or renamed (structural baseline unchanged: 22 pauses / 26 steps). -->
+
+**Copy rules (the calm-CLI-wizard contract — every gate obeys these):**
+1. **Never print process/eval labels.** No `GATE N`, no `Step N`, no `Auto-decision: …`, no `LLM confidence`, no async-polling-contract talk. The rail already shows where we are — use the rail or a compact header (`Ritual build · 2/6 Scope`), never both, and never a `GATE N` banner.
+2. **One decision per message.** Never bundle two gates (e.g. workspace-bind + overlap check) into one visible block. Render one gate, take the reply, then the next.
+3. **End every decision gate with one clear CTA line.** A single `Reply …` / `Next: …` line, not a paragraph of options.
+4. **Lead with "Recommended: …"** instead of multi-line justification. State the recommendation; don't explain why across several lines.
+5. **Status updates are one sentence, no rail** (unless the stage changed). "Still preparing the brief — retrying safely." — never "Timeout on generate call — polling status (per async-polling contract)."
+6. **Use user nouns, not internal shorthand:** workspace history (not KG), build requirements (not RB list), follow-ups (not deferrals), recommendations (not recs), signed-in user (not principal), "saves this selection" (not "commits the set"), strong/likely/possible match (not a confidence %).
+7. **Hide mechanism unless it changes what the user should do.** Names of engine internals, scoring tiers, citation ids, and contracts stay out of gate copy.
+8. **Only three kinds of message may be user-visible — nothing else (allowlist, load-bearing).** Between gates you output EITHER nothing, OR exactly one approved status line, OR the next gate (which OPENS with its rail — no preamble before it). Never narrate machinery: no "I'll read the reference files…", no "Classifying the job…", no "Running silent recon…", no "Polling / Fetching / Computing / Committing / Submitting / Triggering …", no "skipping … silently", no step numbers, no tool / schema / phase names. The **only** status lines that may appear between gates — render one of these verbatim, or stay silent:
+   - `Generating discovery questions…`
+   - `Saving selected questions…`
+   - `Answering {N} questions from the codebase…`
+   - `{N} answers saved. Generating recommendations…`
+   - `Generating recommendations…`
+   - `Recommendations ready.`
+   - `Requirements ready.`
+   - `Still generating…` / `Still preparing…` (while a slow step runs)
+   - `No related prior runs in this workspace — starting a new run.` (empty-overlap case only)
+
+   A gate must OPEN with its rail. Do **not** print "Computing the suggested 12…", "Rendering the landing", or any "here's what I'm about to show you" line before the rail. And never advance the rail to a stage that hasn't started — mark a stage active (●) only once its work is actually running. (Anything outside these three shapes is caught by the behavioral eval's `no_render_leaks` allowlist.)
+
+   **Render-allowlist precedence (load-bearing — this rule outranks every example below).** This allowlist overrides every local example in the rest of this file. If a later section says to "tell the user", "emit one line", "print", "surface", or "render" a status that is **not** in the list above, treat that instruction as **stale** and do not render it — unless it is a full gate template that begins with the rail. **Never render transition narration after a user reply.** After any reply, the next visible message is exactly one of: the next gate, one approved status line, or nothing. A line that announces what you just did or are about to do ("Workspace selected. Now checking…", "Moving to scope", "Job confirmed. Now…") is forbidden even though no example prescribes it — the rail already shows where we are.
+
+(These are enforced on authored copy by `scripts/check-skill-voice.mjs`; agent-invented violations — like the ones above — are caught by the behavioral eval's `no_render_leaks` linter reading the rendered snapshots.)
+
+<!-- skill-options:no-gate-change: 2026-06-16 round-2 leak polish — adds voice rule #8 (no machinery narration between gates), plainer job-gate CTA + brief-handoff copy, tightened ordering-barrier wording. No tracked pause gate, option token, or Step header is added, removed, or renamed (structural baseline unchanged: 22 pauses / 26 steps). -->
+
+<!-- skill-options:no-gate-change: 2026-06-16 round-3 leak polish — turns voice rule #8 into a render allowlist (gate | approved status | nothing) with the verbatim status list; compacts the Job gate to one validation sentence; plainer workspace/overlap/rec-CTA copy; accept-recs screen keeps the next stage ○ not ●. Copy + behavioral rules only — no tracked pause gate, option token, or Step header is added, removed, or renamed (structural baseline unchanged: 22 pauses / 26 steps). -->
+
+<!-- skill-options:no-gate-change: 2026-06-16 vocab cleanup — de-jargons internal labels the agent was parroting ("ordering barrier" → "before the Job gate is confirmed"; "silent recon" / "codebase recon" → "reading the codebase"). Wording only — no tracked pause gate, option token, or Step header is added, removed, or renamed (structural baseline unchanged: 22 pauses / 26 steps). -->
+
+<!-- skill-options:no-gate-change: 2026-06-16 allowlist-precedence pass — adds the render-allowlist precedence clause + no-transition-narration rule to voice rule #8, expands the approved-status list (Saving selected questions / Requirements ready / empty-overlap line), and normalizes conflicting local examples (Step 4 prior-work callout, Step 5.7 internal-only heading, discovery-landing copy, sub-problem parenthetical removed, categoryName grouping key, "skip silently" → "no user-visible output", resume picker "explorations" → "prior runs"). Copy + behavioral only — no tracked pause gate, option token, or Step header is added, removed, or renamed (structural baseline unchanged: 22 pauses / 26 steps). -->
+
 **Per-agent indicators** (informational, for the SKILL's own awareness — NOT to gate behavior):
 
 | Agent | Where the mode shows up |
@@ -198,7 +233,7 @@ If the user types `always audit for this build` mid-flow at the Step 9.6 prompt,
 Persist `auditMode` to `Exploration.metadata.auditMode` at `create_exploration` time (additive JSONB key — no schema migration) so `/ritual resume <exploration-id>` picks up the same mode the original build started with, and `/ritual lineage <exploration-id>` can render which gates ran + their outcomes.
 
 
-<!-- skill-options:no-gate-change: 2b (clarifying question) + 2c (generic terminal) are loud-fallback COPY variants of the same gate; options are unchanged (proceed | name-the-job) -->
+<!-- skill-options:no-gate-change: 2b (low-confidence clarifying question — server sets clarifyingQuestion only when confidence <20% or it defaulted) + 2c (confident generic — accept and proceed) are COPY variants of the same gate; options are unchanged (proceed | name-the-job; 2b adds answer-the-question, which is a name-the-job correction) -->
 #### Step 0.7 — The Job gate: classify the job to be done
 
 **The FIRST tool call of a fresh build.** The server — not you — classifies the user's raw ask into
@@ -212,16 +247,24 @@ When this gate runs:
   (the user describes what they want to build), run this gate before continuing.
 - Resume paths (Step 1.5 → resume) → skip this gate entirely; the exploration's job is already set.
 
+<!-- skill-options:no-gate-change: ordering barrier + overlap-render copy cleanup — adds a behavioral rule and rewrites prescribed render copy; adds/removes no tracked pause gate, option token, or Step header -->
+
+**Before the Job gate is confirmed (load-bearing, forbidden behavior — this rule is internal; never name it to the user).** For `/ritual build <ask>`, `classify_work_item` is the FIRST tool call, and **until the Job gate is confirmed you must NOT**: read `.ritual/config.json`, call `list_workspaces`, or mention workspace/config state. Workspace selection (Step 1) begins ONLY after the Job gate is confirmed. Narrating the upcoming step — e.g. *"Now I have the classification. No `.ritual/config.json` found, so I'll list workspaces next…"* — is a forbidden process-leak: render the Job gate's prescribed copy and nothing else (no plan narration, no "I'll … next"). (The classifier needs no workspace context; passing one is unnecessary.) This rule only constrains what you may inspect and say *before* confirmation — the normal gate rules govern pausing/turn-handling, unchanged.
+
 1. **Call `mcp__ritual__classify_work_item`** with `raw_input` = the user's ask, verbatim. Do NOT
    classify yourself, do NOT pre-filter to development jobs. It returns
-   `{ jtbd, workItemLabel, deliverableTemplate, why, confidence, isGenericFallback, personaCoverage }`.
+   `{ jtbd, workItemLabel, deliverableTemplate, why, confidence, isGenericFallback, clarifyingQuestion?, personaCoverage }`.
    `isGenericFallback` (and `confidence`) are the typed-uncertainty signal: when it's `true`, the
    result is the catch-all (`build-feature` / `produce-deliverable`) or the classifier wasn't sure —
-   it is NOT a confident match, and which render variant you use in step 2 depends on it.
+   it is NOT a confident match, and which render variant you use in step 2 depends on it. On that
+   generic path the response also carries `clarifyingQuestion` — a plain-language question generated
+   from the user's ask, which step 2b renders verbatim to disambiguate toward a specific job.
 
 2. **Render the validation prompt** (rail stage `Job`). This gate is a plain-language VALIDATION of
    what you're about to build: restate the ask + the matched job in the user's words, then let them
-   confirm or correct. Which variant you render depends on `isGenericFallback`.
+   confirm or correct. Route to a variant by the response: a **`clarifyingQuestion`** present → **2b**
+   (we're genuinely unsure — ask, but let them proceed); else `isGenericFallback` true → **2c** (a
+   confident generic build — accept and proceed); else → **2a** (a confident specific match).
 
    **2a — Confident match** (`isGenericFallback` is `false`): the classifier matched a specific job.
 
@@ -229,23 +272,22 @@ When this gate runs:
    Ritual build
    ● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ {Deliverable}  ○ Implementation (Your agent)
 
-   You're looking to: {restate the ask in one short clause}
-
-   Once you run the exploration and review recommendations, a {deliverableTemplate} will be
-   created as context for your coding agent.
+   Ritual will produce a {deliverableTemplate} for {restate the ask in one short clause}.
 
-   Reply `proceed` to frame the problem (sub-problems + problem statement), or tell me what the
-   job actually is.
+   Reply `proceed` if that's right, or tell me what to adjust.
    ```
 
-   **2b — No specific job matched, FIRST time** (`isGenericFallback` is `true` — the result is the
-   catch-all `build-feature` / `produce-deliverable`, or `confidence` is `low` — AND you have not yet
-   asked the clarifying question this gate): do NOT present the catch-all as a verdict. This case
-   should be RARE. Instead ask ONE clarifying question that elicits the missing signal — what KIND of
-   work this is — grounded in their ask, with concrete examples that lead the reply. The examples
-   span the catalog's functions so the user can self-identify; tailor the wording to their ask. This
-   is the fallback step that lets us classify properly instead of defaulting blind (see
-   `loud-fallback-escalation.md`).
+   **2b — Genuinely unsure: ask, but let them proceed** (the response carries a **`clarifyingQuestion`**
+   — the server sets it ONLY when it was essentially guessing: numeric confidence below 20, or it
+   failed to classify and defaulted). A generic result alone does NOT land here — only a *low-confidence*
+   one does; a confident generic build goes to **2c**. The clarifying question is a single plain-language
+   question the server generated FROM the user's specific ask. **Render it verbatim** — it is grounded in
+   their words and leak-free. Do not rephrase it, do not append a menu, do not mention classification /
+   jobs / categories / confidence. The user has TWO ways out: answer to focus it, OR reply `proceed` to
+   continue with the deliverable. **Leak rule (load-bearing):** the rendered copy must NEVER say
+   "generic", "I couldn't classify", "fallback", "catch-all", or otherwise reveal that classification was
+   uncertain — that is internal state. Present it as a normal question about their ask. (See
+   `loud-fallback-escalation.md`.)
 
    ```text
    Ritual build
@@ -253,34 +295,35 @@ When this gate runs:
 
    You're looking to: {restate the ask in one short clause}
 
-   I couldn't pin this to a specific job — your ask reads as an outcome, and the flow scopes much
-   better when I know what KIND of work it is. Which is closest (or say it in your own words)?
-     • A coding-agent / MCP / skill capability — tooling the agent itself uses
-     • A backend service or API
-     • A frontend / UI feature
-     • A refactor, migration, or infra / platform change
-     • Something else — tell me in a sentence
+   {clarifyingQuestion — verbatim}
 
-   Reply with the closest fit (or your own words) and I'll lock the job.
+   Answer in a sentence — or reply `proceed` and I'll continue with a {Deliverable}.
    ```
 
-   When the user answers, call `mcp__ritual__classify_work_item` AGAIN with the same `raw_input` plus
-   `correction` = their reply (and `previous_jtbd`), then re-render: **2a** if it now matched a
-   specific job, otherwise **2c**.
+   (Rare degraded case — you reached 2b but `clarifyingQuestion` is missing: ask which KIND of work it
+   is, with the same `proceed` option — • a coding-agent / MCP / skill capability • a backend service
+   or API • a frontend / UI feature • a refactor, migration, or infra change • something else, in your
+   own words.)
+
+   If the user ANSWERS, call `mcp__ritual__classify_work_item` AGAIN with the same `raw_input` plus
+   `correction` = their reply (and `previous_jtbd`), then re-render: **2a** if it now matched a specific
+   job, otherwise **2c**. If the user replies `proceed`, go straight to **2c** (accept the generic).
 
-   **2c — Still generic after the clarifying question** (`isGenericFallback` is STILL `true` after the
-   user answered 2b): do NOT ask again. Proceed as a generic build with the function-agnostic
-   `Feature Brief` deliverable, and note the job can be renamed later. The job name stays generic —
-   never show a function-specific deliverable (e.g. "Frontend Web") for an unclassified build.
+   **2c — Accept and proceed** (`isGenericFallback` is `true` with NO `clarifyingQuestion` — a
+   confident-enough generic build — OR the user chose to proceed from 2b, OR a re-classification is still
+   generic): do NOT interrogate. Present the deliverable as a normal accept-and-proceed — **same clean
+   shape as 2a**. Internally the job stays generic and is renamable later, but **the rendered copy must
+   NEVER say "generic", "couldn't classify", "fallback", or otherwise reveal that** — that is internal
+   state. Just name what Ritual will produce for their ask. (Never show a function-specific deliverable
+   like "Frontend Web" for an unclassified build — only the function-agnostic `Feature Brief`.)
 
    ```text
    Ritual build
    ● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ Feature Brief
 
-   You're looking to: {restate the ask in one short clause}
-   I'll treat this as a generic build — deliverable: Feature Brief. You can rename the job later.
+   Ritual will produce a {Deliverable} for {restate the ask in one short clause}.
 
-   Reply `proceed` to frame the problem.
+   Reply `proceed` if that's right, or tell me what to focus on.
    ```
 
    Do not render `personaCoverage` — persona representation is handled server-side now; only surface
@@ -337,10 +380,10 @@ Resolution order:
 
    <!-- skill-options:no-gate-change: adds explainer prose to the existing workspace-pick gate; options and pause unchanged -->
 
-   > No `.ritual/config.json` found — this repo isn't bound to a workspace yet.
-   > A workspace is Ritual's memory for this codebase: the context and reasoning behind every build lands there, so the next build (by you, a teammate, or an agent) starts from what's already known.
+   > This repo isn't connected to a workspace yet.
+   > A workspace keeps the context and reasoning Ritual needs for future runs.
    >
-   > Which workspace should this exploration live in?
+   > Where should Ritual save this run?
    > {numbered list}
 
    **[LITE AUTO — no pause; auto-pick the recommended default]** for selection.
@@ -440,7 +483,7 @@ Steps:
 
    If `raw_input` is present, frame this as an overlap/continuation check before starting fresh:
 
-   > I see {N} exploration{s} already in this workspace:
+   > I see {N} prior run{s} in this workspace:
    >
    > **{state_glyph} {state_label}** ({count})
    >
@@ -697,25 +740,27 @@ Steps:
 
    - **If `candidates.length === 0`**: silently proceed to Step 2. Don't mention the overlap check happened. The whole point of the two-tier filter is silence in the common case.
 
-   - **If `candidates.length > 0`**: surface a callout BEFORE moving to Step 2:
+<!-- skill-options:no-gate-change: 2026-06-16 overlap-gate copy — disambiguates it from the workspace picker (anchors "Using workspace:", drops "exploration"/"overlap" headline, names continue/inspect/new). Displayed start-fresh verb changes proceed→`new` but `proceed` stays an accepted silent alias; the pause, the three semantic options (resume/details/start-fresh), and the structural baseline (22 pauses / 26 steps) are unchanged. -->
 
-     > ⚠ **What you're describing may overlap with existing explorations in this workspace:**
+   - **If `candidates.length > 0`**: surface a COMPACT callout BEFORE moving to Step 2 — a match list + one recommendation + one CTA. No URLs, no per-candidate "why it overlaps" essay, no future field names:
+
+     > Using workspace: {workspace.name}.
+     >
+     > I found related prior runs in this workspace. You can continue one, inspect one, or start a new run.
      >
-     > {for each candidate (in order, strongest first):}
-     > **{candidate.name}** *(LLM confidence: {Math.round(candidate.llmConfidence * 100)}%)*
-     > - *"{candidate.problemStatement first 120 chars, no ellipsis padding}..."*
-     > - Why I think it overlaps: {candidate.llmRationale}
-     > - URL: `https://app.ritualapp.cloud/e/{candidate.explorationId}`
+     > {for each candidate (in order, strongest first), numbered from 1:}
+     > {N}. **{candidate.name}** — {candidate.matchLabel}
+     >    {candidate.problemStatement, first ~100 chars, one line}
      > {endfor}
      >
-     > **Choose:**
-     > 1. **Resume one of these instead** — give me the number, I'll jump to the right step based on its state.
-     > 2. **Proceed anyway** — I'll create a new exploration. The relationship to these {N} won't be lost — when `related_exploration_ids` is supported it'll be captured automatically.
-     > 3. **Show me one in detail first** — give me the number, I'll fetch its full state before you decide.
+     > Recommended: continue one if it's the work you meant.
+     > Reply `resume 1`, `details 1`, or `new` to start a new run.
+
+     This gate looks like the workspace picker but isn't — the workspace is already chosen (anchor it with the `Using workspace:` line), and this screen is only about reusing related prior work vs. starting fresh. Do NOT headline it with "exploration" or "overlap". `check_exploration_overlap` returns `matchLabel` as plain language (`strong match` / `likely match` / `possible match`) — render it verbatim; the raw model confidence is projected out, so there is no number to surface. The model's `whyOverlaps` rationale and the exploration URL are NOT rendered at the gate — they live behind `details {N}`.
 
-   - If the user picks (1): treat the chosen one as the resumed exploration (same as Step 1.5 step 5 above — jump to the right downstream step based on the state badge).
-   - If the user picks (2): continue to Step 2. Future PR will populate `related_exploration_ids` on the new exploration so the linkage is preserved.
-   - If the user picks (3): show the full exploration via `mcp__ritual__get_exploration` + `get_recommendations` if any exist, then loop back to the choose prompt.
+   - `resume {N}`: treat the chosen one as the resumed exploration (same as Step 1.5 step 5 — jump to the right downstream step based on its state badge).
+   - `new` (display this verb; accept `proceed` as a silent alias): continue to Step 2 (a new exploration; the relationship to the candidates is captured automatically server-side — do not narrate that).
+   - `details {N}`: show the chosen exploration's full state via `mcp__ritual__get_exploration` (+ `get_recommendations` if any), including `whyOverlaps` and the URL, then re-render the compact callout above.
 
    **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.
 
@@ -874,12 +919,12 @@ LLM call, ~5–10s. Returns 5–6 sub-problems — different framing axes the sy
 
 **If the response includes `kg_context_used` with `implementationCount > 0`:** surface this to the user BEFORE presenting the considerations. It's the visible signal that prior shipped work shaped this draft.
 
-> Reading the codebase I overlapped with 3 prior Ritual explorations on these files:
+> Prior Ritual work on these files may shape this draft:
 >  - **"Anonymous checkout opt-in"** (shipped 2026-04-12) · 1 open deferral
 >  - **"Payment-method routing"** (shipped 2026-03-22)
 >  - **"Session-data persistence"** (shipped 2026-02-08)
 >
-> I factored those into the sub-problems below.
+> The sub-problems below account for them.
 
 (Drop the per-exploration decision count from this listing — recommendations + ship status are the user-facing signals, not decision counts. Keep `· N open deferral{s}` when `deferrals > 0` since open deferrals are scope-warning notes the user cares about. If `deferrals === 0`, just show `(shipped {date})` with no trailing segment.)
 
@@ -898,9 +943,6 @@ Solving for these sub-problems
 
 2. {Title}
    {Short explanation, wrapped for terminal width.}
-
-(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. Do NOT include a "Reply with…" prompt or a `**[LITE AUTO — no pause; auto-pick the recommended default]**` here — the next user-facing gate is the problem statement (Step 5).
@@ -1002,7 +1044,9 @@ When the user locks the frame, store the final text as `problem_statement` for S
 
 **No pulse here.** The context pulse appears only from the curate-questions step onward (cli-output-contract § Inline pulses) — early on the score is low/noisy and the line clutters the gate. The first pulse is at Step 7.4.
 
-#### Step 5.7 — Ground the exploration (silent recon — runs AFTER the frame locks)
+#### Step 5.7 — Context grounding (internal only — runs AFTER the frame locks)
+
+**Never render this section's title, its step number, or the word "recon" to the user.** This step produces ZERO user-visible output — no "running…", no "grounding…", no "reading the codebase…". It happens between the problem-frame gate and the first product output; the user sees nothing until the next gate or an approved status line.
 
 **Skip only if the user explicitly asks ("just generate, don't read the code") OR if you're operating outside a codebase context.**
 
@@ -1232,7 +1276,7 @@ Keep the list focused. 5–10 is the sweet spot; >20 dilutes the KG signal.
 
 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)`.
 
-Run the silent Step 5.7 recon first, then create the exploration — the job was already confirmed at the Step 0.7 Job gate, so do not add a *further* confirmation here. If a name is ambiguous, **choose the shortest clear noun phrase and continue without pausing** — the name is editable later and shouldn't become a decision gate. Do NOT rely on "proceed on Enter" or empty input in agent chat (see `references/cli-output-contract.md` § Surface-aware continuation prompts).
+Read the codebase silently (Step 5.7) first, then create the exploration — the job was already confirmed at the Step 0.7 Job gate, so do not add a *further* confirmation here. If a name is ambiguous, **choose the shortest clear noun phrase and continue without pausing** — the name is editable later and shouldn't become a decision gate. Do NOT rely on "proceed on Enter" or empty input in agent chat (see `references/cli-output-contract.md` § Surface-aware continuation prompts).
 
 User-visible before the call, if needed:
 
@@ -1341,9 +1385,9 @@ Call `mcp__ritual__suggest_discovery_questions(exploration_id)`. Returns immedia
 
 ```text
 Ritual build
-✓ Job  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Job  ✓ Scope  ● Discovery  ○ Recommendations  ○ {Deliverable}  ○ Implementation (Your agent)
 
-Generating discovery questions for each area…
+Generating discovery questions…
 ```
 
 ##### 7.2 — Poll until ready
@@ -1378,7 +1422,7 @@ The user always confirms; nothing is committed without their reply.
 
 **Per-Area recommended set** (the ★ set, for the Area currently shown):
 
-- Pick the top 3–4 questions per Area most likely to shape the recommendations, based on the problem statement, locked sub-problems from Step 4, and the codebase recon context from Step 3. Bias toward questions whose absence would force later stages to invent consequential facts.
+- Pick the top 3–4 questions per Area most likely to shape the recommendations, based on the problem statement, locked sub-problems from Step 4, and the codebase context read at Step 3. Bias toward questions whose absence would force later stages to invent consequential facts.
 - Area has **< 4 questions**: all are recommended.
 - Area has **4–7 questions**: top 3 are recommended.
 - Area has **8+ questions**: top 4 are recommended.
@@ -1395,9 +1439,7 @@ Ritual build
 
 Discovery questions ready — {M} generated across {N} areas.
 
-These 12 questions target where this problem is hardest — the tradeoffs,
-constraints, and unknowns that decide the design. Next, agents will develop
-answers and generate recommendations.
+These 12 questions target the tradeoffs and unknowns most likely to change the plan.
 
 {Area name 1}
   ✓ 1. {question, full text, wrapped readably}
@@ -1409,9 +1451,7 @@ answers and generate recommendations.
 
 {…every suggested question, grouped by Area, all 12 visible…}
 
-Next: reply `proceed` to run discovery with these 12 (commits the set;
-the run confirmation follows) · `expert` to review all {M} questions and
-adjust the selection · `pause` to stop here.
+Reply `proceed` to use these 12, `expert` to adjust, or `pause`.
 ```
 
 Branch on reply:
@@ -1525,7 +1565,7 @@ Question picking · Summary                              {T} picked
 
 ###### 7.3.5 — What NOT to say
 
-- DO NOT add machinery copy like *"The answer engine will then investigate them via codebase recon and surface clarifying questions for you to review."* The user only needs to know that picking them triggers investigation.
+- DO NOT add machinery copy like *"The answer engine will then investigate them by reading the codebase and surface clarifying questions for you to review."* The user only needs to know that picking them triggers investigation.
 - DO NOT use `Press Enter` anywhere in this picker (see § Surface-aware continuation prompts).
 - DO NOT say `lock` for the picking confirmation; use `done` (to the Summary) then `commit`.
 - DO NOT number Areas and questions in the same view — one numbering stream (the current Area's questions). The breadcrumb `Area i of N` carries position; it is not a pickable number.
@@ -1567,10 +1607,10 @@ exactly one Area. If for some reason you must use it across several Areas
 (e.g. the batch tool is unavailable), call it **sequentially** (`await` each
 in turn) — never in parallel.
 
-User-facing: emit ONE status line for the whole commit, not one per Area:
+User-facing: emit the ONE approved status line for the whole save, not one per Area (verbatim — it's in the rule #8 allowlist):
 
 ```text
-Saving picks across {N} Areas…
+Saving selected questions…
 ```
 
 The batch call is all-or-nothing — validation fails the whole request if any
@@ -1613,7 +1653,7 @@ If the user mentioned things they DON'T want investigated ("don't touch enterpri
 
 Call `mcp__ritual__set_anti_goals(exploration_id, [{ text, reason? }, ...])`.
 
-Skip silently if no anti-goals were mentioned. (No mention = nothing to confirm; the pre-flight only runs when the user actually states out-of-scope items.)
+If no anti-goals were mentioned, skip this with NO user-visible output. (No mention = nothing to confirm; the pre-flight only runs when the user actually states out-of-scope items.)
 
 **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.
 
@@ -1656,7 +1696,7 @@ Visible CTA is `run`. Accept `r`, `go`, `continue`, or `next` as aliases. Per `r
 
 On `run`, **if you're genuinely repo-linked (per the check above), answer the questions yourself** (BYO-answerer; do NOT call `start_agentic_run`):
 1. The Step 7.4 accept (`accept_discovery_questions_batch`) returned `materialized[]` — the committed questions with their row `id`s. (If you didn't keep them, the same ids are what you passed to accept.)
-2. For each committed question, call `mcp__ritual__write_answer_context(question_id, content)` with an answer grounded in your codebase recon — the files you read at Step 5.7, the actual code, real constraints. Answer in PARALLEL where your agent supports it (e.g. one subagent per Area). The content is provisional + provenance-tagged agentic until committed; only the final committed set drives recommendations.
+2. For each saved question, call `mcp__ritual__write_answer_context(question_id, content)` with an answer grounded in your reading of the codebase — the files you read at Step 5.7, the actual code, real constraints. Answer in PARALLEL where your agent supports it (e.g. one subagent per Area). The content is provisional + provenance-tagged agentic until saved; only the final saved set drives recommendations.
    - **Length:** keep each answer to **~300–600 words by default** — tight and grounded, not an essay. Go longer only when the question genuinely needs it.
    - **Code:** the answer itself is **prose** — keep it that way. Code is **optional reference, not part of the answer**: attach a snippet only when it would help a future reader or agent reason about your answer (a key type, contract, or call site worth pointing back to), never to complete the answer. When you do, `content` is **markdown** — add it as a **fenced code block with a language tag** (e.g. ` ```ts `) with the `file/path` and the minimal illustrative lines, never a whole-file paste. Spark lifts these fences out of the prose into a collapsed "View details" reference beside the answer, and markdown keeps them portable to the `.ritual/` projection.
    - **Never leak secrets or sensitive data.** A snippet is **illustrative, not a verbatim copy** — it only has to convey the shape/idea, so simplify and elide freely. **NEVER** include API keys, tokens, passwords, connection strings, credentials, `.env` values, real customer data, or PII — even if they're literally in the file you read. Replace them with obvious placeholders (`process.env.X`, `"<api-key>"`, `"user@example.com"`). The same goes for the prose: describe constraints without pasting secret values.
@@ -1873,7 +1913,7 @@ This is the most-read screen in the build flow, and — as of 2026-06-08 — a *
 **Data source.** Use `mcp__ritual__get_recommendations(exploration_id)` (the raw array) — the walk shows full per-rec content, so you need the fields a titles-only preview omits:
 
 - top-level: `id`, `title`, `content` (the description / summary), `status`, `priority`, `points`, `confidence`
-- `metadata.category.name` — **the load-bearing grouping key** (one rec → one category)
+- `categoryName` — **the load-bearing grouping key** (one rec → one category; `get_recommendations` exposes it top-level so you never reach into raw metadata for it)
 - `metadata.explainability` — `rationale` (chained `→` arrow string), `faq_references[]`, `problem_alignment`, `inferred_elements`
 - `metadata.acceptance_criteria[]` — concrete pass conditions (optional to surface; see § 9.1)
 
@@ -1881,7 +1921,7 @@ Assign stable `R1..RN` IDs **globally across all categories** in page order (NOT
 
 **Vocabulary — load-bearing:**
 
-- Recommendations are grouped by **category** (`metadata.category.name`). They are **NEVER** grouped by `matter` or by `Area` — those are discovery-phase concepts. `matter_id` must never appear in user-facing copy. Anti-pattern observed in agent output: *"44 recs grouped by matter"* — the right framing is *"44 recs across K categories."*
+- Recommendations are grouped by **category** (the `categoryName` field). They are **NEVER** grouped by `matter` or by `Area` — those are discovery-phase concepts. `matter_id` must never appear in user-facing copy. Anti-pattern observed in agent output: *"44 recs grouped by matter"* — the right framing is *"44 recs across K categories."*
 - Do NOT use "Reasoning chain" / "reasoning_chain" in user-facing copy. The user-visible label is **"Why this"** — a short Problem / Discovery / Tradeoff distillation derived from the `rationale` field, NOT the literal `→` arrow chain (that's the model's internal scratchpad shape).
 
 **Action set — load-bearing (exactly three, no freelancing):**
@@ -1918,10 +1958,10 @@ or proceed to your {Deliverable}.
 
 {…every category, every rec, one line each…}
 
-Pulse: Reasoning Readiness ~88% · Context Debt 12% ↓16% (recommendations ready)
+Pulse: Reasoning Readiness 88% · Context Debt 12% ↓16% (answering discovery dropped it 16%)
 
-A few assumptions are still unverified — the build brief is what locks them down.
-Reply  drill R{N} (read one in full)   ·   edit R{N} <your change>   ·   proceed (generate the {Deliverable})
+A few assumptions are still unverified — the {Deliverable} is what locks them down.
+Reply `drill R1`, `edit R1 <change>`, or `proceed` to generate the {Deliverable}.
 ```
 
 Notes:
@@ -1989,15 +2029,17 @@ Editing is non-destructive and does not advance the flow — the user can `edit`
 
 ```text
 Ritual build
-✓ Job  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
+✓ Job  ✓ Scope  ✓ Discovery  ✓ Recommendations  ○ {Deliverable}  ○ Implementation (Your agent)
 
 Reviewed {N} recommendations.
 
 View: https://app.ritualapp.cloud/e/{exploration_id}
 
-Next: preparing the build brief…
+Next: generate the {Deliverable}.
 ```
 
+(The `{Deliverable}` stage stays `○`, not `●` — this screen records the review and names what's next; the stage flips to `●` only when brief generation actually starts. Render `{Deliverable}` as the job's `deliverableTemplate`, e.g. `Frontend Feature Brief`, never the literal "Build brief".)
+
 **Pulse (recommendations reviewed):** emit a pulse — this is almost always a state-tier crossing into **Recommendation-ready**. Render full.
 
 Continue to Step 9.5 (`Wait for requirements`).
@@ -2040,7 +2082,7 @@ Steps:
 
 4. **Special case — `proceed` not yet called (accept_recommendations hasn't run):** if the user jumped ahead without the rec-review `proceed`, there's no fire-and-forget auto-trigger from that path. Skip the polling entirely and let Step 10's auto-trigger handle requirement generation inline. The brief call will take ~30s longer than it otherwise would. (Note: auto-finalize at rec-gen completion usually already queued requirements, so this case is rare.)
 
-5. When `status === 'READY'`, tell the user one line ("Requirements ready…") and continue to Step 9.6 (if anti-goals exist) OR directly to Step 10 (if no anti-goals, audit step is skipped silently).
+5. When `status === 'READY'`, render the approved status line `Requirements ready.` and continue to Step 9.6 (if anti-goals exist) OR directly to Step 10 (if no anti-goals, the audit step runs with NO user-visible output).
 
 #### Step 9.6 — Audit the recommendations + requirements against declared anti-goals (load-bearing — audit-repair loop)
 
@@ -2048,7 +2090,7 @@ Run a constraint-survival audit on the typed Recommendation + Requirement substr
 
 **Why this is load-bearing**: an inert anti-goal — declared but not actually constraining anything in the recs+reqs — propagates downstream as an unconstrained brief. By Step 11 (implementation) it's too late; the agent codes against a substrate whose forbidden states were never enforced. The audit catches inert directives at the upstream typed substrate where the fix is cheap (rec content edit), not at the brief markdown where the fix is expensive (full regen).
 
-**Skip condition**: if the exploration has zero anti-goals (`set_anti_goals` was never called OR all anti-goals are `confidence < 0.4`) OR no APPROVED recommendations exist OR the latest RequirementSet isn't READY, skip this step silently and continue to Step 10. The audit tool returns 404 in any of those cases; check the substrate state first if unsure.
+**Skip condition**: if the exploration has zero anti-goals (`set_anti_goals` was never called OR all anti-goals are `confidence < 0.4`) OR no APPROVED recommendations exist OR the latest RequirementSet isn't READY, skip this step with NO user-visible output and continue to Step 10. The audit tool returns 404 in any of those cases; check the substrate state first if unsure.
 
 **Build modes** (per `documents/architecture/audit-suite.md` § 7a) — the gate prompt below renders differently depending on which mode flag the user invoked:
 
@@ -2228,7 +2270,7 @@ The Build Brief is the markdown document the engineer reads RIGHT BEFORE writing
 Call `mcp__ritual__generate_build_brief` with:
 
 - `exploration_id`
-- `icp` (optional — defaults to the exploration template's primary ICP, then PM; pass `TECH_PM` for engineering-flavored explorations)
+- `icp` — **omit this.** The brief sources from the requirement set the flow already generated (on accept), whose ICP the server resolves from the exploration's persona/template. Passing a different ICP here forces a redundant requirement regeneration and a slow cold start. The engineering flavor is already baked into the server-resolved template — you do not need to (and should not) pass `TECH_PM` or any other ICP.
 - `recon_context` — the Step 3 `codebase_context_packet` plus any explicit phase/later candidates from discovery. Do not pass raw recon notes. This grounds "Codebase Anchors" in real file paths while keeping agent hypotheses auditable and non-authoritative.
 - `sources` — the **same** file-path array passed to `generate_considerations` and `generate_problem_statement` in Steps 4–5. Critical for KG consistency: the brief's "Previously Deferred" section only populates when overlapping prior implementations exist on these files.
 
@@ -2299,7 +2341,7 @@ Steps:
 7. **Print a compact CLI summary** (≤ 8 lines, CLI Tenet #1, #6):
 
    ```text
-   ✓ Verification complete — `BUILD-BRIEF-VERIFICATION.md` on disk; synced to KG.
+   ✓ Verification complete — saved `BUILD-BRIEF-VERIFICATION.md`.
 
    Verified: {N}  ·  Contradicted: {M}  ·  Not found: {K}
 
@@ -2437,7 +2479,7 @@ Ritual build
 Implementation (Your agent)
 
 The build brief is on disk. From here, your agent codes against the
-RB list. Ritual will track commits via the `Ritual-Exploration:` trailer
+build requirements. Ritual will track commits via the `Ritual-Exploration:` trailer
 so they link back to this exploration when you sync.
 
 Next: I'll do a quick branch / dirty-worktree safety check, then hand
@@ -2688,7 +2730,7 @@ I'm about to log this implementation into the workspace's knowledge graph. After
   · The implementation gets linked back to the recommendations it
     implements — so future `/ritual build` calls touching
     `{first 2 of filesChanged}` will see this implementation as priorContext.
-  · The {M} open deferrals you intentionally punted get logged with
+  · The {M} follow-ups you intentionally punted get logged with
     their reasons — peers can see them in `/ritual lineage` on these
     files later.