@ritualai/cli 0.36.35 → 0.36.37

package/skills/vscode/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/vscode/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/vscode/ritual/references/lite-flow.md

@@ -1,5 +1,5 @@
 <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
-<!-- source-sha: 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/vscode/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`).