@ritualai/cli 0.36.9 → 0.36.14

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

@@ -1,5 +1,5 @@
 <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
-<!-- source-sha: d91bf82d5264e811 -->
+<!-- source-sha: 3d973c8d7e6a514b -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -40,6 +40,31 @@ Follow build-flow.md's steps below EXACTLY, with these **LITE OVERRIDES**:
 UX brief review, plan-fidelity audit, and sibling-exploration forks are omitted
 (they're removed from the flow below).
 
+## Autonomous worktree mode (discovery — no human, stop at the brief)
+**Trigger:** the invocation carries the `--worktree` flag (you were launched by
+`ritual lite --worktree "<ask>"` — a git worktree was spun up and you are running
+HEADLESS inside it, with no human present). A developer parked an unchosen option
+for background discovery (unchosen-options → discovery worktrees). When you see
+`--worktree`, apply these EXTRA rules on top of the lite overrides above:
+- **There is no human, so auto-resolve EVEN the two touchpoints.** Accept the
+  classified job (Step 0.7) and the recommendations (Step 9) without waiting —
+  take the default at every gate, including those two. (If the job comes back
+  generic, proceed as the generic `Feature Brief` build; there's no one to
+  clarify with.)
+- **Create the exploration with `spawn_origin: 'discovery_worktree'`** (Step 6,
+  `create_exploration`) so `get_exploration_status` reports
+  `autonomousDiscovery: true`.
+- **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
+  this worktree, so the developer who `cd`s in reads the reasoning as files, not
+  just a graph id. Projection, not replica: the live graph stays authoritative.
+- **STOP there.** Do NOT branch, plan, implement, or open a PR — that is the
+  developer's call when they land in the worktree. The brief is **agent-authored
+  and NOT human-reviewed**; surface it as such so it's read with skepticism.
+This mode adds no new skill — it IS `lite`, just with no human to pause for and a
+hard stop at the brief. A normal (attended) `lite` run ignores this section.
+
 ---
 
 ## /ritual build
@@ -151,6 +176,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) -->
 #### 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
@@ -166,9 +192,16 @@ 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, personaCoverage }`.
+   `{ jtbd, workItemLabel, deliverableTemplate, why, confidence, isGenericFallback, 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.
+
+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`.
 
-2. **Render the validation prompt** (rail stage `Job`):
+   **2a — Confident match** (`isGenericFallback` is `false`): the classifier matched a specific job.
 
    ```text
    Ritual build
@@ -182,21 +215,68 @@ When this gate runs:
    job actually is.
    ```
 
+   **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`).
+
+   ```text
+   Ritual build
+   ● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ Feature Brief
+
+   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
+
+   Reply with the closest fit (or your own words) and I'll lock the job.
+   ```
+
+   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**.
+
+   **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.
+
+   ```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.
+
+   Reply `proceed` to frame the problem.
+   ```
+
    Do not render `personaCoverage` — persona representation is handled server-side now; only surface
    it if the user explicitly asks who's involved.
 
    Rail naming (deliverable-named rail, 2026-06-11): render `{Deliverable}` as the PROPOSED job's
