@ritualai/cli 0.36.22 → 0.36.28

package/skills/vscode/ritual/references/cli-output-contract.md

@@ -307,6 +307,7 @@ When you need to wait for async server work (requirements generation, build brie
 This rule applies to: Step 9.5 (`get_requirement_set_status`), Step 10b (`get_build_brief_status` on timeout), and any future status-poll surface.
 
 <!-- skill-options:no-gate-change: pulse render gains a delta + next-lift line; no decision gate, option, or pause is added or changed -->
+<!-- skill-options:no-gate-change: pulse delta now renders as a Context Debt directional drop (Context Debt N% ↓M%) instead of a bare · +N%, so the movement reads as debt going down; render-only, no gate/option/pause change -->
 
 #### Inline pulses — surface reasoning readiness climbing as context debt drops
 
@@ -319,11 +320,11 @@ The pulse rule and visual specs live in the [§ /ritual context-pulse](#ritual-c
   ```text
   {…the step's content…}
 
-  Pulse: Reasoning Readiness 58% · Context Debt 42% · +3% (scope locked)
+  Pulse: Reasoning Readiness 58% · Context Debt 42% ↓3% (scope locked)
   Reply  proceed (run discovery → recommendations)  ·  expert  ·  pause
   ```
 
-  - **Score line** (top of the message). Full capitalized labels — `Reasoning Readiness` and `Context Debt`, NOT lowercase. The **`· +N%` delta is MANDATORY** on every pulse after the first (the first pulse has no prior, so it shows just the baseline + reason). The delta is the visible-progress signal — never drop it. Show `+0%` honestly if a step didn't move the score, and `−N%` on a regression (rare; render full then).
+  - **Score line** (top of the message). Full capitalized labels — `Reasoning Readiness` and `Context Debt`, NOT lowercase. The progress delta attaches to **Context Debt as a directional drop** — `Context Debt 42% ↓3%` — so the movement reads unambiguously as debt going DOWN. (A bare `· +3%` sitting next to the debt figure reads like debt went UP by 3, the opposite of progress — that's the confusion this avoids.) The delta is **MANDATORY** on every pulse after the first (the first pulse has no prior → just the baseline + reason). Use `↓N%` when debt drops (the normal, good case), `↑N%` on a regression (rare; render full then), and `±0%` when a step didn't move the score. Never drop it — it's the visible-progress signal. (Readiness climbing and debt dropping are the same move — `Reasoning Readiness + Context Debt = 100%` — so the debt-drop arrow IS the readiness-gain signal, just framed the way users read it.)
   - **Lift bridge** (ONE sentence, immediately ABOVE the action/CTA line — NOT under the score). This is the load-bearing piece: it turns the score into a reason to proceed. Three requirements:
     1. **Plain language for the gap — NEVER the internal dimension name.** The lowest dimension from `score_context_pulse`'s breakdown picks the message, but the user sees what it MEANS, not the label:
        | lowest dimension (internal) | what the user reads (plain) |
@@ -335,7 +336,7 @@ The pulse rule and visual specs live in the [§ /ritual context-pulse](#ritual-c
     2. **Name the NEXT STEP as the resolver, explicitly.** The bridge must make clear that the action the user is about to take is what closes the gap — `that's exactly what the next step, discovery, resolves` / `code recon next grounds it` / `the build brief locks those down`. The bridge and the forward-CTA below it name the SAME move — one story.
     3. **Terse + declarative** — no `now let me help you improve this` assistant/affect register (`cli-experience-tenets.md`).
     On the LAST scoreable step (Step 10, implementation-ready), there's no further lift — the bridge becomes the readiness statement: `The brief is your build path — implement when ready.`
-- **Full (with bars + Reasoning Readiness / Context Debt / Context Surface labels)** when crossing a state-tier boundary, jumping ≥15%, or regressing. Full mode keeps the same `+N%` delta on the score line and the same lift bridge above the CTA.
+- **Full (with bars + Reasoning Readiness / Context Debt / Context Surface labels)** when crossing a state-tier boundary, jumping ≥15%, or regressing. Full mode keeps the same `Context Debt N% ↓M%` delta on the score line and the same lift bridge above the CTA.
 - The score line goes near the top of the step's message; the lift bridge goes right before the action line. Both are additive, not replacements.
 - Prefer `mcp__ritual__score_context_pulse` (one canonical server-side call, persisted for trend reporting); fall back to deterministic agent-side counts only if the tool errors. No LLM call in the hot path either way.
 

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: 49db57c7a618c67e -->
+<!-- source-sha: 890b590159dbb59d -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -929,6 +929,8 @@ Store the final sub-problems for Step 5 — they go into `considerations[]`.
 
 #### Step 5 — Generate problem frame
 
+<!-- skill-options:no-gate-change: Step 5 adds a render-only rule (do not surface follow_up_questions / an "open questions" preview / fuzzy-meta at the frame gate); the frame's pause + options + Reply line are unchanged. -->
+
 ##### 5.1 First draft
 
 Call `mcp__ritual__generate_problem_statement` with:
@@ -971,6 +973,7 @@ Or reply with edits, e.g. `tighten`, `broaden`, `focus on outbox`, `drop dashboa
 ```
 
 Rules:
+- **Render ONLY the four blocks above** — Problem frame, Optimize for, References, and the Reply line. Nothing else. The `generate_problem_statement` response may include `follow_up_questions` and quality scores: those are for YOUR internal awareness, never for display. Do NOT add an "Open questions" / "what discovery will resolve" section, do NOT preview or list discovery questions here, and do NOT editorialize about what's "still fuzzy" or "what the next step pins down." Discovery is the next step and owns open questions; the frame is a lock-point, not a discovery preview. Surfacing them here both pre-empts Step 7 and clutters the gate.
 - Do not show the old versioned scope heading.
 - Do not show `Engineering problem:` as the heading; use `Problem frame`.
 - Do not say `ship it` unless the user used that language first.
@@ -1736,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.
+
+The *only* difference between the two answerer paths — **local coding agent** (you, repo-linked) vs **Ritual's server agentic run** — is how you reach this wait (agent-answered → straight to the status poll; server → poll the run to `COMPLETED` first, then the status). Never render the Step 9 landing, and never call `accept_recommendations`, from anything but `ready`.
 
-**Agent-answered path (default):** you already wrote + `submit_all_answers`'d, so there's no agentic run to poll — go straight to the recommendation wait: poll `mcp__ritual__get_recommendations_preview(exploration_id)` (`Bash sleep 20` per iteration, a "still generating recommendations…" line every ~3 polls) until it returns **at least one recommendation**, then continue to Step 9. NEVER render the Step 9 landing — and never call `accept_recommendations` — from a zero-rec read; if 10+ min pass with zero rows, surface it as an anomaly. (Skip the `get_agentic_run` polling below — that's the server-fallback path.)
+**Agent-answered path (default):** you already wrote + `submit_all_answers`'d, so there's no agentic run to poll — go straight to the recommendation wait: poll `mcp__ritual__get_exploration_status(exploration_id).recommendationsStatus` (`Bash sleep 20` per iteration, a "still generating recommendations…" line every ~3 polls) until it reads `ready`, then fetch + continue to Step 9. `generating` → keep polling; `empty` → genuine zero-rec terminal; NEVER render the Step 9 landing or call `accept_recommendations` from anything but `ready`; if 10+ min pass still `generating`, surface it as an anomaly. (Skip the `get_agentic_run` polling below — that's the server-fallback path.)
 
 **Server fallback path** (you called `start_agentic_run`): poll `mcp__ritual__get_agentic_run(run_id)` using `references/async-polling.md`: **`Bash sleep 20` (constant 20 — matches Spark's 20s agentic cadence; never escalate)** per iteration, then a fresh status call. Even if the run takes 2+ minutes, the sleep value stays a constant 20; the harness blocks chained-shorter-sleeps-at-increasing-N just like it blocks `sleep ≥ 30`, but a fixed `20` is non-escalating and under 30 → guard-safe. Agentic runs CAN exceed 5 min for large explorations — if you see status still running past ~5 min of polling, switch to the `Monitor` + `until <check>; do sleep 2; done` pattern from `references/async-polling.md` § Long waits.
 
@@ -1750,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.
@@ -1905,7 +1918,7 @@ or proceed to your {Deliverable}.
 
 {…every category, every rec, one line each…}
 
-Pulse: Reasoning Readiness ~88% · Context Debt 12% · +16% (recommendations ready)
+Pulse: Reasoning Readiness ~88% · Context Debt 12% ↓16% (recommendations ready)
 
 A few assumptions are still unverified — the build brief is what locks them down.
 Reply  drill R{N} (read one in full)   ·   edit R{N} <your change>   ·   proceed (generate the {Deliverable})