@ritualai/cli 0.36.14 → 0.36.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ritualai/cli",
-  "version": "0.36.14",
+  "version": "0.36.22",
   "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.14",
-  "builtAt": "2026-06-14T21:33:31.224Z",
-  "skillsHash": "ee9a77046c96"
+  "cliVersion": "0.36.22",
+  "builtAt": "2026-06-15T13:28:31.790Z",
+  "skillsHash": "8a8905aae549"
 }

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: ee9a77046c96
+stamp: 8a8905aae549
 ---
 
 # /ritual

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

@@ -46,7 +46,7 @@ When **not** to use:
 
 Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must choose among options, approve creation or acceptance, resolve ambiguity, authorize implementation, accept cost/time, or provide missing non-code context. Do **not** pause for status-only steps, safe defaults, internal recon, or silent checks.
 
-**Pauses are not optional even in auto-mode** (load-bearing). When the host agent has auto-accept / bypass-permissions enabled, the SKILL must still honor every `[USER PAUSE]` as a hard stop. Inferring an answer from context, choosing a default, or pressing on without an actual user reply defeats the build flow's value: Ritual is producing aligned recommendations because the human shaped the inputs, not because the agent guessed plausibly. The auto-mode reminder in Step 0 below is informational only — it does not relax this rule; it's a heads-up to the user, not permission to bypass pauses.
+**Pauses are not optional even in auto-mode** (load-bearing). When the host agent has auto-accept / bypass-permissions enabled, the SKILL must still honor every `[USER PAUSE]` as a hard stop. Inferring an answer from context, choosing a default, or pressing on without an actual user reply defeats the build flow's value: Ritual is producing aligned recommendations because the human shaped the inputs, not because the agent guessed plausibly. We do not surface a heads-up about this to the user (Step 0) — we simply enforce the gates regardless of the host's auto-accept mode.
 
 ---
 
@@ -60,19 +60,18 @@ Follow `references/cli-output-contract.md` for terminal output, dense-list forma
 >
 > The new shape: one informational line in the FIRST user-visible message of the flow. No pause. No `[USER PAUSE]` here. If the user IS in auto-mode, the next genuine decision pause (workspace pick, scope pick, etc.) is the natural place they'll notice it racing past. The line below gives them the right cue + remediation.
 
-The SKILL MUST include the following one-line heads-up at the top of the **first** user-visible message in a `/ritual build` flow (typically the workspace summary in Step 1, or the no-args prompt in Step 1.1). Include it once per flow only:
+Do NOT show an auto-mode / "~N decisions" / Shift+Tab heads-up. It reads as meta-instruction clutter at the start of the flow — just begin the flow plainly. (The pausing discipline below is enforced regardless of the host's auto-accept mode; we simply don't preface it with a lecture.)
 
-```text
-Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
-scope, discovery picks, rec acceptance, implementation approval). If your
-agent is in auto-accept / bypass-permissions mode, those pauses won't
-actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
-back to "default").
-```
+Pausing discipline is still load-bearing — every `[USER PAUSE]` later in the flow is a hard stop regardless of whether the user reads it. The agent's contract is unchanged from the preamble: never infer an answer, never pick a default, never press on without an actual user reply. Auto-mode collapsing those pauses is the user's risk to accept; the SKILL enforces the gates regardless.
+
+<!-- skill-options:no-gate-change: voice/copy cleanup — removes the auto-mode "~5 decisions" heads-up, adds a no-preamble/no-editorializing/render-verbatim voice rule, replaces job-gate + run-gate copy with plainer wording, and moves the context pulse to the bottom (above the CTA) starting only at the curate-questions step. No tracked pause gate, option, or Step header is added, removed, or changed. -->
 
-That's it. No menu. No required reply. Just inform.
+**Voice — render gates plainly, add NOTHING (load-bearing, applies to EVERY message in the flow).** Output the gate copy this skill prescribes and nothing else. In particular, NEVER:
+- **Preface a tool call with narration.** Don't say "I'll start by classifying the job…", "Let me kick off an exploration…", "I'll create the exploration and pull questions…". Just make the tool call; report the result plainly after.
+- **Editorialize about the work.** Don't add commentary like "this is exactly the kind of ambiguous, cross-cutting work where it pays to surface context before writing code", "the design decisions still aren't settled", or any "here's why this step matters" justification. The user knows why they ran `/ritual build`.
+- **Narrate internal mechanics or paraphrase the gate copy into process-talk.** Don't say "You're framed. Grounding in the codebase, then I'll…" or describe what Ritual's research agents do under the hood. Lead with the plain meaning for the user; surface mechanism only if they ask.
 
