@ritualai/cli 0.24.0 → 0.25.0

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

@@ -24,6 +24,28 @@ Default user-visible messages should be:
 - free of raw file-by-file recon dumps unless requested
 - formatted for terminal readability: short paragraphs, blank lines between major items, and label/value blocks instead of dense wrapped prose
 
+**Output discipline — never leak internal reasoning or mechanics (load-bearing, worked examples):**
+
+The two failure modes below are the most common leaks. They are forbidden, not discouraged.
+
+1. **Don't editorialize — just ask.** When you ask the user to choose, render the question + the options. Do NOT justify *why* you're asking or how costly getting it wrong is — that's your reasoning, not the user's decision input.
+   - ❌ `"New social commerce experience" maps to several distinct features — picking the wrong one wastes significant scope.`
+   - ❌ `Because this spans three cross-functional tracks, attribution rules have real product decisions baked in.`
+   - ✅ `What would you like to explore?` (then the options + a recommended one)
+
+2. **Silent checks stay silent — never name a tool or narrate plumbing.** Connection/freshness pings, config reads, workspace lookups, and code recon are invisible. Do NOT print "let me ping Ritual", "checking the workspace config", or any `mcp__ritual__*` tool name.
+   - ❌ `Now I'll start the build flow. Let me check the workspace config and ping Ritual simultaneously.`
+   - ❌ `Pinging Ritual to verify the connection…`
+   - ✅ (nothing — run the check silently; the next user-visible line is the actual gate or status)
+
+3. **Don't narrate your process or restate your own instructions.** Loading a spec, fetching a preview, "before presenting", "must print it verbatim", and naming an internal **Step N** are all scratchpad — do them silently and just present the result. The user never sees the machinery between "I have the data" and "here it is."
+   - ❌ `6 recommendations ready. Let me load Step 9's exact rendering spec before presenting.`
+   - ❌ `Now I'll fetch the server-rendered preview — must print it verbatim.`
+   - ❌ `Let me check what the skill says here, then render it.`
+   - ✅ (just present it — the recommendations / the picker / the rail, with no preamble about how you produced it)
+
+Rule of thumb: if a line describes what *you* are doing internally (a tool call, loading a spec, a check, why a question matters, what you're about to render), cut it. The user wants the work and the decision, not your scratchpad. Internal **Step N** labels and artifact names ("rendering spec", "server-rendered preview", "the contract") never appear in user-facing copy.
+
 Use this compact status shape whenever possible:
 
 ```text
@@ -112,19 +134,19 @@ When in doubt, prefer one blank line over none. The cost of a tiny gap is unnoti
 
 **Build progress anchor — load-bearing (never omit, render per surface):** Every TOP-LEVEL user-facing message in `/ritual build` and `/ritual resume` MUST begin with a progress anchor before any other content. The anchor is the user's only "where am I in the flow" signal; dropping it silently is worse than printing it redundantly. The agent was historically inferring the rail from examples and squeezing it out under any pressure — this rule makes it explicit, with the exact rendering chosen per surface so the anchor doesn't wrap badly on narrow chat or duplicate a persistent UI stepper.
 
-**Surface-aware rendering** — the canonical six stages stay constant; only the visual changes:
+**Surface-aware rendering** — the canonical five stages stay constant; only the visual changes:
 
 | Surface | Rendering | When to use |
 |---|---|---|
-| **CLI / terminal** (current default) | Full two-line rail. `Ritual build` on line 1, `✓ Context  ● 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: Context · Next: Discovery`. | Six-stage rail wraps and looks noisy inside chat bubbles. |
+| **CLI / terminal** (current default) | Full two-line rail. `Ritual build` on line 1, `● 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 · 1/5 Scope`. Optionally add a second line: `Done: Scope · Next: Recommendations`. | Five-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.
-- 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.
+- The rule is: **progress anchor is mandatory; exact visual rendering is surface-specific.** Do NOT force the full five-stage rail when it will wrap.
 
 **Applies to:**
 
@@ -163,19 +185,18 @@ The chip's job is "you're still in this phase, this is which item of the series"
 
 | Stage              | Active during…                                                                 |
 |--------------------|--------------------------------------------------------------------------------|
-| `Context`          | Workspace selection, resume/start check, template, knowledge sources, code recon |
-| `Scope`            | Problem frame + sub-problem generation/selection, until scope is locked        |
+| `Scope`            | Silent code recon, problem frame + sub-problem generation/selection, until scope is locked |
 | `Discovery`        | Exploration creation, discovery questions, answers, question picking, answer review |
-| `Recommendations`  | Recommendation generation, review, admin/collaborator acceptance path           |
+| `Recommendations`  | Recommendation generation + review                                              |
 | `Build brief`      | Requirements + build brief generation/review                                   |
 | `Implementation (Your agent)` | Coding, branch/PR work, `sync_implementation`                       |
 
-Note that the FIRST rail stage is `Context`, not `Recon`. `Context` is broader — workspace pick, resume check, template choice, knowledge sources, AND code recon all live there. Use `Code recon` as the SECTION title inside the stage when the active work is repo inspection (see `references/build-flow.md` § Step 3 examples), not as the rail label. There's also a naming hazard: `/ritual recon` was retired as a command surface, so reusing `Recon` at the rail level could imply it's a separate command.
+The FIRST rail stage is `Scope`. **There is no `Context` stage** — workspace pick, resume/start check, template resolution, and **code recon** all happen as **silent plumbing inside Scope**, never as a visible rail stage. Recon runs but is not surfaced to the user by default (see `references/build-flow.md` § Step 3); only narrate repo inspection if the user explicitly asks. Naming hazard: `/ritual recon` was retired as a command surface, so don't reuse `Recon`/`Context` at the rail level.
 
 **Canonical ordering (only the active marker moves):**
 
 ```
-Context → Scope → Discovery → Recommendations → Build brief → Implementation (Your agent)
+Scope → Discovery → Recommendations → Build brief → Implementation (Your agent)
 ```
 
 - Completed stages: `✓`
@@ -185,46 +206,41 @@ Context → Scope → Discovery → Recommendations → Build brief → Implemen
 **Build rail spec (`progressHeader(stage)`) — CLI / terminal rendering:**
 
 ```text
-progressHeader("context") =>
-Ritual build
-● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
-
 progressHeader("scope") =>
 Ritual build
-✓ Context  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 progressHeader("discovery") =>
 Ritual build
-✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 progressHeader("recommendations") =>
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ● Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Scope  ✓ Discovery  ● Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 progressHeader("build-brief") =>
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
+✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
 
 progressHeader("implementation") =>
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
+✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
 ```
 
 **Compact chip spec — mobile chat / narrow chat:**
 
 ```text
-compactChip("context") =>      Ritual build · 1/6 Context
-compactChip("scope") =>        Ritual build · 2/6 Scope
-compactChip("discovery") =>    Ritual build · 3/6 Discovery
-compactChip("recommendations")=> Ritual build · 4/6 Recommendations
-compactChip("build-brief") =>  Ritual build · 5/6 Build brief
-compactChip("implementation")=> Ritual build · 6/6 Implementation (Your agent)
+compactChip("scope") =>        Ritual build · 1/5 Scope
+compactChip("discovery") =>    Ritual build · 2/5 Discovery
+compactChip("recommendations")=> Ritual build · 3/5 Recommendations
+compactChip("build-brief") =>  Ritual build · 4/5 Build brief
+compactChip("implementation")=> Ritual build · 5/5 Implementation (Your agent)
 ```
 
 Optional second line at phase transitions, resumes, and decision gates:
 
 ```text
-Done: Context · Next: Discovery
+Done: Scope · Next: Recommendations
 ```
 
 **Rich-app spec — persistent stepper:**
@@ -319,7 +335,7 @@ For no-arg `/ritual build` with zero explorations, do not frame `/ritual context
 
 ```text
 Ritual build
-● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Using workspace: {workspaceName}.
 

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

@@ -1,5 +1,5 @@
 <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
-<!-- source-sha: 31cf08b9ce5c9988 -->
+<!-- source-sha: f920ab690a90c84e -->
 
 # /ritual lite — fast build (generated; do not edit)
 
@@ -68,7 +68,7 @@ Before running this flow, apply `references/cli-output-contract.md` and `referen
 
 **Build rail is load-bearing.** Every top-level user-facing message below MUST begin with the 6-stage build rail per `references/cli-output-contract.md` § Build progress anchor. Examples in this file show the rail in context; the canonical stage table + `progressHeader(stage)` spec lives in the output contract. Do not drop the rail to save space.
 
-For narrow/mobile chat surfaces, use the **compact progress anchor** defined in `references/cli-output-contract.md` § Build progress anchor (the `Ritual build · 2/6 Scope` chip) instead of forcing the full six-stage rail to wrap. Same contract, different rendering.
+For narrow/mobile chat surfaces, use the **compact progress anchor** defined in `references/cli-output-contract.md` § Build progress anchor (the `Ritual build · 1/5 Scope` chip) instead of forcing the full five-stage rail to wrap. Same contract, different rendering.
 
 ### When to use
 
@@ -220,7 +220,7 @@ If there are **zero existing explorations** and `raw_input = null`, do not say "
 
 ```text
 Ritual build
-● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
 scope, discovery picks, rec acceptance, implementation approval). If your
@@ -616,11 +616,15 @@ If no seed file is found, OR the seed's `## The ask` doesn't match the current `
    - use neutral labels like `agent_observed_scope_pressure` or `candidate_scope_pressure`, not `priority_considerations`
    - never present the packet as authoritative; MCP/tooling decides final sub-problems, recommendations, and scope
 
-   C. `recon_digest` — user-visible, compact
-   - 3–6 bullets max
-   - key surfaces, hard constraints, scope corrections, and next action
-   - avoid quoting code comments unless they are load-bearing
-   - avoid listing every file read
+   C. `recon_digest` — **internal-only by default; NOT surfaced to the user.** Recon
+      is silent plumbing inside Scope: we do NOT dump repo signals / constraints /
+      a recon summary back to the user. Keep a compact digest in working memory for
+      your own use (and to render ONLY if the user explicitly asks "what did you
+      find?"), but by default show nothing — the user's first gate is the explore
+      picker (§ 3.2, only when recon is genuinely ambiguous) or the problem frame
+      (Step 5). The `codebase_context_packet` still feeds Step 4 silently.
+   - keep it tight if ever shown: key surfaces, hard constraints, scope corrections
+   - never list every file read; never quote non-load-bearing comments
 
    `codebase_context_packet` structure:
 
@@ -694,32 +698,15 @@ If no seed file is found, OR the seed's `## The ask` doesn't match the current `
    Next: attach PRDs/tickets if they should shape scope, or `proceed` to continue.
    ```
 
-   Example `recon_digest` — ambiguity case (multiple plausible interpretations):
+   **Explore-directions picker — the ONLY user-visible recon output, and only when recon is genuinely ambiguous.**
 
-   When recon surfaces two materially different product/implementation paths for the same ask, name them both, **mark one as recommended with a one-line reason**, and pause with a concrete reply syntax. Do not expose raw tier labels (use the translations from `references/cli-output-contract.md`).
+   When (and ONLY when) recon surfaces two+ materially different directions for the same ask, present them as a **pick-one** headed **"What would you like to explore?"** — mark one recommended with a one-line reason, and pause with a concrete reply syntax. Do NOT preface it with a "Repo signals / Constraint" dump (recon is silent), and do NOT justify why the choice matters (no "picking the wrong one wastes scope" — just ask). Do not expose raw tier labels (use the translations from `references/cli-output-contract.md`).
 
    ```text
-   Code recon
-
-   Repo signals:
-   - `GatewayForm` already supports "create account before checkout," but
-     redirects away from checkout to `customer:register`. There is no inline
-     or post-order account path today.
-   - Guest checkout is already wired through order placement:
-     `CheckoutSessionData.set_guest_email()`, `AbstractOrder.guest_email`, and
-     `build_submission()` preserve guest identity.
-   - `RegisterUserMixin` is the reusable account-creation surface:
-     user creation, `user_registered`, login, and registration email.
-   - `OrderPlacementMixin` and `post_checkout` are the clean hooks for
-     creating or claiming an account at order placement.
-
-   Constraint:
-   - Oscar's dynamic class loading via `get_class()` is the extension
-     pattern here. Implement with subclass-overridable views/mixins, not
-     monkey-patches.
+   Ritual build
+   ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
-   Ambiguity to resolve:
-   "Join while booking" maps to two plausible features.
+   What would you like to explore?
 
      1. Inline registration at checkout
         Let new customers register on the checkout page itself instead of
@@ -736,15 +723,17 @@ If no seed file is found, OR the seed's `## The ask` doesn't match the current `
    registration, or describe a different intent. Reply `pause` to stop here.
    ```
 
-   Notes on the ambiguity-case shape:
-   - **"Repo signals"** (not "Found" or "Key surfaces") signals these are the evidence behind the recommendation.
-   - **Recommendation goes after the option name on the SAME line**, with a single concise reason on the line below. This keeps the options scannable in a decision moment.
+   Notes on the explore-directions shape:
+   - **Header is "What would you like to explore?"** — an invitation to pick a direction, NOT "Ambiguity to resolve." No preamble dump of repo signals/constraints; recon stays silent.
+   - **No editorializing** about why the choice matters (no "wastes scope" / "picking wrong is costly"). The options + the recommendation carry the signal; just ask.
+   - **Recommendation goes after the option name on the SAME line**, with a single concise reason on the line below. Keeps the options scannable.
    - **`Next:` is a single line** ending in a concrete reply syntax (`reply N`), not an open-ended question. Lead with the recommended default; the escape hatch comes last.
    - **The pulse line uses the user-facing label**, never the raw tier identifier.
+   - On pick, feed the chosen direction + the `codebase_context_packet` into Step 4's `generate_considerations`.
 
-   Example `recon_digest` — Capability Boundary Check (feature spans systems not in this repo):
+   Capability Boundary Check (feature spans systems not in this repo) — **internal/packet-only; NOT displayed:**
 
-   When the user's ask requires capabilities that aren't present in this repo (frontend-only repo asked for full-stack feature, mobile repo with no API contract, etc.), surface the boundary as a normal architecture fact and name the three scoping options as **informational** context. **Do not pause on this.** The boundary information is folded into the `codebase_context_packet` so the downstream `generate_considerations` call produces boundary-aware sub-problems against the repo's actual capability surface. The user's first real gate is the problem statement in Step 5 — they can reshape scope there if the default narrowing was wrong. NEVER continue as if the repo can implement the missing half; NEVER invent the missing systems.
+   When the user's ask requires capabilities that aren't present in this repo (frontend-only repo asked for full-stack feature, mobile repo with no API contract, etc.), capture the boundary + the inferred default scope **into the `codebase_context_packet` only** — do **NOT** render it to the user (recon is silent). **Do not pause on this.** The packet drives `generate_considerations` to produce boundary-aware sub-problems against the repo's actual capability surface; the user's first real gate is the problem statement in Step 5, where they reshape scope if the default narrowing was wrong. NEVER continue as if the repo can implement the missing half; NEVER invent the missing systems. The block below is a **reference for what to capture in the packet**, not something to print.
 
    ```text
    Code recon
@@ -795,19 +784,17 @@ If no seed file is found, OR the seed's `## The ask` doesn't match the current `
    - **The pulse line stays parenthetical** with a user-facing reason (`repo boundary unresolved`), per the Pulse tier labels rule in `references/cli-output-contract.md`.
    - **Internal classification (not user-facing):** track each candidate piece against the boundary as `in_repo_buildable`, `external_dependency_known`, `external_dependency_unknown`, `needs_additional_repo`, or `contract_first_candidate`. These shape how downstream scoring + build-brief generation handle the missing half. Stamp the inferred default scope as `inferred_scope` in the packet so `generate_considerations` / `generate_problem_statement` see it. None of these labels should appear in user-facing copy.
 
-##### 3.2 — Surface the digest and continue
+##### 3.2 — Recon is silent; surface nothing unless ambiguous
 
-Surface only `recon_digest` by default. Do **not** dump `raw_recon_notes` or the full `codebase_context_packet` to the CLI unless the user asks for detail.
+**Recon runs silently.** Do NOT surface the recon digest, repo signals, constraints, or the `codebase_context_packet` to the user by default — recon is plumbing inside Scope. The packet feeds Step 4; the user sees nothing here.
 
-Pause only if:
-- recon contradicts the user's stated scope,
-- there are multiple plausible implementation areas and choosing wrong would waste work (use the ambiguity-case `recon_digest` shape above),
-- a legal/product/business constraint is required before generation,
-- the user explicitly asked to review recon before continuing.
+**The ONLY user-visible recon output is the explore-directions picker (§ 3.1), and ONLY when recon is genuinely ambiguous** — two+ materially different directions for the same ask. Then render **"What would you like to explore?"** and pause for the pick. Do NOT justify why the pick matters (no "wastes scope").
 
-**Capability boundary detection does NOT pause.** When recon shows the feature spans systems not in this repo, render the Capability Boundary Check digest from § 3.1 (it's informational), pick the default scope per the "Default narrowing logic" rule, and proceed to Step 3.5. The user reshapes scope at Step 5 (problem-statement gate) if the default narrowing was wrong.
+For a crisp, single-direction ask: **render nothing** — go straight to sub-problem generation (Step 4) with the packet. The user's first gate is the problem frame (Step 5), where they reshape scope in plain English if the default was wrong.
 
-If no pause is needed, proceed to Step 3.5. The user still has a cheap escape hatch: `recon: detail`, `recon: refresh`, or a correction in plain English.
+**Capability boundary detection does NOT pause and is NOT displayed.** When recon shows the feature spans systems not in this repo, fold the boundary + the inferred default scope into the `codebase_context_packet` (silent — see § 3.1 internal classification), pick the default scope per the "Default narrowing logic" rule, and proceed. The user reshapes scope at Step 5 if needed.
+
+If the user explicitly asks "what did you find?", you may show a tight digest then — otherwise stay silent.
 
 **Pulse (Step 3 done):** Emit a pulse line — repo grounding just moved meaningfully (sources collected, agent inspected files, possibly KG hits). Compute per `/ritual context-pulse` § Step CP3 and render compact unless this is the FIRST pulse of the build flow, in which case use full.
 
@@ -830,36 +817,11 @@ Keep the list focused. 5–10 is the sweet spot; >20 dilutes the KG signal.
 
 The codebase recon you just did handles the *code* grounding. Most real features ALSO have non-code context — PRDs, Jira/Linear tickets, design specs, meeting transcripts, Slack threads, customer-research notes — that get paraphrased into the problem statement and lose detail. Step 3.5 ingests those as first-class **knowledge sources** attached to the exploration BEFORE generating sub-problems, so the priorContext you'll see in Step 4 (`generate_considerations`) and downstream is grounded in what the user actually brought, not the paraphrase.
 
-##### 3.5.1 — Prompt the user only when useful
-
-Knowledge sources are a feature multiplier, not a mandatory gate. Ask for PRDs/tickets/designs/transcripts only when at least one of these is true:
-
-- the ask is ambiguous or cross-functional,
-- context-pulse / Reference Grounding is low,
-- the user mentioned a PRD, ticket, design, chat, customer request, or meeting,
-- the feature has legal, privacy, billing, permissions, enterprise, analytics, migration, or compliance constraints,
-- code recon found implementation surfaces but not product intent.
-
-When triggered, frame references as an optional booster, not a mandatory phase. The happy path is to continue. Keep the prompt tight — the user's decision here is simply "attach context or continue":
-
-```text
-Optional: add non-code context before scope generation.
-
-Because this touches {constraint}, PRDs, tickets, designs, incidents, or
-customer requests may change what we prioritize.
-
-Reply `go` to continue with code context only.
-Or paste files/text/URLs to attach context first.
-Reply `pause` to stop here.
-```
+##### 3.5.1 — Reactive only — do NOT prompt for non-code context
 
-Accept (alias) `go`, `g`, `generate`, `continue`, `skip`, `next`, or `none` as proceed. Per `references/cli-output-contract.md` § Surface-aware continuation prompts, do NOT treat empty input as proceed inside agent chat — chat surfaces can't reliably observe an empty message. Wait only if the user provides refs, asks a question, or types `pause` / `stop`.
+**Do NOT proactively ask the user to attach PRDs/tickets/designs/transcripts.** This is a pure capability, not a gate — surfacing an "Optional: add non-code context" prompt before the user has even framed the problem is front-of-flow friction we deliberately removed (it also tends to over-justify *why* it matters, which is internal reasoning the user doesn't need). There is **no pause here.**
 
-Process language like *"Next: we'll generate a list of suggested problems to pick from"* used to live here — removed because the decision at this moment is "attach context or continue," not a preview of what comes next. The follow-up step's framing belongs in the follow-up step, not stacked on this prompt.
-
-If none of the triggers apply, do **not** block. Print a non-blocking line and proceed:
-
-> Proceeding with codebase context only. Paste a PRD/ticket anytime before discovery if it should shape the scope.
+Handle knowledge sources **only reactively**: if the user *spontaneously* pastes a file/URL/text or says "use this PRD/ticket," ingest it via 3.5.2–3.5.4 below. Otherwise say nothing and proceed silently to Step 4 with code context only. The user can always attach context later via `/ritual context-pulse <exploration>` or by dragging refs in mid-flow.
 
 ##### 3.5.2 — Read the content
 
@@ -1017,7 +979,7 @@ If `implementationCount === 0`: don't mention the KG check (silent — would jus
 
 ```text
 Ritual build
-✓ Context  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Solving for these sub-problems
 
@@ -1152,9 +1114,9 @@ Store `exploration_id`. Move the progress header from Scope to Discovery:
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
-Exploration created. Track progress at https://app.ritualapp.cloud/e/{exploration_id}
+Exploration created.
 
 Next: generate discovery questions to resolve the implementation trade-offs.
 ```
@@ -1238,7 +1200,7 @@ Call `mcp__ritual__suggest_discovery_questions(exploration_id)`. Returns immedia
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Generating discovery questions for each area…
 ```
@@ -1295,7 +1257,7 @@ Open ON Area 1 with the **rail above and Area 1's questions below it** — never
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Question picking · Area 1 of {N} · {Area name}          picked so far: 0
 
@@ -1491,7 +1453,7 @@ For `engineering`, `delivery`, and `operations` roles, show:
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Run discovery
 
@@ -1512,7 +1474,7 @@ For `product`, `design`, or explicitly PRD-style flows, answer review may be use
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Run discovery
 
@@ -1608,7 +1570,7 @@ Landing (first question, full rail + intro):
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Run Agentic Exploration
 
@@ -1718,7 +1680,7 @@ First category (rail shown):
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ● Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Scope  ✓ Discovery  ● Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Scope:
 {one-line compressed scope — ~80-120 chars; truncate at a clause boundary, no ellipsis}
@@ -1806,7 +1768,7 @@ Editing is non-destructive and does not advance the flow — the user can `edit`
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
+✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
 
 Reviewed {N} recommendations.
 
@@ -2091,6 +2053,13 @@ Steps:
    - `contradicted` — brief claim is wrong; the code does something different.
    - `not_found` — symbol couldn't be located.
 
+   **Narrating a finding (if you surface one before the summary): frame it as resolving drift, not as an error report.** Lead with *resolving drift between the brief and the codebase*, then ONE plain sentence describing the drift and where the real pattern lives. Do **not** lead with "X doesn't exist" / "references a function that doesn't exist" — a `not_found` / `contradicted` verdict is the verification working as intended (it caught a brief-vs-code gap before you shipped), not a failure to alarm the user about.
+
+   ❌ `get_core_apps is not in the codebase — the brief's RB-1 references a function that doesn't exist. The actual pattern is direct INSTALLED_APPS manipulation (index + replace), as seen in tests/settings.py.`
+   ✅ `Resolving drift between the brief and the codebase: RB-1 cites get_core_apps, but the repo edits INSTALLED_APPS directly (index + replace — see tests/settings.py). Noting it in the verification.`
+
+   This is a progress line, not a gate — keep it to one sentence and continue; the structured findings land in `BUILD-BRIEF-VERIFICATION.md` and the Step 10d gate.
+
 5. **Write `BUILD-BRIEF-VERIFICATION.md`** to disk alongside `BUILD-BRIEF.md` using the schema in `references/brief-verification-checklist.md`. Cite file + line range + actual code snippet on every contradiction. Do not fabricate evidence.
 
 6. **Sync the verification to Ritual's KG** — call `mcp__ritual__sync_brief_review` with:
@@ -2207,7 +2176,7 @@ End Step 10 with a single recommended action plus a cheap escape hatch — never
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
+✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
 
 Build brief ready
 
@@ -2242,7 +2211,7 @@ The Implementation phase landing — full rail (the rail moves to Implementation
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
+✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
 
 Implementation (Your agent)
 
@@ -2487,7 +2456,7 @@ Before asking for permission, frame the call in language the user can act on. `s
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
+✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
 
 Log implementation
 
@@ -2530,7 +2499,7 @@ When sync_implementation succeeds, the response includes:
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ✓ Implementation (Your agent)
+✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ✓ Implementation (Your agent)
 
 ✓ Logged implementation for {exploration name}
 
@@ -2565,7 +2534,7 @@ User-visible (full rail — sync failure is a top-level state):
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
+✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
 
 Sync failed (recoverable)
 
@@ -2603,7 +2572,7 @@ If stale, surface to the user with the full rail (top-level decision gate):
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
+✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
 
 Pending sync is stale
 

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

@@ -4,7 +4,7 @@
 
 Output: the user lands on the right step of an existing exploration's `/ritual build` flow — no new exploration created, no fresh-start path offered.
 
-**Build rail is load-bearing here too.** Every top-level user-facing message in `/ritual resume` MUST begin with the 6-stage build rail per `references/cli-output-contract.md` § Build rail — both during the picker (rail at `● Context`) and once you teleport into the chosen exploration (rail at whatever stage that exploration is in).
+**Build rail is load-bearing here too.** Every top-level user-facing message in `/ritual resume` MUST begin with the 5-stage build rail per `references/cli-output-contract.md` § Build rail — both during the picker (rail at `● Scope`) and once you teleport into the chosen exploration (rail at whatever stage that exploration is in).
 
 
 ### When to use

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

@@ -1,4 +1,4 @@
 {
-  "cliVersion": "0.24.0",
-  "builtAt": "2026-06-08T22:51:34.833Z"
+  "cliVersion": "0.25.0",
+  "builtAt": "2026-06-09T00:58:35.759Z"
 }

package/skills/codex/ritual/references/brief-verification-checklist.md

@@ -4,7 +4,7 @@ Reference for `/ritual build` Step 10b.5 (the auto-fire verify-brief pass that r
 
 The brief generator runs server-side and **does not have repo access**. It writes assertions about cited files / functions / classes based on the agent's earlier recon summary — which is a text summary, not the actual code. When the brief says *"`is_allowed_to_see` is insufficient — needs token-based access"* but the code actually ships email-allowlist semantics, the contradiction is invisible to the brief generator and to the user reading the brief.
 
-Step 10b.5 closes this gap: **the agent (with repo access) reads the bodies of the specific symbols the brief cites and produces a structured list of findings before the user sees the brief.** Findings flow back into the brief via `refine_build_brief` if any contradictions are detected.
+Step 10b.5 closes this gap: **the agent (with repo access) reads the bodies of the specific symbols the brief cites and produces a structured list of findings before the user sees the brief.** Findings are written to a **separate** file (`BUILD-BRIEF-VERIFICATION.md`) and synced to Ritual's KG via `sync_brief_review` — they are **never** written back into `BUILD-BRIEF.md`. The brief stays the read-only historical artifact Ritual generated; the corrections reach the implementation through plan mode's KG `priorContext`, not through a brief rewrite. (There is **no** `refine_build_brief` tool — it was removed 2026-05-15 and replaced by `sync_brief_review`.)
 
 This is the **non-UI sibling of `references/ui-ux-checklist.md`** (Step 10.5 UX review). Same methodology shape (read brief → identify citations → find in repo → compare → fill schema → surface findings), different targets (functions / data shapes / model fields instead of UI components).
 
@@ -61,13 +61,18 @@ Three verdicts:
 - **`contradicted`** — the brief's claim is **wrong**. The code does something different. This is the verdict that drives a refinement.
 - **`not_found`** — the brief cited a symbol the agent could not locate in the repo. Either the symbol was renamed, deleted, or never existed. Either way: the brief is asserting against a phantom; surface to user.
 
+**Narrating a finding mid-verification — frame it as resolving drift, not as an error.** If you surface a `contradicted` / `not_found` finding in a progress line before the summary, lead with *resolving drift between the brief and the codebase*, then one plain sentence on the drift + where the real pattern lives. A caught gap is the verification doing its job, not a failure to alarm about — don't lead with "X doesn't exist" / "references a function that doesn't exist."
+
+- ❌ `get_core_apps is not in the codebase — the brief's RB-1 references a function that doesn't exist. The actual pattern is direct INSTALLED_APPS manipulation (index + replace), as seen in tests/settings.py.`
+- ✅ `Resolving drift between the brief and the codebase: RB-1 cites get_core_apps, but the repo edits INSTALLED_APPS directly (index + replace — see tests/settings.py). Noting it in the verification.`
+
 **5. Fill the output schema with evidence.**
 
 Write `BUILD-BRIEF-VERIFICATION.md` to disk alongside `BUILD-BRIEF.md`. Use the schema below. **Each finding cites the file + line range + the actual code snippet that justified the verdict.** The user reading this must be able to verify your verification — no hand-waving, no claims without evidence.
 
 **6. If any findings are `contradicted`, surface to the user inline at Step 10d.**
 
-The Step 10d gate normally reads *"Reply `go` to implement, `refine` for edits, `drill {N}` to inspect, `pause` to stop."* When `contradicted` findings exist, the gate's CTA shifts to highlight the contradictions:
+The Step 10d gate is `go` / `drill {N}` / `pause` (plus `ux-review`) — there is **no `refine` action**; the brief is read-only after generation. When `contradicted` findings exist, the gate prepends a summary so the user sees what the agent learned about the brief before deciding:
 
 ```text
 ⚠ Verification found {N} contradiction(s) between the brief and the actual code:
@@ -76,11 +81,12 @@ The Step 10d gate normally reads *"Reply `go` to implement, `refine` for edits,
     "{code_reality}" (see {cited_file}:{cited_lines}).
   · ...
 
-Reply `refine` to apply these corrections, `go` to proceed anyway,
-or `drill {N}` to inspect one rec.
+These are synced to Ritual; plan mode reads them when you `go`.
+Reply `go` to implement (corrections flow in via KG), `drill {N}` to
+inspect, or `pause` to stop.
 ```
 
-The user can `refine` (recommended) — at which point the SKILL calls `refine_build_brief` with the structured findings array, and the LLM produces an updated brief that incorporates the corrections authoritatively. Or `go` if the user has context the agent doesn't (e.g. "yes the brief is wrong but I want to ship it as-is for now"). The decision stays with the user; the agent surfaces the evidence.
+The findings do **not** rewrite the brief. They were already persisted via `sync_brief_review` (a durable `BriefReview` row) at step 5; when the user replies `go`, **plan mode reads the brief + that review via KG `priorContext`** and the implementation incorporates the corrections — without the brief text changing. If the user has context the agent doesn't ("yes the brief is wrong but ship as-is"), `go` proceeds the same way; the corrections are recorded regardless. The only path to *new brief content* is `generate_build_brief` with `force: true` (full regen from changed source data) — used when the underlying recs/requirements actually changed, never to patch a verification finding.
 
 ---
 
@@ -146,7 +152,7 @@ checked out, state that clearly.}
 
 - **Verify everything in the brief.** Only the symbol-citation slice. Pose-level claims, framing, and general direction are out of scope.
 - **Read the full file.** Read enough surrounding context to verify the symbol (~10 lines); not the whole file. Capped at ~15 citations total to keep this fast.
-- **Edit the brief directly.** Step 10b.5 only writes `BUILD-BRIEF-VERIFICATION.md`. The user decides whether to call `refine_build_brief` with the findings at Step 10d (recommended) or proceed with the brief as-is.
+- **Edit the brief directly.** Step 10b.5 only writes the **separate** `BUILD-BRIEF-VERIFICATION.md` and syncs it via `sync_brief_review`. `BUILD-BRIEF.md` is never touched — it stays the read-only historical artifact. Findings reach the implementation through plan mode's KG `priorContext` at Step 11, not through a brief rewrite. (Regenerating from changed source data is a different operation — `generate_build_brief` with `force: true` — not part of this step.)
 - **Persist findings to the KG.** Phase 1 is local-only. Phase 2 (filed at `memory/backlog_brief_verification_findings_kg_promotion.md`) adds the `BriefVerificationFinding` Prisma model + endpoint + priorContext injection so future briefs on overlapping files inherit verified facts.
 
 ---