@ritualai/cli 0.24.0 → 0.25.0

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: 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/vscode/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