@ritualai/cli 0.7.14 → 0.7.15

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

@@ -85,25 +85,47 @@ If exactly one in-flight exploration is recent and clearly the likely target, le
 >
 > Resume this? (Y/n, or `list`)
 
-If there are multiple plausible targets, group by state badge and show:
+If there are multiple plausible targets, group by state badge and show. **One picker number per exploration; continuation prose is plain text under it, never its own list item.** Use the exact shape below:
 
 > Here's what you have in flight in **{workspace.name}**:
 >
-> **📍 still in discovery** (1)
-> - **{name}** — {first 80 chars of problemStatement}
->   *Last touched {N} {days/hours} ago. Next: continue sub-problem generation.*
+> **📍 still in discovery** ({count})
 >
-> **💬 waiting on admin to accept recommendations** (2)
-> - **{name}** — {…}
->   *Last touched {N} days ago. Next: admin reviews + accepts in Step 9.*
-> - **{name}** — {…}
->   *…*
+> 1. **{name}** — {first 80 chars of problemStatement}
+>    Last touched {N} {days/hours} ago. Next: continue sub-problem generation.
 >
-> **✅ ready for build brief** (1)
-> - **{name}** — {…}
->   *Last touched {N} days ago. Next: generate the build brief.*
+> **💬 waiting on admin to accept recommendations** ({count})
 >
-> **Which one do you want to resume? (give me the number/name, or "none" to exit)**
+> 2. **{name}** — {…}
+>    Last touched {N} days ago. Next: admin reviews + accepts in Step 9.
+> 3. **{name}** — {…}
+>    Last touched {N} days ago. Next: …
+>
+> **✅ ready for build brief** ({count})
+>
+> 4. **{name}** — {…}
+>    Last touched {N} days ago. Next: generate the build brief.
+>
+> **Which one do you want to resume? Reply with the number, the name, or `none` to exit.**
+
+**Rendering anti-pattern (load-bearing) — observed 2026-05-15:**
+
+- ❌ Numbering the SAME exploration's continuation lines (summary, "Last touched", "Next") as separate numbered items:
+  ```text
+  1. Social shopping — activate wishlist sharing
+  1. Activate dormant wishlist sharing primitives...
+  1. Last touched ~10 min ago. Next: generate the build brief.
+  2. Join while booking — post-order account claim
+  2. Post-checkout account creation flow...
+  2. Last touched ~2 hours ago. Next: admin reviews + accepts.
+  ```
+  Three `1.` lines + three `2.` lines is wrong. **Each exploration gets ONE picker number on its title line. The summary, last-touched, and next-action lines belong to that exploration as indented continuation prose — never their own numbered or bulleted entries.**
+
+- ❌ Using `-` bullets for explorations when the picker tells the user "reply with the number." Bullets have no numbers; the user can't say "I pick `-`."
+
+- ❌ Restarting the picker count at each state bucket (`1.` under "still in discovery", then `1.` again under "waiting on admin"). Numbering is **flat across all buckets** so a single number unambiguously identifies one exploration.
+
+**The correct shape is exactly:** state-bucket header → blank line → `{N}. **{name}** — {summary}` → indented continuation prose (2-space indent, no leading marker) → blank line before next exploration. State-bucket count in parens `({count})` is informational and is NEVER a picker number.
 
 State badge → user-facing label + suggested next step (same table as `/ritual build` Step 1.5):
 

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

