@ritualai/cli 0.7.13 → 0.7.15

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

@@ -0,0 +1,169 @@
+## Brief verification — methodology + output schema
+
+Reference for `/ritual build` Step 10b.5 (the auto-fire verify-brief pass that runs after the build brief is generated, before the user reviews it at the Step 10d gate).
+
+The brief generator runs server-side and **does not have repo access**. It writes assertions about cited files / functions / classes based on the agent's earlier recon summary — which is a text summary, not the actual code. When the brief says *"`is_allowed_to_see` is insufficient — needs token-based access"* but the code actually ships email-allowlist semantics, the contradiction is invisible to the brief generator and to the user reading the brief.
+
+Step 10b.5 closes this gap: **the agent (with repo access) reads the bodies of the specific symbols the brief cites and produces a structured list of findings before the user sees the brief.** Findings flow back into the brief via `refine_build_brief` if any contradictions are detected.
+
+This is the **non-UI sibling of `references/ui-ux-checklist.md`** (Step 10.5 UX review). Same methodology shape (read brief → identify citations → find in repo → compare → fill schema → surface findings), different targets (functions / data shapes / model fields instead of UI components).
+
+---
+
+### Core principle
+
+**The brief's assertions about cited code must be verified against the actual code before the user is asked to approve them.**
+
+The brief generator hedges this risk passively with phrases like *"these recommendations may deviate if the codebase has a stronger existing pattern."* That hedge is honest but not actionable — it tells the reader to maybe check, without telling anyone to actually do the checking. Step 10b.5 makes the checking happen.
+
+---
+
+### Methodology (chain of thought — execute in this order)
+
+Do NOT skip to the output schema. The schema only gets filled correctly when the analysis upstream is done.
+
+**1. Read the brief end-to-end first.**
+
+Open `BUILD-BRIEF.md`. The sections most likely to contain verifiable assertions:
+
+- **Codebase Anchors** — explicit file/function citations the brief expects you to extend or replace.
+- **RB-N rationale** — review-blocking claims often cite specific primitives ("the existing `X` is insufficient because Y").
+- **Suggested Implementation** — sequencing claims about what's "already present" vs "needs to be added."
+- **Previously Deferred** — references to prior decisions on overlapping files (sourced from KG).
+
+Output of this step: a flat list of every specific code citation the brief makes. **Symbol + file + assertion**. If a section says *"the recommendations may deviate if the codebase has a stronger existing pattern,"* that's exactly the kind of hedge this step exists to resolve — treat it as a high-priority verification target.
+
+**2. Extract the explicit citations.**
+
+For each cited symbol, capture:
+
+- `cited_symbol` — function / class / model field / endpoint name.
+- `cited_file` — file path if mentioned; if not, infer from context (Codebase Anchors usually pairs them).
+- `brief_assertion` — the brief's exact claim about this symbol. One sentence.
+
+Cap the list at **15 citations** (highest-leverage ones first — primitives the RBs depend on, symbols cited in multiple sections). 15 is enough to cover the load-bearing risks; more bloats the verification time without proportional signal.
+
+**3. For each citation, read the actual code.**
+
+Use Grep / Glob / Read. For each cited symbol:
+
+- Find the file (Grep `def {symbol}` / `class {symbol}` / `const {symbol}` / `function {symbol}`).
+- Read the function body / class definition / data shape. Include surrounding context (~10 lines) so callers and conventions are visible.
+- Note line numbers (`cited_lines.start` / `cited_lines.end`) so the finding pins to a stable location.
+
+**Do not fabricate citations.** If `Grep` returns nothing, the verdict is `not_found`, not "I'll infer what it probably does."
+
+**4. Compare brief assertion vs code reality. Assign a verdict per citation.**
+
+Three verdicts:
+
+- **`verified`** — the brief's claim matches what the code actually does. Most common verdict on a well-anchored brief; the agent's recon summary was accurate; the brief generator got it right.
+- **`contradicted`** — the brief's claim is **wrong**. The code does something different. This is the verdict that drives a refinement.
+- **`not_found`** — the brief cited a symbol the agent could not locate in the repo. Either the symbol was renamed, deleted, or never existed. Either way: the brief is asserting against a phantom; surface to user.
+
+**5. Fill the output schema with evidence.**
+
+Write `BUILD-BRIEF-VERIFICATION.md` to disk alongside `BUILD-BRIEF.md`. Use the schema below. **Each finding cites the file + line range + the actual code snippet that justified the verdict.** The user reading this must be able to verify your verification — no hand-waving, no claims without evidence.
+
+**6. If any findings are `contradicted`, surface to the user inline at Step 10d.**
+
+The Step 10d gate normally reads *"Reply `go` to implement, `refine` for edits, `drill {N}` to inspect, `pause` to stop."* When `contradicted` findings exist, the gate's CTA shifts to highlight the contradictions:
+
+```text
+⚠ Verification found {N} contradiction(s) between the brief and the actual code:
+
+  · "{cited_symbol}" — brief says "{brief_assertion}". Code reality:
+    "{code_reality}" (see {cited_file}:{cited_lines}).
+  · ...
+
+Reply `refine` to apply these corrections, `go` to proceed anyway,
+or `drill {N}` to inspect one rec.
+```
+
+The user can `refine` (recommended) — at which point the SKILL calls `refine_build_brief` with the structured findings array, and the LLM produces an updated brief that incorporates the corrections authoritatively. Or `go` if the user has context the agent doesn't (e.g. "yes the brief is wrong but I want to ship it as-is for now"). The decision stays with the user; the agent surfaces the evidence.
+
+---
+
+### Output schema — `BUILD-BRIEF-VERIFICATION.md`
+
+Render exactly the sections below. Every section MUST exist (use `(none)` / `(no contradictions)` for empty cases — do not skip).
+
+```markdown
+<!--
+Generated by Ritual — brief verification pass
+Exploration: https://app.ritualapp.cloud/e/{exploration_id}
+Source brief: BUILD-BRIEF.md
+Do not remove this header.
+-->
+
+# Brief Verification — {exploration name}
+
+## Summary
+
+Verified: {N}   ·   Contradicted: {M}   ·   Not found: {K}
+
+{One-paragraph natural-language summary of the verification result. If
+contradictions exist, lead with the most load-bearing one. If everything
+checked out, state that clearly.}
+
+## ⚠ Contradicted ({M})
+
+(one block per contradicted citation, omit section entirely if M=0)
+
+### `{cited_symbol}` — {cited_file}:{lines.start}-{lines.end}
+
+- **Brief asserts:** "{brief_assertion}"
+- **Code reality:** "{code_reality}"
+- **Evidence (from the file):**
+
+  ```{language}
+  {actual code snippet, ~10 lines}
+  ```
+
+- **Recommendation:** {what should change in the brief — concrete next step}
+
+## ❓ Not found ({K})
+
+(one block per missing citation, omit section entirely if K=0)
+
+### `{cited_symbol}` — cited in {section}
+
+- **Brief asserts:** "{brief_assertion}"
+- **Searched:** {file paths / grep queries the agent tried}
+- **Action:** ask the user whether the cited symbol exists under a different name, or whether the brief is referencing something that was renamed / removed.
+
+## ✅ Verified ({N})
+
+(compact list; one bullet per verified citation; no body required)
+
+- `{cited_symbol}` — {cited_file}:{lines.start}-{lines.end} — brief assertion matches code.
+- ...
+```
+
+---
+
+### What this verification step does NOT do
+
+- **Verify everything in the brief.** Only the symbol-citation slice. Pose-level claims, framing, and general direction are out of scope.
+- **Read the full file.** Read enough surrounding context to verify the symbol (~10 lines); not the whole file. Capped at ~15 citations total to keep this fast.
+- **Edit the brief directly.** Step 10b.5 only writes `BUILD-BRIEF-VERIFICATION.md`. The user decides whether to call `refine_build_brief` with the findings at Step 10d (recommended) or proceed with the brief as-is.
+- **Persist findings to the KG.** Phase 1 is local-only. Phase 2 (filed at `memory/backlog_brief_verification_findings_kg_promotion.md`) adds the `BriefVerificationFinding` Prisma model + endpoint + priorContext injection so future briefs on overlapping files inherit verified facts.
+
+---
+
+### Anti-patterns
+
+- **❌ Fabricating evidence.** Every claim in the output file must trace to a real file + line range that the agent actually Read. If Grep returned nothing, the verdict is `not_found`, NOT "I'll just describe what the function probably does."
+- **❌ Re-deriving the brief.** This step is verification, not authoring. Findings exist on a per-citation basis; the agent does not re-write the brief's framing or add new RBs.
+- **❌ Skipping the step on backend-only features.** Step 10b.5 fires automatically regardless of UI / non-UI shape. UI-shaped features use `references/ui-ux-checklist.md` (Step 10.5) on top of this step for the additional UI-pattern review — but every brief runs through the citation-level verification.
+- **❌ Treating the brief's hedge as authorization to skip.** *"may deviate if codebase has a stronger pattern"* is exactly the case Step 10b.5 exists to resolve. The hedge means "go verify"; don't read it as "no need to verify."
+- **❌ Padding the verified list.** Don't enumerate citations the brief didn't actually make just to inflate the "Verified" count. Only cite what the brief cited.
+
+---
+
+### Failure modes to watch for
+
+- **Brief makes ZERO citations.** Some brief generations are framing-only and don't reference specific symbols. The verification pass should write a summary noting *"the brief makes no specific code citations; no verification possible"* and the gate proceeds normally. Phase 2 will treat this as a brief-quality signal (briefs without citations are harder to verify).
+- **Symbol exists in multiple places.** When Grep finds the symbol in N>1 files, capture the file the brief most likely meant (use Codebase Anchors context as the disambiguator). If still ambiguous, render one finding per match with verdict `not_found` and surface the ambiguity to the user.
+- **Code semantics ≠ visible signature.** A function might be named one thing but documented to do another. Read the docstring + the body; trust the body. If the docstring contradicts the body, that's its own finding (`contradicted` with verdict notes).
+- **Brief assertion is too vague to verify.** *"The auth flow needs hardening"* doesn't cite a specific symbol; not verifiable. Skip; verify only the assertions specific enough to check.

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

