@ritualai/cli 0.24.0 → 0.36.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/dist/commands/build.js +89 -0
  2. package/dist/commands/build.js.map +1 -0
  3. package/dist/commands/init.js +95 -109
  4. package/dist/commands/init.js.map +1 -1
  5. package/dist/commands/uninstall.js +6 -1
  6. package/dist/commands/uninstall.js.map +1 -1
  7. package/dist/index.js +18 -0
  8. package/dist/index.js.map +1 -1
  9. package/dist/lib/agents/configure-mcp.js +63 -0
  10. package/dist/lib/agents/configure-mcp.js.map +1 -1
  11. package/dist/lib/agents/launch.js +70 -0
  12. package/dist/lib/agents/launch.js.map +1 -0
  13. package/dist/lib/agents/providers.js +8 -2
  14. package/dist/lib/agents/providers.js.map +1 -1
  15. package/dist/lib/final-cta-box.js +22 -10
  16. package/dist/lib/final-cta-box.js.map +1 -1
  17. package/dist/lib/help-style.js +65 -0
  18. package/dist/lib/help-style.js.map +1 -0
  19. package/dist/lib/onboarding-state.js +9 -8
  20. package/dist/lib/onboarding-state.js.map +1 -1
  21. package/dist/lib/uninstall-plan.js +18 -1
  22. package/dist/lib/uninstall-plan.js.map +1 -1
  23. package/dist/lib/workspace-explainer.js +42 -111
  24. package/dist/lib/workspace-explainer.js.map +1 -1
  25. package/dist/lib/workspace-flow.js +4 -1
  26. package/dist/lib/workspace-flow.js.map +1 -1
  27. package/package.json +1 -1
  28. package/skills/claude-code/ritual/.ritual-bundle.json +3 -2
  29. package/skills/claude-code/ritual/SKILL.md +8 -0
  30. package/skills/claude-code/ritual/references/brief-verification-checklist.md +12 -6
  31. package/skills/claude-code/ritual/references/build-flow.md +485 -456
  32. package/skills/claude-code/ritual/references/cli-output-contract.md +111 -39
  33. package/skills/claude-code/ritual/references/lite-flow.md +494 -462
  34. package/skills/claude-code/ritual/references/resume-flow.md +1 -1
  35. package/skills/codex/ritual/.ritual-bundle.json +3 -2
  36. package/skills/codex/ritual/SKILL.md +8 -0
  37. package/skills/codex/ritual/references/brief-verification-checklist.md +12 -6
  38. package/skills/codex/ritual/references/build-flow.md +485 -456
  39. package/skills/codex/ritual/references/cli-output-contract.md +111 -39
  40. package/skills/codex/ritual/references/lite-flow.md +494 -462
  41. package/skills/codex/ritual/references/resume-flow.md +1 -1
  42. package/skills/cursor/ritual/.ritual-bundle.json +3 -2
  43. package/skills/cursor/ritual/SKILL.md +8 -0
  44. package/skills/cursor/ritual/references/brief-verification-checklist.md +12 -6
  45. package/skills/cursor/ritual/references/build-flow.md +485 -456
  46. package/skills/cursor/ritual/references/cli-output-contract.md +111 -39
  47. package/skills/cursor/ritual/references/lite-flow.md +494 -462
  48. package/skills/cursor/ritual/references/resume-flow.md +1 -1
  49. package/skills/gemini/ritual/.ritual-bundle.json +3 -2
  50. package/skills/gemini/ritual/SKILL.md +8 -0
  51. package/skills/gemini/ritual/references/brief-verification-checklist.md +12 -6
  52. package/skills/gemini/ritual/references/build-flow.md +485 -456
  53. package/skills/gemini/ritual/references/cli-output-contract.md +111 -39
  54. package/skills/gemini/ritual/references/lite-flow.md +494 -462
  55. package/skills/gemini/ritual/references/resume-flow.md +1 -1
  56. package/skills/kiro/ritual/.ritual-bundle.json +3 -2
  57. package/skills/kiro/ritual/SKILL.md +8 -0
  58. package/skills/kiro/ritual/references/brief-verification-checklist.md +12 -6
  59. package/skills/kiro/ritual/references/build-flow.md +485 -456
  60. package/skills/kiro/ritual/references/cli-output-contract.md +111 -39
  61. package/skills/kiro/ritual/references/lite-flow.md +494 -462
  62. package/skills/kiro/ritual/references/resume-flow.md +1 -1
  63. package/skills/vscode/ritual/.ritual-bundle.json +3 -2
  64. package/skills/vscode/ritual/SKILL.md +8 -0
  65. package/skills/vscode/ritual/references/brief-verification-checklist.md +12 -6
  66. package/skills/vscode/ritual/references/build-flow.md +485 -456
  67. package/skills/vscode/ritual/references/cli-output-contract.md +111 -39
  68. package/skills/vscode/ritual/references/lite-flow.md +494 -462
  69. package/skills/vscode/ritual/references/resume-flow.md +1 -1
  70. package/dist/lib/build-flow-explainer.js +0 -226
  71. package/dist/lib/build-flow-explainer.js.map +0 -1
  72. package/dist/lib/persona-picker.js +0 -171
  73. package/dist/lib/persona-picker.js.map +0 -1
@@ -1,5 +1,5 @@
1
1
  <!-- GENERATED from references/build-flow.md by apps/cli/scripts/generate-lite-flow.js — DO NOT EDIT. -->
2
- <!-- source-sha: 31cf08b9ce5c9988 -->
2
+ <!-- source-sha: d91bf82d5264e811 -->
3
3
 
4
4
  # /ritual lite — fast build (generated; do not edit)
5
5
 
@@ -18,17 +18,20 @@ Follow build-flow.md's steps below EXACTLY, with these **LITE OVERRIDES**:
18
18
  - **Workspace (Step 1):** use `.ritual/config.json`'s workspace, or the only/first
19
19
  project workspace. No pause.
20
20
  - **Scope / problem frame (Step 5):** auto-lock the first draft. No pause.
21
- - **Discovery (Step 7):** auto-accept the **top 2–3 most impactful (server-ranked)
22
- questions per Area** — do NOT walk Area-by-Area. Commit in ONE batch, then run
21
+ - **Discovery (Step 7):** auto-accept **the suggested 12** (the landing's set,
22
+ § 7.3.0 rubric) — do NOT walk Area-by-Area. Commit in ONE batch, then run
23
23
  the agentic exploration.
24
24
  - **Recommendations are auto-accepted at generation**; requirements + deliverable
25
25
  + build brief generate automatically. The review never blocks them.
26
26
 
27
27
  ## The only human touchpoints in lite
28
- 1. **Front gate (Step 3.9) — confirm the job + pick the lead persona.** Render the
29
- two beats: (a) "run lite discovery for *<feature>*? It'll produce a
30
- *<deliverable>*" with a `deep` escape to `/ritual build`; then (b) after
31
- `work_item`, "Which persona should the agent take on?" (recommended first).
28
+ 1. **Front gate (Step 0.7) — confirm the job to be done.** Call
29
+ `classify_work_item` with the raw ask verbatim (the SERVER classifies never
30
+ classify yourself), then render ONE beat: "run lite discovery for *<feature>*?
31
+ The job: *<workItemLabel>* it'll produce a *<deliverable>*" with a `deep`
32
+ escape to `/ritual build`. `proceed` confirms; any other substantive reply is
33
+ a correction (re-call the tool with `correction` + `previous_jtbd`). No
34
+ persona pick — the server resolves the job's persona coverage.
32
35
  2. **Recommendation review (Step 9) — "review or proceed" (NON-BLOCKING).** Offer:
33
36
  `edit R{N}` (suggest-edit → preview → accept persists) or `proceed`. **No
34
37
  reject CTA.** Artifacts are already generating; proceeding never blocks.
@@ -66,7 +69,8 @@ When the user says "tighten the scope," call `generate_problem_statement(...)` w
66
69
 
67
70
  Before running this flow, apply `references/cli-output-contract.md` and `references/async-polling.md`. Keep raw recon internal, pass the `codebase_context_packet` downstream, and show the user only the compact `recon_digest`.
68
71
 
69
- **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.
72
+ <!-- skill-options:no-gate-change: deliverable-named rail stage labels + conditional Implementation stage only; no pause or option changes -->
73
+ **Build rail is load-bearing.** Every top-level user-facing message below MUST begin with the build rail per `references/cli-output-contract.md` § Build progress anchor — SIX stages for development jobs, FIVE for non-development jobs (no `Implementation` stage), with stage 5 named for the job's deliverable (`deliverableTemplate` from the Job gate). The literal `Build brief` in this file's examples is the generic-build label; substitute the confirmed job's deliverable name. 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.
70
74
 
71
75
  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.
72
76
 
@@ -146,6 +150,58 @@ If the user types `always audit for this build` mid-flow at the Step 9.6 prompt,
146
150
 
147
151
  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.
148
152
 