-Pausing discipline is still load-bearing — every `[USER PAUSE]` later in the flow is a hard stop regardless of whether the user reads or ignores this heads-up. The agent's contract is unchanged from the preamble: never infer an answer, never pick a default, never press on without an actual user reply. Auto-mode collapsing those pauses is the user's risk to accept; the SKILL's job is just to surface that risk visibly once, then enforce the gates regardless.
+Every message should be the prescribed gate copy (rail + content + CTA) — terse, plain, no preamble, no sign-off commentary.
 
 **Per-agent indicators** (informational, for the SKILL's own awareness — NOT to gate behavior):
 
@@ -139,8 +138,9 @@ When this gate runs:
    ● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ {Deliverable}  ○ Implementation (Your agent)
 
    You're looking to: {restate the ask in one short clause}
-   The job to be done: {workItemLabel} — {why}
-   Deliverable: {deliverableTemplate}
+
+   Once you run the exploration and review recommendations, a {deliverableTemplate} will be
+   created as context for your coding agent.
 
    Reply `proceed` to frame the problem (sub-problems + problem statement), or tell me what the
    job actually is.
@@ -235,10 +235,8 @@ Resolution order:
    - **Not found** (deleted, access revoked, wrong id in config): pause with a clear error and offer `workspace: list` to re-bind. Don't fall through to `list_explorations` later — it errors with a less actionable message.
    - **Found:** store `workspace.explorationCount` for Step 1.5. The SKILL never maintains a local "empty workspace" cache because that goes stale against anything that mutates the workspace outside this CLI's view.
 
-   User-visible (per Step 0, prepend the one-line auto-mode heads-up — once per flow):
+   User-visible:
 
-   > Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace, scope, discovery picks, rec acceptance, implementation approval). If your agent is in auto-accept / bypass-permissions mode, those pauses won't actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle back to "default").
-   >
    > Using workspace: **{workspaceName}** from `.ritual/config.json`.
    > Override with `workspace: list`.
 
@@ -303,12 +301,6 @@ If there are **zero existing explorations** and `raw_input = null`, do not say "
 Ritual build
 ✓ Job  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
-Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
-scope, discovery picks, rec acceptance, implementation approval). If your
-agent is in auto-accept / bypass-permissions mode, those pauses won't
-actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
-back to "default").
-
 Using workspace: {workspaceName}.
 
 No Ritual history here yet.
@@ -913,7 +905,7 @@ The returned text becomes the new current draft. Show it using the same `Problem
 
 When the user locks the frame, store the final text as `problem_statement` for Step 6.
 
-**Pulse (Step 5 done):** Emit a pulse — feature clarity just jumped. Compute per `/ritual context-pulse` § Step CP3. Render full if this crosses Raw ask → Under-specified, else compact. Translate raw tier labels into user-facing copy per `references/cli-output-contract.md` § Pulse tier labels — never expose `RAW_ASK` / `UNDER_SPECIFIED` / etc. directly.
+**No pulse here.** The context pulse appears only from the curate-questions step onward (cli-output-contract § Inline pulses) — early on the score is low/noisy and the line clutters the gate. The first pulse is at Step 7.4.
 
 #### Step 5.7 — Ground the exploration (silent recon — runs AFTER the frame locks)
 
@@ -1056,11 +1048,6 @@ If no seed file is found, OR the seed's `## The ask` doesn't match the current `
    Scope correction:
    - I did not find `guest_session_id` in the inspected models.
 
-   Pulse: Reasoning Readiness ~55% · Context Debt 45% · +12% (initial ask + code recon)
-
-   (lift bridge — renders right above the next action) Most of the gap left is
-   unsettled design decisions — that's exactly what the next step, discovery, resolves.
-
    Next: attach PRDs/tickets if they should shape scope, or `proceed` to continue.
    ```
 
@@ -1137,7 +1124,7 @@ If no seed file is found, OR the seed's `## The ask` doesn't match the current `
 
 If the user explicitly asks "what did you find?", you may show a tight digest then — otherwise stay silent.
 
-**Pulse (recon done):** Emit a pulse line — repo grounding just moved meaningfully (sources collected, agent inspected files, possibly KG hits). Compute per `/ritual context-pulse` § Step CP3 and render compact unless this is the FIRST pulse of the build flow, in which case use full.
+**No pulse here** (pre-curate — see cli-output-contract § Inline pulses; the first pulse is at Step 7.4).
 
 ##### 5.7.3 — Collect the `sources` array
 
@@ -1342,9 +1329,8 @@ Ritual build
 Discovery questions ready — {M} generated across {N} areas.
 
 These 12 questions target where this problem is hardest — the tradeoffs,