@@ -1,6 +1,6 @@
 ## /ritual build
 
-Walks the engineer from a free-form problem statement to vetted, accepted Ritual recommendations using the vNext MCP tool surface.
+Walks the engineer from a free-form problem statement to vetted, accepted Ritual recommendations using the Ritual MCP tool surface.
 
 Output: a fully-closed loop — **exploration in COMPLETE state, recommendations accepted (or explicitly handed off to an admin), build brief generated, code implemented, and `sync_implementation` called to register the result in the knowledge graph**. The engineer stays in the driver's seat through concise status updates and explicit pauses only at real decision gates.
 
@@ -191,10 +191,11 @@ Steps:
 
    > I see {N} exploration{s} already in this workspace:
    >
-   > **{state_glyph} {state_label}**
-   > - **{name}** — {short scope summary, first 80 chars of problemStatement}
-   >   - {recommendationCount} rec{s} ({accepted}/{total} approved{implementationSegment}), {openDeferralsCount} open deferral{s}
-   >   - {state-specific call-to-action — see table below}
+   > **{state_glyph} {state_label}** ({count})
+   >
+   > 1. **{name}** — {short scope summary, first 80 chars of problemStatement}
+   >    {recommendationCount} rec{s} ({accepted}/{total} approved{implementationSegment}), {openDeferralsCount} open deferral{s}.
+   >    Next: {state-specific call-to-action — see table below}.
    >
    > Recommended: resume one if it matches this work.
    > Reply with a number/name to resume, `suggest` to find high-leverage candidates from repo + workspace history, `delete N` to remove a duplicate/misfire, or `proceed` to start fresh.
