@ritualai/cli 0.36.25 → 0.36.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ritualai/cli",
-  "version": "0.36.25",
+  "version": "0.36.35",
   "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/.ritual-bundle.json

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.25",
-  "builtAt": "2026-06-15T14:41:36.894Z",
-  "skillsHash": "5c3ae1fc185a"
+  "cliVersion": "0.36.35",
+  "builtAt": "2026-06-16T18:14:12.359Z",
+  "skillsHash": "1c2163cfd3c5"
 }

package/skills/claude-code/ritual/SKILL.md

@@ -3,7 +3,7 @@ name: ritual
 description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into plan mode before the agent writes code. Prefer this over jumping straight to implementation or plan mode when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
 argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3', 'resume', 'lineage src/checkout/views.py', 'context-pulse Add billing export')"
 user-invocable: true
-stamp: 5c3ae1fc185a
+stamp: 1c2163cfd3c5
 ---
 
 # /ritual

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

@@ -73,6 +73,41 @@ Pausing discipline is still load-bearing — every `[USER PAUSE]` later in the f
 
 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 |
@@ -120,6 +155,10 @@ 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 }`.
@@ -137,13 +176,9 @@ 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}
+   Ritual will produce a {deliverableTemplate} for {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.
-
-   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
@@ -245,10 +280,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}
 
    **[USER PAUSE]** for selection.
@@ -348,7 +383,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})
    >
@@ -605,25 +640,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. -->
+
+   - **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:
 
-     > ⚠ **What you're describing may overlap with existing explorations in this workspace:**
+     > 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.
 
-   - 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.
+     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}`.
+
+   - `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.
 
@@ -782,12 +819,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.)
 
@@ -806,9 +843,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 `[USER PAUSE]` here — the next user-facing gate is the problem statement (Step 5).
@@ -910,7 +944,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.**
 
@@ -1140,7 +1176,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:
 
@@ -1277,9 +1313,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
@@ -1314,7 +1350,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.
@@ -1331,9 +1367,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}
@@ -1345,9 +1379,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:
@@ -1461,7 +1493,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.
@@ -1503,10 +1535,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
@@ -1549,7 +1581,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.
 
@@ -1592,7 +1624,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.
@@ -1675,9 +1707,16 @@ Pick whichever fits the user's flow — they're equivalent in content. Do not in
 
 <!-- skill-options:no-gate-change: adds a convergence note at the top of the rec-wait — both answerers (local coding agent vs Ritual server) poll get_recommendations_preview until ≥1 rec; the only difference is who produced the answers. No new pause gate or Step header; the run/pause gate + its options are unchanged. -->
 
-**Both answerers converge here — once the run is underway, poll until recommendations exist.** The job from this point on is the SAME regardless of who produced the answers: poll `mcp__ritual__get_recommendations_preview(exploration_id)` until it returns **at least one recommendation**, then continue to Step 9. The *only* difference between the two paths is the **answerer** — the **local coding agent** (you, when repo-linked) vs **Ritual's server agentic run** — and that only changes how you reach this wait (agent-answered → straight to the rec poll; server → poll the run to `COMPLETED` first, then the recs). Never render the Step 9 landing, and never call `accept_recommendations`, from a zero-rec read.
+<!-- skill-options:no-gate-change: Step 8.1 rec-wait polls get_exploration_status.recommendationsStatus (not_started|generating|ready|empty|failed); on `failed` it offers retry_recommendations (re-enqueues rec-gen only). Render-only signal + an offered action, no pause/option/Step-header change. -->
+**Both answerers converge here — once the run is underway, poll until recommendations are READY.** The job from this point on is the SAME regardless of who produced the answers. **Poll the authoritative signal: `mcp__ritual__get_exploration_status(exploration_id).recommendationsStatus`.** It removes the guesswork that bit us before — it is unambiguous:
+- `not_started` / `generating` → **keep polling.** A zero `recommendationCount` here is NORMAL — generation is enqueued/in flight, NEVER a "miss." (Older servers may omit the field; if `recommendationsStatus` is absent, fall back to polling `get_recommendations_preview` until ≥1.)
+- `ready` → recommendations exist. Fetch them (`get_recommendations_preview`) and continue to Step 9.
+- `empty` → generation FINISHED with genuinely zero recs (rare, real terminal state). Surface it plainly — do NOT render a fake Step 9 landing, do NOT re-run.
+- `failed` → generation exhausted its auto-retries (terminal). Surface it with the one-line `recommendationsError` if present, and **offer to retry** — on a `yes`, call `mcp__ritual__retry_recommendations(exploration_id)` (re-enqueues ONLY rec-gen on the existing answers; status returns to `generating`, resume polling). Do NOT call `start_agentic_run` (that re-answers the whole exploration) and do NOT auto-retry without asking.
+
+The *only* difference between the two answerer paths — **local coding agent** (you, repo-linked) vs **Ritual's server agentic run** — is how you reach this wait (agent-answered → straight to the status poll; server → poll the run to `COMPLETED` first, then the status). Never render the Step 9 landing, and never call `accept_recommendations`, from anything but `ready`.
 
-**Agent-answered path (default):** you already wrote + `submit_all_answers`'d, so there's no agentic run to poll — go straight to the recommendation wait: poll `mcp__ritual__get_recommendations_preview(exploration_id)` (`Bash sleep 20` per iteration, a "still generating recommendations…" line every ~3 polls) until it returns **at least one recommendation**, then continue to Step 9. NEVER render the Step 9 landing — and never call `accept_recommendations` — from a zero-rec read; if 10+ min pass with zero rows, surface it as an anomaly. (Skip the `get_agentic_run` polling below — that's the server-fallback path.)
+**Agent-answered path (default):** you already wrote + `submit_all_answers`'d, so there's no agentic run to poll — go straight to the recommendation wait: poll `mcp__ritual__get_exploration_status(exploration_id).recommendationsStatus` (`Bash sleep 20` per iteration, a "still generating recommendations…" line every ~3 polls) until it reads `ready`, then fetch + continue to Step 9. `generating` → keep polling; `empty` → genuine zero-rec terminal; NEVER render the Step 9 landing or call `accept_recommendations` from anything but `ready`; if 10+ min pass still `generating`, surface it as an anomaly. (Skip the `get_agentic_run` polling below — that's the server-fallback path.)
 
 **Server fallback path** (you called `start_agentic_run`): poll `mcp__ritual__get_agentic_run(run_id)` using `references/async-polling.md`: **`Bash sleep 20` (constant 20 — matches Spark's 20s agentic cadence; never escalate)** per iteration, then a fresh status call. Even if the run takes 2+ minutes, the sleep value stays a constant 20; the harness blocks chained-shorter-sleeps-at-increasing-N just like it blocks `sleep ≥ 30`, but a fixed `20` is non-escalating and under 30 → guard-safe. Agentic runs CAN exceed 5 min for large explorations — if you see status still running past ~5 min of polling, switch to the `Monitor` + `until <check>; do sleep 2; done` pattern from `references/async-polling.md` § Long waits.
 
@@ -1689,15 +1728,18 @@ Then print progress only when `progress_pct` or `current_step` changes, or every
 
 > Agentic run: {progress_pct}% — {current_step}
 
-When `status` is `COMPLETED`: **wait for recommendation ROWS before Step 9.** The run reporting
+When `status` is `COMPLETED`: **wait for `recommendationsStatus: ready` before Step 9.** The run reporting
 `completed` does NOT mean recommendations exist yet — rec generation is a separate queued job that
-lands MINUTES later (the 2026-06-05 premature-accept incident class; observed again live 2026-06-12:
-an agent rendered "0 recommendations across 0 categories" and vacuously proceeded). Poll
-`mcp__ritual__get_recommendations_preview(exploration_id)` on the standard cadence (`Bash sleep 20`
-per iteration, "still generating recommendations…" line every ~3 polls) until the preview returns
-**at least one recommendation**, then continue to Step 9. NEVER render the Step 9 landing — and
-never call `accept_recommendations` — from a zero-rec read. If 10+ minutes pass with zero rows,
-surface that as an anomaly instead of proceeding.
+lands MINUTES later (the 2026-06-05 premature-accept incident class; observed again live 2026-06-12
+and 2026-06-15). Poll `mcp__ritual__get_exploration_status(exploration_id).recommendationsStatus` on
+the standard cadence (`Bash sleep 20` per iteration, "still generating recommendations…" line every
+~3 polls): `generating` → keep polling; `ready` → continue to Step 9; `empty` → genuine zero-rec
+terminal, surface it. NEVER render the Step 9 landing — and never call `accept_recommendations` —
+from anything but `ready`. If 10+ minutes pass still `generating`, surface that as an anomaly
+instead of proceeding.
+
+<!-- skill-options:no-gate-change: Step 8.1 adds a load-bearing clause closing the "zero-rec = generation miss → re-run / reroute" loophole; tightens the existing wait-for-rows rule only — no pause, option, or Step header added or changed. -->
+**A zero-rec read is NEVER a "generation miss," and re-running is NOT a recovery (load-bearing).** The run reporting `completed` only means *answering* finished — recommendation synthesis is a SEPARATE async job that may still be in flight, so zero rows means **not yet**, never **failed**. Do NOT relabel it a "generation miss" / "the synthesizer came back empty" / "0 recommendations" and act on that: do NOT call `start_agentic_run` again to "regenerate" (the answers are already committed — a re-run re-answers the whole exploration from scratch, burns a full pipeline, and can double-generate), and do NOT propose "routing around" synthesis by building a plan from the raw discovery answers. Just keep polling `get_exploration_status.recommendationsStatus` until `ready` (or `empty` — the rare genuine terminal). The synthesizer is almost never the problem — being early in the async window (`generating`) is. The ONLY escalation, and only after the 10-min ceiling still `generating`, is to surface it as an anomaly and offer `/ritual status` or the web app — never an automatic re-run, never a reroute.
 When `status` is `COMPLETED_WITH_ERRORS`: tell the user, then apply the same wait-for-rows rule — 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` (product/design answer-review mode only): continue to Step 8.5.