@@ -0,0 +1,94 @@
+## /ritual status
+
+Thin in-chat mirror of the terminal CLI command `ritual status [--watch]` (CLI 0.7.14+).
+
+The CLI is the primary affordance for the "I walked away from this run; let me check on it" case — it works from any terminal, survives this agent session closing, and supports `--watch` for live tail. **This SKILL subcommand exists for the orthogonal case:** the user is still in the agent session, wants a quick status snapshot, and doesn't want to context-switch to a separate terminal.
+
+Same content, two surfaces. Pick whichever fits the user's flow.
+
+### When to use this vs. the terminal CLI
+
+| Context | Use |
+|---|---|
+| User is in chat with you and types `/ritual status` | This SKILL subcommand. |
+| User is mid-run and walks away | Tell them about `ritual status --watch` in a separate terminal. Their session can close; the CLI keeps tailing. |
+| User wants to script status / pipe to other tools | Terminal CLI. The SKILL is render-only; the CLI prints to stdout with proper exit codes. |
+| User asks "what's happening?" without typing the slash | Plain English answer — call `mcp__ritual__get_agentic_run` and respond naturally. Don't gratuitously invoke this subcommand. |
+
+### Steps
+
+#### Step S1 — Resolve the run
+
+The subcommand can be invoked three ways:
+
+1. **`/ritual status`** (no arg) — auto-resolve the current run from workspace context:
+   - If `.ritual/config.json` is bound (i.e. `/ritual init` was run in this repo), load `workspaceId` from there.
+   - Call `mcp__ritual__list_explorations(workspace_id)`, sort by `updatedAt` desc.
+   - For each of the top 5 most-recently-updated, call `mcp__ritual__list_agentic_runs(exploration_id, status='RUNNING', limit=1)` until one returns a run.
+   - If none has a RUNNING run, fall back to the most-recently-updated exploration with step != `COMPLETED`.
+   - If no workspace is bound to the project, ask the user for an exploration id or to run `/ritual init` first.
+
+2. **`/ritual status <exploration-id>`** — skip auto-resolve, fetch that exploration directly.
+
+3. **`/ritual status --runs`** — list every RUNNING agentic run across the workspace (multi-run case). Render as a numbered picker.
+
+#### Step S2 — Fetch state
+
+Call in parallel:
+
+- `mcp__ritual__get_exploration(exploration_id)` → exploration name, step, updatedAt, agenticProgress.
+- `mcp__ritual__get_agentic_run(run_id)` IF a RUNNING run was found — gives live progress + run id + status. Read from the **merged view** the MCP tool returns; never from raw `agentic_jobs.totalQuestions` or `agentic_jobs.progress.steps` directly (those fields have a known unwritten-for-`full_exploration_v1` bug).
+
+#### Step S3 — Render the run-first layout
+
+Mirror the terminal CLI exactly. Run line first, exploration name as a footer parenthetical:
+
+```text
+Run        ba4d2b42-…  ·  RUNNING for 17m 41s
+Phase      answering  (58%)
+Questions  42 / 67  ·  0 failed
+Activity   last DB write 1m 12s ago
+Pace       ~14s/question  ·  ETA ~5m 50s remaining
+Next       Recommendations (auto-advances when questions are done)
+
+(Exploration: Join while booking — post-order account claim)
+  51f16182-…  ·  step: DEVELOPING_ANSWERS
+```
+
+Rendering rules:
+
+- **Run line first.** "RUNNING for 17m 41s" is the headline.
+- **Pace + ETA** computed client-side from `(now - run.startedAt) / progress.completedQuestions × (totalQuestions - completedQuestions)`. Only show when `completedQuestions >= 3` — below that, render `Pace       warming up — check back in 30s`.
+- **Activity** is the freshness signal — if `last write` has been climbing past ~3 min without `completedQuestions` advancing, that's actionable info. Surface it plainly; do not invent a "stuck" diagnosis (that's `RecStallSweeper`'s job, server-side).
+- **Next line** is heuristic based on `progress.phase`:
+  - `answering` → `Recommendations (auto-advances when questions are done)`
+  - `submitting` → `Recommendations`
+  - `recommendations` → `Build brief (after admin review)`
+  - `complete` / `failed` → `—`
+  - any unknown → omit the line entirely
+- **No run, but progress data exists** (run completed or never started): render `Run        (no active run)` + phase + Activity. Useful when the user types `/ritual status` after a run finished.
+- **No run, no progress**: render `Run        (no run started yet)` + Step + Activity.
+
+#### Step S4 — Wrap up
+
+After rendering, the agent's job is done. Do NOT auto-poll, do NOT enter a watch loop inside the chat. The CLI's `--watch` is the live-tail surface; this SKILL is a snapshot.
+
+If the user wants to check again, they type `/ritual status` again. The agent re-runs S1–S3 from scratch.
+
+### Tools used
+
+Read-tier subset of the build-flow tools:
+
+1. `mcp__ritual__list_explorations` (auto-resolve)
+2. `mcp__ritual__list_agentic_runs` (find RUNNING)
+3. `mcp__ritual__get_exploration` (S2 — name + step + progress)
+4. `mcp__ritual__get_agentic_run` (S2 — merged live view)
+
+No new MCP tools required. `/ritual status` is a thin orchestration over what already exists.
+
+### Anti-patterns
+
+- **Don't introduce a "watch" mode inside this SKILL.** The terminal CLI's `--watch` is the live-tail surface. Re-implementing it in chat doubles the affordance and creates polling loops that survive past the user's intent.
+- **Don't render raw `agentic_jobs` fields.** `AgenticJob.totalQuestions` and `progress.steps[*].status` are not written for `full_exploration_v1` runs. Reading them directly produces the "all-pending" snapshot lie surfaced 2026-05-15. The merged view returned by `get_agentic_run` is the only correct source.
+- **Don't synthesize ETA from `progress.percent` alone.** Use the question-count math (`completedQuestions / elapsed × remaining`) because it's more accurate than the coarse percent rounded up at major step boundaries.
+- **Don't gratuitously invoke this subcommand.** If the user asks "what's happening?" without typing `/ritual status`, just answer in plain English using `get_agentic_run`. The slash-command is for explicit status snapshots, not for every progress question.

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

