@ritualai/cli 0.7.13 → 0.7.14

package/dist/commands/status.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statusCommand = statusCommand;
+const config_1 = require("../lib/config");
+const api_client_1 = require("../lib/api-client");
+const project_config_1 = require("../lib/project-config");
+const status_formatter_1 = require("../lib/status-formatter");
+async function statusCommand(explorationIdArg, options) {
+    const token = await (0, config_1.getValidAccessToken)();
+    if (token.kind === 'not-signed-in') {
+        console.error('  ✗ Not signed in. Run `ritual login` first.');
+        process.exit(1);
+    }
+    if (token.kind === 're-auth-required') {
+        console.error(`  ✗ Session expired (${token.reason}). Run \`ritual login\` to re-auth.`);
+        process.exit(1);
+    }
+    const api = new api_client_1.ApiClient({
+        issuer: token.creds.issuer,
+        accessToken: token.accessToken,
+    });
+    if (options.watch) {
+        await runWatchLoop(api, explorationIdArg);
+    }
+    else {
+        await runOnce(api, explorationIdArg);
+    }
+}
+async function runOnce(api, explorationIdArg) {
+    const inputs = await fetchStatus(api, explorationIdArg);
+    if (!inputs) {
+        // Already printed a friendly error in fetchStatus.
+        process.exit(1);
+    }
+    console.log((0, status_formatter_1.formatStatus)(inputs));
+}
+/**
+ * --watch loop. Renders the status snapshot every 5s, in-place using
+ * ANSI cursor controls. Exits on:
+ *   - terminal run states (`completed` / `failed` / `cancelled`)
+ *   - the user pressing Ctrl+C
+ *   - 3 consecutive fetch errors (no point thrashing if the API is down)
+ *
+ * Cadence locked at 5s — short enough to feel live, polite enough not
+ * to hammer the API on a long-running poll.
+ */
+async function runWatchLoop(api, explorationIdArg) {
+    let lastRenderedLines = 0;
+    let consecutiveErrors = 0;
+    const POLL_MS = 5000;
+    const stop = (code) => {
+        process.stdout.write('\n');
+        process.exit(code);
+    };
+    process.on('SIGINT', () => stop(130));
+    // First render: print fresh, no clear.
+    while (true) {
+        let inputs = null;
+        try {
+            inputs = await fetchStatus(api, explorationIdArg);
+            consecutiveErrors = 0;
+        }
+        catch (err) {
+            consecutiveErrors += 1;
+            if (consecutiveErrors >= 3) {
+                console.error(`\n  ✗ Repeated errors fetching status (${err.message}). Exiting watch.`);
+                process.exit(1);
+            }
+        }
+        if (inputs) {
+            const rendered = (0, status_formatter_1.formatStatus)(inputs);
+            if (lastRenderedLines > 0) {
+                // Move cursor up by the previous render's line count + clear from there.
+                process.stdout.write(`\x1b[${lastRenderedLines}A\x1b[0J`);
+            }
+            process.stdout.write(rendered + '\n');
+            lastRenderedLines = rendered.split('\n').length + 1;
+            // Exit if run reached a terminal state.
+            const status = inputs.run?.status?.toLowerCase();
+            if (status === 'completed' || status === 'completed_with_errors') {
+                process.stdout.write('\n  ✓ Run finished. Exiting watch.\n');
+                process.exit(0);
+            }
+            if (status === 'failed') {
+                process.stdout.write('\n  ✗ Run failed. Exiting watch.\n');
+                process.exit(1);
+            }
+            if (status === 'cancelled') {
+                process.stdout.write('\n  · Run cancelled. Exiting watch.\n');
+                process.exit(0);
+            }
+        }
+        await sleep(POLL_MS);
+    }
+}
+async function fetchStatus(api, explorationIdArg) {
+    let explorationId;
+    if (explorationIdArg) {
+        explorationId = explorationIdArg;
+    }
+    else {
+        // Auto-resolve from .ritual/config.json.
+        const project = (0, project_config_1.loadProjectConfig)(process.cwd());
+        if (!project) {
+            console.error('  ✗ No `.ritual/config.json` in this directory. Either:\n' +
+                '      ritual init                              — bind a workspace to this repo, OR\n' +
+                '      ritual status <exploration-id>           — fetch a specific exploration');
+            return null;
+        }
+        const picked = await pickCurrentExploration(api, project.workspaceId);
+        if (!picked) {
+            console.error(`  ✗ No active or recent explorations found in workspace ${project.workspaceName}.`);
+            return null;
+        }
+        explorationId = picked;
+    }
+    // Fetch exploration shell + agentic-status + run in parallel.
+    const [exp, agenticStatus, runs] = await Promise.all([
+        api
+            .get(`/explorations/${encodeURIComponent(explorationId)}`)
+            .catch((err) => {
+            if (err.status === 404) {
+                console.error(`  ✗ Exploration ${explorationId} not found.`);
+                return null;
+            }
+            throw err;
+        }),
+        api
+            .get(`/explorations/${encodeURIComponent(explorationId)}/agentic-status`)
+            .catch(() => null),
+        api
+            .get(`/agentic-runs?exploration_id=${encodeURIComponent(explorationId)}&status=running`)
+            .catch(() => []),
+    ]);
+    if (!exp)
+        return null;
+    const run = runs && runs.length > 0
+        ? { id: runs[0].agentic_run_id, status: runs[0].status }
+        : null;
+    return {
+        exploration: {
+            id: exp.id,
+            name: exp.name,
+            step: exp.step,
+            updatedAt: exp.updatedAt,
+        },
+        progress: agenticStatus?.progress ?? null,
+        run,
+    };
+}
+/**
+ * Pick the "current" exploration for `ritual status` with no arg.
+ *
+ * Ranking:
+ *   1. Any exploration with a RUNNING agentic run → return its id.
+ *   2. Else most-recently-updated where step != COMPLETED.
+ *   3. Else most-recently-updated full stop.
+ *
+ * Multiple RUNNING runs is uncommon. For v1 we pick whichever the API
+ * returns first (most-recently-started in practice); a multi-run picker
+ * can land in MVP-2 with `ritual status --runs`.
+ */
+async function pickCurrentExploration(api, workspaceId) {
+    const exps = await api.get(`/explorations?workspaceId=${encodeURIComponent(workspaceId)}&withImplementationStatus=true`);
+    if (!exps || exps.length === 0)
+        return null;
+    // Probe for a RUNNING run across explorations. Sorted by updatedAt
+    // desc first so the most recently-touched exploration gets the
+    // first run-probe — usually the right answer in one call.
+    const sorted = [...exps].sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+    for (const e of sorted.slice(0, 5)) {
+        try {
+            const runs = await api.get(`/agentic-runs?exploration_id=${encodeURIComponent(e.id)}&status=running`);
+            if (runs && runs.length > 0)
+                return e.id;
+        }
+        catch {
+            // fall through — never block on a probe failure
+        }
+    }
+    // No RUNNING runs — pick most-recently-updated non-completed.
+    const nonComplete = sorted.find((e) => e.step !== 'COMPLETED');
+    if (nonComplete)
+        return nonComplete.id;
+    return sorted[0]?.id ?? null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=status.js.map

package/dist/commands/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -8,6 +8,14 @@ const whoami_1 = require("./commands/whoami");
 const refresh_1 = require("./commands/refresh");
 const init_1 = require("./commands/init");
 const doctor_1 = require("./commands/doctor");
+// 2026-05-15 (PR D) — `ritual status [--watch]` instant snapshot of
+// an in-flight agentic run. Auto-resolves the current exploration
+// from `.ritual/config.json` so the user doesn't have to remember
+// IDs; --watch polls every 5s and redraws in place. Paired with the
+// SKILL Step 8 reframe ("you're unblocked; runs continue server-
+// side") to break the mental model where users feel obligated to
+// stare at the polling loop.
+const status_1 = require("./commands/status");
 const graph_1 = require("./commands/graph");
 const package_info_1 = require("./lib/package-info");
 // 2026-05-15 (PR C) — pre-flight one-line stderr warning when the
@@ -61,6 +69,13 @@ program
     .command('refresh')
     .description('Force-refresh the cached access token using the stored refresh token')
     .action(refresh_1.refreshCommand);
+program
+    .command('status')
+    .description('Show the current agentic run status. With --watch, polls every 5s and redraws in place. ' +
+    'With no exploration ID, auto-resolves the workspace\'s currently-active run.')
+    .argument('[exploration-id]', 'Specific exploration to inspect (defaults to the current run)')
+    .option('--watch', 'Poll every 5s and redraw in place; exits on terminal state or Ctrl+C')
+    .action((explorationId, opts) => (0, status_1.statusCommand)(explorationId, { watch: opts.watch }));
 program
     .command('doctor')
     .description('Sanity check the CLI environment: credentials, endpoints, detected agents')

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/status-formatter.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Pure formatter for `ritual status` output.
+ *
+ * Kept as a side-effect-free function so it can be unit-tested in
+ * isolation without HTTP / filesystem / clock mocks. The command
+ * orchestration in `commands/status.ts` does the fetching; this just
+ * turns shapes into strings.
+ *
+ * Design choices (locked in `backlog_ritual_status_and_unblocked_framing.md`):
+ *
+ *   - Run line first. "RUNNING for 17m 41s" is the headline; exploration
+ *     name is a footer parenthetical, not the lead.
+ *   - Pace + ETA computed only when `completedQuestions >= 3` so the
+ *     average doesn't get whiplashed by the first question's latency.
+ *   - Activity / last-write age is the real "is it actually moving?"
+ *     signal — climbing past ~3 min without `completedQuestions`
+ *     advancing is actionable info, not a snapshot lie.
+ *
+ * The shape this formatter consumes is the merged view (live progress
+ * from `Exploration.agenticProgress` + run id from
+ * `GET /agentic-runs?explorationId=...&status=RUNNING&limit=1`), never
+ * the raw `AgenticJob` row whose `totalQuestions` / `progress.steps`
+ * fields can sit unwritten for entire runs (bug filed
+ * 2026-05-15 — see `backlog_ritual_status_and_unblocked_framing.md`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatStatus = formatStatus;
+exports.humanizeDuration = humanizeDuration;
+function formatStatus(input) {
+    const now = (input.now ?? new Date()).getTime();
+    const lines = [];
+    if (input.run && input.progress) {
+        lines.push(...formatRunSection(input.run, input.progress, input.exploration, now));
+    }
+    else if (input.progress) {
+        lines.push(...formatNoRunButProgress(input.progress, input.exploration, now));
+    }
+    else {
+        lines.push(...formatNoProgress(input.exploration));
+    }
+    lines.push('');
+    lines.push(`(Exploration: ${input.exploration.name})`);
+    lines.push(`  ${input.exploration.id}  ·  step: ${input.exploration.step}`);
+    return lines.join('\n');
+}
+function formatRunSection(run, progress, exploration, now) {
+    const runShort = truncateId(run.id);
+    const ageSec = progress.startedAt
+        ? Math.round((now - new Date(progress.startedAt).getTime()) / 1000)
+        : null;
+    const runLine = ageSec != null
+        ? `Run        ${runShort}  ·  ${run.status.toUpperCase()} for ${humanizeDuration(ageSec)}`
+        : `Run        ${runShort}  ·  ${run.status.toUpperCase()}`;
+    const phaseLine = formatPhaseLine(progress);
+    const questionsLine = formatQuestionsLine(progress);
+    const activityLine = formatActivityLine(exploration.updatedAt, now);
+    const paceLine = formatPaceLine(progress, now);
+    const nextLine = formatNextLine(progress);
+    const out = [runLine, phaseLine];
+    if (questionsLine)
+        out.push(questionsLine);
+    out.push(activityLine);
+    if (paceLine)
+        out.push(paceLine);
+    if (nextLine)
+        out.push(nextLine);
+    return out;
+}
+function formatNoRunButProgress(progress, exploration, now) {
+    // No active run, but agenticProgress on the exploration shows past
+    // activity. Either the run completed or it never started. Either
+    // way, the last-snapshot view is what's useful.
+    const out = [`Run        (no active run)`];
+    out.push(formatPhaseLine(progress));
+    const questionsLine = formatQuestionsLine(progress);
+    if (questionsLine)
+        out.push(questionsLine);
+    out.push(formatActivityLine(exploration.updatedAt, now));
+    return out;
+}
+function formatNoProgress(exploration) {
+    return [
+        `Run        (no run started yet)`,
+        `Phase      —`,
+        `Step       ${exploration.step}`,
+    ];
+}
+function formatPhaseLine(progress) {
+    const phase = progress.phase ?? '—';
+    const pct = typeof progress.percent === 'number' ? `  (${progress.percent}%)` : '';
+    return `Phase      ${phase}${pct}`;
+}
+function formatQuestionsLine(progress) {
+    const total = progress.totalQuestions;
+    const done = progress.completedQuestions;
+    const failed = progress.failedQuestions ?? 0;
+    if (typeof total !== 'number' || typeof done !== 'number')
+        return null;
+    if (total === 0)
+        return null;
+    const failedSegment = failed > 0 ? `  ·  ${failed} failed` : `  ·  0 failed`;
+    return `Questions  ${done} / ${total}${failedSegment}`;
+}
+function formatActivityLine(updatedAt, now) {
+    const ageSec = Math.max(0, Math.round((now - new Date(updatedAt).getTime()) / 1000));
+    return `Activity   last DB write ${humanizeDuration(ageSec)} ago`;
+}
+function formatPaceLine(progress, now) {
+    const done = progress.completedQuestions ?? 0;
+    const total = progress.totalQuestions ?? 0;
+    if (done < 3)
+        return `Pace       warming up — check back in 30s`;
+    if (!progress.startedAt || total <= done)
+        return null;
+    const elapsedSec = (now - new Date(progress.startedAt).getTime()) / 1000;
+    if (elapsedSec <= 0)
+        return null;
+    const secPerQ = elapsedSec / done;
+    const remainingSec = Math.round(secPerQ * (total - done));
+    return `Pace       ~${Math.round(secPerQ)}s/question  ·  ETA ~${humanizeDuration(remainingSec)} remaining`;
+}
+function formatNextLine(progress) {
+    const phase = (progress.phase ?? '').toLowerCase();
+    const nextByPhase = {
+        discovery: 'Accepting questions',
+        accepting: 'Answering',
+        answering: 'Recommendations (auto-advances when questions are done)',
+        submitting: 'Recommendations',
+        recommendations: 'Build brief (after admin review)',
+        complete: '—',
+        failed: '—',
+    };
+    const next = nextByPhase[phase];
+    return next ? `Next       ${next}` : null;
+}
+function humanizeDuration(seconds) {
+    if (seconds < 0)
+        seconds = 0;
+    if (seconds < 60)
+        return `${seconds}s`;
+    const m = Math.floor(seconds / 60);
+    const s = seconds % 60;
+    if (m < 60) {
+        return s === 0 ? `${m}m` : `${m}m ${s}s`;
+    }
+    const h = Math.floor(m / 60);
+    const remM = m % 60;
+    return remM === 0 ? `${h}h` : `${h}h ${remM}m`;
+}
+function truncateId(id) {
+    // "ba4d2b42-…" form — first 8 chars + ellipsis. Matches the agent-
+    // facing copy in the SKILL so users can pattern-match against IDs
+    // they've seen elsewhere. UUIDs slice cleanly at 8 (no trailing
+    // hyphen); for non-UUID inputs we strip a trailing dash so we
+    // don't render "r1-aaaa--…" with double hyphens.
+    if (id.length <= 8)
+        return id;
+    const head = id.slice(0, 8).replace(/-+$/, '');
+    return `${head}-…`;
+}
+//# sourceMappingURL=status-formatter.js.map

package/dist/lib/status-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-formatter.js","sourceRoot":"","sources":["../../src/lib/status-formatter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ritualai/cli",
-	"version": "0.7.13",
+	"version": "0.7.14",
 	"description": "Ritual CLI — scaffold AI coding agent skills + register MCP servers. Connects Claude Code, Cursor, Windsurf, Kiro, Gemini CLI, VS Code/Copilot, and Codex to Ritual Cloud.",
 	"private": false,
 	"license": "Apache-2.0",

package/skills/claude-code/ritual/.ritual-bundle.json

@@ -1,4 +1,4 @@
 {
-  "cliVersion": "0.7.13",
-  "builtAt": "2026-05-15T14:17:47.561Z"
+  "cliVersion": "0.7.14",
+  "builtAt": "2026-05-15T16:06:46.162Z"
 }

package/skills/claude-code/ritual/manifest.json

@@ -21,8 +21,8 @@
   },
   {
     "path": "references/build-flow.md",
-    "lines": 1519,
-    "bytes": 88142
+    "lines": 2466,
+    "bytes": 148766
   },
   {
     "path": "references/cli-output-contract.md",
@@ -53,5 +53,10 @@
     "path": "references/scoring-fallback.md",
     "lines": 126,
     "bytes": 6494
+  },
+  {
+    "path": "references/ui-ux-checklist.md",
+    "lines": 198,
+    "bytes": 12167
   }
 ]

package/skills/claude-code/ritual/references/build-flow.md

@@ -1416,7 +1416,54 @@ 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.
+
+Live progress:
+  ritual status --watch
+
+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
+
+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.
+
+##### 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. Use `ritual status --watch` if you want to follow along live.
+
+Then print progress only when `progress_pct` or `current_step` changes, or every ~3 polls if unchanged:
 
 > Agentic run: {progress_pct}% — {current_step}
 
@@ -1983,18 +2030,97 @@ Build brief ready
   · `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.
+- **`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).
 - **`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`.
 
 **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`?"*).
+
+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 +2171,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.