-constraints, and unknowns that decide the design. When you proceed, Ritual
-dispatches its research agents to answer them against this codebase and your
-sources; those answers become the spine of the {Deliverable}.
+constraints, and unknowns that decide the design. Next, agents will develop
+answers and generate recommendations.
 
 {Area name 1}
   ✓ 1. {question, full text, wrapped readably}
@@ -1566,7 +1552,21 @@ Skip silently if no anti-goals were mentioned. (No mention = nothing to confirm;
 
 #### Step 8 — Run discovery through recommendations
 
-The agentic pipeline runs sourcing → answers → recommendations. For engineering / agentic-coding flows, do **not** offer an answers-only mode; the happy path is to run through recommendations.
+The pipeline runs answers → recommendations. **Choose the answerer by whether you
+actually have the code to ground answers in — this is NOT decided by the fact
+it's `/ritual build`.**
+
+- **You're genuinely repo-linked** — Step 5.7 recon ran and you read real files
+  (you have a `sources` list / codebase context packet, and filesystem access to
+  the repo): **YOU answer the picked questions** yourself. You're closest to the
+  code, so the answers are grounded in what you actually read.
+- **You're not** — recon was skipped (Step 5.7.6), no repo is open, or the ask
+  isn't a codebase task: use the **server agentic run** (`start_agentic_run`),
+  which sources answers from the knowledge graph + registered sources instead.
+
+Pick the path honestly; don't claim to answer from code you didn't read.
+
+<!-- skill-options:no-gate-change: Step 8 answerer is chosen by real repo-linkage (recon ran / code open), not by the /ritual build invocation; agent-answers when repo-linked, server-run fallback. Includes prose guidance on answer length (~300-600 words), that attached code is OPTIONAL illustrative reference (not part of the answer, not a verbatim copy), and a hard no-secrets/no-PII redaction rule for the BYO answerer. The run/pause gate + its options are unchanged — no new pause gate or Step header. -->
 
 For `engineering`, `delivery`, and `operations` roles, show:
 
@@ -1576,20 +1576,28 @@ Ritual build
 
 Run discovery
 
-Ritual will source answers for the picked questions, then generate
+I'll answer the picked questions from the codebase, then generate
 recommendations. This usually takes a few minutes.
 
-Reply `run` to source answers → generate recommendations.
+Reply `run` to answer → generate recommendations.
 Reply `pause` to stop here.
 ```
 
+(Match the first line to the path you'll actually take: repo-linked → "I'll answer the picked questions from the codebase…"; fallback → "Ritual will source answers for the picked questions…". Don't claim to answer from code if you're taking the server path.)
+
 Visible CTA is `run`. Accept `r`, `go`, `continue`, or `next` as aliases. Per `references/cli-output-contract.md` § Surface-aware continuation prompts, do NOT treat empty input as proceed inside agent chat.
 
-Call `mcp__ritual__start_agentic_run` with:
-- `scope_type: 'exploration'`
-- `exploration_id`
+On `run`, **if you're genuinely repo-linked (per the check above), answer the questions yourself** (BYO-answerer; do NOT call `start_agentic_run`):
+1. The Step 7.4 accept (`accept_discovery_questions_batch`) returned `materialized[]` — the committed questions with their row `id`s. (If you didn't keep them, the same ids are what you passed to accept.)
+2. For each committed question, call `mcp__ritual__write_answer_context(question_id, content)` with an answer grounded in your codebase recon — the files you read at Step 5.7, the actual code, real constraints. Answer in PARALLEL where your agent supports it (e.g. one subagent per Area). The content is provisional + provenance-tagged agentic until committed; only the final committed set drives recommendations.
+   - **Length:** keep each answer to **~300–600 words by default** — tight and grounded, not an essay. Go longer only when the question genuinely needs it.
+   - **Code:** the answer itself is **prose** — keep it that way. Code is **optional reference, not part of the answer**: attach a snippet only when it would help a future reader or agent reason about your answer (a key type, contract, or call site worth pointing back to), never to complete the answer. When you do, `content` is **markdown** — add it as a **fenced code block with a language tag** (e.g. ` ```ts `) with the `file/path` and the minimal illustrative lines, never a whole-file paste. Spark lifts these fences out of the prose into a collapsed "View details" reference beside the answer, and markdown keeps them portable to the `.ritual/` projection.
+   - **Never leak secrets or sensitive data.** A snippet is **illustrative, not a verbatim copy** — it only has to convey the shape/idea, so simplify and elide freely. **NEVER** include API keys, tokens, passwords, connection strings, credentials, `.env` values, real customer data, or PII — even if they're literally in the file you read. Replace them with obvious placeholders (`process.env.X`, `"<api-key>"`, `"user@example.com"`). The same goes for the prose: describe constraints without pasting secret values.
+3. When every committed question has answer context, call `mcp__ritual__submit_all_answers(exploration_id)` — it commits the set and triggers recommendation generation. Then go to the recommendation wait (Step 8.1, agent-answered path).
+
+**Fallback — server answers (no repo / nothing to ground in):** call `mcp__ritual__start_agentic_run` with `scope_type: 'exploration'` + `exploration_id`, then follow the server polling path (8.0 → 8.1).
 
