@ritualai/cli 0.36.35 → 0.36.37

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

@@ -141,7 +141,7 @@ If the user types `always audit for this build` mid-flow at the Step 9.6 prompt,
 Persist `auditMode` to `Exploration.metadata.auditMode` at `create_exploration` time (additive JSONB key — no schema migration) so `/ritual resume <exploration-id>` picks up the same mode the original build started with, and `/ritual lineage <exploration-id>` can render which gates ran + their outcomes.
 
 <!-- lite:keep-start -->
-<!-- skill-options:no-gate-change: 2b (clarifying question) + 2c (generic terminal) are loud-fallback COPY variants of the same gate; options are unchanged (proceed | name-the-job) -->
+<!-- skill-options:no-gate-change: 2b (low-confidence clarifying question — server sets clarifyingQuestion only when confidence <20% or it defaulted) + 2c (confident generic — accept and proceed) are COPY variants of the same gate; options are unchanged (proceed | name-the-job; 2b adds answer-the-question, which is a name-the-job correction) -->
 #### Step 0.7 — The Job gate: classify the job to be done
 
 **The FIRST tool call of a fresh build.** The server — not you — classifies the user's raw ask into
@@ -161,14 +161,18 @@ When this gate runs:
 
 1. **Call `mcp__ritual__classify_work_item`** with `raw_input` = the user's ask, verbatim. Do NOT
    classify yourself, do NOT pre-filter to development jobs. It returns
-   `{ jtbd, workItemLabel, deliverableTemplate, why, confidence, isGenericFallback, personaCoverage }`.
+   `{ jtbd, workItemLabel, deliverableTemplate, why, confidence, isGenericFallback, clarifyingQuestion?, personaCoverage }`.
    `isGenericFallback` (and `confidence`) are the typed-uncertainty signal: when it's `true`, the
    result is the catch-all (`build-feature` / `produce-deliverable`) or the classifier wasn't sure —
-   it is NOT a confident match, and which render variant you use in step 2 depends on it.
+   it is NOT a confident match, and which render variant you use in step 2 depends on it. On that
+   generic path the response also carries `clarifyingQuestion` — a plain-language question generated
+   from the user's ask, which step 2b renders verbatim to disambiguate toward a specific job.
 
 2. **Render the validation prompt** (rail stage `Job`). This gate is a plain-language VALIDATION of
    what you're about to build: restate the ask + the matched job in the user's words, then let them
-   confirm or correct. Which variant you render depends on `isGenericFallback`.
+   confirm or correct. Route to a variant by the response: a **`clarifyingQuestion`** present → **2b**
+   (we're genuinely unsure — ask, but let them proceed); else `isGenericFallback` true → **2c** (a
+   confident generic build — accept and proceed); else → **2a** (a confident specific match).
 
    **2a — Confident match** (`isGenericFallback` is `false`): the classifier matched a specific job.
 
@@ -181,14 +185,17 @@ When this gate runs:
    Reply `proceed` if that's right, or tell me what to adjust.
    ```
 
-   **2b — No specific job matched, FIRST time** (`isGenericFallback` is `true` — the result is the
-   catch-all `build-feature` / `produce-deliverable`, or `confidence` is `low` — AND you have not yet
-   asked the clarifying question this gate): do NOT present the catch-all as a verdict. This case
-   should be RARE. Instead ask ONE clarifying question that elicits the missing signal — what KIND of
-   work this is — grounded in their ask, with concrete examples that lead the reply. The examples
-   span the catalog's functions so the user can self-identify; tailor the wording to their ask. This
-   is the fallback step that lets us classify properly instead of defaulting blind (see
-   `loud-fallback-escalation.md`).
+   **2b — Genuinely unsure: ask, but let them proceed** (the response carries a **`clarifyingQuestion`**
+   — the server sets it ONLY when it was essentially guessing: numeric confidence below 20, or it
+   failed to classify and defaulted). A generic result alone does NOT land here — only a *low-confidence*
+   one does; a confident generic build goes to **2c**. The clarifying question is a single plain-language
+   question the server generated FROM the user's specific ask. **Render it verbatim** — it is grounded in
+   their words and leak-free. Do not rephrase it, do not append a menu, do not mention classification /
+   jobs / categories / confidence. The user has TWO ways out: answer to focus it, OR reply `proceed` to
+   continue with the deliverable. **Leak rule (load-bearing):** the rendered copy must NEVER say
+   "generic", "I couldn't classify", "fallback", "catch-all", or otherwise reveal that classification was
+   uncertain — that is internal state. Present it as a normal question about their ask. (See
+   `loud-fallback-escalation.md`.)
 
    ```text
    Ritual build
@@ -196,34 +203,35 @@ When this gate runs:
 
    You're looking to: {restate the ask in one short clause}
 