-   `deliverableTemplate` (e.g. `Launch Brief`, `PRD`, `Service Build Brief`; `Build brief` for the
-   generic `build-feature`), and OMIT the `Implementation (Your agent)` stage entirely when the
-   proposed job is not a development job — non-dev rails have FIVE stages ending at the deliverable.
-   A correction that changes the job updates the rail on the next render. Spec:
+   `deliverableTemplate` from the classify result (e.g. `Launch Brief`, `PRD`, `Service Build Brief`;
+   `Feature Brief` for the generic `build-feature`), and OMIT the `Implementation (Your agent)` stage
+   entirely when the proposed job is not a development job — non-dev rails have FIVE stages ending at
+   the deliverable. A correction that changes the job updates the rail on the next render. Spec:
    `references/cli-output-contract.md` § Canonical stage table.
 
 3. **[USER PAUSE]** — wait for the user's actual reply. Never infer confirmation from the original
    ask, auto-mode, or silence. `proceed` / `yes` / `ok` confirms. ANY other substantive reply is a
    correction: call `mcp__ritual__classify_work_item` AGAIN with the same `raw_input`, plus
    `correction` (the user's words) and `previous_jtbd` (the rejected slug), then re-render step 2.
-   Loop until the user proceeds.
+   The clarifying QUESTION (2b) is asked AT MOST ONCE per gate — if the re-classification after the
+   user's answer is still generic, render **2c** (proceed as a generic `Feature Brief`); do not ask
+   the clarifying question again. Loop until the user proceeds.
 
 4. **Remember the confirmed `jtbd`** — you pass it to `create_exploration` at Step 6. Only after the
    user proceeds does the flow enter the `Scope` stage (workspace pick onward).
@@ -543,7 +623,33 @@ Steps:
    f. **If the user picks one (1-N):**
       - Set the chosen candidate's `summary` as the `raw_input` for the rest of the flow.
       - **Skip Step 1.5 step 8 (overlap check)** — the user just picked from system suggestions explicitly grounded in workspace state; a fresh overlap pass would be redundant noise.
-      - Continue to Step 2 (template selection).
+      - **Run the unchosen-candidates gate (f.1) BEFORE continuing**, then continue to Step 2.
+
+<!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
+   f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
+
+      ```text
+      You picked #{k}. The other {M} — want to keep any going?
+        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
+                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
+        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
+        • `skip`             — drop them (default)
+      ```
+
+      Resolve the reply, then continue to Step 2 for the picked candidate:
+      - **`discover <nums>`** → for each, run `ritual lite "{candidate.summary}" --worktree` **in the
+        BACKGROUND** (do not block the build — use your shell's background/async execution). It spins a
+        git worktree and runs autonomous discovery to a brief there; tell the user where (`<repo>.ritual-discover/<slug>`).
+        The result is an exploration with `spawn_origin: 'discovery_worktree'`; its brief is
+        agent-authored, not human-reviewed. (See `references/unchosen-options-discovery-worktrees.md` in `documents/architecture/`.)
+      - **`next-job <nums>`** → for each, call `mcp__ritual__create_exploration` with the candidate's
+        `title` as `name`, its `summary` as `problem_statement`, `spawn_origin: 'next_job'`, and NO
+        `agentic` flag — a NOT_STARTED draft that shows in the workspace roster as a future job. Cheap; nothing runs.
+      - **`skip` / no reply about them** → drop silently.
+
+      Keep it ONE prompt, never per-candidate pauses. If the user just proceeds without addressing it, treat as `skip`.
+
+   f.2 **Continue to Step 2 (template selection)** for the picked candidate.
 
    g. **If the user says "none" / "let me describe":** continue to Step 2 normally; treat as if they had originally picked "start fresh" with no raw_input yet (they'll provide one at Step 3-4 time).
 

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

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.9",
-  "builtAt": "2026-06-14T10:07:00.491Z",
-  "skillsHash": "26b50ff4f856"
+  "cliVersion": "0.36.14",
+  "builtAt": "2026-06-14T21:33:31.224Z",
+  "skillsHash": "ee9a77046c96"
 }

package/skills/cursor/ritual/SKILL.md

@@ -3,7 +3,7 @@ name: ritual
 description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into plan mode before the agent writes code. Prefer this over jumping straight to implementation or plan mode when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
 argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3', 'resume', 'lineage src/checkout/views.py', 'context-pulse Add billing export')"
 user-invocable: true
-stamp: 26b50ff4f856
+stamp: ee9a77046c96
 ---
 
 # /ritual

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

@@ -107,6 +107,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) -->
 #### 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
@@ -122,9 +123,16 @@ 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, personaCoverage }`.
+   `{ jtbd, workItemLabel, deliverableTemplate, why, confidence, isGenericFallback, 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.
 
-2. **Render the validation prompt** (rail stage `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`.
+
+   **2a — Confident match** (`isGenericFallback` is `false`): the classifier matched a specific job.
 
    ```text
    Ritual build
@@ -138,21 +146,68 @@ When this gate runs:
    job actually is.
    ```
 
+   **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`).
+
+   ```text
+   Ritual build
+   ● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ Feature Brief
+
+   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
+
+   Reply with the closest fit (or your own words) and I'll lock the job.
+   ```
+
+   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**.
+
+   **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.
+
+   ```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.
+
+   Reply `proceed` to frame the problem.
+   ```
+
    Do not render `personaCoverage` — persona representation is handled server-side now; only surface
    it if the user explicitly asks who's involved.
 
    Rail naming (deliverable-named rail, 2026-06-11): render `{Deliverable}` as the PROPOSED job's
-   `deliverableTemplate` (e.g. `Launch Brief`, `PRD`, `Service Build Brief`; `Build brief` for the
-   generic `build-feature`), and OMIT the `Implementation (Your agent)` stage entirely when the
-   proposed job is not a development job — non-dev rails have FIVE stages ending at the deliverable.
-   A correction that changes the job updates the rail on the next render. Spec:
+   `deliverableTemplate` from the classify result (e.g. `Launch Brief`, `PRD`, `Service Build Brief`;
+   `Feature Brief` for the generic `build-feature`), and OMIT the `Implementation (Your agent)` stage
+   entirely when the proposed job is not a development job — non-dev rails have FIVE stages ending at
+   the deliverable. A correction that changes the job updates the rail on the next render. Spec:
    `references/cli-output-contract.md` § Canonical stage table.
 
 3. **[USER PAUSE]** — wait for the user's actual reply. Never infer confirmation from the original
    ask, auto-mode, or silence. `proceed` / `yes` / `ok` confirms. ANY other substantive reply is a
    correction: call `mcp__ritual__classify_work_item` AGAIN with the same `raw_input`, plus
    `correction` (the user's words) and `previous_jtbd` (the rejected slug), then re-render step 2.
-   Loop until the user proceeds.
+   The clarifying QUESTION (2b) is asked AT MOST ONCE per gate — if the re-classification after the
+   user's answer is still generic, render **2c** (proceed as a generic `Feature Brief`); do not ask
+   the clarifying question again. Loop until the user proceeds.
 
 4. **Remember the confirmed `jtbd`** — you pass it to `create_exploration` at Step 6. Only after the
    user proceeds does the flow enter the `Scope` stage (workspace pick onward).
@@ -499,7 +554,33 @@ Steps:
    f. **If the user picks one (1-N):**
       - Set the chosen candidate's `summary` as the `raw_input` for the rest of the flow.
       - **Skip Step 1.5 step 8 (overlap check)** — the user just picked from system suggestions explicitly grounded in workspace state; a fresh overlap pass would be redundant noise.
-      - Continue to Step 2 (template selection).
+      - **Run the unchosen-candidates gate (f.1) BEFORE continuing**, then continue to Step 2.
+
+<!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
+   f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
+
+      ```text
+      You picked #{k}. The other {M} — want to keep any going?
+        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
+                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
+        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
+        • `skip`             — drop them (default)
+      ```
+
+      Resolve the reply, then continue to Step 2 for the picked candidate:
+      - **`discover <nums>`** → for each, run `ritual lite "{candidate.summary}" --worktree` **in the
+        BACKGROUND** (do not block the build — use your shell's background/async execution). It spins a
+        git worktree and runs autonomous discovery to a brief there; tell the user where (`<repo>.ritual-discover/<slug>`).
+        The result is an exploration with `spawn_origin: 'discovery_worktree'`; its brief is
+        agent-authored, not human-reviewed. (See `references/unchosen-options-discovery-worktrees.md` in `documents/architecture/`.)
+      - **`next-job <nums>`** → for each, call `mcp__ritual__create_exploration` with the candidate's
+        `title` as `name`, its `summary` as `problem_statement`, `spawn_origin: 'next_job'`, and NO
+        `agentic` flag — a NOT_STARTED draft that shows in the workspace roster as a future job. Cheap; nothing runs.
+      - **`skip` / no reply about them** → drop silently.
+
+      Keep it ONE prompt, never per-candidate pauses. If the user just proceeds without addressing it, treat as `skip`.
+
+   f.2 **Continue to Step 2 (template selection)** for the picked candidate.
 
    g. **If the user says "none" / "let me describe":** continue to Step 2 normally; treat as if they had originally picked "start fresh" with no raw_input yet (they'll provide one at Step 3-4 time).
 

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: d91bf82d5264e811 -->
+<!-- source-sha: 3d973c8d7e6a514b -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -40,6 +40,31 @@ Follow build-flow.md's steps below EXACTLY, with these **LITE OVERRIDES**:
 UX brief review, plan-fidelity audit, and sibling-exploration forks are omitted
 (they're removed from the flow below).
 
+## Autonomous worktree mode (discovery — no human, stop at the brief)
+**Trigger:** the invocation carries the `--worktree` flag (you were launched by
+`ritual lite --worktree "<ask>"` — a git worktree was spun up and you are running
+HEADLESS inside it, with no human present). A developer parked an unchosen option
+for background discovery (unchosen-options → discovery worktrees). When you see
+`--worktree`, apply these EXTRA rules on top of the lite overrides above:
+- **There is no human, so auto-resolve EVEN the two touchpoints.** Accept the
+  classified job (Step 0.7) and the recommendations (Step 9) without waiting —
+  take the default at every gate, including those two. (If the job comes back
+  generic, proceed as the generic `Feature Brief` build; there's no one to
+  clarify with.)
+- **Create the exploration with `spawn_origin: 'discovery_worktree'`** (Step 6,
+  `create_exploration`) so `get_exploration_status` reports
+  `autonomousDiscovery: true`.
+- **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
+  this worktree, so the developer who `cd`s in reads the reasoning as files, not
+  just a graph id. Projection, not replica: the live graph stays authoritative.
+- **STOP there.** Do NOT branch, plan, implement, or open a PR — that is the
+  developer's call when they land in the worktree. The brief is **agent-authored
+  and NOT human-reviewed**; surface it as such so it's read with skepticism.
+This mode adds no new skill — it IS `lite`, just with no human to pause for and a
+hard stop at the brief. A normal (attended) `lite` run ignores this section.
+
 ---
 
 ## /ritual build
@@ -151,6 +176,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) -->
 #### 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
@@ -166,9 +192,16 @@ 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, personaCoverage }`.
+   `{ jtbd, workItemLabel, deliverableTemplate, why, confidence, isGenericFallback, 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.
+
+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`.
 
-2. **Render the validation prompt** (rail stage `Job`):
+   **2a — Confident match** (`isGenericFallback` is `false`): the classifier matched a specific job.
 
    ```text
    Ritual build
@@ -182,21 +215,68 @@ When this gate runs:
    job actually is.
    ```
 
+   **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`).
+
+   ```text
+   Ritual build
+   ● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ Feature Brief
+
+   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
+
+   Reply with the closest fit (or your own words) and I'll lock the job.
+   ```
+
+   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**.
+
+   **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.
+
+   ```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.
+
+   Reply `proceed` to frame the problem.
+   ```
+
    Do not render `personaCoverage` — persona representation is handled server-side now; only surface
    it if the user explicitly asks who's involved.
 
    Rail naming (deliverable-named rail, 2026-06-11): render `{Deliverable}` as the PROPOSED job's
-   `deliverableTemplate` (e.g. `Launch Brief`, `PRD`, `Service Build Brief`; `Build brief` for the
-   generic `build-feature`), and OMIT the `Implementation (Your agent)` stage entirely when the
-   proposed job is not a development job — non-dev rails have FIVE stages ending at the deliverable.
-   A correction that changes the job updates the rail on the next render. Spec:
+   `deliverableTemplate` from the classify result (e.g. `Launch Brief`, `PRD`, `Service Build Brief`;
+   `Feature Brief` for the generic `build-feature`), and OMIT the `Implementation (Your agent)` stage
+   entirely when the proposed job is not a development job — non-dev rails have FIVE stages ending at
+   the deliverable. A correction that changes the job updates the rail on the next render. Spec:
    `references/cli-output-contract.md` § Canonical stage table.
 
 3. **[USER PAUSE]** — wait for the user's actual reply. Never infer confirmation from the original
    ask, auto-mode, or silence. `proceed` / `yes` / `ok` confirms. ANY other substantive reply is a
    correction: call `mcp__ritual__classify_work_item` AGAIN with the same `raw_input`, plus
    `correction` (the user's words) and `previous_jtbd` (the rejected slug), then re-render step 2.
-   Loop until the user proceeds.
+   The clarifying QUESTION (2b) is asked AT MOST ONCE per gate — if the re-classification after the
+   user's answer is still generic, render **2c** (proceed as a generic `Feature Brief`); do not ask
+   the clarifying question again. Loop until the user proceeds.
 
 4. **Remember the confirmed `jtbd`** — you pass it to `create_exploration` at Step 6. Only after the
    user proceeds does the flow enter the `Scope` stage (workspace pick onward).
@@ -543,7 +623,33 @@ Steps:
    f. **If the user picks one (1-N):**
       - Set the chosen candidate's `summary` as the `raw_input` for the rest of the flow.
       - **Skip Step 1.5 step 8 (overlap check)** — the user just picked from system suggestions explicitly grounded in workspace state; a fresh overlap pass would be redundant noise.
-      - Continue to Step 2 (template selection).
+      - **Run the unchosen-candidates gate (f.1) BEFORE continuing**, then continue to Step 2.
+
+<!-- skill-options:no-gate-change: f.1 is an OPTIONAL skippable sub-prompt nested in Step 1.5 step 6 (default skip); adds no tracked pause gate or Step header, so the structural fingerprint is unchanged (check-skill-options-contract green). -->
+   f.1 **Unchosen-candidates gate (2026-06-14, unchosen-options → discovery worktrees).** The candidates the user did NOT pick are paths worth not silently dropping. Render ONE compact, SKIPPABLE prompt — for each unchosen candidate, the user can spin up **discovery now** (a background worktree reasons it to a build brief) or **log it as a future job**. Promote DELIBERATELY: the default is to drop. (This gate is itself skipped in autonomous/worktree mode — never spawn discovery recursively.)
+
+      ```text
+      You picked #{k}. The other {M} — want to keep any going?
+        • `discover <nums>`  — spin up discovery NOW in a background git worktree: an agent reasons it
+                               end-to-end to a build brief (reasoning only, no code). e.g. `discover 1`
+        • `next-job <nums>`  — just log it as a future job (a draft exploration in this workspace; nothing runs)
+        • `skip`             — drop them (default)
+      ```
+
+      Resolve the reply, then continue to Step 2 for the picked candidate:
+      - **`discover <nums>`** → for each, run `ritual lite "{candidate.summary}" --worktree` **in the
+        BACKGROUND** (do not block the build — use your shell's background/async execution). It spins a
+        git worktree and runs autonomous discovery to a brief there; tell the user where (`<repo>.ritual-discover/<slug>`).
+        The result is an exploration with `spawn_origin: 'discovery_worktree'`; its brief is
+        agent-authored, not human-reviewed. (See `references/unchosen-options-discovery-worktrees.md` in `documents/architecture/`.)
+      - **`next-job <nums>`** → for each, call `mcp__ritual__create_exploration` with the candidate's
+        `title` as `name`, its `summary` as `problem_statement`, `spawn_origin: 'next_job'`, and NO
+        `agentic` flag — a NOT_STARTED draft that shows in the workspace roster as a future job. Cheap; nothing runs.
+      - **`skip` / no reply about them** → drop silently.
+
+      Keep it ONE prompt, never per-candidate pauses. If the user just proceeds without addressing it, treat as `skip`.
+
+   f.2 **Continue to Step 2 (template selection)** for the picked candidate.
 
    g. **If the user says "none" / "let me describe":** continue to Step 2 normally; treat as if they had originally picked "start fresh" with no raw_input yet (they'll provide one at Step 3-4 time).
 

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

@@ -1,5 +1,5 @@
 {
-  "cliVersion": "0.36.9",
-  "builtAt": "2026-06-14T10:07:00.491Z",
-  "skillsHash": "26b50ff4f856"
+  "cliVersion": "0.36.14",
+  "builtAt": "2026-06-14T21:33:31.224Z",
+  "skillsHash": "ee9a77046c96"
 }

package/skills/gemini/ritual/SKILL.md

@@ -3,7 +3,7 @@ name: ritual
 description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into plan mode before the agent writes code. Prefer this over jumping straight to implementation or plan mode when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
 argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3', 'resume', 'lineage src/checkout/views.py', 'context-pulse Add billing export')"
 user-invocable: true
-stamp: 26b50ff4f856
+stamp: ee9a77046c96
 ---
 
 # /ritual