@@ -1799,7 +1841,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)
 
@@ -1807,7 +1849,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):**
@@ -1844,10 +1886,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:
@@ -1915,15 +1957,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`).
@@ -1966,7 +2010,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)
 
@@ -1974,7 +2018,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:
 
@@ -2225,7 +2269,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}
 
@@ -2458,7 +2502,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
@@ -2790,7 +2834,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.
 

package/skills/claude-code/ritual/references/cli-output-contract.md

@@ -71,10 +71,10 @@ Default dense-list shape:
 {1-3 sentence description, wrapped for terminal width.}
 
 Why high-leverage:
-{specific signal: RB id, prior decision, open deferral, shipped PR, or file-level pattern.}
+{specific signal: build-requirement id, prior decision, open follow-up, shipped PR, or file-level pattern.}
 
 Touches:
-{exploration / PR / deferral references, comma-separated only if short; otherwise wrap.}
+{exploration / PR / follow-up references, comma-separated only if short; otherwise wrap.}
 ```
 
 Use this format for high-leverage problem candidates, recommendation lists with rationale, lineage summaries with multiple events, and any other CLI section where each item has more than one sentence of explanation.
@@ -320,11 +320,11 @@ The pulse rule and visual specs live in the [§ /ritual context-pulse](#ritual-c
   ```text
   {…the step's content…}
 
-  Pulse: Reasoning Readiness 58% · Context Debt 42% ↓3% (scope locked)
+  Pulse: Reasoning Readiness 58% · Context Debt 42% ↓3% (locking scope cut it 3%)
   Reply  proceed (run discovery → recommendations)  ·  expert  ·  pause
   ```
 
-  - **Score line** (top of the message). Full capitalized labels — `Reasoning Readiness` and `Context Debt`, NOT lowercase. The progress delta attaches to **Context Debt as a directional drop** — `Context Debt 42% ↓3%` — so the movement reads unambiguously as debt going DOWN. (A bare `· +3%` sitting next to the debt figure reads like debt went UP by 3, the opposite of progress — that's the confusion this avoids.) The delta is **MANDATORY** on every pulse after the first (the first pulse has no prior → just the baseline + reason). Use `↓N%` when debt drops (the normal, good case), `↑N%` on a regression (rare; render full then), and `±0%` when a step didn't move the score. Never drop it — it's the visible-progress signal. (Readiness climbing and debt dropping are the same move — `Reasoning Readiness + Context Debt = 100%` — so the debt-drop arrow IS the readiness-gain signal, just framed the way users read it.)
+  - **Score line** (top of the message). Full capitalized labels — `Reasoning Readiness` and `Context Debt`, NOT lowercase. The progress delta attaches to **Context Debt as a directional drop** — `Context Debt 42% ↓3%` — so the movement reads unambiguously as debt going DOWN. (A bare `· +3%` sitting next to the debt figure reads like debt went UP by 3, the opposite of progress — that's the confusion this avoids.) The delta is **MANDATORY** on every pulse after the first (the first pulse has no prior → just the baseline + reason). Use `↓N%` when debt drops (the normal, good case), `↑N%` on a regression (rare; render full then), and `±0%` when a step didn't move the score. Never drop it — it's the visible-progress signal. (Readiness climbing and debt dropping are the same move — `Reasoning Readiness + Context Debt = 100%` — so the debt-drop arrow IS the readiness-gain signal, just framed the way users read it.) **The trailing parenthetical is a plain CAUSAL gloss — it attributes the drop to the step the user just took, in everyday words: `(locking scope cut it 3%)`, `(answering discovery dropped it 16%)`, `(grounding in your code cut it 9%)`. Not a bare state label like `(scope locked)` — the user should read what they DID and how much debt it removed. Keep the branded `Context Debt` term; the gloss makes the number mean something.** (The first pulse has no prior, so its parenthetical names the open gap instead — e.g. `(repo boundary unresolved)`.)
   - **Lift bridge** (ONE sentence, immediately ABOVE the action/CTA line — NOT under the score). This is the load-bearing piece: it turns the score into a reason to proceed. Three requirements:
     1. **Plain language for the gap — NEVER the internal dimension name.** The lowest dimension from `score_context_pulse`'s breakdown picks the message, but the user sees what it MEANS, not the label:
        | lowest dimension (internal) | what the user reads (plain) |