-For `product`, `design`, or explicitly PRD-style flows, answer review may be useful. Offer two choices without time estimates:
+For `product`, `design`, or explicitly PRD-style flows where answer review is useful, offer two choices without time estimates (this path uses the SERVER answer engine so the user can review each generated answer — Step 8.5):
 
 ```text
 Ritual build
@@ -1608,9 +1616,11 @@ Reply `1` or `2`. Reply `pause` to stop here.
 
 If they pick 1, call `start_agentic_run` with `stop_after: 'answers'` and continue to Step 8.5 when it pauses. If they pick 2, call without `stop_after` and continue to Step 9 when complete.
 
-##### 8.0 — "You're unblocked" pre-roll (right after `start_agentic_run` returns the run_id)
+##### 8.0 — "You're unblocked" pre-roll (once server-side work is running)
 
-**Lock the product promise BEFORE you enter the polling loop.** The run continues server-side; the user is free to step away. The polling loop becomes the agent's job, not the user's obligation.
+This pre-roll is for the **rec-generation wait** — fire it once server-side work is running: on the agent-answered path, right after `submit_all_answers` returns (recommendation generation is now queued); on the server fallback, right after `start_agentic_run` returns the run_id. (On the agent-answered path the *answering itself* is your active work — don't show the pre-roll until you've submitted.)
+
+**Lock the product promise BEFORE you enter the polling loop.** Recommendation generation continues server-side; the user is free to step away. The polling loop becomes the agent's job, not the user's obligation.
 
 Tier the pre-roll by projected duration. Latency baseline: ~15s/question (V5.2 + KG injection, calibrate quarterly against `recs-pipeline.ts` eval results). Multiply the picked-question count by 15s, divide by 60 to get minutes.
 
@@ -1660,7 +1670,13 @@ Pick whichever fits the user's flow — they're equivalent in content. Do not in
 
 ##### 8.1 — Polling loop
 
-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.
+<!-- 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.
+
+**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.)
+
+**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.
 
 **On the FIRST poll only** (not every poll), prepend one line that locks the "background execution is default" mental model:
 

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

@@ -310,19 +310,16 @@ This rule applies to: Step 9.5 (`get_requirement_set_status`), Step 10b (`get_bu
 
 #### Inline pulses — surface reasoning readiness climbing as context debt drops
 