-   I couldn't pin this to a specific job — your ask reads as an outcome, and the flow scopes much
-   better when I know what KIND of work it is. Which is closest (or say it in your own words)?
-     • A coding-agent / MCP / skill capability — tooling the agent itself uses
-     • A backend service or API
-     • A frontend / UI feature
-     • A refactor, migration, or infra / platform change
-     • Something else — tell me in a sentence
+   {clarifyingQuestion — verbatim}
 
-   Reply with the closest fit (or your own words) and I'll lock the job.
+   Answer in a sentence — or reply `proceed` and I'll continue with a {Deliverable}.
    ```
 
-   When the user answers, call `mcp__ritual__classify_work_item` AGAIN with the same `raw_input` plus
-   `correction` = their reply (and `previous_jtbd`), then re-render: **2a** if it now matched a
-   specific job, otherwise **2c**.
+   (Rare degraded case — you reached 2b but `clarifyingQuestion` is missing: ask which KIND of work it
+   is, with the same `proceed` option — • a coding-agent / MCP / skill capability • a backend service
+   or API • a frontend / UI feature • a refactor, migration, or infra change • something else, in your
+   own words.)
 
-   **2c — Still generic after the clarifying question** (`isGenericFallback` is STILL `true` after the
-   user answered 2b): do NOT ask again. Proceed as a generic build with the function-agnostic
-   `Feature Brief` deliverable, and note the job can be renamed later. The job name stays generic —
-   never show a function-specific deliverable (e.g. "Frontend Web") for an unclassified build.
+   If the user ANSWERS, call `mcp__ritual__classify_work_item` AGAIN with the same `raw_input` plus
+   `correction` = their reply (and `previous_jtbd`), then re-render: **2a** if it now matched a specific
+   job, otherwise **2c**. If the user replies `proceed`, go straight to **2c** (accept the generic).
+
+   **2c — Accept and proceed** (`isGenericFallback` is `true` with NO `clarifyingQuestion` — a
+   confident-enough generic build — OR the user chose to proceed from 2b, OR a re-classification is still
+   generic): do NOT interrogate. Present the deliverable as a normal accept-and-proceed — **same clean
+   shape as 2a**. Internally the job stays generic and is renamable later, but **the rendered copy must
+   NEVER say "generic", "couldn't classify", "fallback", or otherwise reveal that** — that is internal
+   state. Just name what Ritual will produce for their ask. (Never show a function-specific deliverable
+   like "Frontend Web" for an unclassified build — only the function-agnostic `Feature Brief`.)
 
    ```text
    Ritual build
    ● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ Feature Brief
 
-   You're looking to: {restate the ask in one short clause}
-   I'll treat this as a generic build — deliverable: Feature Brief. You can rename the job later.
+   Ritual will produce a {Deliverable} for {restate the ask in one short clause}.
 
-   Reply `proceed` to frame the problem.
+   Reply `proceed` if that's right, or tell me what to focus on.
    ```
 
    Do not render `personaCoverage` — persona representation is handled server-side now; only surface
@@ -449,7 +457,7 @@ Steps:
    - For `ready` or `in_flight` states, jump directly to Step 10 (build brief generation).
    - For `awaiting_admin`, jump to Step 9 (review + `proceed`). Only an admin can move it forward; collaborators see the recs and proceed only if they're explicitly authorized to implement ahead.
    - For `implemented_ahead`, surface the situation to the user and ask what to do — typically the admin reconciles by either approving the recs post-hoc (no code change needed) or updating the recs to match shipped reality.
-   - **For `done` or `in_flight` — branch-existence sanity check FIRST.** *(CLI Tenet #9 — sanity-check the world before trusting the database.)* The state badge is computed from `ImplementationRecord` rows in the KG. If the KG was seeded from synthetic/bootstrap data (a common state in early pilot deployments), the record can assert a PR/branch that doesn't exist in this repo. Before treating the exploration as ✓ shipped, verify:
+   - **For `done` or `in_flight` — branch-existence sanity check FIRST (when your agent can run shell + git).** *(CLI Tenet #9 — sanity-check the world before trusting the database.)* **If your agent can't run shell/git** (v0, Lovable, browser-only agents), skip this probe and the footprint probe below, treat the KG state badge as truth, and tell the user you couldn't cross-check it against local git. The state badge is computed from `ImplementationRecord` rows in the KG. If the KG was seeded from synthetic/bootstrap data (a common state in early pilot deployments), the record can assert a PR/branch that doesn't exist in this repo. Before treating the exploration as ✓ shipped, verify:
 
      ```bash
      # If implementationRecord.branch is set:
@@ -468,7 +476,7 @@ Steps:
 
      Don't paint 3-4 options ("treat as done / treat as fresh / inspect the KG row / something else") — one decisive proposal with a yes/no/correct-me escape hatch. If yes: jump to Step 10 (build brief). If no/correct-me: take the user's input as ground truth and update the next move accordingly.
 
