@ritualai/cli 0.7.14 → 0.7.15

package/skills/kiro/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
@@ -1432,8 +1489,11 @@ 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.
 
-Live progress:
-  ritual status --watch
+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
@@ -1447,13 +1507,21 @@ 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
+  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
 ```
 
-The two affordances (`ritual status --watch` from a second terminal, `/ritual resume` later) are NOT modes the user has to opt into — they're the natural escape hatches the user can reach for without re-engaging this session. Do not introduce a `reply watch` mode in this SKILL; the CLI command IS the watch affordance.
+**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
 
@@ -1461,7 +1529,7 @@ Poll `mcp__ritual__get_agentic_run(run_id)` using `references/async-polling.md`:
 
 **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. Use `ritual status --watch` if you want to follow along live.
+> 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:
 
@@ -1578,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.
@@ -1616,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
@@ -1954,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.
@@ -2027,7 +2194,6 @@ 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
 
 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.
@@ -2035,12 +2201,16 @@ Before `go`, you can run `ux-review` for a design-quality pass on the brief (rec
 
 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.
-- **`ux-review` / review / `ux`**: continue to Step 10.5 (writes `UX-REVIEW.md`, then continues to Step 11 with the tailored plan-mode prompt). Opt-in; absence is the existing path.
-- **`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)
@@ -2078,6 +2248,21 @@ Steps:
    - **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):
 
    ```
@@ -2417,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)
@@ -2448,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
 

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