153
+
154
+ #### Step 0.7 — The Job gate: classify the job to be done
155
+
156
+ **The FIRST tool call of a fresh build.** The server — not you — classifies the user's raw ask into
157
+ one canonical job-to-be-done (the full catalog: development, product, marketing, prototyping). Your
158
+ job is to relay the result and get an explicit confirmation before ANYTHING else happens. This is the
159
+ `Job` stage of the build rail (see `references/cli-output-contract.md`).
160
+
161
+ When this gate runs:
162
+ - `/ritual build <ask text>` → run it IMMEDIATELY, before the workspace pick.
163
+ - Bare `/ritual build` (no ask) → proceed to Step 1/1.5 first; the moment a FRESH ask is captured
164
+ (the user describes what they want to build), run this gate before continuing.
165
+ - Resume paths (Step 1.5 → resume) → skip this gate entirely; the exploration's job is already set.
166
+
167
+ 1. **Call `mcp__ritual__classify_work_item`** with `raw_input` = the user's ask, verbatim. Do NOT
168
+ classify yourself, do NOT pre-filter to development jobs. It returns
169
+ `{ jtbd, workItemLabel, deliverableTemplate, why, personaCoverage }`.
170
+
171
+ 2. **Render the validation prompt** (rail stage `Job`):
172
+
173
+ ```text
174
+ Ritual build
175
+ ● Job ○ Scope ○ Discovery ○ Recommendations ○ {Deliverable} ○ Implementation (Your agent)
176
+
177
+ You're looking to: {restate the ask in one short clause}
178
+ The job to be done: {workItemLabel} — {why}
179
+ Deliverable: {deliverableTemplate}
180
+
181
+ Reply `proceed` to frame the problem (sub-problems + problem statement), or tell me what the
182
+ job actually is.
183
+ ```
184
+
185
+ Do not render `personaCoverage` — persona representation is handled server-side now; only surface
186
+ it if the user explicitly asks who's involved.
187
+
188
+ Rail naming (deliverable-named rail, 2026-06-11): render `{Deliverable}` as the PROPOSED job's
189
+ `deliverableTemplate` (e.g. `Launch Brief`, `PRD`, `Service Build Brief`; `Build brief` for the
190
+ generic `build-feature`), and OMIT the `Implementation (Your agent)` stage entirely when the
191
+ proposed job is not a development job — non-dev rails have FIVE stages ending at the deliverable.
192
+ A correction that changes the job updates the rail on the next render. Spec:
193
+ `references/cli-output-contract.md` § Canonical stage table.
194
+
195
+ 3. **[USER PAUSE]** — wait for the user's actual reply. Never infer confirmation from the original
196
+ ask, auto-mode, or silence. `proceed` / `yes` / `ok` confirms. ANY other substantive reply is a
197
+ correction: call `mcp__ritual__classify_work_item` AGAIN with the same `raw_input`, plus
198
+ `correction` (the user's words) and `previous_jtbd` (the rejected slug), then re-render step 2.
199
+ Loop until the user proceeds.
200
+
201
+ 4. **Remember the confirmed `jtbd`** — you pass it to `create_exploration` at Step 6. Only after the
202
+ user proceeds does the flow enter the `Scope` stage (workspace pick onward).
203
+
204
+
149
205
  #### Step 1 — Pick a workspace
150
206
 
151
207
  <!-- skill-options:no-gate-change: connection-freshness ping check is a non-interactive warn, adds no user-facing gate or option -->
@@ -176,7 +232,17 @@ Resolution order:
176
232
  > Override with `workspace: list`.
177
233
 
178
234
  Pause only if the file is missing/malformed, the workspace cannot be accessed (validation failed above), or the user explicitly asks to switch.
179
- 2. **List existing project workspaces.** If no `.ritual/config.json`, call `mcp__ritual__list_workspaces` — this returns project-type workspaces (the General workspace is excluded by default; agents never use it). Present as a numbered list (id, name). **[LITE AUTOno pause; auto-pick the recommended default]** for selection.
235
+ 2. **List existing project workspaces.** If no `.ritual/config.json`, call `mcp__ritual__list_workspaces` — this returns project-type workspaces (the General workspace is excluded by default; agents never use it). This path is usually a first-time user who has never been told what a workspace IS open the render with the one-line explainer (same register as the CLI's `ritual init`), then the numbered list (id, name):
236
+
237
+ <!-- skill-options:no-gate-change: adds explainer prose to the existing workspace-pick gate; options and pause unchanged -->
238
+
239
+ > No `.ritual/config.json` found — this repo isn't bound to a workspace yet.
240
+ > A workspace is Ritual's memory for this codebase: the context and reasoning behind every build lands there, so the next build (by you, a teammate, or an agent) starts from what's already known.
241
+ >
242
+ > Which workspace should this exploration live in?
243
+ > {numbered list}
244
+
245
+ **[LITE AUTO — no pause; auto-pick the recommended default]** for selection.
180
246
  3. **Create a new one if none exist or user wants a fresh one.** Call `mcp__ritual__create_workspace` with a name — convention is to name it after the repo (basename of cwd, or origin remote). Confirm the name with the user first. **[LITE AUTO — no pause; auto-pick the recommended default]**
181
247
 
182
248
  Store `workspace_id` for the rest of the flow.
@@ -200,6 +266,7 @@ When you later see `.ritual/config.json` in `git status` output (modified or unt
200
266
 
201
267
  #### Step 1.1 — No-arg `/ritual build` entry
202
268
 
269
+ <!-- skill-options:no-gate-change: ask-copy gains example asks + the granularity teaching line; no pause or option changes -->
203
270
  If the user invokes `/ritual build` with no problem statement, set `raw_input = null` and **do not ask for a problem statement before checking the workspace**. A no-arg build is often a continuation or next-work discovery intent, so `resume` and `suggest high-leverage work` must remain available.
204
271
 
205
272
  After workspace selection, proceed into the existing-exploration check below. User-facing copy should avoid internal step labels and should offer these paths when applicable:
@@ -214,13 +281,16 @@ Reply with:
214
281
  - `suggest` to have me look for high-leverage candidates from repo + workspace history
215
282
  - a feature/problem description to start fresh
216
283
  - `none` to exit
284
+
285
+ e.g. "audit log for admin actions" — a few words works; discovery extracts
286
+ the detail. Constraints and exclusions you type become binding scope.
217
287
  ```
218
288
 
219
289
  If there are **zero existing explorations** and `raw_input = null`, do not say "starting fresh" and do not advance to template selection yet. Ask for the feature/problem first:
220
290
 
221
291
  ```text
222
292
  Ritual build
223
- Context Scope ○ Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
293
+ Job Scope ○ Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
224
294
 
225
295
  Heads-up: Ritual's build flow needs ~5 real decisions from you (workspace,
226
296
  scope, discovery picks, rec acceptance, implementation approval). If your
@@ -234,6 +304,15 @@ No Ritual history here yet.
234
304
 
235
305
  Next: start with a feature, or let Ritual suggest high-leverage work from the repo.
236
306
 
307
+ Any granularity works, and any job — not just code:
308
+ "audit log for admin actions"
309
+ "Add soft-delete for projects. Restorable 30 days, then purge via the
310
+ existing background-job system. Don't touch billing records; exports
311
+ must exclude deleted data."
312
+ "draft the launch brief for the new pricing tier"
313
+ A few words → discovery extracts the detail. Constraints and exclusions
314
+ you type become binding scope.
315
+
237
316
  Reply with a feature/problem description, `suggest`, `pulse <ask>`, or `none`.
238
317
  ```
239
318
 
@@ -521,7 +600,7 @@ Steps:
521
600
 
522
601
  #### Step 2 — Template selection (server-side, silent)
523
602
 
524
- > **Rewritten 2026-05-21 (CLI 0.9.0+).** Previously this section had three branches (persona-pinned / legacy-pinned / list-and-pick) that the SKILL had to navigate, and could optionally call `mcp__ritual__list_templates`. That tool is gone from the agent-facing MCP surface as of CLI 0.9.0. Template selection is now entirely server-side: when `create_exploration` is called without an explicit `template_id`, the server resolves the right SYSTEM template from `user.persona` (set by `ritual init` FTUE) → `workspace.defaultTemplateId` (team override) → system default, then forks it into a per-exploration Template atomically inside the same `create_exploration` request.
603
+ > **Rewritten 2026-05-21 (CLI 0.9.0+), chain updated 2026-06-11 (JTBD-first entry).** Previously this section had three branches (persona-pinned / legacy-pinned / list-and-pick) that the SKILL had to navigate, and could optionally call `mcp__ritual__list_templates`. That tool is gone from the agent-facing MCP surface as of CLI 0.9.0. Template selection is now entirely server-side: when `create_exploration` is called without an explicit `template_id`, the server resolves the right SYSTEM template from the exploration's `jtbd` (the job confirmed at the Step 0.7 Job gate) → `workspace.defaultTemplateId` (team override) → `user.persona` (legacy — the FTUE picker is gone; set only via `ritual init --persona`) → a designated generic fallback → system default, then forks it into a per-exploration Template atomically inside the same `create_exploration` request.
525
604
 
526
605
  **For the agent: there is no template-selection step. Skip this Step entirely and go to Step 3.** Don't read `.ritual/config.json` for persona, don't try to call `list_templates` (it's not registered), don't render a "Using persona X" confirmation.
527
606
 
@@ -532,9 +611,12 @@ Why no user-visible confirmation: a "do you want to continue with your persona?"
532
611
  ```
533
612
  1. Resolve PARENT template from the chain:
534
613
  explicit dto.templateId
614
+ → jtbd → the picked job's deliverable template
535
615
  → workspace.defaultTemplateId
536
- → user.persona via schema.id-matching SYSTEM template
537
- first SYSTEM template by createdAt
616
+ → user.persona via schema.id-matching SYSTEM template (legacy)
617
+ designated generic fallback (build-feature → Backend Service
618
+ (Implementation Brief); produce-deliverable → Product Brief)
619
+ → first SYSTEM template by createdAt (last resort)
538
620
  2. FORK the parent into a per-exploration Template row
539
621
  (type='EXPLORATION', parentTemplateId set, schema copied)
540
622
  3. CREATE the Exploration pointing at the forked template
@@ -549,317 +631,28 @@ All atomic in one HTTP request. See `apps/api/src/modules/explorations/explorati
549
631
 
550
632
  Recognized roles (use the role keyword the API returns, not a paraphrase): `engineering`, `product`, `design`, `marketing`, `delivery`, `operations`.
551
633
 
552
- If the user corrects the role mid-flow ("actually I'm building a PRD"), update internal role tracking. **Do not** re-pick the template — that requires re-creating the exploration, which is bigger than a mid-flow correction warrants. If the user genuinely wants a different template for this exploration, ask them to start over: `/ritual build` again, or `ritual init --persona <slug>` to change their default first.
634
+ If the user corrects the role mid-flow ("actually I'm building a PRD"), update internal role tracking. **Do not** re-pick the template — that requires re-creating the exploration, which is bigger than a mid-flow correction warrants. If the user genuinely wants a different template for this exploration, ask them to start over with `/ritual build` and correct the job at the Job gate (the jtbd drives the template now; `ritual init --persona <slug>` only changes the legacy personal default).
553
635
 
554
636
  Proceed to Step 3.
555
637
 
556
- #### Step 3 — Code reconnaissance
557
-
558
- **Skip only if the user explicitly asks ("just generate, don't read the code") OR if you're operating outside a codebase context.**
559
-
560
- Before generating considerations, gather codebase context so the sub-problems land specific to *this* code, not generic. The goal is not to show the user every fact you found; the goal is to ground downstream MCP calls and expose only decision-relevant findings in the CLI.
561
-
562
- **Capability Boundary Check (load-bearing):** If recon detects a mismatch between the user's ask and what THIS repo can actually implement — typically because the feature spans systems (backend service, mobile app, billing provider, email worker, schema migrations) that aren't present in the current checkout — DO NOT invent the missing systems and DO NOT continue as if the repo is complete. Run the boundary-check pause described in § 3.2 below before proceeding to scope. Frame the missing half as a normal architecture boundary, not a failure: *"This repo looks like the frontend side of a larger feature,"* not *"I could not find backend dependencies."* The user has not done anything wrong; the agent is asking how to scope the work.
563
-
564
- Common boundary mismatches to detect:
565
-
566
- - Full-stack feature ask + frontend-only repo (UI present, no API/service code)
567
- - Mobile feature ask + no API client contract or backend
568
- - Billing/payments feature + no payment service / subscription code
569
- - Email/notification feature + no worker / job / email-provider integration
570
- - Auth/session feature + no user mutation / session backend
571
- - Data/analytics feature + no schema, migration, or storage layer
572
-
573
- ##### 3.0 — Check for a pre-build context seed
574
-
575
- Before doing fresh recon, check whether the user already seeded one via `/ritual context-pulse`. Glob for `CONTEXT-*.md` at the repo root.
576
-
577
- If a `CONTEXT-<slug>.md` is found AND its `## The ask` section close-matches the current `raw_input`:
578
-
579
- - **Use it to seed `codebase_context_packet`.** Parse the file's `## Candidate files` list — those become the seed for `sources[]`. Parse `## Prior KG context` as evidence inside the packet, not as final prioritization.
580
- - **Skip fresh recon** unless the seed is stale or obviously incomplete. If you skip fresh recon, still normalize the seed into the packet structure below before calling MCP tools.
581
- - **Surface a compact note**:
582
- > Code recon
583
- > Found `CONTEXT-<slug>.md` from `/ritual context-pulse`.
584
- > Using {N} candidate files + {M} related prior exploration{s} as the recon base. Override with `recon: refresh`.
585
- - Proceed directly to 3.2.
586
-
587
- If no seed file is found, OR the seed's `## The ask` doesn't match the current `raw_input`, do fresh recon. For mismatch, mention the ignored seed in one line and do not delete it.
588
-
589
- ##### 3.1 — Fresh recon
590
-
591
- 1. **Read the README + top-level project structure.** Use `ls` / Glob to see top-level files. Identify the language, framework, key directories, and likely entry points.
592
-
593
- 2. **Glob for relevance.** Derive patterns from the user's problem. Examples:
594
- - User says "auth flow" → `**/auth/**`, `**/login*`, `**/user*`, `**/session*`
595
- - User says "checkout" → `**/checkout/**`, `**/cart/**`, `**/order/**`, `**/payment*`
596
- - User says "notifications" → `**/notif*`, `**/email/**`, `**/sms/**`, `**/push/**`
597
- Cap at ~15 hits per pattern.
598
-
599
- 3. **Skim 3–5 most-relevant files.** For each, read the first ~100 lines + scan for class/function names. Triangulate whether the behavior lives there or calls into another area.
600
-
601
- 4. **Build three recon artifacts.**
602
-
603
- A. `raw_recon_notes` — internal evidence only
604
- - files read and why they were selected
605
- - symbols/classes/functions inspected
606
- - relevant comments, schema details, tests, migrations, and config
607
- - KG hits, prior deferrals, and prior implementation references
608
- - uncertain observations, false leads, and things not found
609
- - do **not** show this by default and do **not** pass it as the main MCP planning input
610
-
611
- B. `codebase_context_packet` — downstream planning input
612
- - this is the synthesized artifact passed into `raw_input`, context pulses, and any MCP field named `recon_context`
613
- - it helps MCP understand what the coding agent observed locally without deciding the final considerations itself
614
- - separate factual observations from agent hypotheses
615
- - include confidence levels for hypotheses
616
- - use neutral labels like `agent_observed_scope_pressure` or `candidate_scope_pressure`, not `priority_considerations`
617
- - never present the packet as authoritative; MCP/tooling decides final sub-problems, recommendations, and scope
618
-
619
- C. `recon_digest` — user-visible, compact
620
- - 3–6 bullets max
621
- - key surfaces, hard constraints, scope corrections, and next action
622
- - avoid quoting code comments unless they are load-bearing
623
- - avoid listing every file read
624
-
625
- `codebase_context_packet` structure:
626
-
627
- ```markdown
628
- --- Codebase context packet ---
629
-
630
- ## User intent
631
- {verbatim or lightly normalized ask}
632
-
633
- ## Observed relevant surfaces
634
- - `path` — observed role in this feature or constraint
635
- - `path` — observed extension point, lifecycle, model, or integration seam
636
-
637
- ## Evidence
638
- - `path:symbol` — factual observation from code
639
- - Prior Ritual signal: {exploration / PR / RB / deferral}, if available
640
- - Missing or not-found evidence when it corrects the user's framing
641
-
642
- ## Agent hypotheses
643
- - This may make {candidate area} important because {evidence-backed reason}
644
- Confidence: low / medium / high
645
-
646
- ## Agent-observed scope pressure
647
- - Privacy / lifecycle / migration / compatibility / async / ownership / testing risk
648
- - Only include pressure that intersects with the feature intent and code evidence
649
-
650
- ## Scope corrections
651
- - The ask says X, but the code suggests Y
652
- - Missing fields, renamed concepts, or assumptions the code contradicts
653
-
654
- ## Open questions for discovery
655
- - Questions the code cannot answer and the user/Ritual exploration should resolve
656
- ```
657
-
658
- Example `codebase_context_packet` excerpt:
659
-
660
- ```markdown
661
- ## Observed relevant surfaces
662
- - `apps/conversions/abstract_models.py` — append-only conversion event model; lifecycle changes are modeled as follow-up rows.
663
- - `apps/conversions/outbox.py` — async publish/retry surface; payload shape may affect erasure semantics.
664
- - `apps/order/models.py` — raw guest email appears to live on the order side, not in conversion events.
665
-
666
- ## Agent hypotheses
667
- - Erasure semantics may need to cover both mutable raw PII and append-only pseudonymous digests.
668
- Confidence: high; supported by model fields and schema comments.
669
- - Outbox purge/replay behavior may be a scope pressure because retries can outlive the original conversion write.
670
- Confidence: medium; verify worker idempotency before scoping implementation.
671
-
672
- ## Scope corrections
673
- - No `guest_session_id` column was found in the inspected conversion models; scope may need to use the actual guest attribution identifiers.
674
- ```
675
-
676
- Example `recon_digest` — single-path case (low ambiguity):
677
-
678
- ```text
679
- Code recon
680
-
681
- Repo signals:
682
- - `apps/conversions/abstract_models.py` — append-only conversion events.
683
- - `apps/conversions/outbox.py` — async publish/retry lifecycle.
684
- - `apps/order/models.py` — raw guest email surface.
685
-
686
- Constraint:
687
- - Erasure likely needs to handle mutable raw PII separately from pseudonymous conversion digests.
688
-
689
- Scope correction:
690
- - I did not find `guest_session_id` in the inspected models.
691
-
692
- Pulse: Reasoning Readiness ~55% · Context Debt 45% (initial ask + code recon)
693
-
694
- Next: attach PRDs/tickets if they should shape scope, or `proceed` to continue.
695
- ```
696
-
697
- Example `recon_digest` — ambiguity case (multiple plausible interpretations):
698
-
699
- 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`).
700
-
701
- ```text
702
- Code recon
703
-
704
- Repo signals:
705
- - `GatewayForm` already supports "create account before checkout," but
706
- redirects away from checkout to `customer:register`. There is no inline
707
- or post-order account path today.
708
- - Guest checkout is already wired through order placement:
709
- `CheckoutSessionData.set_guest_email()`, `AbstractOrder.guest_email`, and
710
- `build_submission()` preserve guest identity.
711
- - `RegisterUserMixin` is the reusable account-creation surface:
712
- user creation, `user_registered`, login, and registration email.
713
- - `OrderPlacementMixin` and `post_checkout` are the clean hooks for
714
- creating or claiming an account at order placement.
715
-
716
- Constraint:
717
- - Oscar's dynamic class loading via `get_class()` is the extension
718
- pattern here. Implement with subclass-overridable views/mixins, not
719
- monkey-patches.
720
-
721
- Ambiguity to resolve:
722
- "Join while booking" maps to two plausible features.
723
-
724
- 1. Inline registration at checkout
725
- Let new customers register on the checkout page itself instead of
726
- being redirected to `/accounts/register/`.
727
-
728
- 2. Post-order account creation — recommended
729
- Let guests place the order as today, then claim the order by
730
- setting a password on the thank-you page. Preserves guest checkout
731
- and fits Oscar's `OrderPlacementMixin` / `post_checkout` hooks.
732
-
733
- Pulse: Reasoning Readiness ~35% · Context Debt 65% (scope not locked yet)
734
-
735
- Next: reply `2` for the recommended post-order path, `1` for inline
736
- registration, or describe a different intent. Reply `pause` to stop here.
737
- ```
738
-
739
- Notes on the ambiguity-case shape:
740
- - **"Repo signals"** (not "Found" or "Key surfaces") signals these are the evidence behind the recommendation.
741
- - **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.
742
- - **`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.
743
- - **The pulse line uses the user-facing label**, never the raw tier identifier.
744
-
745
- Example `recon_digest` — Capability Boundary Check (feature spans systems not in this repo):
746
-
747
- 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.
748
-
749
- ```text
750
- Code recon
751
-
752
- Action needed
753
-
754
- This feature likely spans another repo or service.
755
- Add the backend/API context, or choose a narrower scope.
756
-
757
- Repo boundary:
758
- - This repo contains the checkout UI and guest checkout flow.
759
- - I found no backend account-creation endpoint, user/order linking
760
- mutation, email job, or migration layer.
761
- - So the full "join while booking" feature likely spans this repo plus
762
- an API/backend service.
763
-
764
- Can build here:
765
- - Checkout/thank-you page UI
766
- - Password capture or account-claim form
767
- - API client integration point
768
- - Mocked frontend tests
769
- - Empty/error/success states
770
-
771
- Needs outside context:
772
- - Endpoint that creates or claims the account
773
- - Contract for linking a guest order to a user
774
- - Auth/session behavior after claim
775
- - Email/verification behavior, if required
776
-
777
- Scoping inferred: contract-first (default for unsettled API)
778
-
779
- This repo can build: UI integration, API client surface, mocked tests
780
- This repo cannot build: account-creation endpoint, order-linking, email job
781
- Considerations will be scoped to what this repo can ship.
782
-
783
- Pulse: Reasoning Readiness ~30% · Context Debt 70% (repo boundary unresolved)
784
-
785
- Continuing to problem statement. You can reshape scope there in plain
786
- English (e.g. "frontend-only", "add the backend service contract",
787
- or paste API docs to widen the recon).
788
- ```
789
-
790
- Notes on the boundary-check shape:
791
- - **No pause.** Surface the boundary as compact info inside the recon digest, then proceed to `generate_considerations`. The user's first gate is the problem statement (Step 5) where they can reshape scope in plain English. Pausing here was load-bearing in the old SKILL, but it gated FTUE users behind a 1/2/3 menu before they'd seen any product output. The boundary information is preserved — both in user-facing recon (the "Scoping inferred:" block) and in the `codebase_context_packet` that feeds downstream MCP calls.
792
- - **"Scoping inferred:" not "How should I scope this?"** — the agent makes the default narrowing (contract-first when API unsettled; repo-side-only when the missing half is clearly out-of-tree) and names what it picked. The user corrects at Step 5 if it was wrong.
793
- - **"This repo can build:" + "This repo cannot build:"** are paired one-liners — they document the IN/OUT split so the inferred scoping is auditable. Keep them compact (one line each); the full lists live in `codebase_context_packet`.
794
- - **Default narrowing logic:** if the user's ask names a backend/API endpoint, choose **contract-first**. If the user's ask is clearly UI/UX-shaped or the missing systems are obviously out-of-tree (mobile app, separate billing service), choose **repo-side only**. If ambiguous, default to **contract-first** — it preserves more of the user's intent in the downstream artifacts than narrowing to repo-side does.
795
- - **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`.
796
- - **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.
797
-
798
- ##### 3.2 — Surface the digest and continue
799
-
800
- 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.
801
-
802
- Pause only if:
803
- - recon contradicts the user's stated scope,
804
- - there are multiple plausible implementation areas and choosing wrong would waste work (use the ambiguity-case `recon_digest` shape above),
805
- - a legal/product/business constraint is required before generation,
806
- - the user explicitly asked to review recon before continuing.
807
-
808
- **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.
809
-
810
- 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.
811
-
812
- **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.
638
+ #### Step 3 — Code reconnaissance moved (no step here)
813
639
 
814
- ##### 3.3 Compose augmented `raw_input`
815
-
816
- Compose the augmented `raw_input` for Step 4 from:
817
- - the user's original problem (verbatim, top)
818
- - the full `codebase_context_packet`, under `--- Codebase context packet ---`
819
- - any user correction or added constraint from code recon
820
-
821
- Do not pass unsynthesized `raw_recon_notes` as the primary planning input. Step 3 is the difference between generic considerations and considerations grounded in actual code, patterns, risks, and open questions. Keep `raw_recon_notes` internally for auditability; pass the packet downstream for planning.
822
-
823
- ##### 3.4 — Collect the `sources` array
824
-
825
- Collect the file paths you actually read and consider load-bearing for this problem — exactly as they appear in the repo (e.g. `"apps/checkout/views.py"`, not `"./apps/checkout/views.py"` or absolute paths). This list is passed alongside `raw_input` to `generate_considerations`, `generate_problem_statement`, `query_knowledge_graph`, context pulses, and `generate_build_brief` so the API can anchor priorContext consistently.
826
-
827
- Keep the list focused. 5–10 is the sweet spot; >20 dilutes the KG signal.
640
+ > **Relocated 2026-06-11 (context-at-create).** Recon no longer runs before sub-problem
641
+ > generation — it runs AFTER the user locks the problem frame, as **Step 5.7**, so the first
642
+ > product output (sub-problems + frame) lands seconds after the Job gate instead of waiting on
643
+ > repo reads. Step 4 generates sub-problems from the user's ask alone; grounding arrives at
644
+ > discovery via the `additional_context` persisted at create. Nothing to do here — continue to
645
+ > Step 3.5.
828
646
 
829
647
  #### Step 3.5 — Stage knowledge sources (PRDs / tickets / transcripts / etc.)
830
648
 
831
- 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.
832
-
833
- ##### 3.5.1 — Prompt the user only when useful
834
-
835
- 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:
836
-
837
- - the ask is ambiguous or cross-functional,
838
- - context-pulse / Reference Grounding is low,
839
- - the user mentioned a PRD, ticket, design, chat, customer request, or meeting,
840
- - the feature has legal, privacy, billing, permissions, enterprise, analytics, migration, or compliance constraints,
841
- - code recon found implementation surfaces but not product intent.
842
-
843
- 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":
844
-
845
- ```text
846
- Optional: add non-code context before scope generation.
847
-
848
- Because this touches {constraint}, PRDs, tickets, designs, incidents, or
849
- customer requests may change what we prioritize.
850
-
851
- Reply `go` to continue with code context only.
852
- Or paste files/text/URLs to attach context first.
853
- Reply `pause` to stop here.
854
- ```
649
+ Code grounding happens silently after the frame locks (Step 5.7). 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.
855
650
 
856
- 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`.
651
+ ##### 3.5.1 Reactive only do NOT prompt for non-code context
857
652
 
858
- 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.
653
+ **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.**
859
654
 
860
- If none of the triggers apply, do **not** block. Print a non-blocking line and proceed:
861
-
862
- > Proceeding with codebase context only. Paste a PRD/ticket anytime before discovery if it should shape the scope.
655
+ 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.
863
656
 
864
657
  ##### 3.5.2 — Read the content
865
658
 
@@ -937,54 +730,14 @@ If the user says "skip" / "none" / "later", proceed silently to Step 4. Do NOT p
937
730
 
938
731
  The user can always come back later with `/ritual context-pulse <exploration>` to see the current Reference Grounding score, OR drag refs in mid-flow (e.g. at Step 8 if the agentic run surfaces a question that a PRD would have answered).
939
732
 
940
- #### Step 3.9 — Classify the work item + pick the lead persona
941
-
942
- Before generating sub-problems, settle **what job this is** and **whose lens leads it** — both shape
943
- everything downstream, so they come first. **You** classify the job (you have the repo open — you're the
944
- best-informed classifier, and doing it here saves a backend LLM call); the server returns the lenses.
945
-
946
- 1. **Classify the request** into ONE development work-item slug, using the user's raw ask + your code
947
- recon:
948
-
949
- ```text
950
- understand-codebase-area · design-technical-approach · create-implementation-plan ·
951
- build-frontend-feature · build-backend-service · integrate-api · create-docs-site ·
952
- refactor-code · debug-production-issue · improve-performance · add-tests · prepare-release
953
- ```
733
+ #### Step 3.9 — Work item settled at the Job gate (no step here)
954
734
 
955
- (Use `build-feature` only when the ask is a generic build that none of the specific jobs fit.) Pick the
956
- single best match e.g. "add OAuth to the dashboard" → `build-backend-service`; "the checkout page is
957
- slow" `improve-performance`; "clean up the payments module" `refactor-code`.
958
-
959
- 2. **Call `mcp__ritual__work_item`** with that `jtbd` (and `entry_use_case` if known). It returns
960
- `{ workItemLabel, deliverableTemplate, recommended, options: [{ persona, label, whenToChoose }] }`
961
- deterministic, no LLM, already biased by the user's `ritual init` persona.
962
-
963
- 3. **Present the work item + lens options** as a `(label + description)` bottom-drawer choice picker
964
- (same shape as discovery picks, per `references/cli-output-contract.md`), recommended lens first and
965
- marked:
966
-
967
- ```text
968
- This looks like: Build backend service / API → Service Build Brief
969
- Who's leading it? (recommended: Backend Developer)
970
-
971
- 1. Backend Developer — Best when you care about API contracts, data, transactions, scaling. ← recommended
972
- 2. Developer — Best when you care about feasibility, implementation correctness, shippability.
973
- 3. Eng Lead — Best when you care about technical approach, risk, sequencing, review.
974
-
975
- Reply `use` to lead as Backend Developer, a number to switch, or name a lens.
976
- ```
977
-
978
- 4. **Default = the recommended lens.** An ambiguous reply (`use`/`ok`/`go`) accepts it. If the user says
979
- the *work item* is wrong ("no, this is a refactor"), re-classify and call `work_item` again. If they
980
- switch the *lens*, that's a change → run the change pre-flight (`references/change-preflight.md`) to
981
- confirm before adopting it.
982
-
983
- 5. **Remember the chosen `persona` slug** — you pass it through to `create_exploration` as `lead_persona`
984
- at Step 6. (It also carries into the generation prompts once persona-aware generation ships; for now
985
- it's persisted + surfaced.)
986
-
987
- Keep this light — one drawer, recommended pre-selected; most users accept. Don't belabour it.
735
+ > **Removed 2026-06-11 (JTBD-first entry).** Classification moved to the front of the flow the
736
+ > Job gate at Step 0.7 (server-side `classify_work_item`, user-confirmed). The lead-persona PICKER
737
+ > that used to live here is gone with it: persona is no longer a user choice. The server resolves
738
+ > the job's full persona set (lead + contributors, weighted) and guarantees balanced representation
739
+ > in what it generates discovery questions first. Nothing to render and nothing to ask here;
740
+ > continue to Step 4 with the `jtbd` confirmed at Step 0.7.
988
741
 
989
742
  #### Step 4 — Generate sub-problems
990
743
 
@@ -992,14 +745,12 @@ Keep this light — one drawer, recommended pre-selected; most users accept. Don
992
745
 
993
746
  Call `mcp__ritual__generate_considerations` with:
994
747
  - `workspace_id`
995
- - `raw_input` (the user's problem + the Step 3 `codebase_context_packet` + any reference context, concatenated as described above)
748
+ - `raw_input` the user's problem/ask, **verbatim** (plus any reference context the user spontaneously supplied). **Recon does NOT feed this call (2026-06-11, context-at-create):** sub-problems are deliberately generated from the ask alone so the first product output lands fast; repo grounding enters at Step 5.7 and reaches discovery via the persisted `additional_context`.
996
749
  - `template_id` — **OPTIONAL.** Per Step 2 (server-side template resolution), the agent does NOT pick a template_id. Omit this field unless the user explicitly passed `--template-id` on the CLI; the server resolves the right template from `user.persona` → `workspace.defaultTemplateId` → system default and uses the same resolution chain `create_exploration` will use at Step 6. Passing it explicitly only matters when overriding the default.
997
- - `sources` (the file path list from Step 3 step 7 file-path strings only, e.g. `["apps/checkout/views.py", ...]`)
750
+ - `sources` — **OMIT** (recon hasn't run yet; it happens at Step 5.7 after the frame locks).
998
751
 
999
752
  LLM call, ~5–10s. Returns 5–6 sub-problems — different framing axes the system should investigate. Track each one as `{ text, version: 1 }` in your working memory.
1000
753
 
1001
- The coding agent's packet is context, not authority. Do not pre-rank or collapse the generated sub-problems based only on the agent hypotheses. Let MCP/template/KG output determine the candidate considerations; use the packet to make them specific, evidenced, and grounded.
1002
-
1003
754
  **If the response includes `kg_context_used` with `implementationCount > 0`:** surface this to the user BEFORE presenting the considerations. It's the visible signal that prior shipped work shaped this draft.
1004
755
 
1005
756
  > Reading the codebase I overlapped with 3 prior Ritual explorations on these files:
@@ -1017,7 +768,7 @@ If `implementationCount === 0`: don't mention the KG check (silent — would jus
1017
768
 
1018
769
  ```text
1019
770
  Ritual build
1020
- Context ● Scope ○ Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
771
+ Job ● Scope ○ Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1021
772
 
1022
773
  Solving for these sub-problems
1023
774
 
@@ -1127,11 +878,242 @@ When the user locks the frame, store the final text as `problem_statement` for S
1127
878
 
1128
879
  **Pulse (Step 5 done):** Emit a pulse — feature clarity just jumped. Compute per `/ritual context-pulse` § Step CP3. Render full if this crosses Raw ask → Under-specified, else compact. Translate raw tier labels into user-facing copy per `references/cli-output-contract.md` § Pulse tier labels — never expose `RAW_ASK` / `UNDER_SPECIFIED` / etc. directly.
1129
880
 
881
+ #### Step 5.7 — Ground the exploration (silent recon — runs AFTER the frame locks)
882
+
883
+ **Skip only if the user explicitly asks ("just generate, don't read the code") OR if you're operating outside a codebase context.**
884
+
885
+ **When this runs (relocated 2026-06-11, context-at-create):** AFTER the user locks the problem frame at Step 5 and BEFORE `create_exploration` at Step 6 — the natural "creating your exploration…" beat, so the user never waits on repo reads before seeing product output. Sub-problems (Step 4) were deliberately generated from the ask alone; THIS step is where grounding enters: the `codebase_context_packet` you build here is passed to `create_exploration` as `additional_context`, persisted on the exploration, and injected by the server into discovery-question generation (the questions surface the most important tradeoffs the context implies) and the build-brief fallback. The goal is not to show the user what you found; the goal is to ground downstream generation.
886
+
887
+ **Capability Boundary Check (load-bearing):** If recon detects a mismatch between the user's ask and what THIS repo can actually implement — typically because the feature spans systems (backend service, mobile app, billing provider, email worker, schema migrations) that aren't present in the current checkout — DO NOT invent the missing systems and DO NOT continue as if the repo is complete. Apply the boundary heads-up rule in § 5.7.1 below (one line, no pause) before creating the exploration. Frame the missing half as a normal architecture boundary, not a failure: *"This repo looks like the frontend side of a larger feature,"* not *"I could not find backend dependencies."* The user has not done anything wrong; the agent is asking how to scope the work.
888
+
889
+ Common boundary mismatches to detect:
890
+
891
+ - Full-stack feature ask + frontend-only repo (UI present, no API/service code)
892
+ - Mobile feature ask + no API client contract or backend
893
+ - Billing/payments feature + no payment service / subscription code
894
+ - Email/notification feature + no worker / job / email-provider integration
895
+ - Auth/session feature + no user mutation / session backend
896
+ - Data/analytics feature + no schema, migration, or storage layer
897
+
898
+ ##### 5.7.0 — Check for a pre-build context seed
899
+
900
+ Before doing fresh recon, check whether the user already seeded one via `/ritual context-pulse`. Glob for `CONTEXT-*.md` at the repo root.
901
+
902
+ If a `CONTEXT-<slug>.md` is found AND its `## The ask` section close-matches the current `raw_input`:
903
+
904
+ - **Use it to seed `codebase_context_packet`.** Parse the file's `## Candidate files` list — those become the seed for `sources[]`. Parse `## Prior KG context` as evidence inside the packet, not as final prioritization.
905
+ - **Skip fresh recon** unless the seed is stale or obviously incomplete. If you skip fresh recon, still normalize the seed into the packet structure below before calling MCP tools.
906
+ - **Surface a compact note**:
907
+ > Code recon
908
+ > Found `CONTEXT-<slug>.md` from `/ritual context-pulse`.
909
+ > Using {N} candidate files + {M} related prior exploration{s} as the recon base. Override with `recon: refresh`.
910
+ - Proceed directly to 5.7.2.
911
+
912
+ If no seed file is found, OR the seed's `## The ask` doesn't match the current `raw_input`, do fresh recon. For mismatch, mention the ignored seed in one line and do not delete it.
913
+
914
+ ##### 5.7.1 — Fresh recon
915
+
916
+ 1. **Read the README + top-level project structure.** Use `ls` / Glob to see top-level files. Identify the language, framework, key directories, and likely entry points.
917
+
918
+ 2. **Glob for relevance.** Derive patterns from the user's problem. Examples:
919
+ - User says "auth flow" → `**/auth/**`, `**/login*`, `**/user*`, `**/session*`
920
+ - User says "checkout" → `**/checkout/**`, `**/cart/**`, `**/order/**`, `**/payment*`
921
+ - User says "notifications" → `**/notif*`, `**/email/**`, `**/sms/**`, `**/push/**`
922
+ Cap at ~15 hits per pattern.
923
+
924
+ 3. **Skim 3–5 most-relevant files.** For each, read the first ~100 lines + scan for class/function names. Triangulate whether the behavior lives there or calls into another area.
925
+
926
+ 4. **Build three recon artifacts.**
927
+
928
+ A. `raw_recon_notes` — internal evidence only
929
+ - files read and why they were selected
930
+ - symbols/classes/functions inspected
931
+ - relevant comments, schema details, tests, migrations, and config
932
+ - KG hits, prior deferrals, and prior implementation references
933
+ - uncertain observations, false leads, and things not found
934
+ - do **not** show this by default and do **not** pass it as the main MCP planning input
935
+
936
+ B. `codebase_context_packet` — downstream planning input
937
+ - this is the synthesized artifact passed into `raw_input`, context pulses, and any MCP field named `recon_context`
938
+ - it helps MCP understand what the coding agent observed locally without deciding the final considerations itself
939
+ - separate factual observations from agent hypotheses
940
+ - include confidence levels for hypotheses
941
+ - use neutral labels like `agent_observed_scope_pressure` or `candidate_scope_pressure`, not `priority_considerations`
942
+ - never present the packet as authoritative; MCP/tooling decides final sub-problems, recommendations, and scope
943
+
944
+ C. `recon_digest` — **internal-only by default; NOT surfaced to the user.** Recon
945
+ is silent plumbing at the lock→create boundary: we do NOT dump repo signals /
946
+ constraints / a recon summary back to the user. Keep a compact digest in
947
+ working memory for your own use (and to render ONLY if the user explicitly
948
+ asks "what did you find?"), but by default show nothing — the only render is
949
+ the one-line boundary heads-up (§ 5.7.1) on a hard capability mismatch. The
950
+ `codebase_context_packet` feeds `create_exploration.additional_context`
951
+ silently.
952
+ - keep it tight if ever shown: key surfaces, hard constraints, scope corrections
953
+ - never list every file read; never quote non-load-bearing comments
954
+
955
+ `codebase_context_packet` structure:
956
+
957
+ ```markdown
958
+ --- Codebase context packet ---
959
+
960
+ ## User intent
961
+ {verbatim or lightly normalized ask}
962
+
963
+ ## Observed relevant surfaces
964
+ - `path` — observed role in this feature or constraint
965
+ - `path` — observed extension point, lifecycle, model, or integration seam
966
+
967
+ ## Evidence
968
+ - `path:symbol` — factual observation from code
969
+ - Prior Ritual signal: {exploration / PR / RB / deferral}, if available
970
+ - Missing or not-found evidence when it corrects the user's framing
971
+
972
+ ## Agent hypotheses
973
+ - This may make {candidate area} important because {evidence-backed reason}
974
+ Confidence: low / medium / high
975
+
976
+ ## Agent-observed scope pressure
977
+ - Privacy / lifecycle / migration / compatibility / async / ownership / testing risk
978
+ - Only include pressure that intersects with the feature intent and code evidence
979
+
980
+ ## Scope corrections
981
+ - The ask says X, but the code suggests Y
982
+ - Missing fields, renamed concepts, or assumptions the code contradicts
983
+
984
+ ## Open questions for discovery
985
+ - Questions the code cannot answer and the user/Ritual exploration should resolve
986
+ ```
987
+
988
+ Example `codebase_context_packet` excerpt:
989
+
990
+ ```markdown
991
+ ## Observed relevant surfaces
992
+ - `apps/conversions/abstract_models.py` — append-only conversion event model; lifecycle changes are modeled as follow-up rows.
993
+ - `apps/conversions/outbox.py` — async publish/retry surface; payload shape may affect erasure semantics.
994
+ - `apps/order/models.py` — raw guest email appears to live on the order side, not in conversion events.
995
+
996
+ ## Agent hypotheses
997
+ - Erasure semantics may need to cover both mutable raw PII and append-only pseudonymous digests.
998
+ Confidence: high; supported by model fields and schema comments.
999
+ - Outbox purge/replay behavior may be a scope pressure because retries can outlive the original conversion write.
1000
+ Confidence: medium; verify worker idempotency before scoping implementation.
1001
+
1002
+ ## Scope corrections
1003
+ - No `guest_session_id` column was found in the inspected conversion models; scope may need to use the actual guest attribution identifiers.
1004
+ ```
1005
+
1006
+ Example `recon_digest` — single-path case (low ambiguity):
1007
+
1008
+ ```text
1009
+ Code recon
1010
+
1011
+ Repo signals:
1012
+ - `apps/conversions/abstract_models.py` — append-only conversion events.
1013
+ - `apps/conversions/outbox.py` — async publish/retry lifecycle.
1014
+ - `apps/order/models.py` — raw guest email surface.
1015
+
1016
+ Constraint:
1017
+ - Erasure likely needs to handle mutable raw PII separately from pseudonymous conversion digests.
1018
+
1019
+ Scope correction:
1020
+ - I did not find `guest_session_id` in the inspected models.
1021
+
1022
+ Pulse: Reasoning Readiness ~55% · Context Debt 45% · +12% (initial ask + code recon)
1023
+
1024
+ (lift bridge — renders right above the next action) Most of the gap left is
1025
+ unsettled design decisions — that's exactly what the next step, discovery, resolves.
1026
+
1027
+ Next: attach PRDs/tickets if they should shape scope, or `proceed` to continue.
1028
+ ```
1029
+
1030
+ **No explore-directions picker here (removed 2026-06-11).** The problem frame is already
1031
+ locked — direction ambiguity was resolved by the user's own framing at Step 5. If recon
1032
+ contradicts the locked frame outright, use the boundary heads-up rule below; never re-open
1033
+ a picker.
1034
+
1035
+ Capability Boundary Check (feature spans systems not in this repo) — **internal/packet-only; NOT displayed:**
1036
+
1037
+ 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`**, then surface exactly ONE heads-up line (no pause — see below). The persisted packet drives discovery-question generation to probe the boundary; the locked frame stays as-is unless the user reacts. 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.
1038
+
1039
+ ```text
1040
+ Code recon
1041
+
1042
+ Action needed
1043
+
1044
+ This feature likely spans another repo or service.
1045
+ Add the backend/API context, or choose a narrower scope.
1046
+
1047
+ Repo boundary:
1048
+ - This repo contains the checkout UI and guest checkout flow.
1049
+ - I found no backend account-creation endpoint, user/order linking
1050
+ mutation, email job, or migration layer.
1051
+ - So the full "join while booking" feature likely spans this repo plus
1052
+ an API/backend service.
1053
+
1054
+ Can build here:
1055
+ - Checkout/thank-you page UI
1056
+ - Password capture or account-claim form
1057
+ - API client integration point
1058
+ - Mocked frontend tests
1059
+ - Empty/error/success states
1060
+
1061
+ Needs outside context:
1062
+ - Endpoint that creates or claims the account
1063
+ - Contract for linking a guest order to a user
1064
+ - Auth/session behavior after claim
1065
+ - Email/verification behavior, if required
1066
+
1067
+ Scoping inferred: contract-first (default for unsettled API)
1068
+
1069
+ This repo can build: UI integration, API client surface, mocked tests
1070
+ This repo cannot build: account-creation endpoint, order-linking, email job
1071
+ Considerations will be scoped to what this repo can ship.
1072
+
1073
+ Pulse: Reasoning Readiness ~30% · Context Debt 70% (repo boundary unresolved)
1074
+
1075
+ (lift bridge) The plan isn't grounded in your code yet — scoping to what this
1076
+ repo can actually ship is what the next step settles.
1077
+
1078
+ ```
1079
+
1080
+ With the frame already locked, the user-facing output of a boundary hit is ONE line, no pause:
1081
+
1082
+ > Heads-up: this repo covers {the in-repo half} — I've scoped the exploration's context
1083
+ > accordingly. Say `re-frame` to widen the scope, or just continue.
1084
+
1085
+ Notes on the boundary-check shape:
1086
+ - **No pause.** One heads-up line, then continue to Step 6. The boundary information is preserved in the `codebase_context_packet` (persisted as `additional_context`), where discovery-question generation reads it; the user can say `re-frame` to reopen the frame, and discovery itself will probe the boundary.
1087
+ - **"Scoping inferred:" not "How should I scope this?"** — the agent makes the default narrowing (contract-first when API unsettled; repo-side-only when the missing half is clearly out-of-tree) and names what it picked. The user corrects at Step 5 if it was wrong.
1088
+ - **"This repo can build:" + "This repo cannot build:"** are paired one-liners — they document the IN/OUT split so the inferred scoping is auditable. Keep them compact (one line each); the full lists live in `codebase_context_packet`.
1089
+ - **Default narrowing logic:** if the user's ask names a backend/API endpoint, choose **contract-first**. If the user's ask is clearly UI/UX-shaped or the missing systems are obviously out-of-tree (mobile app, separate billing service), choose **repo-side only**. If ambiguous, default to **contract-first** — it preserves more of the user's intent in the downstream artifacts than narrowing to repo-side does.
1090
+ - **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`.
1091
+ - **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 discovery generation and the build brief see it. None of these labels should appear in user-facing copy.
1092
+
1093
+ ##### 5.7.2 — Recon is silent
1094
+
1095
+ **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 at the lock→create boundary. The packet feeds `create_exploration.additional_context` (Step 6); the user sees nothing here.
1096
+
1097
+ **There is no explore-directions picker (removed 2026-06-11)** — the frame the user just locked IS the direction. For a crisp single-direction repo read: render nothing and go straight to Step 6.
1098
+
1099
+ **Capability boundary detection does NOT pause.** When recon shows the feature spans systems not in this repo, fold the boundary + the inferred default scope into the `codebase_context_packet` (see § 5.7.1 internal classification), pick the default per the "Default narrowing logic" rule, surface the ONE-line heads-up from § 5.7.1, and proceed to Step 6.
1100
+
1101
+ If the user explicitly asks "what did you find?", you may show a tight digest then — otherwise stay silent.
1102
+
1103
+ **Pulse (recon 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.
1104
+
1105
+ ##### 5.7.3 — Collect the `sources` array
1106
+
1107
+ Collect the file paths you actually read and consider load-bearing for this problem — exactly as they appear in the repo (e.g. `"apps/checkout/views.py"`, not `"./apps/checkout/views.py"` or absolute paths). This list is passed to `create_exploration` (Step 6) — persisted on the exploration so the answer engine, context pulses, and `generate_build_brief` anchor priorContext consistently without you re-passing it.
1108
+
1109
+ Keep the list focused. 5–10 is the sweet spot; >20 dilutes the KG signal.
1110
+
1111
+
1130
1112
  #### Step 6 — Create the exploration
1131
1113
 
1132
1114
  Generate a short name (≤60 chars) from the scope — typically the noun phrase, not the full HMW. E.g. "Reduce T2 customer churn in Q3" → name `T2 churn reduction (Q3)`.
1133
1115
 
1134
- Create the exploration immediately once the frame is locked the work item + lead persona were already settled at Step 3.9, so do not add a *further* confirmation here. If a name is ambiguous, **choose the shortest clear noun phrase and continue without pausing** — the name is editable later and shouldn't become a decision gate. Do NOT rely on "proceed on Enter" or empty input in agent chat (see `references/cli-output-contract.md` § Surface-aware continuation prompts).
1116
+ Run the silent Step 5.7 recon first, then create the exploration the job was already confirmed at the Step 0.7 Job gate, so do not add a *further* confirmation here. If a name is ambiguous, **choose the shortest clear noun phrase and continue without pausing** — the name is editable later and shouldn't become a decision gate. Do NOT rely on "proceed on Enter" or empty input in agent chat (see `references/cli-output-contract.md` § Surface-aware continuation prompts).
1135
1117
 
1136
1118
  User-visible before the call, if needed:
1137
1119
 
@@ -1145,21 +1127,23 @@ Call `mcp__ritual__create_exploration` with:
1145
1127
  - `problem_statement` (the scope from Step 5)
1146
1128
  - `template_id` — **OPTIONAL.** Per Step 2, omit by default. The server resolves from `explicit dto.templateId → workspace.defaultTemplateId → user.persona → first SYSTEM template`, then forks the resolved template into a per-exploration Template row atomically inside this same `create_exploration` request. Pass `template_id` ONLY when the user explicitly overrides on the CLI (`/ritual build --template-id <id>`). If you passed `template_id` to Step 4's `generate_considerations`, pass the same value here so the LLM prompt context the considerations were generated under matches the exploration's stamped template. Do NOT read `.ritual/config.json` or invent a `template_id` from persona — the server does the resolution.
1147
1129
  - `agentic: false` — **do NOT** pass `agentic: true`. We want explicit per-step control so the user gets to pick discovery questions in Step 7. Auto-agentic skips that.
1148
- - `jtbd` — **REQUIRED for `/ritual build`.** The work-item slug you classified at **Step 3.9** (e.g. `'build-backend-service'`, `'refactor-code'`, or `'build-feature'` for a generic build). Tags the exploration's job-to-be-done so the workflow surfaces the build-brief code-plan implement PR deliverable phase across every surface (the Spark panel, etc.), not the generic produce-deliverable flow. Omit only if this is a non-build exploration (defaults to `produce-deliverable`).
1149
- - `lead_persona` — the lens slug the user chose at **Step 3.9** (e.g. `'backend-developer'`). Pass the chosen `persona` from `work_item`. Omit only if Step 3.9 was skipped — the server then resolves the jtbd's canonical lens. Unknown slugs are ignored server-side.
1130
+ - `additional_context` — the full `codebase_context_packet` from Step 5.7 (omit only if recon was skipped). Persisted on the exploration; the server injects it into discovery-question generation as evidence (the questions cover the important tradeoffs it implies) and uses it as the build-brief recon fallback so it survives `/ritual resume`.
1131
+ - `sources` — the file-path list from Step 5.7.3.
1132
+ - `jtbd` — **REQUIRED for `/ritual build`.** The slug the user CONFIRMED at the **Step 0.7 Job gate** (e.g. `'build-backend-service'`, `'refactor-code'`). Tags the exploration's job-to-be-done so the workflow surfaces the build-brief → code-plan → implement → PR deliverable phase across every surface (the Spark panel, etc.), not the generic produce-deliverable flow. Omit only if this is a non-build exploration (defaults to `produce-deliverable`).
1133
+ - `lead_persona` — **OMIT (2026-06-11, JTBD-first entry).** Persona is no longer a user pick: the server resolves the job's canonical lead and owns balanced persona REPRESENTATION across the job's full persona set (lead + contributors, weighted) in generation. Do not call `work_item` to pick a lens and do not pass this field.
1150
1134
 
1151
1135
  Store `exploration_id`. Move the progress header from Scope to Discovery:
1152
1136
 
1153
1137
  ```text
1154
1138
  Ritual build
1155
- Context ✓ Scope ● Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1139
+ Job ✓ Scope ● Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1156
1140
 
1157
- Exploration created. Track progress at https://app.ritualapp.cloud/e/{exploration_id}
1141
+ Exploration created.
1158
1142
 
1159
1143
  Next: generate discovery questions to resolve the implementation trade-offs.
1160
1144
  ```
1161
1145
 
1162
- ##### 6.1 — Promote the pre-build seed (if one was consumed in Step 3.0)
1146
+ ##### 6.1 — Promote the pre-build seed (if one was consumed in Step 5.7.0)
1163
1147
 
1164
1148
  If Step 3.0 consumed a `CONTEXT-<slug>.md` seed file, promote it into the exploration's artifact trail now that an exploration id exists. Move + rename the file from `CONTEXT-<slug>.md` to `.ritual/exploration-notes/<exploration-id>.md` using the Bash tool:
1165
1149
 
@@ -1213,21 +1197,21 @@ Longest phase because generation is async + the user picks per-Area. (Internally
1213
1197
  1. Call `mcp__ritual__suggest_discovery_questions(exploration_id)` (Step 7.1) — no user input needed; just kick it off.
1214
1198
  2. Poll `mcp__ritual__get_discovery_state(exploration_id)` until `ready: true` (Step 7.2).
1215
1199
  3. Render the **Area rail + Area 1's questions together** and walk Area-by-Area per § 7.3.1 (the rail orients; a rail with NO questions under it — a bare index — is the failure mode).
1216
- 4. `**[LITE AUTO — no pause; auto-pick the recommended default]**` — the user picks questions across Areas (**floor: 6 to run; aim for 15–20; no cap**), or types `accept shortlist`.
1200
+ 4. `**[LITE AUTO — no pause; auto-pick the recommended default]**` — the suggested-12 landing (§ 7.3.1): the user replies `proceed` (commit the 12), `expert` (walk + adjust; floor 6 to run, aim 15–20, no cap), or `pause`.
1217
1201
  5. Commit all picked Areas in ONE `mcp__ritual__accept_discovery_questions_batch` call (Step 7.4) — never one parallel call per Area.
1218
1202
  6. Optionally capture anti-goals (Step 7.5), then proceed to Step 8 and render the *"Reply `run` to continue"* CTA.
1219
1203
 
1220
1204
  **Picking is a deliberate step-through, not a bulk action (load-bearing):** the user going Area by Area and choosing the questions that matter IS the value of discovery — that per-question judgment shapes the whole downstream chain. So **nudge the user to step through and pick**; don't lead with bulk shortcuts.
1221
1205
  - **Nudge to step through.** Walk the user Area-by-Area (drop into Area 1, `next`/`prev`) and invite deliberate picks per Area, with `show more` to expand an Area. The framing is "which of these should we dig into?", not "want all of them?".
1222
1206
  - **Floor (HARD): at least 6 questions** across any Areas — below this, do NOT commit or proceed (tell them how many more to pick and keep them in the picker). There is NO "skip discovery" path — the agentic run needs a real question set to develop answers against. **Good coverage (SOFT): 15–20 questions** — nudge toward it on the Summary, but never block once ≥6. **No upper cap** — picking many (or all) is a legitimate explicit choice, never a default or fallback. (Uncovered scope is handled downstream when recommendations + requirements are generated and audited, so a thin set is the failure mode to prevent.)
1223
- - **The default is the shortlist, never "all."** For a user who doesn't want to step through every Area, **`accept shortlist` (the 6–10 highest-leverage questions)** is the convenience default. An ambiguous reply (`proceed`, `go`, `ok`) at this gate means **accept the shortlist** — never silently accept everything.
1207
+ - **The default is the suggested 12 on screen, never "all."** The landing shows exactly what `proceed` commits. An ambiguous reply (`proceed`, `go`, `ok`) at this gate means **accept the suggested 12 the user is looking at** — never silently accept everything.
1224
1208
  - **Taking all IS allowed — but only as an explicit user choice, never the default or a fallback.** If the user genuinely says "take all" / "all of them", honor it and commit them; that's a legitimate choice, not an error. Just never *offer* "I'll take all" as the default, and never auto-fall-back to it. (Worth mentioning once, not as a gate: every accepted question is answered individually in the agentic run, so accepting all of them across every Area means many more questions to answer and a much longer run — but it's the user's call.)
1225
1209
 
1226
1210
  **Forbidden behaviors:**
1227
1211
 
1228
1212
  - Calling `start_agentic_run` before at least 6 discovery picks have been committed for this exploration (via `accept_discovery_questions_batch`, or `accept_discovery_questions`). There is no skip-discovery exception.
1229
1213
  - Silently auto-picking all generated questions and proceeding to Step 8 — observed in agent output 2026-05-15 as "the engineering-mode default is to run, which skips the per-question picker." There is no such default; the picker is mandatory.
1230
- - **Offering "or I'll default to taking all of them" (or any accept-all fallback), then committing the full set on an ambiguous reply** — observed 2026-06-05 (a `proceed` at this gate → `accept_discovery_questions_batch` with all 68 questions → a ~25-min run the user never chose). Accept-all is a legitimate choice **only when the user explicitly asks for it** — it is NEVER the default you offer, and NEVER the fallback. The default you offer + fall back to is always **`accept shortlist`** (6–10). An ambiguous reply (`proceed`/`go`/`ok`) at the pick gate means **accept the shortlist**, not the full set. Lead by nudging the user to step through Areas and pick deliberately.
1214
+ - **Offering "or I'll default to taking all of them" (or any accept-all fallback), then committing the full set on an ambiguous reply** — observed 2026-06-05 (a `proceed` at this gate → `accept_discovery_questions_batch` with all 68 questions → a ~25-min run the user never chose). Accept-all is a legitimate choice **only when the user explicitly asks for it** — it is NEVER the default you offer, and NEVER the fallback. The default you offer + fall back to is always **the suggested 12 rendered on the landing**. An ambiguous reply (`proceed`/`go`/`ok`) at the pick gate means **accept those 12**, not the full set structurally safe because the 12 are on screen in full.
1231
1215
  - Rendering "Next: run discovery through recommendations / Reply `run` to continue" anywhere in the chat before Step 7.4 has completed.
1232
1216
 
1233
1217
  The picker is **not** a UI suggestion — it's the load-bearing decision gate where the user expresses what to investigate. Skipping it converts the agentic run into an automated "answer everything" pass and erases the user's judgment.
@@ -1238,7 +1222,7 @@ Call `mcp__ritual__suggest_discovery_questions(exploration_id)`. Returns immedia
1238
1222
 
1239
1223
  ```text
1240
1224
  Ritual build
1241
- Context ✓ Scope ● Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1225
+ Job ✓ Scope ● Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1242
1226
 
1243
1227
  Generating discovery questions for each area…
1244
1228
  ```
@@ -1252,11 +1236,11 @@ Loop:
1252
1236
 
1253
1237
  Don't poll faster than every 10 seconds (matches the Spark UI's 10s discovery cadence). Follow the global polling rule above: single `Bash sleep 10` per iteration and a one-line update every ~2 polls (~20s). Polling heartbeats are exempt from the Build rail rule per `references/cli-output-contract.md` § Build progress anchor — does NOT apply to.
1254
1238
 
1255
- ##### 7.3 — Matter-walk picker (Area rail + selected Area's questions → walk with `next`/`prev` → Summary)
1239
+ ##### 7.3 — Question picking: the suggested-12 landing (default) + the expert walk (on request)
1256
1240
 
1257
1241
  The state contains `matters[]`, each with `id`, `name`, and `questions[]`. Internally these are `matter`s; user-facing copy ALWAYS calls them **Areas**.
1258
1242
 
1259
- This MIRRORS the Spark `/discover` picker exactly: Spark shows a **tab bar of all Areas with one tab selected AND that tab's questions already rendered below it**. The CLI does the same in text every render shows a compact **Area rail** (all Areas, the current one marked, with running picked counts) **and, directly beneath it, the current Area's questions**. The user picks questions, then moves between Areas with `next`/`prev`, and finally lands on a **Summary** grouped by Area before committing. Seeing each Area's questions and choosing deliberately IS the value of discovery.
1243
+ **Landing-first (2026-06-12).** The default render is NOT the Area walk it is the **suggested-12 landing**: Ritual's 12 suggested questions across all Areas, listed IN FULL (never truncated), grouped by Area, pre-selected. One word (`proceed`) commits them; `expert` opens the Area-by-Area walk with the 12 already selected (toggle to adjust). The walk MIRRORS the Spark `/discover` picker (Area rail + current Area's questions + Summary before commit) and remains the place to push toward the 15–20 good-coverage range it's just opt-in now instead of mandatory.
1260
1244
 
1261
1245
  The two failure modes this contract prevents:
1262
1246
  - **A bare Area index** — the rail (or a "pick an Area" menu) with **no questions under it**. The rail without its current Area's questions is exactly the removed model; always render the questions inline. (This is the failure d3 caught on 2026-06-07: the agent rendered the Area list alone.)
@@ -1264,14 +1248,14 @@ The two failure modes this contract prevents:
1264
1248
 
1265
1249
  **Turn boundaries (load-bearing — this is a multi-turn walk, not a one-shot render).** Render the rail + **exactly ONE Area's questions per turn**. After rendering, **STOP and end your turn** — wait for the user's reply (`numbers` / `next` / `prev` / `skip` / `done`). Each of `next` / `prev` / `done` produces the **next render in a NEW turn**, never appended to the current message. You already hold every Area's questions from `get_discovery_state` — that is NOT license to render the whole walk or multiple Areas' questions in a single message. The rail lists Area *names + counts* (cheap orientation); only the current Area's *questions* render. One Area → STOP → reply → next Area. The Summary (§ 7.3.3) is likewise its own turn.
1266
1250
 
1267
- ###### 7.3.0 — Compute per-Area recommendations + the global shortlist (internal, not user-facing)
1251
+ ###### 7.3.0 — Compute the suggested 12 + per-Area recommendations (internal, not user-facing)
1268
1252
 
1269
- Three things surface, **none auto-applied**:
1270
- - **(a) The Area rail** — every Area's name + its running picked count. Cheap orientation (names + counts, NOT their questions), shown above the current Area's questions from the very first render. This is the legitimate, always-visible "tab bar" it is NOT the forbidden bare index, *because the current Area's questions always render beneath it*.
1271
- - **(b) The per-Area ★ recommended set** (3–4 questions) — computed for the Area you are currently showing.
1272
- - **(c) The global shortlist** (610 across all Areas) — computed only when the user types `accept shortlist`.
1253
+ Three things are computed up front, **none auto-committed**:
1254
+ - **(a) The suggested 12** — 12 questions TOTAL across all Areas, the landing's content. Selection rubric (a rule, not vibes): start from the server's ranked/recommended flags; guarantee at least one question from every Area that contains a genuinely hard question; fill the rest by leverage, biased toward questions that probe **tradeoffs, constraints, and the scope-pressure/boundary items** the exploration's additional context surfaced. If fewer than 12 questions clear the bar, suggest fewer (floor 6) — never pad to hit the number.
1255
+ - **(b) The Area rail** (expert mode) — every Area's name + its running picked count, shown above the current Area's questions.
1256
+ - **(c) The per-Area ★ recommended set** (34 questions, expert mode) — computed for the Area currently showing.
1273
1257
 
1274
- The user always picks; nothing is auto-committed.
1258
+ The user always confirms; nothing is committed without their reply.
1275
1259
 
1276
1260
  **Per-Area recommended set** (the ★ set, for the Area currently shown):
1277
1261
 
@@ -1280,30 +1264,58 @@ The user always picks; nothing is auto-committed.
1280
1264
  - Area has **4–7 questions**: top 3 are recommended.
1281
1265
  - Area has **8+ questions**: top 4 are recommended.
1282
1266
 
1283
- **Global shortlist** (what `accept shortlist` acceptsavailable from any Area or the Summary):
1267
+ **Legacy token:** `accept shortlist` (the old 6–10 power path) is retired as a displayed option the suggested 12 IS the landing now. If a user types it anywhere, treat it as the landing's `proceed` (commit the suggested 12) and note in one line that the landing already covers it.
1284
1268
 
1285
- - Pick **6–10 questions TOTAL across all Areas**, biased toward questions most likely to change recommendations.
1286
- - Preserve Area diversity by default — at least one question from each Area where the per-Area recommended set was non-empty, unless the scope is clearly concentrated (e.g. one Area dominates the recon evidence).
1287
- - Cap at 10 even when the per-Area recommended sets sum to more. The point of the shortlist is to give the user a clean "the highest-signal triage set across the whole space" — picking 24–32 questions because 8 Areas each have 3–4 recommended brings back the "no triage signal" problem under a new name.
1288
- - If the per-Area recommended sets sum to ≤10, the shortlist IS just the union (no further trimming).
1269
+ ###### 7.3.1 First render: the suggested-12 landing (the default)
1289
1270
 
1290
- Neither set is auto-applied. The user still picks per Area, or uses `accept shortlist` as a power path that bypasses the area-by-area drill.
1271
+ Render ALL 12 suggested questions IN FULL, grouped by Area — never truncate, elide, or "(… N more)" this list; the whole point is that the user reads exactly what one word will commit. Full phase rail on this message (we just entered Discovery).
1291
1272
 
1292
- ###### 7.3.1 — First render: Area rail + Area 1's questions (the walk begins)
1273
+ ```text
1274
+ Ritual build
1275
+ ✓ Job ✓ Scope ● Discovery ○ Recommendations ○ {Deliverable} ○ Implementation (Your agent)
1276
+
1277
+ Discovery questions ready — {M} generated across {N} areas.
1278
+
1279
+ These 12 questions target where this problem is hardest — the tradeoffs,
1280
+ constraints, and unknowns that decide the design. When you proceed, Ritual
1281
+ dispatches its research agents to answer them against this codebase and your
1282
+ sources; those answers become the spine of the {Deliverable}.
1283
+
1284
+ {Area name 1}
1285
+ ✓ 1. {question, full text, wrapped readably}
1286
+ ✓ 2. {question}
1293
1287
 
1294
- Open ON Area 1 with the **rail above and Area 1's questions below it** — never the rail alone. The rail lists every Area (current one marked, picked count per Area); the questions are Area 1's ★ recommended set. Full phase rail on this first message (we just entered Discovery); subsequent Area messages use the in-phase chip.
1288
+ {Area name 2}
1289
+ ✓ 3. {question}
1290
+ ✓ 4. {question}
1291
+
1292
+ {…every suggested question, grouped by Area, all 12 visible…}
1293
+
1294
+ Next: reply `proceed` to run discovery with these 12 (commits the set;
1295
+ the run confirmation follows) · `expert` to review all {M} questions and
1296
+ adjust the selection · `pause` to stop here.
1297
+ ```
1298
+
1299
+ Branch on reply:
1300
+ - **`proceed`** (or an ambiguous `ok`/`go`): commit exactly the 12 on screen via § 7.4's single batch call (grouped per Area), then continue to § 7.5 → Step 8. The ambiguous-reply rule is now structurally safe: what gets accepted is exactly what the user is looking at.
1301
+ - **`expert`**: enter the Area walk below with the suggested 12 **pre-selected** (`picked so far: 12`, ✓ on each suggested row). Numbers TOGGLE in expert mode — typing a selected question's number unselects it.
1302
+ - **`pause`**: stop here; nothing committed.
1303
+
1304
+ ###### 7.3.1b — Expert mode: the Area walk (entered via `expert`)
1305
+
1306
+ Open ON Area 1 with the **rail above and Area 1's questions below it** — never the rail alone. The rail lists every Area (current one marked, picked count per Area); the questions are Area 1's ★ recommended set, with ✓ already on rows that are in the suggested 12. Subsequent Area messages use the in-phase chip. The 15–20 soft nudge lives here: the user arrives with 12 — the walk is where they push toward broader coverage (floor 6 HARD if they unselect).
1295
1307
 
1296
1308
  ```text
1297
1309
  Ritual build
1298
- Context ✓ Scope ● Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1310
+ Job ✓ Scope ● Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1299
1311
 
1300
- Question picking · Area 1 of {N} · {Area name} picked so far: 0
1312
+ Question picking · Area 1 of {N} · {Area name} picked so far: 12
1301
1313
 
1302
1314
  Areas ● {Area name 1} ○ {Area name 2} ○ {Area name 3} ○ {Area name 4} ○ {Area name 5}
1303
1315
  ● current · ✓N after a name = picked in that Area · move with `next` / `prev`
1304
1316
 
1305
- Ritual generated questions across {N} areas for {M} locked sub-problems.
1306
- I'll walk you through each — aim for 15–20 total (6 minimum to run, no cap).
1317
+ Expert mode the suggested 12 are pre-selected (✓). Numbers toggle;
1318
+ aim for 15–20 total (6 minimum to run, no cap).
1307
1319
 
1308
1320
  Showing the {k} most likely to change the plan ({total} in this Area):
1309
1321
 
@@ -1312,19 +1324,21 @@ Showing the {k} most likely to change the plan ({total} in this Area):
1312
1324
  3. {recommended question 3, wrapped readably}
1313
1325
 
1314
1326
  pick numbers (e.g. `1,3`) · `suggested` (these ★) · `add <your question>` · `show more` ({total−k} more)
1315
- walk `next` · `prev` · `skip` · `done` (≥6) · `accept shortlist`
1327
+ walk `next` · `prev` · `skip` · `done` (≥6)
1316
1328
  ```
1317
1329
 
1318
1330
  **Single numbering stream — number the QUESTIONS only; the rail Areas are NOT numbered.** The 2026-05-15 failure numbered Areas AND question previews in one view, so a reply of `5` was ambiguous. Here the rail uses `●`/`○` markers + names (no numbers) and you move it with `next`/`prev` — the only numbered list is the current Area's questions, so a bare number is never ambiguous. Wrap long question text readably. The `picked so far` count, the rail markers/`✓N` counts, and the `Area i of N` breadcrumb all update on every render of the walk.
1319
1331
 
1320
- **Why `accept shortlist`, not `accept recommended`:** "recommended" is ambiguous (per-Area? global?). The picker uses **shortlist** for the global 6–10 power path (§ 7.3.0), keeping a clean vocabulary split: **discovery = `accept shortlist`** (questions), **recommendation review = `proceed`** (Step 9). The ★ marks the per-Area recommended set; `suggested` picks it.
1332
+ **Vocabulary split:** the landing's `proceed` commits the suggested 12 (questions); Step 9's `proceed` continues recommendation review. Inside expert mode, the ★ marks the per-Area recommended set and `suggested` picks it; `accept shortlist`/`accept recommended` are legacy aliases for the landing's `proceed`.
1333
+
1334
+ ###### 7.3.2 — Within an Area (pick → auto-advance)
1321
1335
 
1322
- ###### 7.3.2Within an Area (pick, then move)
1336
+ **Picking IS progress (2026-06-12).** A pick reply (`numbers` or `suggested`) ADVANCES to the next Area never re-render the same Area and wait for `next` (that costs two replies per Area and stalls the walk; observed live: users picked, then were shown the same Area again). `prev` is the way back if they want to adjust; `next` still exists for moving WITHOUT picking.
1323
1337
 
1324
1338
  **Every render in this section keeps the `Areas …` rail line on top** (current Area marked, `✓N` counts updated) — it's omitted from the snippets below only for brevity. Never re-render an Area's questions without the rail above them.
1325
1339
 
1326
- - **`numbers`** (e.g. `1,3` or `1,2,5`): add those questions to the picked set, re-render this Area (rail + questions) with `✓` on the picked rows + the updated `picked so far`, then prompt `next` / `prev` / `done`.
1327
- - **`suggested`**: pick this Area's recommended (★) set in one go.
1340
+ - **`numbers`** (e.g. `1,3` or `1,2,5`): TOGGLE those questions unselected ones join the picked set, already-✓ ones (including pre-selected suggested-12 rows) leave it. Then **ADVANCE: render the NEXT Area** (rail + its questions), opening with a one-line ack of the Area just left — `{Area name}: {n} picked ✓` and the updated `picked so far`. On the LAST Area, a pick advances to the Summary (§ 7.3.3). Do NOT re-render the same Area after a pick; `prev` returns if the user wants to adjust.
1341
+ - **`suggested`**: pick this Area's recommended (★) set in one go — then advance exactly like `numbers`.
1328
1342
  - **`show more`**: reveal the rest, grouped Recommended / More (lazy per-Area expansion — never a global dump):
1329
1343
 
1330
1344
  ```text
@@ -1366,9 +1380,11 @@ Question picking · Summary {T} picked
1366
1380
  ...
1367
1381
 
1368
1382
  {if T < 15} A good set is usually 15–20 — you've picked {T}. Reply an Area
1369
- number to add more, `more` to suggest new Areas, or `commit`.
1370
- {if T ≥ 15} Reply `commit` to run discovery on these {T} questions, an Area
1371
- number to adjust, `more` for new Areas, or `pause` to stop.
1383
+ number to add more, `more` to suggest new Areas, or `commit`
1384
+ (run discovery recommendations).
1385
+ {if T 15} Reply `commit` to run discovery on these {T} questions
1386
+ (answers → recommendations, ~a few minutes), an Area number
1387
+ to adjust, `more` for new Areas, or `pause` to stop.
1372
1388
  ```
1373
1389
 
1374
1390
  **The minimum model — floor 6 HARD, good 15–20 SOFT, no cap:**
@@ -1384,7 +1400,7 @@ Question picking · Summary {T} picked
1384
1400
 
1385
1401
  ###### 7.3.4 — Power paths (available from any Area or the Summary)
1386
1402
 
1387
- - **`accept shortlist`**: accept the 6–10-question global shortlist computed in § 7.3.0 — the fast path for a user who doesn't want to walk every Area. Group those by their owning Area, commit them in ONE `accept_discovery_questions_batch` call (§ 7.4 one entry per Area), and proceed to Step 7.5. Intentionally NOT "top 3–4 of every Area" (which would scale to 24–32 picks and reintroduce the "no triage signal" problem). The shortlist is the quick minimal set; the walk is how a user reaches the 15–20 good-coverage range.
1403
+ - **`accept shortlist`** (legacy alias): treat as the landing's `proceed` commit the suggested 12 via ONE `accept_discovery_questions_batch` call (§ 7.4, one entry per Area) and continue to Step 7.5. The walk is how a user reaches the 15–20 good-coverage range; the suggested 12 is the quick high-signal set.
1388
1404
  - **`show all`**: accepted as a reply but NOT advertised on the CTA line. Expands every Area's questions into one long list. Use only when the user explicitly asks — the per-Area `show more` is the default.
1389
1405
  - **`done`**: jump to the Summary from any Area to review + `commit`.
1390
1406
  - **Below the floor** (fewer than 6 picked on `commit`): do NOT proceed. Reply with how many more are needed and return to the Summary — e.g. *"Pick at least 6 to run discovery — you've picked 3, choose 3 more."* There is no skip path. (6–14 is allowed with the soft nudge; ≥15 is the good-coverage target — see § 7.3.3.)
@@ -1399,7 +1415,7 @@ Question picking · Summary {T} picked
1399
1415
  ###### Legacy alias notes
1400
1416
 
1401
1417
  - `suggest` (legacy per-Area shortcut) is now spelled **`suggested`** — picks the current Area's recommended (★) set. If a user types `suggest` inside an Area, treat it the same.
1402
- - `accept recommended` (legacy global shortcut): at the DISCOVERY stage, if a user types this, treat it as `accept shortlist` and surface a one-line note that the discovery-stage token is `accept shortlist` (questions). (At Step 9 the recommendation-review CTA is `proceed`, not `accept recommended`.)
1418
+ - `accept recommended` (legacy global shortcut): treat as the landing's `proceed` (commit the suggested 12) with a one-line note. (At Step 9 the recommendation-review CTA is `proceed` for continuing review.)
1403
1419
  - `all` (legacy fourth option) remains removed (see § Removed below).
1404
1420
 
1405
1421
  ###### Removed: `all` (the old fourth option)
@@ -1491,14 +1507,14 @@ For `engineering`, `delivery`, and `operations` roles, show:
1491
1507
 
1492
1508
  ```text
1493
1509
  Ritual build
1494
- Context ✓ Scope ● Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1510
+ Job ✓ Scope ● Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1495
1511
 
1496
1512
  Run discovery
1497
1513
 
1498
1514
  Ritual will source answers for the picked questions, then generate
1499
1515
  recommendations. This usually takes a few minutes.
1500
1516
 
1501
- Reply `run` to continue.
1517
+ Reply `run` to source answers → generate recommendations.
1502
1518
  Reply `pause` to stop here.
1503
1519
  ```
1504
1520
 
@@ -1512,7 +1528,7 @@ For `product`, `design`, or explicitly PRD-style flows, answer review may be use
1512
1528
 
1513
1529
  ```text
1514
1530
  Ritual build
1515
- Context ✓ Scope ● Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1531
+ Job ✓ Scope ● Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1516
1532
 
1517
1533
  Run discovery
1518
1534
 
@@ -1589,8 +1605,16 @@ Then print progress only when `progress_pct` or `current_step` changes, or every
1589
1605
 
1590
1606
  > Agentic run: {progress_pct}% — {current_step}
1591
1607
 
1592
- When `status` is `COMPLETED`: continue to Step 9.
1593
- When `status` is `COMPLETED_WITH_ERRORS`: tell the user, but proceed partial recommendations may still be useful.
1608
+ When `status` is `COMPLETED`: **wait for recommendation ROWS before Step 9.** The run reporting
1609
+ `completed` does NOT mean recommendations exist yetrec generation is a separate queued job that
1610
+ lands MINUTES later (the 2026-06-05 premature-accept incident class; observed again live 2026-06-12:
1611
+ an agent rendered "0 recommendations across 0 categories" and vacuously proceeded). Poll
1612
+ `mcp__ritual__get_recommendations_preview(exploration_id)` on the standard cadence (`Bash sleep 20`
1613
+ per iteration, "still generating recommendations…" line every ~3 polls) until the preview returns
1614
+ **at least one recommendation**, then continue to Step 9. NEVER render the Step 9 landing — and
1615
+ never call `accept_recommendations` — from a zero-rec read. If 10+ minutes pass with zero rows,
1616
+ surface that as an anomaly instead of proceeding.
1617
+ When `status` is `COMPLETED_WITH_ERRORS`: tell the user, then apply the same wait-for-rows rule — partial recommendations may still be useful.
1594
1618
  When `status` is `FAILED`: surface the error message, ask if they want to retry (`start_agentic_run` again with same exploration_id) or stop.
1595
1619
  When `status` is `PAUSED_FOR_REVIEW` (product/design answer-review mode only): continue to Step 8.5.
1596
1620
 
@@ -1608,7 +1632,7 @@ Landing (first question, full rail + intro):
1608
1632
 
1609
1633
  ```text
1610
1634
  Ritual build
1611
- Context ✓ Scope ● Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1635
+ Job ✓ Scope ● Discovery ○ Recommendations ○ Build brief ○ Implementation (Your agent)
1612
1636
 
1613
1637
  Run Agentic Exploration
1614
1638
 
@@ -1682,11 +1706,11 @@ For each question's loop:
1682
1706
 
1683
1707
 
1684
1708
 
1685
- #### Step 9 — Review recommendations (category walk)
1709
+ #### Step 9 — Review recommendations (landing + drill)
1686
1710
 
1687
1711
  This is the most-read screen in the build flow, and — as of 2026-06-08 — a **non-blocking review**. Recommendations are **auto-accepted at generation** (created `approved`); the artifacts that depend on them (requirements, the deliverable doc, and — for developer-function jobs — the build brief) are **already being generated** the moment rec-gen completes. Step 9 is the user's chance to **read and refine** the set, not an accept-or-reject gate. Replying `proceed` records that a human reviewed it (stamps `reviewedAt` / `reviewedBy`) and continues to the build brief — it never blocks, and there is **no reject path here**.
1688
1712
 
1689
- The review is a **category walk**, mirroring Spark's recommendation drawer: the user moves through one **category** at a time, sees each recommendation in that category in full (title, description, and the "Why this" reasoning), and can refine any one of them in place before continuing.
1713
+ **Landing-first (2026-06-12) — the same shape as the suggested-12 discovery landing:** the default render is ONE screen showing EVERY recommendation grouped by category title + one truncated description line each — so the user sees the whole set at a glance and can `proceed` immediately. Depth is opt-in: `drill R{N}` opens a single recommendation in full (complete description, "Why this", pass criteria); `edit R{N}` refines one in place. The goal is the shortest honest path to the {Deliverable}: scan, optionally drill or refine, proceed.
1690
1714
 
1691
1715
  **Data source.** Use `mcp__ritual__get_recommendations(exploration_id)` (the raw array) — the walk shows full per-rec content, so you need the fields a titles-only preview omits:
1692
1716
 
@@ -1704,64 +1728,66 @@ Assign stable `R1..RN` IDs **globally across all categories** in page order (NOT
1704
1728
 
1705
1729
  **Action set — load-bearing (exactly three, no freelancing):**
1706
1730
 
1707
- - `edit R{N} <your change>` refine one recommendation: regenerate its title / description / reasoning from a plain-language ask, **preview** the change, then **apply** it. (§ 9.2)
1708
- - `next`move to the next category. (§ 9.3)
1709
- - `proceed` — mark the set reviewed and continue to the build brief, from any category. (§ 9.3)
1731
+ - `drill R{N}`open ONE recommendation in full: complete description, "Why this", pass criteria. (§ 9.1b)
1732
+ - `edit R{N} <your change>` refine one recommendation: regenerate its title / description / reasoning from a plain-language ask, **preview** the change, then **apply** it. Works from the landing or from a drill view. (§ 9.2)
1733
+ - `proceed` — mark the set reviewed and generate the {Deliverable} (the job's deliverable — render its rail name, e.g. `Service Build Brief`). Available everywhere. (§ 9.3)
1710
1734
 
1711
- **Do NOT freelance other actions.** There is **no `drop` / reject** (recs are auto-accepted and the review is non-blocking — a rec the user dislikes is refined with `edit`, or simply left as-is), **no `comment`**, and **no separate `drill` / `detail`** (full content is already on screen). Reject none of these by inventing compounds either (`dedupe`, `accept the survivors`, `merge similar`, `open the admin UI` — all forbidden). If the rec set itself looks wrong (e.g. apparent duplicates), surface the anomaly explicitly and consult `mcp__ritual__get_recommendation_attestation` (`duplicateTitlePrefixes`) — don't paper over it with an invented action.
1735
+ **Do NOT freelance other actions.** There is **no `drop` / reject** (recs are auto-accepted and the review is non-blocking — a rec the user dislikes is refined with `edit`, or simply left as-is), **no `comment`**, and **no `next`** (there is no pagination — the landing already shows everything). Reject invented compounds too (`dedupe`, `accept the survivors`, `merge similar`, `open the admin UI` — all forbidden). If the rec set itself looks wrong (e.g. apparent duplicates), surface the anomaly explicitly and consult `mcp__ritual__get_recommendation_attestation` (`duplicateTitlePrefixes`) — don't paper over it with an invented action.
1712
1736
 
1713
- ##### 9.1 — The walk: one category per turn
1737
+ ##### 9.1 — The landing: every recommendation, one screen
1714
1738
 
1715
- **[USER PAUSE]** Render the **current category only**, then stop and wait for the user's reply. One category per turnnever dump every category's full content in a single message (that's the wall-of-text failure mode; the walk is what keeps a 13-rec set readable). The first render opens with the full rail; subsequent categories use the in-phase chip.
1739
+ **Zero-rec guard (load-bearing):** if `get_recommendations` returns an empty array, do NOT render this landing and do NOT call `accept_recommendations`you arrived before rec generation finished. Go back to the Step 8 wait-for-rows polling. A "0 recommendations across 0 categories" render is always a bug, never a state to present.
1716
1740
 
1717
- First category (rail shown):
1741
+ **[USER PAUSE]** Render ALL recommendations grouped by category — every title visible, each with ONE truncated description line. This is a scan surface, not a reading surface: titles carry the signal; `drill` carries the depth. Never omit a category or a rec ("… N more" is forbidden — the user must see exactly what `proceed` reviews); never expand to multi-line descriptions here (that's the wall-of-text failure mode the landing exists to prevent).
1718
1742
 
1719
1743
  ```text
1720
1744
  Ritual build
1721
- Context ✓ Scope ✓ Discovery ● Recommendations ○ Build brief ○ Implementation (Your agent)
1745
+ Job ✓ Scope ✓ Discovery ● Recommendations ○ {Deliverable} ○ Implementation (Your agent)
1722
1746
 
1723
1747
  Scope:
1724
1748
  {one-line compressed scope — ~80-120 chars; truncate at a clause boundary, no ellipsis}
1725
1749
 
1726
- {N} recommendations across {K} categories. They're accepted by default
1727
- review and refine any, or proceed anytime.
1750
+ {N} recommendations across {K} categories. Scan the set, drill into any,
1751
+ or proceed to your {Deliverable}.
1728
1752
 
1729
- Category 1/{K} — {category name}
1753
+ {Category name 1}
1754
+ R1 {title} — {description truncated ~90 chars at a word boundary…}
1755
+ R2 {title} — {truncated description…}
1730
1756
 
1731
- R1 {title}
1732
- {contentthe description, wrapped at terminal width, 1-3 lines}
1733
- Why this: {one-line Problem→Discovery→Tradeoff distillation, plain prose}
1757
+ {Category name 2}
1758
+ R3 {title}{truncated description}
1759
+ R4 {title} {truncated description…}
1734
1760
 
1735
- R2 {title}
1736
- {description}
1737
- Why this: {...}
1761
+ {…every category, every rec, one line each…}
1738
1762
 
1739
- Pulse: Reasoning Readiness ~88% · Context Debt 12% (implementation-ready)
1763
+ Pulse: Reasoning Readiness ~88% · Context Debt 12% · +16% (recommendations ready)
1740
1764
 
1741
- Reply edit R{N} <your change> · next (Category 2/{K}) · proceed (build brief)
1765
+ A few assumptions are still unverified — the build brief is what locks them down.
1766
+ Reply drill R{N} (read one in full) · edit R{N} <your change> · proceed (generate the {Deliverable})
1742
1767
  ```
1743
1768
 
1744
- Subsequent categories (in-phase chip, no full rail):
1769
+ Notes:
1770
+
1771
+ - **Global `R{N}` IDs** in page order across categories. The R-ID is how the user references a rec in `drill R{N}` / `edit R{N}`; never restart numbering per category.
1772
+ - **Title + one truncated description line per rec** — truncate at a word boundary with `…`. No "Why this" at the landing; that lives in the drill view.
1773
+ - **`proceed` is the primary CTA** — the user never has to drill anything to continue.
1774
+
1775
+ ##### 9.1b — `drill R{N}`: one recommendation in full
1776
+
1777
+ **[USER PAUSE]** Render the single recommendation completely, then wait:
1745
1778
 
1746
1779
  ```text
1747
- Recommendations · Category 2/{K} — {category name}
1780
+ Recommendations · R{N} — {title}
1748
1781
 
1749
- R3 {title}
1750
- {description}
1751
- Why this: {...}
1782
+ {content — the full description, wrapped at terminal width}
1752
1783
 
1753
- ...
1784
+ Why this: {one-line Problem→Discovery→Tradeoff distillation, plain prose}
1785
+ Pass: {acceptance_criteria, one line each — omit the block if empty}
1754
1786
 
1755
- Reply edit R{N} <your change> · next (Category 3/{K}) · proceed (build brief)
1787
+ Reply edit R{N} <your change> · back (all recommendations) · proceed (generate the {Deliverable})
1756
1788
  ```
1757
1789
 
1758
- Notes:
1759
-
1760
- - **Global `R{N}` IDs** continue across categories (Category 2 starts at R3 if Category 1 held R1–R2). The R-ID is how the user references a rec in `edit R{N}`; never restart numbering per category.
1761
- - **`content` (the description) and "Why this" ARE shown** at the walk — unlike the old titles-only landing. That's deliberate: the user reads and refines in place. Keep each rec to title + 1–3 description lines + one "Why this" line. If a rec's `acceptance_criteria` are short and genuinely useful you may add a single `Pass: {...}` line, but don't pad — the walk must stay scannable.
1762
- - **One blank line between recs**; indent rec bodies under their `R{N}` so the eye lands on the title first.
1763
- - **`proceed` is the primary CTA** and is offered on every category — the user never has to walk all categories to continue.
1764
- - **On the last category**, the action line drops `next`; if the user types `next` there, reply: "That was the last category — reply `proceed` to continue, or `edit R{N}` to refine one."
1790
+ `back` re-renders the landing (§ 9.1, unchanged). Drilling is read-only — nothing advances or persists.
1765
1791
 
1766
1792
  ##### 9.2 — `edit R{N} <ask>`: preview, then apply
1767
1793
 
@@ -1794,19 +1820,18 @@ Reply apply (save this revision) · discard (keep the original)
1794
1820
  - Render ONLY the `diff` fields that are present. Map `field: "title"` → `Title`, `"description"` → `Description`, `"chain.<idx>"` → `Why this — step {idx+1}`.
1795
1821
  - If the proposal's `diff` is empty (the LLM found no meaningful change), say so plainly and return to the category view unchanged — don't fabricate a diff.
1796
1822
 
1797
- 4. On `apply`: call `mcp__ritual__apply_recommendation_proposal({ recommendation_id, proposal_id })`. It persists a new version, replays the reasoning chain, and returns the applied proposal. Re-fetch the rec (`get_recommendations`) and **re-render the current category with R{N} updated in place**, then continue the walk (action line `edit R{N} <change> · next · proceed`).
1798
- On `discard`: return to the current category unchanged — nothing was persisted.
1823
+ 4. On `apply`: call `mcp__ritual__apply_recommendation_proposal({ recommendation_id, proposal_id })`. It persists a new version, replays the reasoning chain, and returns the applied proposal. Re-fetch the rec (`get_recommendations`) and **re-render the view the user came from** the landing 9.1) or the drill view (§ 9.1b) with R{N} updated in place.
1824
+ On `discard`: return to that view unchanged — nothing was persisted.
1799
1825
 
1800
- Editing is non-destructive and does not advance the flow — the user can `edit` several recs, across categories, before `proceed`.
1826
+ Editing is non-destructive and does not advance the flow — the user can `edit` several recs before `proceed`.
1801
1827
 
1802
- ##### 9.3 — `next` and `proceed`
1828
+ ##### 9.3 — `proceed`
1803
1829
 
1804
- - **`next`** → render the next category per § 9.1 (in-phase chip). After the last category, prompt `proceed`.
1805
- - **`proceed`** (from any category) → call `mcp__ritual__accept_recommendations({ exploration_id })`. Under the non-blocking model this **records the human review** (stamps `reviewedAt` / `reviewedBy`) and advances; it is NOT a draft→approved promotion (the recs are already `approved`). The downstream artifacts were queued at rec-gen time, so this returns fast. Then show the completion rail and continue to Step 9.5:
1830
+ - **`proceed`** (from the landing or any drill view) call `mcp__ritual__accept_recommendations({ exploration_id })`. Under the non-blocking model this **records the human review** (stamps `reviewedAt` / `reviewedBy`) and advances; it is NOT a draft→approved promotion (the recs are already `approved`). The downstream artifacts were queued at rec-gen time, so this returns fast. Then show the completion rail and continue to Step 9.5:
1806
1831
 
1807
1832
  ```text
1808
1833
  Ritual build
1809
- Context ✓ Scope ✓ Discovery ✓ Recommendations ● Build brief ○ Implementation (Your agent)
1834
+ Job ✓ Scope ✓ Discovery ✓ Recommendations ● Build brief ○ Implementation (Your agent)
1810
1835
 
1811
1836
  Reviewed {N} recommendations.
1812
1837
 
@@ -1886,7 +1911,7 @@ Run a constraint-survival audit on the typed Recommendation + Requirement substr
1886
1911
  ```text
1887
1912
  Recommendations + requirements are ready. Optional constraint-survival audit available.
1888
1913
 
1889
- Reply `audit` to run, or `proceed` to skip to brief generation.
1914
+ Reply `audit` to run, or `proceed` to skip the audit and generate the {Deliverable}.
1890
1915
  ```
1891
1916
 
1892
1917
  **For `--audited` mode:**
@@ -1897,7 +1922,7 @@ Recommendations + requirements are ready.
1897
1922
  Recommended: run constraint-survival audit before brief generation.
1898
1923
  This checks whether anti-goals survived into the recs + requirements.
1899
1924
 
1900
- Reply `audit`, `proceed`, or `always audit for this build`.
1925
+ Reply `audit` to run, `proceed` to skip and generate the {Deliverable}, or `always audit for this build`.
1901
1926
  ```
1902
1927
 
1903
1928
  **For `--audit=strict` mode:** SKIP the prompt; jump directly to Step 9.6.2 (run the audit).
@@ -2091,6 +2116,13 @@ Steps:
2091
2116
  - `contradicted` — brief claim is wrong; the code does something different.
2092
2117
  - `not_found` — symbol couldn't be located.
2093
2118
 
2119
+ **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.
2120
+
2121
+ ❌ `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.`
2122
+ ✅ `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.`
2123
+
2124
+ 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.
2125
+
2094
2126
  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.
2095
2127
 
2096
2128
  6. **Sync the verification to Ritual's KG** — call `mcp__ritual__sync_brief_review` with:
@@ -2207,7 +2239,7 @@ End Step 10 with a single recommended action plus a cheap escape hatch — never
2207
2239
 
2208
2240
  ```text
2209
2241
  Ritual build
2210
- Context ✓ Scope ✓ Discovery ✓ Recommendations ● Build brief ○ Implementation (Your agent)
2242
+ Job ✓ Scope ✓ Discovery ✓ Recommendations ● Build brief ○ Implementation (Your agent)
2211
2243
 
2212
2244
  Build brief ready
2213
2245
 
@@ -2242,7 +2274,7 @@ The Implementation phase landing — full rail (the rail moves to Implementation
2242
2274
 
2243
2275
  ```text
2244
2276
  Ritual build
2245
- Context ✓ Scope ✓ Discovery ✓ Recommendations ✓ Build brief ● Implementation (Your agent)
2277
+ Job ✓ Scope ✓ Discovery ✓ Recommendations ✓ Build brief ● Implementation (Your agent)
2246
2278
 
2247
2279
  Implementation (Your agent)
2248
2280
 
@@ -2487,7 +2519,7 @@ Before asking for permission, frame the call in language the user can act on. `s
2487
2519
 
2488
2520
  ```text
2489
2521
  Ritual build
2490
- Context ✓ Scope ✓ Discovery ✓ Recommendations ✓ Build brief ● Implementation (Your agent)
2522
+ Job ✓ Scope ✓ Discovery ✓ Recommendations ✓ Build brief ● Implementation (Your agent)
2491
2523
 
2492
2524
  Log implementation
2493
2525
 
@@ -2530,7 +2562,7 @@ When sync_implementation succeeds, the response includes:
2530
2562
 
2531
2563
  ```text
2532
2564
  Ritual build
2533
- Context ✓ Scope ✓ Discovery ✓ Recommendations ✓ Build brief ✓ Implementation (Your agent)
2565
+ Job ✓ Scope ✓ Discovery ✓ Recommendations ✓ Build brief ✓ Implementation (Your agent)
2534
2566
 
2535
2567
  ✓ Logged implementation for {exploration name}
2536
2568
 
@@ -2565,7 +2597,7 @@ User-visible (full rail — sync failure is a top-level state):
2565
2597
 
2566
2598
  ```text
2567
2599
  Ritual build
2568
- Context ✓ Scope ✓ Discovery ✓ Recommendations ✓ Build brief ● Implementation (Your agent)
2600
+ Job ✓ Scope ✓ Discovery ✓ Recommendations ✓ Build brief ● Implementation (Your agent)
2569
2601
 
2570
2602
  Sync failed (recoverable)
2571
2603
 
@@ -2603,7 +2635,7 @@ If stale, surface to the user with the full rail (top-level decision gate):
2603
2635
 
2604
2636
  ```text
2605
2637
  Ritual build
2606
- Context ✓ Scope ✓ Discovery ✓ Recommendations ✓ Build brief ● Implementation (Your agent)
2638
+ Job ✓ Scope ✓ Discovery ✓ Recommendations ✓ Build brief ● Implementation (Your agent)
2607
2639
 
2608
2640
  Pending sync is stale
2609
2641