-After **Steps 3, 5, 7.4, 8, 9, and 10**, emit a one-line **context pulse** showing how the score moved. This is the visible encouragement loop — the user watches **reasoning readiness** climb (or equivalently, **context debt** drop) with each step instead of just feeling like the agent is asking for more inputs.
+The context pulse appears **only from the curate-questions step onward** — emit it after **Steps 7.4, 8, 9, and 10**, the FIRST one being when the user proceeds from curating discovery questions. Do NOT emit a pulse at the Job gate, the Scope gate, or after recon (Steps 3/5) — early on the score is low and noisy and the line just clutters the gate. This is the visible encouragement loop once the build is genuinely moving — the user watches **reasoning readiness** climb (context debt drop) as discovery → recommendations → brief land.
 
 The pulse rule and visual specs live in the [§ /ritual context-pulse](#ritual-context-pulse) section below — see *Step CP5 — visual modes*. TL;DR:
 
-The pulse has TWO parts, and they sit in DIFFERENT places — the score at the top of the message (status: where you are), and the **lift bridge** immediately above the action line (motivation: why your next move matters).
+**Placement — always at the BOTTOM of the message, never the first line.** The pulse score line sits **immediately above the action/CTA line** (with the one-sentence lift bridge), so the message leads with the step's actual content and ends with the progress signal + the next move. Never open a message with the pulse.
 
   ```text
-  Pulse: Reasoning Readiness 58% · Context Debt 42% · +3% (scope locked)
-
   {…the step's content…}
 
-  Most of the gap left is unsettled design decisions — that's exactly what
-  the next step, discovery, resolves.
+  Pulse: Reasoning Readiness 58% · Context Debt 42% · +3% (scope locked)
   Reply  proceed (run discovery → recommendations)  ·  expert  ·  pause
   ```
 

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: 3d973c8d7e6a514b -->
+<!-- source-sha: 49db57c7a618c67e -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -54,6 +54,29 @@ for background discovery (unchosen-options → discovery worktrees). When you se
 - **Create the exploration with `spawn_origin: 'discovery_worktree'`** (Step 6,
   `create_exploration`) so `get_exploration_status` reports
   `autonomousDiscovery: true`.
+- **Answer the discovery questions YOURSELF (Step 8 override) — do NOT call
+  `start_agentic_run`.** You have the repo open; you are the best answerer. The
+  accept call (Step 7.4, `accept_discovery_questions_batch`) returns
+  `materialized[]` — the committed questions with their row `id`s. For each, call
+  `mcp__ritual__write_answer_context(question_id, content)` with an answer
+  grounded in your codebase recon — answer in PARALLEL where your agent supports
+  it (e.g. one subagent per Area). Keep each answer to **~300–600 words by
+  default**. The answer is **prose**; code is **optional reference, not part of
+  the answer** — attach a snippet only when it would help a future reader/agent
+  reason about your answer (a key type/contract/call site), never to complete it.
+  When you do, `content` is **markdown**: add it as a **fenced code block with a
+  language tag** (minimal lines + a `file/path`, never a whole-file paste — Spark
+  lifts these into a collapsed "View details" reference and markdown stays
+  portable to the `.ritual/` projection). A snippet is **illustrative, not a
+  verbatim copy** — simplify/elide freely, and **NEVER** include secrets, API
+  keys, tokens, credentials, `.env` values, real customer data, or PII (use
+  placeholders like `process.env.X` / `"<api-key>"`); the same goes for the prose.
+  The content is provisional + provenance-tagged agentic until committed. When
+  every committed question has answer context, call
+  `mcp__ritual__submit_all_answers(exploration_id)` — it commits the set and
+  triggers recommendation generation (the BYO-answerer flow; `start_agentic_run`
+  is unnecessary). Then poll `get_recommendations_preview` until ≥1 recommendation
+  and continue to the brief.
 - **Materialize the reasoning as files (OKF projection).** Once the brief is
   written, run `ritual project <exploration-id>` — it projects the exploration
   (index + build-brief + scope-contract + recommendations) into `.ritual/` in
@@ -115,7 +138,7 @@ When **not** to use:
 
 Use explicit **[LITE AUTO — no pause; auto-pick the recommended default]** only at decision gates. Pause when the user must choose among options, approve creation or acceptance, resolve ambiguity, authorize implementation, accept cost/time, or provide missing non-code context. Do **not** pause for status-only steps, safe defaults, internal recon, or silent checks.
 
-**Pauses are not optional even in auto-mode** (load-bearing). When the host agent has auto-accept / bypass-permissions enabled, the SKILL must still honor every `**[LITE AUTO — no pause; auto-pick the recommended default]**` as a hard stop. Inferring an answer from context, choosing a default, or pressing on without an actual user reply defeats the build flow's value: Ritual is producing aligned recommendations because the human shaped the inputs, not because the agent guessed plausibly. The auto-mode reminder in Step 0 below is informational only — it does not relax this rule; it's a heads-up to the user, not permission to bypass pauses.
+**Pauses are not optional even in auto-mode** (load-bearing). When the host agent has auto-accept / bypass-permissions enabled, the SKILL must still honor every `**[LITE AUTO — no pause; auto-pick the recommended default]**` as a hard stop. Inferring an answer from context, choosing a default, or pressing on without an actual user reply defeats the build flow's value: Ritual is producing aligned recommendations because the human shaped the inputs, not because the agent guessed plausibly. We do not surface a heads-up about this to the user (Step 0) — we simply enforce the gates regardless of the host's auto-accept mode.
 
 ---
 
@@ -129,19 +152,18 @@ Follow `references/cli-output-contract.md` for terminal output, dense-list forma
 >
 > The new shape: one informational line in the FIRST user-visible message of the flow. No pause. No `**[LITE AUTO — no pause; auto-pick the recommended default]**` here. If the user IS in auto-mode, the next genuine decision pause (workspace pick, scope pick, etc.) is the natural place they'll notice it racing past. The line below gives them the right cue + remediation.
 
-The SKILL MUST include the following one-line heads-up at the top of the **first** user-visible message in a `/ritual build` flow (typically the workspace summary in Step 1, or the no-args prompt in Step 1.1). Include it once per flow only:
+Do NOT show an auto-mode / "~N decisions" / Shift+Tab heads-up. It reads as meta-instruction clutter at the start of the flow — just begin the flow plainly. (The pausing discipline below is enforced regardless of the host's auto-accept mode; we simply don't preface it with a lecture.)
 
-```text
-Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
-scope, discovery picks, rec acceptance, implementation approval). If your
-agent is in auto-accept / bypass-permissions mode, those pauses won't
-actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
-back to "default").
-```
+Pausing discipline is still load-bearing — every `**[LITE AUTO — no pause; auto-pick the recommended default]**` later in the flow is a hard stop regardless of whether the user reads it. The agent's contract is unchanged from the preamble: never infer an answer, never pick a default, never press on without an actual user reply. Auto-mode collapsing those pauses is the user's risk to accept; the SKILL enforces the gates regardless.
+
+<!-- skill-options:no-gate-change: voice/copy cleanup — removes the auto-mode "~5 decisions" heads-up, adds a no-preamble/no-editorializing/render-verbatim voice rule, replaces job-gate + run-gate copy with plainer wording, and moves the context pulse to the bottom (above the CTA) starting only at the curate-questions step. No tracked pause gate, option, or Step header is added, removed, or changed. -->
 
-That's it. No menu. No required reply. Just inform.
+**Voice — render gates plainly, add NOTHING (load-bearing, applies to EVERY message in the flow).** Output the gate copy this skill prescribes and nothing else. In particular, NEVER:
+- **Preface a tool call with narration.** Don't say "I'll start by classifying the job…", "Let me kick off an exploration…", "I'll create the exploration and pull questions…". Just make the tool call; report the result plainly after.
+- **Editorialize about the work.** Don't add commentary like "this is exactly the kind of ambiguous, cross-cutting work where it pays to surface context before writing code", "the design decisions still aren't settled", or any "here's why this step matters" justification. The user knows why they ran `/ritual build`.
+- **Narrate internal mechanics or paraphrase the gate copy into process-talk.** Don't say "You're framed. Grounding in the codebase, then I'll…" or describe what Ritual's research agents do under the hood. Lead with the plain meaning for the user; surface mechanism only if they ask.
 
-Pausing discipline is still load-bearing — every `**[LITE AUTO — no pause; auto-pick the recommended default]**` later in the flow is a hard stop regardless of whether the user reads or ignores this heads-up. The agent's contract is unchanged from the preamble: never infer an answer, never pick a default, never press on without an actual user reply. Auto-mode collapsing those pauses is the user's risk to accept; the SKILL's job is just to surface that risk visibly once, then enforce the gates regardless.
+Every message should be the prescribed gate copy (rail + content + CTA) — terse, plain, no preamble, no sign-off commentary.
 
 **Per-agent indicators** (informational, for the SKILL's own awareness — NOT to gate behavior):
 
@@ -208,8 +230,9 @@ When this gate runs:
    ● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ {Deliverable}  ○ Implementation (Your agent)
 
    You're looking to: {restate the ask in one short clause}
-   The job to be done: {workItemLabel} — {why}
-   Deliverable: {deliverableTemplate}
+
+   Once you run the exploration and review recommendations, a {deliverableTemplate} will be
+   created as context for your coding agent.
 
    Reply `proceed` to frame the problem (sub-problems + problem statement), or tell me what the
    job actually is.
@@ -304,10 +327,8 @@ Resolution order:
    - **Not found** (deleted, access revoked, wrong id in config): pause with a clear error and offer `workspace: list` to re-bind. Don't fall through to `list_explorations` later — it errors with a less actionable message.
    - **Found:** store `workspace.explorationCount` for Step 1.5. The SKILL never maintains a local "empty workspace" cache because that goes stale against anything that mutates the workspace outside this CLI's view.
 
-   User-visible (per Step 0, prepend the one-line auto-mode heads-up — once per flow):
+   User-visible:
 
-   > Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace, scope, discovery picks, rec acceptance, implementation approval). If your agent is in auto-accept / bypass-permissions mode, those pauses won't actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle back to "default").
-   >
    > Using workspace: **{workspaceName}** from `.ritual/config.json`.
    > Override with `workspace: list`.
 
@@ -372,12 +393,6 @@ If there are **zero existing explorations** and `raw_input = null`, do not say "
 Ritual build
 ✓ Job  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
-Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
-scope, discovery picks, rec acceptance, implementation approval). If your
-agent is in auto-accept / bypass-permissions mode, those pauses won't
-actually pause for you — toggle off first (Claude Code: Shift+Tab to cycle
-back to "default").
-
 Using workspace: {workspaceName}.
 
 No Ritual history here yet.