@@ -1,4 +1,4 @@
 {
-  "cliVersion": "0.7.14",
-  "builtAt": "2026-05-15T16:06:46.162Z"
+  "cliVersion": "0.7.15",
+  "builtAt": "2026-05-19T15:51:30.453Z"
 }

package/skills/cursor/ritual/DESIGN.md

@@ -20,7 +20,7 @@ The split version keeps:
 
 ## Retired `/ritual recon`
 
-`/ritual recon` is intentionally not part of the vNext command surface. Its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and its repo-reading behavior is normal coding-agent behavior in plain English.
+`/ritual recon` is intentionally not part of the Ritual command surface. Its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and its repo-reading behavior is normal coding-agent behavior in plain English.
 
 ## Context packet principle
 

package/skills/cursor/ritual/SKILL.md

@@ -18,6 +18,36 @@ Before executing any subcommand, read and follow:
 
 Do not reintroduce `/ritual recon`. Use plain-language repo inspection, `/ritual resume`, or `/ritual lineage` depending on intent.
 
+## Contract strength — load-bearing for all subcommands
+
+Every section in this SKILL or its reference files labeled **load-bearing**, **forbidden behavior**, **anti-pattern**, **rendering contract**, or **fire-on-trigger** is **contract-strength**, not guidance.
+
+If this SKILL says *"DO NOT do X"*, your default action is to not do X. You may not override based on your in-the-moment assessment that X would be:
+
+- helpful
+- clearer
+- shorter
+- more convenient
+- *"obviously what the user really wants"*
+- *"a small improvement on top of the SKILL's contract"*
+
+When a local example or your own instinct conflicts with a contract-strength rule, **the contract wins.** Re-read the rule. Trust that the prior version of you also thought the override "feels right" — that's exactly the case the contract exists to prevent.
+
+When two contract-strength rules genuinely conflict (rare): **stop, surface the conflict to the user, and ask which to honor.** Do not improvise a resolution.
+
+This rule is the meta-pattern that closes the failure class we kept hitting before 2026-05-15: the SKILL named the right behavior in each step (Step 7 picker, Step 9 preview-verbatim, Step 9 action menu, picker numbering, etc.), but the agent treated the prose as advisory and freelanced anyway. Anti-patterns are **executable constraints, not taste guidance.** When an anti-pattern says "agent must NOT", read it as a hard error, not a preference.
+
+Examples of contract-strength rules currently in force (non-exhaustive):
+
+- `references/build-flow.md` Step 7 transition lock — must NOT skip the Areas picker, must call `accept_discovery_questions` before `start_agentic_run`.
+- `references/build-flow.md` Step 7.3.1 rendering contract — Areas index has NO question previews, single numbering stream.
+- `references/build-flow.md` Step 7.4.5 fire-on-trigger — scope-classification gate is the contract, not a suggestion.
+- `references/build-flow.md` Step 9 action menu lock — blessed set is exactly `accept recommended` / `drop R{N}` / `drill R{N}` / `comment R{N}` / `pause` (+ `request admin review` for collaborators). NO freelance `dedupe` / `open the admin` / invented compound actions.
+- `references/build-flow.md` Step 9 rendering — use the server preview verbatim; no free-form summarization on top.
+- `references/resume-flow.md` § R2 picker rendering — ONE picker number per exploration; continuation prose indented; flat numbering across state buckets.
+
+When you encounter a rule labeled with any of the marker words above, treat it the same way you'd treat a unit-test assertion: violating it is a regression, not a stylistic choice.
+
 ## Routing
 
 Parse the first token of the argument:
@@ -28,9 +58,10 @@ Parse the first token of the argument:
 | `resume` | `references/resume-flow.md` | "Pick up where I left off." Lists in-flight explorations with state badges and jumps to the right step. |
 | `lineage` | `references/lineage-flow.md` | Paste a file path (or set of paths); see every prior exploration / decision / deferral that touched those files. |
 | `context-pulse` | `references/context-pulse-flow.md` | Score readiness / context debt for a feature ask or exploration. Can seed a `CONTEXT-<feature>.md` file with relevant codebase + KG context that `/ritual build` picks up automatically. Also surfaces inline during build so the user watches debt drop. |
+| `status` | `references/status-flow.md` | Read-only mirror of the `ritual status` terminal CLI command (CLI 0.7.14+) for users who want a quick run-progress check inside the agent session instead of in a separate terminal. Calls `mcp__ritual__get_agentic_run` + renders the same run-first layout the CLI uses. |
 | (anything else, OR no subcommand) | default to `build` and treat the entire argument as the problem statement | |
 
-The vNext CLI surface is intentionally **just these four**. Legacy exposed `explore`, `run`, `brief`, `gate`, `spec`, `questions`, `gherkin`, `status`, `recs` — all of which mapped 1:1 to MCP tool calls and provided no agent-CLI value over plain English. We don't replicate them; the agent can call any MCP tool directly when the user asks for "the recs on exp-X" or "status of exp-Y". (`/ritual recon` shipped briefly in PR #174 as a fifth command — retired in this PR because its unique value duplicated `/ritual resume` (workspace history) + `/ritual lineage` (decisions on files), and its non-duplicate parts (map repo, trace flow, explain file) are exactly what the agent does fluently in plain English without needing a SKILL-defined menu.)
+The Ritual CLI surface is intentionally narrow: `build`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror. Legacy exposed `explore`, `run`, `brief`, `gate`, `spec`, `questions`, `gherkin`, `recs` — all of which mapped 1:1 to MCP tool calls and provided no agent-CLI value over plain English. We don't replicate them; the agent can call any MCP tool directly when the user asks for "the recs on exp-X" or "decisions on file Y". (`/ritual recon` shipped briefly in PR #174 as a fifth command — retired because its unique value duplicated `/ritual resume` (workspace history) + `/ritual lineage` (decisions on files), and its non-duplicate parts (map repo, trace flow, explain file) are exactly what the agent does fluently in plain English without needing a SKILL-defined menu.)
 
 
 ## Subcommand reference files