-   - **For `ready` or `in_flight` — implementation footprint check FIRST.** *(Same shape as `/ritual resume` Step R3.5.)* The KG can't distinguish "brief generated, no code yet" from "mid-implementation, unsynced" from "implementation was started and then dropped" — all three look like `ready` because no `ImplementationRecord` exists until `sync_implementation` is called. Run the footprint probes using the `Ritual-Exploration: <id>` commit trailer mandated by Tenet #14:
+   - **For `ready` or `in_flight` — implementation footprint check FIRST (when your agent can run shell + git; otherwise skip — see the guard above).** *(Same shape as `/ritual resume` Step R3.5.)* The KG can't distinguish "brief generated, no code yet" from "mid-implementation, unsynced" from "implementation was started and then dropped" — all three look like `ready` because no `ImplementationRecord` exists until `sync_implementation` is called. Run the footprint probes using the `Ritual-Exploration: <id>` commit trailer mandated by Tenet #14:
 
      ```bash
      git log --all --grep="Ritual-Exploration: ${exploration_id}" --oneline 2>/dev/null
@@ -2198,7 +2206,7 @@ The Build Brief is the markdown document the engineer reads RIGHT BEFORE writing
 Call `mcp__ritual__generate_build_brief` with:
 
 - `exploration_id`
-- `icp` (optional — defaults to the exploration template's primary ICP, then PM; pass `TECH_PM` for engineering-flavored explorations)
+- `icp` — **omit this.** The brief sources from the requirement set the flow already generated (on accept), whose ICP the server resolves from the exploration's persona/template. Passing a different ICP here forces a redundant requirement regeneration and a slow cold start. The engineering flavor is already baked into the server-resolved template — you do not need to (and should not) pass `TECH_PM` or any other ICP.
 - `recon_context` — the Step 3 `codebase_context_packet` plus any explicit phase/later candidates from discovery. Do not pass raw recon notes. This grounds "Codebase Anchors" in real file paths while keeping agent hypotheses auditable and non-authoritative.
 - `sources` — the **same** file-path array passed to `generate_considerations` and `generate_problem_statement` in Steps 4–5. Critical for KG consistency: the brief's "Previously Deferred" section only populates when overlapping prior implementations exist on these files.
 

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

@@ -1,8 +1,8 @@
-# CLI output contract
+# Agent output contract
 
 ### Developer-facing output contract
 
-This skill drives a CLI surface where the user reads every line. Optimize for a busy engineer who wants enough signal to trust the workflow without reading the agent's scratchpad.
+This skill drives an agent surface where the user reads every line of the agent's output. Optimize for a busy engineer who wants enough signal to trust the workflow without reading the agent's scratchpad.
 
 Maintain two layers throughout the flow:
 
@@ -18,7 +18,7 @@ Do **not** pass raw notes as the primary context to MCP generation tools. Raw no
 
 Default user-visible messages should be:
 - 3–7 bullets max, unless the user explicitly asks for detail
-- no more than one terminal screen
+- no more than one screen
 - focused on findings, constraints, next action, and specific signals
 - free of “I inferred…” / “that means I'll bias…” narration unless the inference changes a user-facing choice
 - free of raw file-by-file recon dumps unless requested
@@ -138,14 +138,14 @@ When in doubt, prefer one blank line over none. The cost of a tiny gap is unnoti
 
 | Surface | Rendering | When to use |
 |---|---|---|
-| **CLI / terminal** (current default) | Full two-line rail. `Ritual build` on line 1, `● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)` on line 2. | Terminal scrollback has no persistent UI — the rail IS the anchor. |
+| **CLI / terminal** (terminal agents — Claude Code, Cursor, Codex in a built-in terminal) | Full two-line rail. `Ritual build` on line 1, `● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)` on line 2. | Terminal scrollback has no persistent UI — the rail IS the anchor. |
 | **Mobile chat / narrow chat** | Compact one-line chip. `Ritual build · 2/6 Scope`. Optionally add a second line: `Done: Job, Scope · Next: Recommendations`. | Six-stage rail wraps and looks noisy inside chat bubbles. |
 | **Rich app with persistent stepper** | Single-line stage label. `Scope` (or `Phase: Scope`). The app's pinned stepper above the conversation is the primary anchor; messages just need the current label. At phase transitions, resume points, and major decision gates, include the compact mobile-style chip even in rich-app surface for transcript portability. | The persistent UI carries the anchor; redundant chrome in every bubble is noise. |
 
 **How the agent picks the surface:**
 
-- Default to **CLI / terminal** rendering. This SKILL exists primarily to drive CLI surfaces (Claude Code, Cursor, Codex, etc. in their built-in terminals).
-- If the host signals a non-terminal surface via context (mobile-app chat embedding, web-app chat UI, etc.), drop to the compact chip.
+- When your agent runs in a terminal (Claude Code, Cursor, Codex, etc. in their built-in terminals), default to **CLI / terminal** rendering.
+- When the surface is a chat UI rather than a terminal (web-app agents like v0/Lovable, mobile-app chat embedding, etc.), drop to the compact chip.
 - The rule is: **progress anchor is mandatory; exact visual rendering is surface-specific.** Do NOT force the full six-stage rail when it will wrap.
 
 **Applies to:**
@@ -282,15 +282,15 @@ The host app pins a stepper above the conversation; the message only carries the
 All `/ritual build` and `/ritual resume` top-level messages in `references/build-flow.md` anchor to this spec — when a stage transitions, the existing examples advance the marker per the canonical ordering. If you need to rename a stage in the future, update this table first; everything else follows.
 
 
-### CLI experience cheat-sheet
+### Agent experience cheat-sheet
 
-This skill drives a CLI surface where the user reads every line you print. Keep these tenets in mind — full doc at `documents/design/cli-experience-tenets.md`:
+This skill drives an agent surface where the user reads every line you print. Keep these tenets in mind — full doc at `documents/design/cli-experience-tenets.md`:
 
 - **Long artifacts (briefs, recon notes) → files, not terminal dumps.** The CLI summarizes; the file holds the detail. End every output with what the user can do next.
 - **Single recommended action + escape hatch > 3-option menu.** Lead with the best next step, give them a cheap "no, do this instead" out. Reserve 3-way branches for genuinely distinct intents (implement / refine / drill — yes; "generate brief / look at deferrals / something else" — no).
 - **Cite the specific signal**, not the abstract gesture. *"Recommended because RB-001 is blocking…"* beats *"based on prior workspace context."*
 - **Silence on no-data.** Don't print "Checked X — nothing." Just don't render the section.
-- **Sanity-check the world before trusting the DB.** When an `ImplementationRecord` asserts a branch/PR, verify it exists locally before treating the exploration as done (Step 1.5 step 5).
+- **Sanity-check the world before trusting the DB (when you can).** If your agent has shell + git, verify an `ImplementationRecord`'s asserted branch/PR exists locally before treating the exploration as done (Step 1.5 step 5). If it can't run git, treat the KG record as truth and say you couldn't verify it locally.
 - **Never commit to `main` / `master` from this workflow.** Step 11 creates a feature branch FIRST — no exceptions, no user-prompt offering "commit to trunk" as an option (Tenet #13).
 - **Attribute back to Ritual on outbound artifacts.** Commit-message trailers + PR body + generated-file headers carry the exploration link so future readers can trace the lineage without re-asking the agent (Tenet #14).
 - **Format dense CLI lists for scanning.** When an item has a title, explanation, rationale, and references, split those into labeled blocks with blank lines between items. Do not rely on terminal auto-wrap to make long prose readable.

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: 3cfb8c30115f21ac -->
+<!-- source-sha: 41c0a8e8e2f22f6c -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -233,7 +233,7 @@ If the user types `always audit for this build` mid-flow at the Step 9.6 prompt,
 Persist `auditMode` to `Exploration.metadata.auditMode` at `create_exploration` time (additive JSONB key — no schema migration) so `/ritual resume <exploration-id>` picks up the same mode the original build started with, and `/ritual lineage <exploration-id>` can render which gates ran + their outcomes.
 
 
-<!-- skill-options:no-gate-change: 2b (clarifying question) + 2c (generic terminal) are loud-fallback COPY variants of the same gate; options are unchanged (proceed | name-the-job) -->
+<!-- skill-options:no-gate-change: 2b (low-confidence clarifying question — server sets clarifyingQuestion only when confidence <20% or it defaulted) + 2c (confident generic — accept and proceed) are COPY variants of the same gate; options are unchanged (proceed | name-the-job; 2b adds answer-the-question, which is a name-the-job correction) -->
 #### Step 0.7 — The Job gate: classify the job to be done
 
 **The FIRST tool call of a fresh build.** The server — not you — classifies the user's raw ask into
@@ -253,14 +253,18 @@ When this gate runs:
 
 1. **Call `mcp__ritual__classify_work_item`** with `raw_input` = the user's ask, verbatim. Do NOT
    classify yourself, do NOT pre-filter to development jobs. It returns
-   `{ jtbd, workItemLabel, deliverableTemplate, why, confidence, isGenericFallback, personaCoverage }`.
+   `{ jtbd, workItemLabel, deliverableTemplate, why, confidence, isGenericFallback, clarifyingQuestion?, personaCoverage }`.
    `isGenericFallback` (and `confidence`) are the typed-uncertainty signal: when it's `true`, the
    result is the catch-all (`build-feature` / `produce-deliverable`) or the classifier wasn't sure —
-   it is NOT a confident match, and which render variant you use in step 2 depends on it.
+   it is NOT a confident match, and which render variant you use in step 2 depends on it. On that
+   generic path the response also carries `clarifyingQuestion` — a plain-language question generated
+   from the user's ask, which step 2b renders verbatim to disambiguate toward a specific job.
 
 2. **Render the validation prompt** (rail stage `Job`). This gate is a plain-language VALIDATION of
    what you're about to build: restate the ask + the matched job in the user's words, then let them
-   confirm or correct. Which variant you render depends on `isGenericFallback`.
+   confirm or correct. Route to a variant by the response: a **`clarifyingQuestion`** present → **2b**
+   (we're genuinely unsure — ask, but let them proceed); else `isGenericFallback` true → **2c** (a
+   confident generic build — accept and proceed); else → **2a** (a confident specific match).
 
    **2a — Confident match** (`isGenericFallback` is `false`): the classifier matched a specific job.
 
@@ -273,14 +277,17 @@ When this gate runs:
    Reply `proceed` if that's right, or tell me what to adjust.
    ```
 