@@ -982,7 +997,7 @@ The returned text becomes the new current draft. Show it using the same `Problem
 
 When the user locks the frame, store the final text as `problem_statement` for Step 6.
 
-**Pulse (Step 5 done):** Emit a pulse — feature clarity just jumped. Compute per `/ritual context-pulse` § Step CP3. Render full if this crosses Raw ask → Under-specified, else compact. Translate raw tier labels into user-facing copy per `references/cli-output-contract.md` § Pulse tier labels — never expose `RAW_ASK` / `UNDER_SPECIFIED` / etc. directly.
+**No pulse here.** The context pulse appears only from the curate-questions step onward (cli-output-contract § Inline pulses) — early on the score is low/noisy and the line clutters the gate. The first pulse is at Step 7.4.
 
 #### Step 5.7 — Ground the exploration (silent recon — runs AFTER the frame locks)
 
@@ -1125,11 +1140,6 @@ If no seed file is found, OR the seed's `## The ask` doesn't match the current `
    Scope correction:
    - I did not find `guest_session_id` in the inspected models.
 
-   Pulse: Reasoning Readiness ~55% · Context Debt 45% · +12% (initial ask + code recon)
-
-   (lift bridge — renders right above the next action) Most of the gap left is
-   unsettled design decisions — that's exactly what the next step, discovery, resolves.
-
    Next: attach PRDs/tickets if they should shape scope, or `proceed` to continue.
    ```
 
@@ -1206,7 +1216,7 @@ If no seed file is found, OR the seed's `## The ask` doesn't match the current `
 
 If the user explicitly asks "what did you find?", you may show a tight digest then — otherwise stay silent.
 
