@ritualai/cli 0.36.25 → 0.36.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ritualai/cli",
-  "version": "0.36.25",
+  "version": "0.36.28",
   "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.28",
+  "builtAt": "2026-06-15T15:33:01.454Z",
+  "skillsHash": "2019cd011119"
 }

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: 2019cd011119
 ---
 
 # /ritual

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

@@ -1675,9 +1675,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.
 
-**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.)
+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_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 +1696,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.

package/skills/claude-code/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: 8175b963af80b591 -->
+<!-- source-sha: 890b590159dbb59d -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -1739,9 +1739,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.
 
-**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.)
+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_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.
 
@@ -1753,15 +1760,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.

package/skills/codex/ritual/.ritual-bundle.json

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.25",
-  "builtAt": "2026-06-15T14:41:36.894Z",
-  "skillsHash": "5c3ae1fc185a"
+  "cliVersion": "0.36.28",
+  "builtAt": "2026-06-15T15:33:01.454Z",
+  "skillsHash": "2019cd011119"
 }

package/skills/codex/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: 2019cd011119
 ---
 
 # /ritual

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

@@ -1675,9 +1675,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.
 
-**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.)
+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_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 +1696,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.

package/skills/codex/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: 8175b963af80b591 -->
+<!-- source-sha: 890b590159dbb59d -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -1739,9 +1739,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.
 
-**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.)
+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_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.
 
@@ -1753,15 +1760,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.

package/skills/cursor/ritual/.ritual-bundle.json

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.25",
-  "builtAt": "2026-06-15T14:41:36.894Z",
-  "skillsHash": "5c3ae1fc185a"
+  "cliVersion": "0.36.28",
+  "builtAt": "2026-06-15T15:33:01.454Z",
+  "skillsHash": "2019cd011119"
 }

package/skills/cursor/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: 2019cd011119
 ---
 
 # /ritual

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

@@ -1675,9 +1675,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.
 
-**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.)
+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_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 +1696,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.

package/skills/cursor/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: 8175b963af80b591 -->
+<!-- source-sha: 890b590159dbb59d -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -1739,9 +1739,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.
 
-**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.)
+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_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.
 
@@ -1753,15 +1760,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.

package/skills/gemini/ritual/.ritual-bundle.json

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.25",
-  "builtAt": "2026-06-15T14:41:36.894Z",
-  "skillsHash": "5c3ae1fc185a"
+  "cliVersion": "0.36.28",
+  "builtAt": "2026-06-15T15:33:01.454Z",
+  "skillsHash": "2019cd011119"
 }

package/skills/gemini/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: 2019cd011119
 ---
 
 # /ritual

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

@@ -1675,9 +1675,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.
 
-**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.)
+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_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 +1696,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.

package/skills/gemini/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: 8175b963af80b591 -->
+<!-- source-sha: 890b590159dbb59d -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -1739,9 +1739,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.
 
-**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.)
+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_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.
 
@@ -1753,15 +1760,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.

package/skills/kiro/ritual/.ritual-bundle.json

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.25",
-  "builtAt": "2026-06-15T14:41:36.894Z",
-  "skillsHash": "5c3ae1fc185a"
+  "cliVersion": "0.36.28",
+  "builtAt": "2026-06-15T15:33:01.454Z",
+  "skillsHash": "2019cd011119"
 }

package/skills/kiro/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: 2019cd011119
 ---
 
 # /ritual

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

@@ -1675,9 +1675,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.
 
-**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.)
+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_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 +1696,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.

package/skills/kiro/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: 8175b963af80b591 -->
+<!-- source-sha: 890b590159dbb59d -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -1739,9 +1739,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.
 
-**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.)
+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_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.
 
@@ -1753,15 +1760,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.

package/skills/vscode/ritual/.ritual-bundle.json

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.25",
-  "builtAt": "2026-06-15T14:41:36.894Z",
-  "skillsHash": "5c3ae1fc185a"
+  "cliVersion": "0.36.28",
+  "builtAt": "2026-06-15T15:33:01.454Z",
+  "skillsHash": "2019cd011119"
 }

package/skills/vscode/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: 2019cd011119
 ---
 
 # /ritual

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

@@ -1675,9 +1675,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.
 
-**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.)
+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_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 +1696,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.

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: 8175b963af80b591 -->
+<!-- source-sha: 890b590159dbb59d -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -1739,9 +1739,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.
 
-**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.)
+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_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.
 
@@ -1753,15 +1760,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.