@@ -203,10 +204,11 @@ Steps:
 
    > I can help you continue existing work or find the next high-leverage thing.
    >
-   > **{state_glyph} {state_label}**
-   > - **{name}** — {short scope summary, first 80 chars of problemStatement}
-   >   - {recommendationCount} rec{s} ({accepted}/{total} approved{implementationSegment}), {openDeferralsCount} open deferral{s}
-   >   - {state-specific call-to-action — see table below}
+   > **{state_glyph} {state_label}** ({count})
+   >
+   > 1. **{name}** — {short scope summary, first 80 chars of problemStatement}
+   >    {recommendationCount} rec{s} ({accepted}/{total} approved{implementationSegment}), {openDeferralsCount} open deferral{s}.
+   >    Next: {state-specific call-to-action — see table below}.
    >
    > Reply with:
    > - a number/name to resume
@@ -215,6 +217,8 @@ Steps:
    > - a feature/problem description to start fresh
    > - `none` to exit
 
+   **Picker rendering anti-pattern (load-bearing) — observed 2026-05-15 in `/ritual resume`, same shape applies here:** each exploration gets ONE picker number `{N}.` on its title line. The summary, recommendation count, and Next-line are indented continuation prose under that number, NEVER their own numbered or bulleted list items. Picker numbering is **flat across all state buckets** (1, 2, 3, … regardless of which `{state_glyph}` header they sit under), so a single number unambiguously picks one exploration. The `({count})` in parens after each state-bucket header is informational and is NEVER a picker number. See `references/resume-flow.md` § R2 for the full anti-pattern with a worked example.
+
    **`{implementationSegment}` resolution rule** — derive from `implementationStatus.implementationRecord` on the listing response:
 
    | Condition | Render |
@@ -1118,6 +1122,24 @@ Then summarize the created siblings in the dense-list format. Do not pause after
 
 Longest phase because generation is async + the user picks per-Area. (Internally the API field is `matter_id`; user-facing copy always says Area.)
 
+**Step 6 → Step 7 transition anti-pattern (load-bearing):** after `create_exploration` succeeds in Step 6, you MUST NOT render Step 8's *"Reply `run` to continue"* CTA. Required next actions, in order, before Step 8 is allowed:
+
+1. Call `mcp__ritual__suggest_discovery_questions(exploration_id)` (Step 7.1) — no user input needed; just kick it off.
+2. Poll `mcp__ritual__get_discovery_state(exploration_id)` until `ready: true` (Step 7.2).
+3. Render the Areas index per § 7.3.1 (NOT a free-form list — see § 7.3.1 rendering anti-pattern below).
+4. `[USER PAUSE]` — the user picks Areas + questions, or types `accept shortlist` / `skip discovery`.
+5. Call `mcp__ritual__accept_discovery_questions` for each picked Area (Step 7.4).
+6. Evaluate Step 7.4.5 triggers; render the scope-classification gate if any fire.
+7. ONLY THEN proceed to Step 8 and render the *"Reply `run` to continue"* CTA.
+
+**Forbidden behaviors:**
+
+- Calling `start_agentic_run` before `accept_discovery_questions` has been called at least once for this exploration. (`skip discovery` is the explicit exception — it intentionally takes the no-picks path through 7.4.5.)
+- 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.
+- Rendering "Next: run discovery through recommendations / Reply `run` to continue" anywhere in the chat before Step 7.4 has completed.
+
+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.
+
 ##### 7.1 — Kick off
 
 Call `mcp__ritual__suggest_discovery_questions(exploration_id)`. Returns immediately with `task_id`. Tell the user with the full rail (we just entered the Discovery phase):
@@ -1193,6 +1215,35 @@ Inside an Area, use `show more` to see the rest.
 
 Number alignment: right-pad the Area name to a consistent column so the counts line up vertically. Drop the `accept shortlist` token when no Area has recommendations (rare; just show the area-number + `skip discovery` CTAs).
 
+**Rendering anti-pattern (load-bearing) — the Areas index renders ONLY area names + counts. Observed violations 2026-05-15:**
+
+- ❌ Question previews under each area:
+  ```text
+  1. Wishlist Visibility Contract (10 qs)
+
+     1. How PUBLIC/SHARED behave across owner controls...
+  2. Shared Wishlist Surfaces (8 qs)
+
+     2. Which entry points light up first...
+  ```
+  No. This invents question previews the SKILL never asked for, AND uses overlapping numbering (`1. {area}` and `1. {question preview}`) that creates ambiguity — when the user replies `5`, neither side can tell what they meant. Single numbering stream: areas only.
+
+- ❌ Free-form bullet lists, "for your convenience" question summaries, or any text under the area line beyond `{N} recommended · {N} total`.
+
+- ❌ Adding a "TL;DR" / "highlights" section above or below the Areas list.
+
+**The correct shape is exactly** (no exceptions):
+
+```
+Areas:
+
+  1. {Area name}                     {N} recommended · {N} total
+  2. {Area name}                     {N} recommended · {N} total
+  ...
+```
+
+If the user wants to see questions, they pick an Area number — that's what § 7.3.2 (Area detail) is for. **Do not pre-empt their drill choice with question previews.** Same rule as Step 9.1's "use server preview verbatim, do not free-form-summarize on top."
+
 **Why `accept shortlist`, not `accept recommended`:**
 
 - "Recommended" is ambiguous (recommended per Area? globally? by category? recommended *recs* later in the flow?). The discovery picker uses **shortlist** explicitly because the shortlist is global (6–10 questions across all Areas, computed in § 7.3.0) — distinct from per-Area recommended counts shown alongside each Area, and distinct from the later `accept recommended` action that accepts implementation themes in Step 9.