-**Pulse (recon done):** Emit a pulse line — repo grounding just moved meaningfully (sources collected, agent inspected files, possibly KG hits). Compute per `/ritual context-pulse` § Step CP3 and render compact unless this is the FIRST pulse of the build flow, in which case use full.
+**No pulse here** (pre-curate — see cli-output-contract § Inline pulses; the first pulse is at Step 7.4).
 
 ##### 5.7.3 — Collect the `sources` array
 
@@ -1383,9 +1393,8 @@ Ritual build
 Discovery questions ready — {M} generated across {N} areas.
 
 These 12 questions target where this problem is hardest — the tradeoffs,
-constraints, and unknowns that decide the design. When you proceed, Ritual
-dispatches its research agents to answer them against this codebase and your
-sources; those answers become the spine of the {Deliverable}.
+constraints, and unknowns that decide the design. Next, agents will develop
+answers and generate recommendations.
 
 {Area name 1}
   ✓ 1. {question, full text, wrapped readably}
@@ -1607,7 +1616,21 @@ Skip silently if no anti-goals were mentioned. (No mention = nothing to confirm;
 
 #### Step 8 — Run discovery through recommendations
 
-The agentic pipeline runs sourcing → answers → recommendations. For engineering / agentic-coding flows, do **not** offer an answers-only mode; the happy path is to run through recommendations.
+The pipeline runs answers → recommendations. **Choose the answerer by whether you
+actually have the code to ground answers in — this is NOT decided by the fact
+it's `/ritual build`.**
+
+- **You're genuinely repo-linked** — Step 5.7 recon ran and you read real files
+  (you have a `sources` list / codebase context packet, and filesystem access to
+  the repo): **YOU answer the picked questions** yourself. You're closest to the
+  code, so the answers are grounded in what you actually read.
+- **You're not** — recon was skipped (Step 5.7.6), no repo is open, or the ask
+  isn't a codebase task: use the **server agentic run** (`start_agentic_run`),
+  which sources answers from the knowledge graph + registered sources instead.
+
+Pick the path honestly; don't claim to answer from code you didn't read.
+
+<!-- skill-options:no-gate-change: Step 8 answerer is chosen by real repo-linkage (recon ran / code open), not by the /ritual build invocation; agent-answers when repo-linked, server-run fallback. Includes prose guidance on answer length (~300-600 words), that attached code is OPTIONAL illustrative reference (not part of the answer, not a verbatim copy), and a hard no-secrets/no-PII redaction rule for the BYO answerer. The run/pause gate + its options are unchanged — no new pause gate or Step header. -->
 
 For `engineering`, `delivery`, and `operations` roles, show:
 
@@ -1617,20 +1640,28 @@ Ritual build
 
 Run discovery
 
-Ritual will source answers for the picked questions, then generate
+I'll answer the picked questions from the codebase, then generate
 recommendations. This usually takes a few minutes.
 
-Reply `run` to source answers → generate recommendations.
+Reply `run` to answer → generate recommendations.
 Reply `pause` to stop here.
 ```
 
+(Match the first line to the path you'll actually take: repo-linked → "I'll answer the picked questions from the codebase…"; fallback → "Ritual will source answers for the picked questions…". Don't claim to answer from code if you're taking the server path.)
+
 Visible CTA is `run`. Accept `r`, `go`, `continue`, or `next` as aliases. Per `references/cli-output-contract.md` § Surface-aware continuation prompts, do NOT treat empty input as proceed inside agent chat.
 
-Call `mcp__ritual__start_agentic_run` with:
-- `scope_type: 'exploration'`
-- `exploration_id`
+On `run`, **if you're genuinely repo-linked (per the check above), answer the questions yourself** (BYO-answerer; do NOT call `start_agentic_run`):
+1. The Step 7.4 accept (`accept_discovery_questions_batch`) returned `materialized[]` — the committed questions with their row `id`s. (If you didn't keep them, the same ids are what you passed to accept.)
+2. For each committed question, call `mcp__ritual__write_answer_context(question_id, content)` with an answer grounded in your codebase recon — the files you read at Step 5.7, the actual code, real constraints. Answer in PARALLEL where your agent supports it (e.g. one subagent per Area). The content is provisional + provenance-tagged agentic until committed; only the final committed set drives recommendations.
+   - **Length:** keep each answer to **~300–600 words by default** — tight and grounded, not an essay. Go longer only when the question genuinely needs it.
+   - **Code:** the answer itself is **prose** — keep it that way. Code is **optional reference, not part of the answer**: attach a snippet only when it would help a future reader or agent reason about your answer (a key type, contract, or call site worth pointing back to), never to complete the answer. When you do, `content` is **markdown** — add it as a **fenced code block with a language tag** (e.g. ` ```ts `) with the `file/path` and the minimal illustrative lines, never a whole-file paste. Spark lifts these fences out of the prose into a collapsed "View details" reference beside the answer, and markdown keeps them portable to the `.ritual/` projection.
+   - **Never leak secrets or sensitive data.** A snippet is **illustrative, not a verbatim copy** — it only has to convey the shape/idea, so simplify and elide freely. **NEVER** include API keys, tokens, passwords, connection strings, credentials, `.env` values, real customer data, or PII — even if they're literally in the file you read. Replace them with obvious placeholders (`process.env.X`, `"<api-key>"`, `"user@example.com"`). The same goes for the prose: describe constraints without pasting secret values.
+3. When every committed question has answer context, call `mcp__ritual__submit_all_answers(exploration_id)` — it commits the set and triggers recommendation generation. Then go to the recommendation wait (Step 8.1, agent-answered path).
+
+**Fallback — server answers (no repo / nothing to ground in):** call `mcp__ritual__start_agentic_run` with `scope_type: 'exploration'` + `exploration_id`, then follow the server polling path (8.0 → 8.1).
 
-For `product`, `design`, or explicitly PRD-style flows, answer review may be useful. Offer two choices without time estimates:
+For `product`, `design`, or explicitly PRD-style flows where answer review is useful, offer two choices without time estimates (this path uses the SERVER answer engine so the user can review each generated answer — Step 8.5):
 
 ```text
 Ritual build
@@ -1649,9 +1680,11 @@ Reply `1` or `2`. Reply `pause` to stop here.
 
 If they pick 1, call `start_agentic_run` with `stop_after: 'answers'` and continue to Step 8.5 when it pauses. If they pick 2, call without `stop_after` and continue to Step 9 when complete.
 
-##### 8.0 — "You're unblocked" pre-roll (right after `start_agentic_run` returns the run_id)
+##### 8.0 — "You're unblocked" pre-roll (once server-side work is running)
 
-**Lock the product promise BEFORE you enter the polling loop.** The run continues server-side; the user is free to step away. The polling loop becomes the agent's job, not the user's obligation.
+This pre-roll is for the **rec-generation wait** — fire it once server-side work is running: on the agent-answered path, right after `submit_all_answers` returns (recommendation generation is now queued); on the server fallback, right after `start_agentic_run` returns the run_id. (On the agent-answered path the *answering itself* is your active work — don't show the pre-roll until you've submitted.)
+
+**Lock the product promise BEFORE you enter the polling loop.** Recommendation generation continues server-side; the user is free to step away. The polling loop becomes the agent's job, not the user's obligation.
 
 Tier the pre-roll by projected duration. Latency baseline: ~15s/question (V5.2 + KG injection, calibrate quarterly against `recs-pipeline.ts` eval results). Multiply the picked-question count by 15s, divide by 60 to get minutes.
 
@@ -1701,7 +1734,13 @@ Pick whichever fits the user's flow — they're equivalent in content. Do not in
 
 ##### 8.1 — Polling loop
 
-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.
+<!-- 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.
+
+**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.)
+
+**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.
 
 **On the FIRST poll only** (not every poll), prepend one line that locks the "background execution is default" mental model:
 

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

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.14",
-  "builtAt": "2026-06-14T21:33:31.224Z",
-  "skillsHash": "ee9a77046c96"
+  "cliVersion": "0.36.22",
+  "builtAt": "2026-06-15T13:28:31.790Z",
+  "skillsHash": "8a8905aae549"
 }

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: ee9a77046c96
+stamp: 8a8905aae549
 ---
 
 # /ritual