-   **2b — No specific job matched, FIRST time** (`isGenericFallback` is `true` — the result is the
-   catch-all `build-feature` / `produce-deliverable`, or `confidence` is `low` — AND you have not yet
-   asked the clarifying question this gate): do NOT present the catch-all as a verdict. This case
-   should be RARE. Instead ask ONE clarifying question that elicits the missing signal — what KIND of
-   work this is — grounded in their ask, with concrete examples that lead the reply. The examples
-   span the catalog's functions so the user can self-identify; tailor the wording to their ask. This
-   is the fallback step that lets us classify properly instead of defaulting blind (see
-   `loud-fallback-escalation.md`).
+   **2b — Genuinely unsure: ask, but let them proceed** (the response carries a **`clarifyingQuestion`**
+   — the server sets it ONLY when it was essentially guessing: numeric confidence below 20, or it
+   failed to classify and defaulted). A generic result alone does NOT land here — only a *low-confidence*
+   one does; a confident generic build goes to **2c**. The clarifying question is a single plain-language
+   question the server generated FROM the user's specific ask. **Render it verbatim** — it is grounded in
+   their words and leak-free. Do not rephrase it, do not append a menu, do not mention classification /
+   jobs / categories / confidence. The user has TWO ways out: answer to focus it, OR reply `proceed` to
+   continue with the deliverable. **Leak rule (load-bearing):** the rendered copy must NEVER say
+   "generic", "I couldn't classify", "fallback", "catch-all", or otherwise reveal that classification was
+   uncertain — that is internal state. Present it as a normal question about their ask. (See
+   `loud-fallback-escalation.md`.)
 
    ```text
    Ritual build
@@ -288,34 +295,35 @@ When this gate runs:
 
    You're looking to: {restate the ask in one short clause}
 
-   I couldn't pin this to a specific job — your ask reads as an outcome, and the flow scopes much
-   better when I know what KIND of work it is. Which is closest (or say it in your own words)?
-     • A coding-agent / MCP / skill capability — tooling the agent itself uses
-     • A backend service or API
-     • A frontend / UI feature
-     • A refactor, migration, or infra / platform change
-     • Something else — tell me in a sentence
+   {clarifyingQuestion — verbatim}
 
-   Reply with the closest fit (or your own words) and I'll lock the job.
+   Answer in a sentence — or reply `proceed` and I'll continue with a {Deliverable}.
    ```
 