@@ -67,5 +98,31 @@ When the user says things like *"what's the status of exp-X?"*, *"show me the re
 | Kick off / re-run the agentic pipeline | `mcp__ritual__start_agentic_run(exploration_id, …)` |
 | Did anyone implement something on these files? | `mcp__ritual__query_knowledge_graph(sources=[…])` — same plumbing as `/ritual lineage` |
 
-This is intentional. Legacy exposed each of these as its own slash-command (`/ritual status`, `/ritual recs`, `/ritual run`) and the surface area ballooned without adding agent value. In vNext we keep the slash-commands narrow (`build`, `resume`, `lineage`, `context-pulse`) and let the agent fluently call MCP tools for everything else. Do not reintroduce `/ritual recon`: its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and repo-reading behaviors are normal coding-agent behavior in plain English.
+This is intentional. Legacy exposed each of these as its own slash-command (`/ritual recs`, `/ritual run`, etc.) and the surface area ballooned without adding agent value. We keep the slash-commands narrow (`build`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror) and let the agent fluently call MCP tools for everything else. Note: `/ritual status` is the one deliberate exception — it exists as a thin SKILL mirror of the terminal CLI command so users who want an in-chat status check don't have to context-switch to a separate terminal. Do not reintroduce `/ritual recon`: its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and repo-reading behaviors are normal coding-agent behavior in plain English.
+
+---
+
+## Before this skill is installed — bootstrap context
+
+This SKILL only governs behavior **after** `ritual init` has run and the
+`/ritual` skill has been copied into the agent's skills directory. Before
+that, the agent has no Ritual-specific instructions in scope.
+
+If you are reading this file by browsing the repo, or as part of a
+post-mortem on why a user's "set up Ritual MCP" request went sideways:
+the **pre-install** instruction surface lives in three places, in priority
+order:
+
+1. **`learn.ritual.work/llms.txt`** — canonical machine-readable bootstrap script. Served as plain text. WebFetch-safe.
+2. **`ritual.work/llms.txt`** — identical bytes to (1). Served from the marketing site so an agent handed any `ritual.work/...` URL can find it without knowing about `learn.ritual.work`.
+3. **`apps/cli/README.md`** in this repo (ships to npmjs.com via `@ritualai/cli`) — has the same "AI coding agents: start here" block at the top.
+
+All three sources must say the same thing. The canonical content is the
+7-step `npm install -g @ritualai/cli` → `ritual init` → `ritual doctor`
+→ restart-agent → verify-MCP → `/ritual build` flow, with explicit
+"do not ask the user about their project until init succeeds" rules.
+
+When updating one, update all three. The cross-repo sync is intentional
+duplication — agents need the bootstrap visible at whichever URL they
+happen to be handed.
 

package/skills/cursor/ritual/manifest.json

@@ -1,13 +1,13 @@
 [
   {
     "path": "DESIGN.md",
-    "lines": 36,
-    "bytes": 2226
+    "lines": 35,
+    "bytes": 2227
   },
   {
     "path": "SKILL.md",
-    "lines": 72,
-    "bytes": 5915
+    "lines": 102,
+    "bytes": 9156
   },
   {
     "path": "agents/openai.yaml",
@@ -21,8 +21,13 @@
   },
   {
     "path": "references/build-flow.md",
-    "lines": 2466,
-    "bytes": 148766
+    "lines": 2652,
+    "bytes": 165455
+  },
+  {
+    "path": "references/brief-verification-checklist.md",
+    "lines": 169,
+    "bytes": 10820
   },
   {
     "path": "references/cli-output-contract.md",
@@ -46,14 +51,19 @@
   },
   {
     "path": "references/resume-flow.md",
-    "lines": 157,
-    "bytes": 9950
+    "lines": 225,
+    "bytes": 14048
   },
   {
     "path": "references/scoring-fallback.md",
     "lines": 126,
     "bytes": 6494
   },
+  {
+    "path": "references/status-flow.md",
+    "lines": 94,
+    "bytes": 6096
+  },
   {
     "path": "references/ui-ux-checklist.md",
     "lines": 198,

package/skills/cursor/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.