@ritualai/cli 0.9.3 → 0.9.4

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

@@ -2094,13 +2094,14 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
    - **Same exploration** (recommendationsHash matches the cached row): silent overwrite + one-line note in the summary that you refreshed it.
    - **Different exploration**: surface a confirm: *"A `BUILD-BRIEF.md` already exists from exploration `{previous_exploration_name}`. Overwrite with brief for `{this_exploration_name}`? (y/N, or save-to-`BUILD-BRIEF-{slug}.md`)"*. (CLI Tenet #11 — confirm before destructive.)
 
-2. **Print a compact CLI summary** — the top-of-mind information plus a single line pointing at the file:
+2. **Print a compact CLI summary** — the top-of-mind information, the verification result, plus a single line pointing at the file:
 
    ```
    ✓ Build brief ready — discovery has become an implementation path.
 
    Signal: {N} accepted recommendations were converted into {M} code-time requirements.
    File: BUILD-BRIEF.md ({line_count} lines, {file_kb_size} KB)
+   Verification: {V} verified · {C} contradicted · {NF} not found  (from Step 10b.5; see BUILD-BRIEF-VERIFICATION.md)
 
    Goal: {first line of Goal section, ≤ 100 chars}
 
@@ -2119,8 +2120,9 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
    ```
 
    Rules for the summary (CLI Tenets #3, #6):
+   - **The `Verification:` line is mandatory** — render the actual numbers from Step 10b.5. If 10b.5 was legitimately skipped (brief made zero specific code citations), render `Verification: n/a — brief made no code citations to verify` instead of omitting the line. The line existing-but-zero is fine; the line being MISSING is a structural signal that 10b.5 was skipped without justification. Reviewing this summary should let the user (and a future SKILL self-check) catch a skipped-verification regression by spotting the missing line. The 2026-05-21 demo regression was Step 10b.5 silently skipped on a brief that cited `AbstractCommunicationEventType`, `utils.py Dispatcher`, `notify_user()`, and `oscar_send_alerts.py` — exactly the case 10b.5 is supposed to verify.
    - **Cap RBs and anchors at top 3 each.** Engineers don't read 12-row tables in terminals.
-   - **Omit any section that's empty.** No "Previously Deferred: none" lines — just don't render that line.
+   - **Omit any section that's empty.** No "Previously Deferred: none" lines — just don't render that line. (The `Verification:` line is exempt — it's always rendered, see above.)
    - If `kgContextUsed.implementationCount > 0`, append one line above the goal: *"Grounded in {N} prior implementation{s}: {top match name}, …"* (CLI Tenet #4 — cite the specific signal).
 
 3. **Offer to open the file** (CLI Tenet #10 — OS-aware affordances, available not mandatory):
@@ -2137,7 +2139,9 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
 
 ##### 10d — Confirm and proceed (CLI Tenet #2, #12)
 
-End Step 10 with a single recommended action plus a cheap escape hatch — never a 3-way option bloom. Full rail (this is a decision gate that closes the Build brief phase):
+End Step 10 with a single recommended action plus a cheap escape hatch — never a 3-way option bloom.
+
+**Rendering contract (load-bearing — see SKILL.md § Contract strength):** the user-facing block below is **verbatim**. Render the text inside the fenced block exactly as written — same option names (`go`, `drill {N}`, `ux-review`, `pause`), same one-line descriptions, same order, same connector word ("Before `go`, you can run `ux-review`…"). Do NOT paraphrase to "implement", "sync", "hold", "ship", or any other reworded synonyms. Do NOT collapse the option list. Do NOT add or omit options. The 2026-05-21 demo regression was an agent rendering `Reply implement / sync / hold` instead of this block — three different options, two with different semantics than the SKILL intends (`sync` ≠ `pause`). The contract-strength rule in SKILL.md is the backstop; this notice is the local reminder.
 
 ```text
 Ritual build
@@ -2153,12 +2157,12 @@ Build brief ready
 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):
+Branch by user response. The CTA on screen is `go`, but accept these as synonyms so a user typing the obvious intent doesn't get penalized for word choice:
 
-- **`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.
+- **`go` / `y` / `yes` / `proceed` / `continue` / `next` / `implement` / `ship`**: 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. (Synonyms accepted because the agent's drift to "Reply `implement`" trained users to type that word; until the verbatim rendering enforcement is fully reliable, treat user input charitably.)
+- **`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`.
+- **`pause`** / `hold` / `stop`: 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:
 
@@ -2276,7 +2280,9 @@ The build brief is on disk. From here, your agent codes against the
 RB list. Ritual will track commits via the `Ritual-Exploration:` trailer
 so they link back to this exploration when you sync.
 
-Next: I'll create a feature branch, then start on RB-1.
+Next: I'll do a quick branch / dirty-worktree safety check, then hand
+off to your agent's plan mode so the first pass is a plan grounded
+in BUILD-BRIEF.md — not file edits.
 ```
 
 ##### 11.0 — Branch strategy (CLI Tenet #13)
@@ -2308,16 +2314,100 @@ Next: I'll create a feature branch, then start on RB-1.
 
 **Never offer "commit to `main` directly" as an option in any user prompt.**
 
-##### 11.1 — Implement
+##### 11.0.5 — Plan-mode handoff (load-bearing — [USER PAUSE])
+
+**Branch is created, working tree is safe — now hand off to plan mode.** Plan mode is user-invoked (the agent can't toggle it programmatically in Claude Code / Cursor / etc.), so without an explicit prompt the implementation phase starts with the agent improvising file edits instead of producing a reviewable plan grounded in `BUILD-BRIEF.md`. This step happens AFTER branch creation (Step 11.0) because plan mode in Claude Code blocks Bash, so branch creation has to happen first.
+
+**Rendering contract — verbatim:**
+
+```text
+Branch ready. Switch your agent into plan mode so the first pass is
+a plan grounded in BUILD-BRIEF.md, not file edits.
+
+  · Claude Code: press Shift+Tab to cycle to "plan mode" (footer shows
+    "plan mode" instead of "default" or "auto-accept edits")
+  · Cursor: open Composer → toggle to "Plan" mode
+  · Other agents: equivalent "plan / propose-only" mode if available;
+    otherwise reply `skip` and I'll continue without
+
+Reply `ready` once you're in plan mode (or `skip` if your agent has no
+plan-mode equivalent). I'll load BUILD-BRIEF.md (and BUILD-BRIEF-
+VERIFICATION.md / UX-REVIEW.md if present) as the FIRST inputs and
+produce a numbered plan you can review before any file is edited.
+```
+
+[USER PAUSE] Branch on response:
+
+- **`ready`**: continue to Step 11.1 (plan generation).
+- **`skip`**: log a one-line note ("Plan mode skipped — agent has no plan-mode equivalent or user opted out. Proceeding directly to implement; risk: less reviewable first pass.") and skip Step 11.1 + 11.1.5, jumping straight to Step 11.2 (implement). This is an escape hatch, not the default.
+- Any other response: re-render the prompt once. If still not `ready` / `skip` after two tries, default to `skip` with the warning line.
+
+**Why this is load-bearing:**
+
+1. Plan mode is the only mechanism that produces a reviewable plan BEFORE file edits. Skipping it means the user is reviewing a diff, not a plan — a more expensive correction loop.
+2. `BUILD-BRIEF-VERIFICATION.md` contradictions are most valuable when they become explicit plan constraints, not when they're discovered during implementation.
+3. Without an explicit prompt, the agent typically goes straight from "build brief ready" to file edits — observed regression during 2026-05-21 demo testing.
+
+##### 11.1 — Plan mode generates the implementation plan
+
+The user is now in plan mode (from Step 11.0.5). The agent must:
+
+1. **Load `BUILD-BRIEF.md`** as the first input. If `BUILD-BRIEF-VERIFICATION.md` exists, load it too — every `contradicted` and `not_found` entry becomes an explicit constraint in the plan ("the brief claimed X but the code does Y; the plan must reconcile / not assume X"). If `UX-REVIEW.md` exists alongside `BUILD-BRIEF.md` (the user opted into Step 10.5), use the "Plan Mode Prompt" block at its bottom as the FIRST input — 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. **Produce a numbered implementation plan** whose top entries are: (1) the RBs from the brief, (2) any contradictions surfaced by verification, (3) any "new work" surfaces from UX review. The plan should name the specific files / functions / new modules each plan step will touch — concrete enough that the user can spot a mistake before any edit happens.
+
+3. **Stay in plan mode until the user accepts the plan.** Do NOT switch to edit/auto-accept mode until the user explicitly approves the plan in plan mode (Claude Code's "accept plan" affordance, or the user typing `accept` / `looks good` / `go`).
+
+##### 11.1.5 — Optional: save the implementation plan as a markdown artifact
+
+After plan mode produces the implementation plan, **but before any code edits**, ask whether to save it.
+
+**Rendering contract — verbatim:**
+
+```text
+Plan ready
+
+Your agent generated an implementation plan from BUILD-BRIEF.md
+{and BUILD-BRIEF-VERIFICATION.md / UX-REVIEW.md if those exist}.
+
+Save this plan to `IMPLEMENTATION-PLAN.md` before coding? (y/N)
+```
+
+[USER PAUSE] Branch on response (default is no — not every plan is worth committing):
+
+- **`y` / `yes` / `save`**: write `IMPLEMENTATION-PLAN.md` alongside `BUILD-BRIEF.md` in the repo root (or `.ritual/IMPLEMENTATION-PLAN.md` if the repo prefers tooling artifacts out of the top level — check `.gitignore` first). Prepend the Ritual attribution header:
+
+  ```markdown
+  <!--
+  Generated by Ritual via plan mode
+  Exploration: https://app.ritualapp.cloud/e/{exploration_id}
+  Build brief: BUILD-BRIEF.md (Ritual requirements)
+  This file: agent's concrete execution strategy
+  Do not remove this header; it preserves implementation lineage.
+  -->
+  ```
+
+  Then continue to Step 11.2.
+- anything else (`n` / `no` / empty / any other text): continue to Step 11.2 without writing the file. Do not re-prompt.
+
+**Rules:**
+
+- **Do not ask this before plan mode has produced the plan.** The question is for the assembled plan, not "do you want me to write a plan in advance."
+- **Do not dump the full plan into the chat when saving.** The plan markdown belongs in the file the user can open, search, share, and revisit — same pattern as `BUILD-BRIEF.md` and `BUILD-BRIEF-VERIFICATION.md` (CLI Tenet #1 — files for detail, CLI for decisions).
+- **Default is `no`** — explicit `y` is required. Most quick implementations don't need a committed plan; saving by default would clutter the repo.
+- If the user later opens the PR (Step 11.5), include `IMPLEMENTATION-PLAN.md` in the PR body's Exploration section if it was saved (see Step 11.5 template).
+
+**Why this matters:** `BUILD-BRIEF.md` is the Ritual requirements artifact (what + why). `IMPLEMENTATION-PLAN.md` is the agent's concrete execution strategy (how). For non-trivial implementations, saving both gives reviewers a useful bridge from requirement to code — and gives `/ritual lineage` queries a richer trail to surface on future builds touching the same files.
+
+##### 11.2 — Implement
 
-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.
+1. Use the standard coding-loop tools (Edit/Write/Bash/etc.) to execute the accepted plan.
+2. Run tests, lint, build per the repo's conventions.
+3. 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.
 
-##### 11.2 — Commit (CLI Tenet #14 — Ritual attribution)
+##### 11.3 — Commit (CLI Tenet #14 — Ritual attribution)
 
-Commit on the feature branch from 11.0. One-or-many commits is fine; conventional-commit prefixes preferred (`feat:`, `fix:`, `test:`, etc.). Include a Ritual footer on the FINAL commit of the implementation so the trace from code → exploration is visible in `git log`:
+Commit on the feature branch from Step 11.0. One-or-many commits is fine; conventional-commit prefixes preferred (`feat:`, `fix:`, `test:`, etc.). Include a Ritual footer on the FINAL commit of the implementation so the trace from code → exploration is visible in `git log`:
 
 ```
 feat(<area>): <one-line headline>
@@ -2331,7 +2421,7 @@ Ritual-RBs-Satisfied: RB-1, RB-2, RB-7
 
 Intermediate commits can skip the footer. The final commit IS the linkage anchor.
 
-##### 11.3 — Post-implementation summary (CLI Tenet #1 — files for detail, CLI for decisions)
+##### 11.4 — Post-implementation summary (CLI Tenet #1 — files for detail, CLI for decisions)
 
 **Don't dump a per-file changelog into the chat.** The full diff lives in `git diff <branch>..HEAD` and the eventual PR body. The CLI summary should be **≤ 8 lines** and surface only what's load-bearing for the user's next decision:
 
@@ -2347,7 +2437,7 @@ Next: push + open PR? (y / show me what changed / abort)
 
 If the user picks "show me what changed", THEN run `git diff --stat HEAD~N..HEAD` or open per-file diffs interactively — on request, not by default.
 
-##### 11.4 — Push + PR (single recommended action)
+##### 11.5 — Push + PR (single recommended action)
 
 If the user says "y" / "push" / "open PR":
 
@@ -2380,6 +2470,7 @@ If the user says "y" / "push" / "open PR":
 
 - Exploration: [<exploration name>](https://app.ritualapp.cloud/e/<exploration_id>)
 - Build brief: see `BUILD-BRIEF.md` (committed in this PR for reviewer reference)
+- Implementation plan: see `IMPLEMENTATION-PLAN.md` *(only include this line if Step 11.1.5 actually wrote the file — agent execution strategy alongside the brief)*
 - Deferrals intentionally punted: <count, with one-line each>
 
 ---

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

@@ -1,4 +1,4 @@
 {
-  "cliVersion": "0.9.3",
-  "builtAt": "2026-05-21T13:04:39.224Z"
+  "cliVersion": "0.9.4",
+  "builtAt": "2026-05-21T14:03:29.145Z"
 }

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

@@ -2094,13 +2094,14 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
    - **Same exploration** (recommendationsHash matches the cached row): silent overwrite + one-line note in the summary that you refreshed it.
    - **Different exploration**: surface a confirm: *"A `BUILD-BRIEF.md` already exists from exploration `{previous_exploration_name}`. Overwrite with brief for `{this_exploration_name}`? (y/N, or save-to-`BUILD-BRIEF-{slug}.md`)"*. (CLI Tenet #11 — confirm before destructive.)
 
-2. **Print a compact CLI summary** — the top-of-mind information plus a single line pointing at the file:
+2. **Print a compact CLI summary** — the top-of-mind information, the verification result, plus a single line pointing at the file:
 
    ```
    ✓ Build brief ready — discovery has become an implementation path.
 
    Signal: {N} accepted recommendations were converted into {M} code-time requirements.
    File: BUILD-BRIEF.md ({line_count} lines, {file_kb_size} KB)
+   Verification: {V} verified · {C} contradicted · {NF} not found  (from Step 10b.5; see BUILD-BRIEF-VERIFICATION.md)
 
    Goal: {first line of Goal section, ≤ 100 chars}
 
@@ -2119,8 +2120,9 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
    ```
 
    Rules for the summary (CLI Tenets #3, #6):
+   - **The `Verification:` line is mandatory** — render the actual numbers from Step 10b.5. If 10b.5 was legitimately skipped (brief made zero specific code citations), render `Verification: n/a — brief made no code citations to verify` instead of omitting the line. The line existing-but-zero is fine; the line being MISSING is a structural signal that 10b.5 was skipped without justification. Reviewing this summary should let the user (and a future SKILL self-check) catch a skipped-verification regression by spotting the missing line. The 2026-05-21 demo regression was Step 10b.5 silently skipped on a brief that cited `AbstractCommunicationEventType`, `utils.py Dispatcher`, `notify_user()`, and `oscar_send_alerts.py` — exactly the case 10b.5 is supposed to verify.
    - **Cap RBs and anchors at top 3 each.** Engineers don't read 12-row tables in terminals.
-   - **Omit any section that's empty.** No "Previously Deferred: none" lines — just don't render that line.
+   - **Omit any section that's empty.** No "Previously Deferred: none" lines — just don't render that line. (The `Verification:` line is exempt — it's always rendered, see above.)
    - If `kgContextUsed.implementationCount > 0`, append one line above the goal: *"Grounded in {N} prior implementation{s}: {top match name}, …"* (CLI Tenet #4 — cite the specific signal).
 
 3. **Offer to open the file** (CLI Tenet #10 — OS-aware affordances, available not mandatory):
@@ -2137,7 +2139,9 @@ When the brief content is in hand (from generate OR polling), **don't dump 300 l
 
 ##### 10d — Confirm and proceed (CLI Tenet #2, #12)
 
-End Step 10 with a single recommended action plus a cheap escape hatch — never a 3-way option bloom. Full rail (this is a decision gate that closes the Build brief phase):
+End Step 10 with a single recommended action plus a cheap escape hatch — never a 3-way option bloom.
+
+**Rendering contract (load-bearing — see SKILL.md § Contract strength):** the user-facing block below is **verbatim**. Render the text inside the fenced block exactly as written — same option names (`go`, `drill {N}`, `ux-review`, `pause`), same one-line descriptions, same order, same connector word ("Before `go`, you can run `ux-review`…"). Do NOT paraphrase to "implement", "sync", "hold", "ship", or any other reworded synonyms. Do NOT collapse the option list. Do NOT add or omit options. The 2026-05-21 demo regression was an agent rendering `Reply implement / sync / hold` instead of this block — three different options, two with different semantics than the SKILL intends (`sync` ≠ `pause`). The contract-strength rule in SKILL.md is the backstop; this notice is the local reminder.
 
 ```text
 Ritual build
@@ -2153,12 +2157,12 @@ Build brief ready
 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):
+Branch by user response. The CTA on screen is `go`, but accept these as synonyms so a user typing the obvious intent doesn't get penalized for word choice:
 
-- **`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.
+- **`go` / `y` / `yes` / `proceed` / `continue` / `next` / `implement` / `ship`**: 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. (Synonyms accepted because the agent's drift to "Reply `implement`" trained users to type that word; until the verbatim rendering enforcement is fully reliable, treat user input charitably.)
+- **`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`.
+- **`pause`** / `hold` / `stop`: 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:
 
@@ -2276,7 +2280,9 @@ The build brief is on disk. From here, your agent codes against the
 RB list. Ritual will track commits via the `Ritual-Exploration:` trailer
 so they link back to this exploration when you sync.
 
-Next: I'll create a feature branch, then start on RB-1.
+Next: I'll do a quick branch / dirty-worktree safety check, then hand
+off to your agent's plan mode so the first pass is a plan grounded
+in BUILD-BRIEF.md — not file edits.
 ```
 
 ##### 11.0 — Branch strategy (CLI Tenet #13)
@@ -2308,16 +2314,100 @@ Next: I'll create a feature branch, then start on RB-1.
 
 **Never offer "commit to `main` directly" as an option in any user prompt.**
 
-##### 11.1 — Implement
+##### 11.0.5 — Plan-mode handoff (load-bearing — [USER PAUSE])
+
+**Branch is created, working tree is safe — now hand off to plan mode.** Plan mode is user-invoked (the agent can't toggle it programmatically in Claude Code / Cursor / etc.), so without an explicit prompt the implementation phase starts with the agent improvising file edits instead of producing a reviewable plan grounded in `BUILD-BRIEF.md`. This step happens AFTER branch creation (Step 11.0) because plan mode in Claude Code blocks Bash, so branch creation has to happen first.
+
+**Rendering contract — verbatim:**
+
+```text
+Branch ready. Switch your agent into plan mode so the first pass is
+a plan grounded in BUILD-BRIEF.md, not file edits.
+
+  · Claude Code: press Shift+Tab to cycle to "plan mode" (footer shows
+    "plan mode" instead of "default" or "auto-accept edits")
+  · Cursor: open Composer → toggle to "Plan" mode
+  · Other agents: equivalent "plan / propose-only" mode if available;
+    otherwise reply `skip` and I'll continue without
+
+Reply `ready` once you're in plan mode (or `skip` if your agent has no
+plan-mode equivalent). I'll load BUILD-BRIEF.md (and BUILD-BRIEF-
+VERIFICATION.md / UX-REVIEW.md if present) as the FIRST inputs and
+produce a numbered plan you can review before any file is edited.
+```
+
+[USER PAUSE] Branch on response:
+
+- **`ready`**: continue to Step 11.1 (plan generation).
+- **`skip`**: log a one-line note ("Plan mode skipped — agent has no plan-mode equivalent or user opted out. Proceeding directly to implement; risk: less reviewable first pass.") and skip Step 11.1 + 11.1.5, jumping straight to Step 11.2 (implement). This is an escape hatch, not the default.
+- Any other response: re-render the prompt once. If still not `ready` / `skip` after two tries, default to `skip` with the warning line.
+
+**Why this is load-bearing:**
+
+1. Plan mode is the only mechanism that produces a reviewable plan BEFORE file edits. Skipping it means the user is reviewing a diff, not a plan — a more expensive correction loop.
+2. `BUILD-BRIEF-VERIFICATION.md` contradictions are most valuable when they become explicit plan constraints, not when they're discovered during implementation.
+3. Without an explicit prompt, the agent typically goes straight from "build brief ready" to file edits — observed regression during 2026-05-21 demo testing.
+
+##### 11.1 — Plan mode generates the implementation plan
+
+The user is now in plan mode (from Step 11.0.5). The agent must:
+
+1. **Load `BUILD-BRIEF.md`** as the first input. If `BUILD-BRIEF-VERIFICATION.md` exists, load it too — every `contradicted` and `not_found` entry becomes an explicit constraint in the plan ("the brief claimed X but the code does Y; the plan must reconcile / not assume X"). If `UX-REVIEW.md` exists alongside `BUILD-BRIEF.md` (the user opted into Step 10.5), use the "Plan Mode Prompt" block at its bottom as the FIRST input — 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. **Produce a numbered implementation plan** whose top entries are: (1) the RBs from the brief, (2) any contradictions surfaced by verification, (3) any "new work" surfaces from UX review. The plan should name the specific files / functions / new modules each plan step will touch — concrete enough that the user can spot a mistake before any edit happens.
+
+3. **Stay in plan mode until the user accepts the plan.** Do NOT switch to edit/auto-accept mode until the user explicitly approves the plan in plan mode (Claude Code's "accept plan" affordance, or the user typing `accept` / `looks good` / `go`).
+
+##### 11.1.5 — Optional: save the implementation plan as a markdown artifact
+
+After plan mode produces the implementation plan, **but before any code edits**, ask whether to save it.
+
+**Rendering contract — verbatim:**
+
+```text
+Plan ready
+
+Your agent generated an implementation plan from BUILD-BRIEF.md
+{and BUILD-BRIEF-VERIFICATION.md / UX-REVIEW.md if those exist}.
+
+Save this plan to `IMPLEMENTATION-PLAN.md` before coding? (y/N)
+```
+
+[USER PAUSE] Branch on response (default is no — not every plan is worth committing):
+
+- **`y` / `yes` / `save`**: write `IMPLEMENTATION-PLAN.md` alongside `BUILD-BRIEF.md` in the repo root (or `.ritual/IMPLEMENTATION-PLAN.md` if the repo prefers tooling artifacts out of the top level — check `.gitignore` first). Prepend the Ritual attribution header:
+
+  ```markdown
+  <!--
+  Generated by Ritual via plan mode
+  Exploration: https://app.ritualapp.cloud/e/{exploration_id}
+  Build brief: BUILD-BRIEF.md (Ritual requirements)
+  This file: agent's concrete execution strategy
+  Do not remove this header; it preserves implementation lineage.
+  -->
+  ```
+
+  Then continue to Step 11.2.
+- anything else (`n` / `no` / empty / any other text): continue to Step 11.2 without writing the file. Do not re-prompt.
+
+**Rules:**
+
+- **Do not ask this before plan mode has produced the plan.** The question is for the assembled plan, not "do you want me to write a plan in advance."
+- **Do not dump the full plan into the chat when saving.** The plan markdown belongs in the file the user can open, search, share, and revisit — same pattern as `BUILD-BRIEF.md` and `BUILD-BRIEF-VERIFICATION.md` (CLI Tenet #1 — files for detail, CLI for decisions).
+- **Default is `no`** — explicit `y` is required. Most quick implementations don't need a committed plan; saving by default would clutter the repo.
+- If the user later opens the PR (Step 11.5), include `IMPLEMENTATION-PLAN.md` in the PR body's Exploration section if it was saved (see Step 11.5 template).
+
+**Why this matters:** `BUILD-BRIEF.md` is the Ritual requirements artifact (what + why). `IMPLEMENTATION-PLAN.md` is the agent's concrete execution strategy (how). For non-trivial implementations, saving both gives reviewers a useful bridge from requirement to code — and gives `/ritual lineage` queries a richer trail to surface on future builds touching the same files.
+
+##### 11.2 — Implement
 
-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.
+1. Use the standard coding-loop tools (Edit/Write/Bash/etc.) to execute the accepted plan.
+2. Run tests, lint, build per the repo's conventions.
+3. 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.
 
-##### 11.2 — Commit (CLI Tenet #14 — Ritual attribution)
+##### 11.3 — Commit (CLI Tenet #14 — Ritual attribution)
 
-Commit on the feature branch from 11.0. One-or-many commits is fine; conventional-commit prefixes preferred (`feat:`, `fix:`, `test:`, etc.). Include a Ritual footer on the FINAL commit of the implementation so the trace from code → exploration is visible in `git log`:
+Commit on the feature branch from Step 11.0. One-or-many commits is fine; conventional-commit prefixes preferred (`feat:`, `fix:`, `test:`, etc.). Include a Ritual footer on the FINAL commit of the implementation so the trace from code → exploration is visible in `git log`:
 
 ```
 feat(<area>): <one-line headline>
@@ -2331,7 +2421,7 @@ Ritual-RBs-Satisfied: RB-1, RB-2, RB-7
 
 Intermediate commits can skip the footer. The final commit IS the linkage anchor.
 
-##### 11.3 — Post-implementation summary (CLI Tenet #1 — files for detail, CLI for decisions)
+##### 11.4 — Post-implementation summary (CLI Tenet #1 — files for detail, CLI for decisions)
 
 **Don't dump a per-file changelog into the chat.** The full diff lives in `git diff <branch>..HEAD` and the eventual PR body. The CLI summary should be **≤ 8 lines** and surface only what's load-bearing for the user's next decision:
 
@@ -2347,7 +2437,7 @@ Next: push + open PR? (y / show me what changed / abort)
 
 If the user picks "show me what changed", THEN run `git diff --stat HEAD~N..HEAD` or open per-file diffs interactively — on request, not by default.
 
-##### 11.4 — Push + PR (single recommended action)
+##### 11.5 — Push + PR (single recommended action)
 
 If the user says "y" / "push" / "open PR":
 
@@ -2380,6 +2470,7 @@ If the user says "y" / "push" / "open PR":
 
 - Exploration: [<exploration name>](https://app.ritualapp.cloud/e/<exploration_id>)
 - Build brief: see `BUILD-BRIEF.md` (committed in this PR for reviewer reference)
+- Implementation plan: see `IMPLEMENTATION-PLAN.md` *(only include this line if Step 11.1.5 actually wrote the file — agent execution strategy alongside the brief)*
 - Deferrals intentionally punted: <count, with one-line each>
 
 ---