@@ -1327,6 +1378,12 @@ After question picking, check for scope mismatch only when one of these triggers
 
 If no trigger fires, proceed silently to anti-goals.
 
+**Fire-on-trigger anti-pattern (load-bearing):** after `accept_discovery_questions` returns, you MUST evaluate the four trigger conditions before proceeding to Step 8. If ANY trigger matches, you MUST render the scope-classification gate. Skipping the gate when a trigger fires — including the "the picks look reasonable to me" / "the user seems decisive" / "they probably know what they're doing" judgment call — is a SKILL violation. The decision signal is the user's **actual pick distribution**, not the agent's confidence in it.
+
+Concretely: at 5 picks out of 70 total questions = 7.1% pick-rate, the < 40% trigger fires. The gate MUST be rendered. Observed violation 2026-05-15: agent proceeded directly to Step 8 after a 5/70 acceptance, never showed the scope-classification gate — silently locking the user into a broad scope while their actual investigation was tightly focused on 5 questions.
+
+This is the same gap as the Step 9 "freelance dedupe action" anti-pattern: the SKILL specifies the behavior; the agent must not override based on its own assessment of whether the gate "feels needed."
+
 If a trigger fires, summarize the pattern in plain language and ask the user to classify unpicked areas. This is a top-level decision gate that closes the picker sub-views, so the full rail returns:
 
 ```text
@@ -1416,7 +1473,65 @@ Reply `1` or `2`. Reply `pause` to stop here.
 
 If they pick 1, call `start_agentic_run` with `stop_after: 'answers'` and continue to Step 8.5 when it pauses. If they pick 2, call without `stop_after` and continue to Step 9 when complete.
 
-Poll `mcp__ritual__get_agentic_run(run_id)` using `references/async-polling.md`: **`Bash sleep 5` (always 5 — never escalate to 15/20/25)** per iteration, then a fresh status call. Even if the run takes 2+ minutes, the sleep value stays 5; the harness blocks chained-shorter-sleeps-at-increasing-N just like it blocks `sleep ≥ 30`. Agentic runs CAN exceed 5 min for large explorations — if you see status still running past ~5 min of polling, switch to the `Monitor` + `until <check>; do sleep 2; done` pattern from `references/async-polling.md` § Long waits. Print progress only when `progress_pct` or `current_step` changes, or every ~3 polls if unchanged:
+##### 8.0 — "You're unblocked" pre-roll (right after `start_agentic_run` returns the run_id)
+
+**Lock the product promise BEFORE you enter the polling loop.** The run continues server-side; the user is free to step away. The polling loop becomes the agent's job, not the user's obligation.
+
+Tier the pre-roll by projected duration. Latency baseline: ~15s/question (V5.2 + KG injection, calibrate quarterly against `recs-pipeline.ts` eval results). Multiply the picked-question count by 15s, divide by 60 to get minutes.
+
+**Projected ≤ 2 min** — skip the pre-roll entirely. The polling micro-copy below covers the framing.
+
+**Projected 2–20 min** — warm framing:
+
+```text
+Deep reasoning run started — this may take ~{minutes} minutes.
+
+You're unblocked: the run continues server-side while you do other work.
+Grab coffee, switch tasks, or close the terminal safely.
+
+For live progress, open a NEW terminal and run:
+  ritual status --watch          # terminal command, not a slash-command
+
+Or check inside this session:
+  /ritual status                 # SKILL subcommand (in-chat)
+
+Come back later:
+  /ritual resume
+```
+
+**Projected 20+ min** — longer framing:
+
+```text
+Long reasoning run started — this one may take 20+ minutes.
+
+You can safely step away; the run continues server-side even if this terminal
+closes. For live progress:
+
+  ritual status --watch          # in a separate terminal (not /ritual status)
+
+Or check inside this session:
+  /ritual status                 # SKILL subcommand for in-chat status
+
+To come back later:
+  /ritual resume
+```
+
+**Two surfaces, two contexts:**
+
+- `ritual status [--watch]` — **terminal command** (CLI 0.7.14+). Run from a separate shell. Survives this session closing; supports `--watch` for live tail.
+- `/ritual status` — **SKILL subcommand** inside Claude Code / Cursor / your agent. Read-only mirror; useful when the user wants a quick check without context-switching to a terminal. Defined in `references/status-flow.md`.
+
+Pick whichever fits the user's flow — they're equivalent in content. Do not introduce a `reply watch` mode in this SKILL; the CLI command IS the live-tail affordance.
+
+##### 8.1 — Polling loop
+
+Poll `mcp__ritual__get_agentic_run(run_id)` using `references/async-polling.md`: **`Bash sleep 5` (always 5 — never escalate to 15/20/25)** per iteration, then a fresh status call. Even if the run takes 2+ minutes, the sleep value stays 5; the harness blocks chained-shorter-sleeps-at-increasing-N just like it blocks `sleep ≥ 30`. Agentic runs CAN exceed 5 min for large explorations — if you see status still running past ~5 min of polling, switch to the `Monitor` + `until <check>; do sleep 2; done` pattern from `references/async-polling.md` § Long waits.
+
+**On the FIRST poll only** (not every poll), prepend one line that locks the "background execution is default" mental model:
+
+> I'll keep working in the background. For a live tail, run `ritual status --watch` in a separate terminal — or type `/ritual status` here for an in-chat snapshot.
+
+Then print progress only when `progress_pct` or `current_step` changes, or every ~3 polls if unchanged:
 
 > Agentic run: {progress_pct}% — {current_step}
 
@@ -1531,6 +1646,28 @@ If you don't already know the user's role on this workspace, prefer the workspac
 
 **Vocabulary**: do NOT use "Reasoning chain" or "reasoning_chain" in user-facing copy. The user-visible label is **"Why this"** — a 4-line Problem / Discovery / Tradeoff / Recommendation breakdown derived from the rationale field. "Reasoning chain" sounds like internal model chain-of-thought; "Why this" is product-native.
 
+**Vocabulary anti-pattern — load-bearing**: recommendations are grouped by **category** (`metadata.category.name`). They are **NEVER** grouped by `matter` or by `Area`. Those are **discovery-phase concepts** — the matter / Area is where DISCOVERY QUESTIONS live; recommendations are synthesized across all matters and grouped by the category the LLM assigns (themes like "Token security & replay", "Atomicity & architecture", etc.). The internal DB field `matter_id` does not appear in the recommendation surface and **must never appear in user-facing copy** at this step. Anti-pattern observed in agent output: *"44 recs grouped by matter"* — the right framing is *"44 recs grouped by category"* (with categoryGroups returned by the preview API doing the work). If you find yourself referring to recommendation groups as "Areas" or "matters," stop and re-read this paragraph.
+
+**Action-menu anti-pattern — load-bearing**: the **blessed action set at the Step 9 acceptance gate** is exactly:
+
+- `accept recommended` — admin path, accepts all on-screen recs
+- `request admin review` — collaborator path, notifies workspace admin
+- `drop R{N}` — remove one rec from the set before accepting
+- `drill R{N}` — show one rec's full detail card
+- `comment R{N}` — leave feedback on a specific rec
+- `pause` — stop here; user can resume via `/ritual resume`
+
+Plus the `continue` (implement-ahead) escape hatch for collaborators with explicit authorization.
+
+**Do NOT freelance other actions.** Anti-patterns observed in agent output:
+
+- ❌ `dedupe` — there is no de-dupe action. The system produces a non-duplicated rec set by design (single-flight rec-generation, V5 cap-enforcer, Stage A.2 quality audit). If duplicates appear, that's a system regression — file a bug, don't offer a workaround.
+- ❌ `open the admin` / "open the admin UI to reject one pass" — there is no admin UI surface invoked from `/ritual build`. The CLI is the surface; the action set above is the contract.
+- ❌ `reject one pass` / `accept the survivors` — assumes a duplicate-pass shape that should not exist post-PR #345.
+- ❌ Any invented compound action (`accept and dedupe`, `merge similar`, etc.) — drives the user into a workflow the system doesn't support.
+
+If the rec set looks wrong, the right responses are: surface the anomaly explicitly, ask the user how to proceed, and consult `mcp__ritual__get_recommendation_attestation` for the quality audit's `duplicateTitlePrefixes` signal. Don't paper over with an invented action.
+
 ##### 9.1 — Landing screen: server-rendered preview (primary path)
 
 The recommendations review is the most-read screen in the whole build flow.
@@ -1569,6 +1706,16 @@ The recommendations review is the most-read screen in the whole build flow.
 
 The server controls the rendering shape (category numbering, R-IDs, titles-only, 78-col wrap, role-aware action hint). Your job is to print and look up — not to invent labels, re-group, or add commentary.
 
+**Rendering anti-pattern — DO NOT DO THIS:** the most-seen Step 9 regression is the agent printing the preview AND THEN free-form-listing the recs themselves as a bulleted summary "for the user's convenience." This is wrong on three axes:
+
+1. **Doubles the content** — preview already has titles + R-IDs + action hint at 78-col wrap. A second free-form list is redundant and pushes the action hint off-screen on small terminals.
+2. **Drops the R-IDs** — a free-form bullet list erases the stable `R{N}` references the user needs to reply with `accept R3` / `drill R7` / `comment R12`. The user then types `view 10` (positional) thinking that's stable; it's not.
+3. **Invents grouping labels** — free-form rendering tempts the agent to label groups as "Areas" or "matters" (already covered by the vocabulary anti-pattern above).
+
+If the user wants more detail than the preview shows, they use `drill R{N}` — that's what the action menu is for. Do not pre-empt their drill choice with a wall of free-form bullets.
+
+**"Many recs" rule — load-bearing for high-count sets**: when `response.uiPreview.stats.totalCount > 20`, the preview is **especially** the right surface to use; do NOT compensate by dumping the rec content inline. The server preview keeps high-count sets navigable (R-IDs + titles + compact category groups). If a 40+ rec set ever lands, the right reaction is to investigate WHY (single-flight regression? cap-enforcer bypass?) — see Stage A.2 audit signals via `get_recommendation_attestation` — not to add helpful free-form rendering on top.
+
 **Fallback path — if the preview tool is unavailable or returns a non-200**: render per the contract block below. The contract is the same shape the server uses, so a mismatch between server-rendered and agent-rendered output is unlikely. The fallback exists for older MCP servers that haven't deployed the preview endpoint yet.
 
 ```text