-   When the user answers, call `mcp__ritual__classify_work_item` AGAIN with the same `raw_input` plus
-   `correction` = their reply (and `previous_jtbd`), then re-render: **2a** if it now matched a
-   specific job, otherwise **2c**.
+   (Rare degraded case — you reached 2b but `clarifyingQuestion` is missing: ask which KIND of work it
+   is, with the same `proceed` option — • a coding-agent / MCP / skill capability • a backend service
+   or API • a frontend / UI feature • a refactor, migration, or infra change • something else, in your
+   own words.)
 
-   **2c — Still generic after the clarifying question** (`isGenericFallback` is STILL `true` after the
-   user answered 2b): do NOT ask again. Proceed as a generic build with the function-agnostic
-   `Feature Brief` deliverable, and note the job can be renamed later. The job name stays generic —
-   never show a function-specific deliverable (e.g. "Frontend Web") for an unclassified build.
+   If the user ANSWERS, call `mcp__ritual__classify_work_item` AGAIN with the same `raw_input` plus
+   `correction` = their reply (and `previous_jtbd`), then re-render: **2a** if it now matched a specific
+   job, otherwise **2c**. If the user replies `proceed`, go straight to **2c** (accept the generic).
+
+   **2c — Accept and proceed** (`isGenericFallback` is `true` with NO `clarifyingQuestion` — a
+   confident-enough generic build — OR the user chose to proceed from 2b, OR a re-classification is still
+   generic): do NOT interrogate. Present the deliverable as a normal accept-and-proceed — **same clean
+   shape as 2a**. Internally the job stays generic and is renamable later, but **the rendered copy must
+   NEVER say "generic", "couldn't classify", "fallback", or otherwise reveal that** — that is internal
+   state. Just name what Ritual will produce for their ask. (Never show a function-specific deliverable
+   like "Frontend Web" for an unclassified build — only the function-agnostic `Feature Brief`.)
 
    ```text
    Ritual build
    ● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ Feature Brief
 
-   You're looking to: {restate the ask in one short clause}
-   I'll treat this as a generic build — deliverable: Feature Brief. You can rename the job later.
+   Ritual will produce a {Deliverable} for {restate the ask in one short clause}.
 
-   Reply `proceed` to frame the problem.
+   Reply `proceed` if that's right, or tell me what to focus on.
    ```
 
    Do not render `personaCoverage` — persona representation is handled server-side now; only surface