@@ -1907,6 +2054,73 @@ Returns the brief markdown + an `id` + `kgContextUsed` block. The brief is **ide
 
 You can ALSO call `get_build_brief_status` **proactively** before `generate_build_brief` — if `exists === true && status === 'READY'` and the hashes haven't changed, you've saved a write-tool roundtrip. Tradeoff: tiny read cost for skipping a maybe-slow write.
 
+##### 10b.5 — Verify brief assertions against the actual code
+
+**This step is mandatory, not opt-in.** The brief generator runs server-side and does NOT have repo access — it writes assertions about cited files / functions / classes based on the agent's earlier recon summary (which is text, not code). Brief assertions that contradict the actual code are invisible to the brief generator AND to the user reading the brief. Step 10b.5 closes that gap before the user is asked to approve the brief at Step 10d.
+
+This step is **SKILL-only — no MCP tool, no LLM cost on Ritual's API.** The verification happens locally in the calling agent because the agent is the one with repo access. The canonical instruction set is at `references/brief-verification-checklist.md` (methodology + output schema + worked example). This Step 10b.5 prose is the thin orchestration layer.
+
+Steps:
+
+1. **Tell the user what's about to happen** (one line, not a multi-line pre-roll):
+
+   > Verifying brief assertions against the actual codebase. Reading cited functions / classes / files, comparing against the brief's claims — about 20–60 seconds.
+
+2. **Read `references/brief-verification-checklist.md`** for the methodology, output schema, and verdict definitions. **Walk the methodology in order — do NOT skip to the output schema.**
+
+3. **Read `BUILD-BRIEF.md`** (the version just generated in Step 10a/10b but NOT YET written to disk — keep it in-memory; you'll write to disk AFTER verification at Step 10c). Extract every specific code citation: symbol + file + assertion. Cap at 15 citations (highest-leverage first).
+
+4. **For each citation, read the actual code** via Grep / Glob / Read. Assign a verdict per citation:
+   - `verified` — brief claim matches the code.
+   - `contradicted` — brief claim is wrong; the code does something different.
+   - `not_found` — symbol couldn't be located.
+
+5. **Write `BUILD-BRIEF-VERIFICATION.md`** to disk alongside `BUILD-BRIEF.md` using the schema in `references/brief-verification-checklist.md`. Cite file + line range + actual code snippet on every contradiction. Do not fabricate evidence.
+
+6. **Sync the verification to Ritual's KG** — call `mcp__ritual__sync_brief_review` with:
+
+   ```
+   {
+     exploration_id,
+     review_type: 'BRIEF_VERIFICATION',
+     content: <full BUILD-BRIEF-VERIFICATION.md markdown>,
+     cited_files: <union of every file path cited across the verification>,
+   }
+   ```
+
+   This persists the verification as a durable `BriefReview` row attached to the exploration. Future briefs on overlapping files will inherit the verified facts via `priorContext`; `/ritual lineage` on any cited file will surface this verification.
+
+7. **Print a compact CLI summary** (≤ 8 lines, CLI Tenet #1, #6):
+
+   ```text
+   ✓ Verification complete — `BUILD-BRIEF-VERIFICATION.md` on disk; synced to KG.
+
+   Verified: {N}  ·  Contradicted: {M}  ·  Not found: {K}
+
+   {If M > 0:}
+   Top contradictions:
+     ⚠ {cited_symbol} — brief says "{brief_assertion[0:60]}…"
+        actual: "{code_reality[0:60]}…"
+     ⚠ {next contradiction, if M > 1}
+   ```
+
+   Rules:
+   - **If M = 0 AND K = 0:** print one line, *"✓ Verification complete — N citations checked, all verified. `BUILD-BRIEF-VERIFICATION.md` synced."*
+   - **If M > 0:** print up to 3 top contradictions inline; rest are in the file. At the Step 10d gate, surface the contradictions count + note that plan mode will read them via KG priorContext.
+   - **If brief made zero citations:** print *"✓ Verification skipped — the brief makes no specific code citations to verify."* Skip the sync call (nothing to persist). Proceed to Step 10c.
+
+8. **Continue to Step 10c** with `BUILD-BRIEF.md` + `BUILD-BRIEF-VERIFICATION.md` both ready to write to disk and the verification synced to KG.
+
+**Step 10d integration:** when contradictions exist, Step 10d's gate prepends an inline summary so the user sees *what the agent learned about the brief* before they decide whether to proceed. The brief itself is NOT rewritten — it stays the historical artifact Ritual generated. The KG carries the truth via the synced `BriefReview` row, and **plan mode (Step 11.1) reads the brief + KG-persisted reviews via `priorContext`** so the implementation incorporates the corrections without the brief content needing to change.
+
+**Anti-patterns:**
+
+- ❌ Skipping Step 10b.5 because "the brief looks fine." Brief-quality is invisible from reading the brief alone — the verification compares against the code.
+- ❌ Treating the brief's hedge ("*may deviate if codebase has a stronger pattern*") as license to skip. The hedge means *"go verify"* — exactly what this step does.
+- ❌ Padding the `verified` list. Only enumerate citations the brief actually made.
+- ❌ Re-writing the brief at Step 10b.5. The verification produces findings; the brief stays as-is. Plan mode reconciles via KG priorContext.
+- ❌ Skipping the `sync_brief_review` call. The local `BUILD-BRIEF-VERIFICATION.md` alone benefits this session only; the KG sync is what lets future briefs on overlapping files inherit the verified facts.
+
 ##### 10c — Write to `BUILD-BRIEF.md` + CLI summary (CLI Tenet #1, #5)
 
 When the brief content is in hand (from generate OR polling), **don't dump 300 lines of markdown into the terminal**. The brief belongs in a file the user can open, search, share, and revisit; the CLI surface is for the decision.
@@ -1980,21 +2194,118 @@ Build brief ready
 `BUILD-BRIEF.md` is on disk. Skim the RBs + anchors, then decide:
 
   · `go` — ready to implement; move to coding
-  · `refine` — something's off; tell me what and I'll regenerate
   · `drill {N}` — drill into RB-{N} before deciding
 
-Reply `pause` to stop here.
+Before `go`, you can run `ux-review` for a design-quality pass on the brief (recommended for UI/UX features — produces `UX-REVIEW.md` and a tailored plan-mode prompt so plan mode stops asking you the same UX questions it always does). Reply `pause` to stop here.
 ```
 
 Branch by user response. Accept `go`, `y`, `yes`, `proceed`, `continue`, `next` as the visible-CTA path (do not display all aliases):
 
-- **`go` / proceed / yes / y**: continue to Step 11.
-- **`refine`**: ask what's off, then call `generate_build_brief` with `force: true` after applying their feedback to the exploration (typically a recommendation re-accept or a requirement adjustment via the web UI).
+- **`go` / proceed / yes / y**: continue to Step 11. Plan mode will read `BUILD-BRIEF.md` + any synced reviews (verify-brief from Step 10b.5; UX review from Step 10.5 if it ran) via KG `priorContext`. If verify-brief produced contradictions, plan mode picks them up there — the brief content itself stays as Ritual's historical artifact.
+- **`ux-review` / review / `ux`**: continue to Step 10.5 (writes `UX-REVIEW.md`, syncs it to KG via `sync_brief_review`, then continues to Step 11 with the tailored plan-mode prompt). Opt-in; absence is the existing path.
 - **`drill {N}`**: open RB-{N} in the markdown, discuss inline, then loop back to the gate above.
 - **`pause`**: stop here. The brief is on disk; the user can resume with `/ritual resume`.
 
+**No `refine` action at Step 10d.** The brief is read-only after generation. Two reasons:
+
+1. **Verification findings reach plan mode via KG, not via brief rewrites.** Step 10b.5 syncs `BriefReview` rows via `sync_brief_review`; plan mode reads them via `priorContext`. Re-rewriting the brief content adds LLM cost for zero implementation-correctness gain — the implementation is governed by plan mode + KG, not by the brief text itself.
+2. **The brief stays as the historical record** of what Ritual generated. If the user wants new content (because underlying recs / requirements actually changed), call `generate_build_brief` with `force: true` — that's full regen with new source data. Don't conflate that with editing existing brief content.
+
 **Pulse (Step 10 done):** Emit a pulse — this often crosses into **Implementation-ready** (90%+). Render full when that crossing happens. Use the build-brief celebration line: `✓ Build brief ready — discovery has become an implementation path.` If still below 90% (e.g. brief flagged residual debt), surface that in the pulse line itself and propose addressing it before coding.
 
+#### Step 10.5 — Optional UX brief review (entered ONLY when the user picks `ux-review` at Step 10d)
+
+This step is opt-in. If the user picked `go` at Step 10d, skip directly to Step 11. The `ux-review` path is reached only when the user explicitly asks for it at the Step 10d gate — there is no auto-gating in this MVP (later iterations may use Stage E's UI-surface classifier to suggest the path automatically; see `backlog_design_recon_stage_e.md`).
+
+Purpose: make the coding agent reason about the experience BEFORE it reasons about files. Plan mode otherwise interrogates the user for the same 10-question UX checklist on every UI-shaped feature. Paying for it once at the right moment — with the brief and the codebase both available — is cheaper than paying it implicitly through plan-mode interrogation.
+
+This step is **SKILL-only — no MCP tool, no LLM-cost on Ritual's API.** The analysis happens locally in the calling agent because the agent is the one with repo access. The reference `references/ui-ux-checklist.md` is the canonical instruction set (methodology + output schema + plan-mode prompt template); this Step 10.5 is the thin orchestration layer that drives the agent through it.
+
+Steps:
+
+1. **Tell the user what's about to happen** (one line, not a multi-line pre-roll):
+
+   > Running a design-quality pass on the brief. Reading `BUILD-BRIEF.md`, mining the repo for existing UI patterns, writing `UX-REVIEW.md` — about 30–60 seconds.
+
+2. **Read `references/ui-ux-checklist.md`** for the methodology, output schema, and plan-mode prompt template. **Walk the methodology in order — do not skip to the output schema.** The methodology's six steps (read brief → identify UI surfaces → find repo analogues → compare brief vs analogues → fill schema with evidence → generate tailored plan-mode prompt) are load-bearing; the output schema only gets filled correctly when the analysis upstream is done.
+
+3. **Read `BUILD-BRIEF.md`** end-to-end. Classify what it covers vs what it's silent on. The brief itself is the input signal — the review's value is on the gaps and codebase-grounding, not on re-deriving brief content.
+
+4. **Mine the repo for existing UI analogues.** Use Grep / Glob / Read against the implied UI surfaces from the brief. Cite file paths in the review; every claim must trace back to either a brief line or a real repo file. **Do not fabricate analogues** — if `Grep` returns nothing, the surface is "new work," not a hallucinated path.
+
+5. **Write `UX-REVIEW.md`** to disk alongside `BUILD-BRIEF.md` (same directory — repo root or `.ritual/`, whichever the brief landed in). Use the exact output schema from the reference file. Prepend the Ritual attribution header:
+
+   ```markdown
+   <!--
+   Generated by Ritual — UX brief review
+   Exploration: https://app.ritualapp.cloud/e/{exploration_id}
+   Source brief: BUILD-BRIEF.md
+   Do not remove this header; it preserves implementation lineage.
+   -->
+   ```
+
+   If a `UX-REVIEW.md` already exists:
+   - **Same exploration**: silent overwrite + one-line note in the summary.
+   - **Different exploration**: confirm before overwriting (same convention as `BUILD-BRIEF.md` in Step 10c — *"A `UX-REVIEW.md` already exists from `{previous}`. Overwrite, or save-to-`UX-REVIEW-{slug}.md`?"*).
+
+5a. **Sync the UX review to Ritual's KG** — call `mcp__ritual__sync_brief_review` with:
+
+   ```
+   {
+     exploration_id,
+     review_type: 'UX_REVIEW',
+     content: <full UX-REVIEW.md markdown>,
+     cited_files: <union of every file path cited across the review's Screen/Component, Design System Fit, and other sections>,
+   }
+   ```
+
+   Persists the UX review as a durable `BriefReview` row attached to the exploration. Plan mode reads it via `priorContext` so the plan-mode prompt's mismatches / gaps / new-work items are KG-grounded, not just session-local. `/ritual lineage` on any cited UI file surfaces this review.
+
+   **Anti-pattern:** skipping the sync because *"UX-REVIEW.md is right here on disk."* The local file benefits this session only; the KG sync is what lets future briefs / explorations on overlapping files inherit the findings.
+
+6. **Print a compact CLI summary** — the file path + the load-bearing findings only, capped at ≤ 10 lines (CLI Tenet #1, #6):
+
+   ```
+   ✓ UX review ready — `UX-REVIEW.md` is on disk.
+
+   Mismatches surfaced: {N}
+     {first mismatch one-liner — brief X vs analogue Y}
+     {second mismatch one-liner}
+
+   Gaps surfaced: {M}
+     {first gap one-liner — brief silent on Z, codebase default is W}
+
+   New-work surfaces: {K}
+     {first new-work surface one-liner}
+
+   Plan mode will read this first when you proceed to `go`.
+   ```
+
+   Rules:
+   - Cap each list at 3 entries. The full set is in the file.
+   - Omit any list that's empty (e.g. "Mismatches surfaced: 0" → don't print the line).
+   - If ALL THREE lists are empty: the brief is unusually complete. Print one line: *"Brief is unusually complete — no mismatches, gaps, or new-work surfaces. Plan mode will verify state coverage against codebase."*
+
+7. **Offer to open the file** — same OS-aware affordance as Step 10c (VS Code → idea → $EDITOR → macOS open). Single yes/no, never a multi-way picker.
+
+8. **Return to the Step 10d gate** with the updated framing — `UX-REVIEW.md` is now part of the implementation context:
+
+   ```text
+   Reply `go` to start implementation with the UX review as plan-mode input,
+   or `refine` / `drill {N}` / `pause` per the earlier options.
+   ```
+
+   When the user replies `go`, continue to Step 11 with the explicit instruction (passed to plan mode) to read both `BUILD-BRIEF.md` AND `UX-REVIEW.md`, and to use the "Plan Mode Prompt" block at the bottom of `UX-REVIEW.md` as its first numbered list — not a generic plan.
+
+**Anti-patterns to avoid in this step:**
+
+- **Don't render the full `UX-REVIEW.md` to the terminal.** It belongs in the file; the CLI surface is the summary plus the path.
+- **Don't auto-`go` after writing the file.** The user explicitly opted into the review — let them open the file and decide when to proceed.
+- **Don't enter plan mode mid-step.** Plan mode is Step 11. This step writes the artifact plan mode will read.
+- **Don't propose visual designs.** This is a planning packet, not a design tool. Where the codebase has no design system, surface that fact and route back to the user.
+
+**Pulse (Step 10.5 done):** Re-emit the Step 10 pulse if the review surfaced material gaps or mismatches — Readiness can dip back below 90% when significant UX work is flagged that the brief didn't capture. If the review came back clean (zero mismatches, zero gaps, zero new-work), keep the existing pulse — the brief was already implementation-ready.
+
 #### Step 11 — Implement
 
 This step happens **inside** the same `/ritual build` chat if the agent is also the coding agent (Claude Code / Cursor / etc.), or hand-off if the user is implementing themselves.
@@ -2045,7 +2356,7 @@ Next: I'll create a feature branch, then start on RB-1.
 
 ##### 11.1 — Implement
 
-1. Take the build brief as input.
+1. Take the build brief as input. **If `UX-REVIEW.md` also exists alongside `BUILD-BRIEF.md` (the user opted into Step 10.5), read it too.** When both files are present, use the "Plan Mode Prompt" block at the bottom of `UX-REVIEW.md` as the FIRST input to plan mode — its numbered list of mismatches / gaps / new-work surfaces is the tailored agenda. The generic plan-mode template is the fallback for when only the brief exists.
 2. Use the standard coding-loop tools (Edit/Write/Bash/etc.) to make the code change.
 3. Run tests, lint, build per the repo's conventions.
 4. Track each architectural decision as you go — the input to Step 12's `sync_implementation` call. Per decision, write down: `area`, `choice`, `alternatives_considered`, `rationale`, `source_recommendation_id` (the RB-N or recommendation id the decision implements). This is what makes lineage queryable later — don't skip it.
@@ -2291,7 +2602,7 @@ Or: re-run `/ritual build` in this workspace later — the existing-work check w
 
 ### Tools used
 
-This subcommand exclusively uses vNext MCP tools, in the order they appear:
+This subcommand exclusively uses Ritual MCP tools, in the order they appear:
 
 1. `mcp__ritual__list_workspaces` (Step 1)
 2. `mcp__ritual__create_workspace` (Step 1, only if no workspace exists)
@@ -2322,11 +2633,12 @@ This subcommand exclusively uses vNext MCP tools, in the order they appear:
 23. `mcp__ritual__get_requirement_set_status` (Step 9.5 polling)
 24. `mcp__ritual__generate_build_brief` (Step 10a)
 24a. `mcp__ritual__get_build_brief_status` (Step 10b — timeout-recovery polling, OR proactive cache-hit check before 10a)
+24d. `mcp__ritual__sync_brief_review` (Step 10b.5 — sync `BUILD-BRIEF-VERIFICATION.md` to KG; AND Step 10.5 — sync `UX-REVIEW.md` to KG)
 24b. `mcp__ritual__add_knowledge_source` (Step 3.5 — register PRDs / tickets / transcripts / etc. provided by the user)
 24c. `mcp__ritual__list_knowledge_sources` (used inline by Step 3.5 to show already-attached refs on resume; also called by `/ritual context-pulse` CP2 for Reference Grounding count)
 25. `mcp__ritual__sync_implementation` (Step 12)
 
-32 of the 43 vNext tools. The other 11 (`ping`, `get_exploration`, `list_agentic_runs`, `add_collaborator`, `check_anti_goals`, `query_knowledge_graph`, `get_workspace_overview`, `get_knowledge_source`, `remove_knowledge_source`, `get_recommendation_attestation`, `score_context_pulse`) are situational, not part of the linear build flow.
+33 of the 44 Ritual MCP tools. The other 11 (`ping`, `get_exploration`, `list_agentic_runs`, `add_collaborator`, `check_anti_goals`, `query_knowledge_graph`, `get_workspace_overview`, `get_knowledge_source`, `remove_knowledge_source`, `get_recommendation_attestation`, `score_context_pulse`) are situational, not part of the linear build flow.
 
 ### After this subcommand