@@ -541,7 +549,7 @@ Steps:
    - For `ready` or `in_flight` states, jump directly to Step 10 (build brief generation).
    - For `awaiting_admin`, jump to Step 9 (review + `proceed`). Only an admin can move it forward; collaborators see the recs and proceed only if they're explicitly authorized to implement ahead.
    - For `implemented_ahead`, surface the situation to the user and ask what to do — typically the admin reconciles by either approving the recs post-hoc (no code change needed) or updating the recs to match shipped reality.
-   - **For `done` or `in_flight` — branch-existence sanity check FIRST.** *(CLI Tenet #9 — sanity-check the world before trusting the database.)* The state badge is computed from `ImplementationRecord` rows in the KG. If the KG was seeded from synthetic/bootstrap data (a common state in early pilot deployments), the record can assert a PR/branch that doesn't exist in this repo. Before treating the exploration as ✓ shipped, verify:
+   - **For `done` or `in_flight` — branch-existence sanity check FIRST (when your agent can run shell + git).** *(CLI Tenet #9 — sanity-check the world before trusting the database.)* **If your agent can't run shell/git** (v0, Lovable, browser-only agents), skip this probe and the footprint probe below, treat the KG state badge as truth, and tell the user you couldn't cross-check it against local git. The state badge is computed from `ImplementationRecord` rows in the KG. If the KG was seeded from synthetic/bootstrap data (a common state in early pilot deployments), the record can assert a PR/branch that doesn't exist in this repo. Before treating the exploration as ✓ shipped, verify:
 
      ```bash
      # If implementationRecord.branch is set:
@@ -560,7 +568,7 @@ Steps:
 
      Don't paint 3-4 options ("treat as done / treat as fresh / inspect the KG row / something else") — one decisive proposal with a yes/no/correct-me escape hatch. If yes: jump to Step 10 (build brief). If no/correct-me: take the user's input as ground truth and update the next move accordingly.
 
-   - **For `ready` or `in_flight` — implementation footprint check FIRST.** *(Same shape as `/ritual resume` Step R3.5.)* The KG can't distinguish "brief generated, no code yet" from "mid-implementation, unsynced" from "implementation was started and then dropped" — all three look like `ready` because no `ImplementationRecord` exists until `sync_implementation` is called. Run the footprint probes using the `Ritual-Exploration: <id>` commit trailer mandated by Tenet #14:
+   - **For `ready` or `in_flight` — implementation footprint check FIRST (when your agent can run shell + git; otherwise skip — see the guard above).** *(Same shape as `/ritual resume` Step R3.5.)* The KG can't distinguish "brief generated, no code yet" from "mid-implementation, unsynced" from "implementation was started and then dropped" — all three look like `ready` because no `ImplementationRecord` exists until `sync_implementation` is called. Run the footprint probes using the `Ritual-Exploration: <id>` commit trailer mandated by Tenet #14:
 
      ```bash
      git log --all --grep="Ritual-Exploration: ${exploration_id}" --oneline 2>/dev/null
@@ -2262,7 +2270,7 @@ The Build Brief is the markdown document the engineer reads RIGHT BEFORE writing
 Call `mcp__ritual__generate_build_brief` with:
 
 - `exploration_id`
-- `icp` (optional — defaults to the exploration template's primary ICP, then PM; pass `TECH_PM` for engineering-flavored explorations)
+- `icp` — **omit this.** The brief sources from the requirement set the flow already generated (on accept), whose ICP the server resolves from the exploration's persona/template. Passing a different ICP here forces a redundant requirement regeneration and a slow cold start. The engineering flavor is already baked into the server-resolved template — you do not need to (and should not) pass `TECH_PM` or any other ICP.
 - `recon_context` — the Step 3 `codebase_context_packet` plus any explicit phase/later candidates from discovery. Do not pass raw recon notes. This grounds "Codebase Anchors" in real file paths while keeping agent hypotheses auditable and non-authoritative.
 - `sources` — the **same** file-path array passed to `generate_considerations` and `generate_problem_statement` in Steps 4–5. Critical for KG consistency: the brief's "Previously Deferred" section only populates when overlapping prior implementations exist on these files.
 

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

@@ -142,6 +142,8 @@ Silence on no-data (CLI Tenet #6): if a state bucket is empty, don't render it.
 
 #### Step R3 — Branch-existence sanity check (`done` / `in_flight` only)
 
+> **Requires shell + git.** Steps R3 and R3.5 verify KG state against local git, so they only run on agents that can execute shell + `git`/`gh` (Claude Code, Codex, Cursor agent mode, …). **If your agent can't run shell/git** (v0, Lovable, browser-only agents), skip both probes entirely, treat the KG state badge as truth, and tell the user you couldn't cross-check it against local git history.
+
 Same as `/ritual build` Step 1.5 step 5's CLI Tenet #9 check. Before treating an exploration as ✓ done, verify the implementation record's branch / PR actually exists locally or remotely:
 
 ```bash
@@ -192,6 +194,7 @@ Cross-reference findings against the KG state:
 
 **Skip the probes when:**
 
+- **Your agent can't run shell + git** (see the R3 guard above) — skip entirely and treat the KG state as truth.
 - The exploration was just created in this same session — no time to have orphan commits.
 - The user just synced (the `done` / `in_flight` state badge was set within the last few minutes).
 - The exploration is in a state where the footprint check doesn't apply (`in_progress`, `awaiting_admin`, `implemented_ahead`).

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

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.35",
-  "builtAt": "2026-06-16T18:14:12.359Z",
-  "skillsHash": "1c2163cfd3c5"
+  "cliVersion": "0.36.37",
+  "builtAt": "2026-06-20T13:23:52.963Z",
+  "skillsHash": "622a0cff45d0"
 }

package/skills/gemini/ritual/SKILL.md

@@ -1,20 +1,22 @@
 ---
 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?)."
+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 the agent's planning step before it writes code. Prefer this over jumping straight to implementation 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: 1c2163cfd3c5
+stamp: 622a0cff45d0
+cli_version: 0.36.37
 ---
 
 # /ritual
 
-Top-level dispatcher for Ritual coding-agent workflows. Designed primarily for Claude Code-style sessions with filesystem, git, shell, and MCP access; adapt commands as needed for Cursor or other agents with equivalent tools.
+Top-level dispatcher for Ritual coding-agent workflows. Works with any coding agent connected to the Ritual MCP — v0, Lovable, Cursor, Claude Code, Codex, Kiro, and others. Some steps use local capabilities (filesystem, git, shell) when your agent has them, and degrade gracefully to MCP-only when it doesn't.
+<!-- skill-options:no-gate-change: agent-neutral rewording + shell/git probes made conditional; no [USER PAUSE] gate or its offered options changed -->
 
 ## Always apply
 
 Before executing any subcommand, read and follow:
 
-- `references/cli-output-contract.md` — terminal output, vocabulary, readability, pause policy
+- `references/cli-output-contract.md` — agent output, vocabulary, readability, pause policy
 - `references/async-polling.md` — harness-safe polling and timeout recovery
 - `references/change-preflight.md` — restate + confirm before any free-text change/add tool call (refine sub-problems, reframe scope, add anti-goal); hard pause, even in auto-mode
 
@@ -24,8 +26,11 @@ Do not reintroduce `/ritual recon`. Use plain-language repo inspection, `/ritual
 <!-- skill-options:no-gate-change: grounding rule adds no [USER PAUSE] gate or options; read-before-claim discipline only -->
 
 **Skill freshness (once per session, silent unless stale):** this file's frontmatter may carry a
-`stamp:` value (injected when the bundle was built — absent on dev/source copies). On the FIRST
-`mcp__ritual__ping` of a session, pass it as `skill_stamp`. If the response says
+`stamp:` value and a `cli_version:` value (both injected when the bundle was built — absent on
+dev/source copies). On the FIRST `mcp__ritual__ping` of a session, pass the stamp as `skill_stamp`
+and, when present, the `cli_version:` value as `cli_version`. This is a silent provenance handshake:
+it lets the server record which skill content + CLI version is driving the session, so support can
+later tell a stale-skill issue from an old-CLI issue from a current-code bug. If the response says
 `skillFreshness: "stale"`, relay its one-line hint ("Skill update available — run
 `ritual init --skills-only` to refresh") exactly once, no pause, and continue with the current flow.
 No stamp, or `in-sync`/`unknown` → say nothing. Never block on this.
@@ -72,10 +77,10 @@ Parse the first token of the argument:
 | `resume` | `references/resume-flow.md` | "Pick up where I left off." Lists in-flight explorations with state badges and jumps to the right step. |
 | `lineage` | `references/lineage-flow.md` | Paste a file path (or set of paths); see every prior exploration / decision / deferral that touched those files. |
 | `context-pulse` | `references/context-pulse-flow.md` | Score readiness / context debt for a feature ask or exploration. Can seed a `CONTEXT-<feature>.md` file with relevant codebase + KG context that `/ritual build` picks up automatically. Also surfaces inline during build so the user watches debt drop. |
-| `status` | `references/status-flow.md` | Read-only mirror of the `ritual status` terminal CLI command (CLI 0.7.14+) for users who want a quick run-progress check inside the agent session instead of in a separate terminal. Calls `mcp__ritual__get_agentic_run` + renders the same run-first layout the CLI uses. |
+| `status` | `references/status-flow.md` | Read-only mirror of the `ritual status` CLI command (CLI 0.7.14+) for a quick run-progress check inside the agent session. Calls `mcp__ritual__get_agentic_run` + renders the same run-first layout the CLI uses. (Most useful when your agent runs alongside the Ritual CLI; harmless elsewhere.) |
 | (anything else, OR no subcommand) | default to `build` and treat the entire argument as the problem statement | |
 
-The Ritual CLI surface is intentionally narrow: `build`, `lite`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror. Legacy exposed `explore`, `run`, `brief`, `gate`, `spec`, `questions`, `gherkin`, `recs` — all of which mapped 1:1 to MCP tool calls and provided no agent-CLI value over plain English. We don't replicate them; the agent can call any MCP tool directly when the user asks for "the recs on exp-X" or "decisions on file Y". (`/ritual recon` shipped briefly in PR #174 as a fifth command — retired because its unique value duplicated `/ritual resume` (workspace history) + `/ritual lineage` (decisions on files), and its non-duplicate parts (map repo, trace flow, explain file) are exactly what the agent does fluently in plain English without needing a SKILL-defined menu.)
+The Ritual `/ritual` command surface is intentionally narrow: `build`, `lite`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror. Legacy exposed `explore`, `run`, `brief`, `gate`, `spec`, `questions`, `gherkin`, `recs` — all of which mapped 1:1 to MCP tool calls and provided no agent value over plain English. We don't replicate them; the agent can call any MCP tool directly when the user asks for "the recs on exp-X" or "decisions on file Y". (`/ritual recon` shipped briefly in PR #174 as a fifth command — retired because its unique value duplicated `/ritual resume` (workspace history) + `/ritual lineage` (decisions on files), and its non-duplicate parts (map repo, trace flow, explain file) are exactly what the agent does fluently in plain English without needing a SKILL-defined menu.)
 
 
 ## Subcommand reference files
@@ -98,11 +103,11 @@ Additional runtime references:
 
 - If the first token is one of the subcommands (`build`, `lite`, `resume`, `lineage`, `context-pulse`), load the matching runtime file and follow it.
 - If there is no subcommand or the token is unknown, default to `build` and treat the full argument as the problem statement.
-- If the user asks for retired or unsupported subcommands, answer in plain English and call the relevant MCP tool directly when appropriate; do not expand the slash-command surface.
+- If the user asks for retired or unsupported subcommands, answer in plain English and call the relevant MCP tool directly when appropriate; do not expand the `/ritual` command surface.
 
 ## Asks that don't map to a subcommand
 
-When the user says things like *"what's the status of exp-X?"*, *"show me the recs on exp-Y"*, or *"kick off the agentic run on exp-Z"* — those don't need a dedicated slash-command. Just call the MCP tool directly:
+When the user says things like *"what's the status of exp-X?"*, *"show me the recs on exp-Y"*, or *"kick off the agentic run on exp-Z"* — those don't need a dedicated command. Just call the MCP tool directly:
 
 | User asks for… | Call this MCP tool |
 |---|---|
@@ -112,15 +117,18 @@ When the user says things like *"what's the status of exp-X?"*, *"show me the re
 | Kick off / re-run the agentic pipeline | `mcp__ritual__start_agentic_run(exploration_id, …)` |
 | Did anyone implement something on these files? | `mcp__ritual__query_knowledge_graph(sources=[…])` — same plumbing as `/ritual lineage` |
 
-This is intentional. Legacy exposed each of these as its own slash-command (`/ritual recs`, `/ritual run`, etc.) and the surface area ballooned without adding agent value. We keep the slash-commands narrow (`build`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror) and let the agent fluently call MCP tools for everything else. Note: `/ritual status` is the one deliberate exception — it exists as a thin SKILL mirror of the terminal CLI command so users who want an in-chat status check don't have to context-switch to a separate terminal. Do not reintroduce `/ritual recon`: its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and repo-reading behaviors are normal coding-agent behavior in plain English.
+This is intentional. Legacy exposed each of these as its own command (`/ritual recs`, `/ritual run`, etc.) and the surface area ballooned without adding agent value. We keep the commands narrow (`build`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror) and let the agent fluently call MCP tools for everything else. Note: `/ritual status` is the one deliberate exception — it exists as a thin SKILL mirror of the `ritual status` CLI command so users who want an in-chat status check don't have to switch surfaces. Do not reintroduce `/ritual recon`: its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and repo-reading behaviors are normal coding-agent behavior in plain English.
 
 ---
 
 ## Before this skill is installed — bootstrap context
 
-This SKILL only governs behavior **after** `ritual init` has run and the
-`/ritual` skill has been copied into the agent's skills directory. Before
-that, the agent has no Ritual-specific instructions in scope.
+This SKILL only governs behavior **after** it has been installed into the
+agent's skills directory. The canonical install path is the Ritual CLI
+(`ritual init` copies the skill in); agents without a CLI install it their own
+way — e.g. uploading the skill bundle directly (v0, Lovable). Either way, before
+the skill is in scope the agent has no Ritual-specific instructions; the runtime
+behavior below is identical once it is.
 
 If you are reading this file by browsing the repo, or as part of a
 post-mortem on why a user's "set up Ritual MCP" request went sideways: