@ritualai/cli 0.11.0 → 0.25.0

package/skills/codex/ritual/references/change-preflight.md

@@ -0,0 +1,81 @@
+# Change pre-flight — restate-before-mutate
+
+When the user asks to **change or add** something via a free-text instruction, the agent has to
+*translate* that instruction into a tool call (a `change_prompt`, an anti-goal text, etc.). That
+translation is where intent gets lost: a misread re-rolls the artifact in the wrong direction, and
+the user only finds out *after* the regeneration. This protocol puts a confirmation **before** the
+mutating call: the agent restates what it heard and shows the exact request it's about to send, and
+waits for a `yes`.
+
+This is **not** the forward-flow confirmation theatre the SKILL deliberately removed (template-pick,
+sub-problem auto-accept, etc.). Those gated the *default happy path*. This gate fires **only** on an
+explicit, free-text *change/add* request — where the input is ambiguous by nature and a read-back is
+genuinely protective.
+
+## When it fires
+
+Before **every** call to a tool that mutates an artifact from a free-text user request:
+
+| User asks (free text) | Tool the agent is about to call |
+|---|---|
+| "rethink / change the sub-problems", "show me other angles" | `mcp__ritual__refine_considerations` |
+| "tighten / broaden / reframe / drop X from the scope" | `mcp__ritual__refine_problem_statement` |
+| "add an anti-goal", "don't touch X", "keep Y out of scope" | `mcp__ritual__set_anti_goals` |
+
+**Always fire — no exceptions for "obvious" requests.** Even a one-word `tighten` or `broaden` gets
+the restate. The user chose maximum safety here: a one-word instruction is exactly where the agent is
+most tempted to guess a direction, so it's still confirmed.
+
+**Does NOT fire on the forward CTAs** — `use` / `run` / `accept shortlist` / `proceed` and their
+aliases already have their own gates. Double-gating those is the theatre we removed. This protocol is
+*only* for the mutate-from-free-text tools above.
+
+## Hard pause — even in auto-mode
+
+This is a real `[USER PAUSE]`. In auto-accept / bypass-permissions mode it **still stops and waits**
+for an actual `yes`. Mutations are where a misread is most costly, so the agent never auto-applies a
+change on the user's behalf — auto-mode collapses *forward* pauses, not this one. Per the SKILL
+preamble: never infer, never default, never press on without a real reply.
+
+## The template
+
+Render this block, then **stop and wait**:
+
+```
+Got it — you want to {specific restatement of the change, in the user's own terms}.
+
+Here's what I'll do: {plain-English effect on the artifact}. I'll ask Ritual to
+{refine the sub-problems / refine the problem frame / add this anti-goal} with this instruction:
+
+  → "{the EXACT change_prompt / anti-goal text the agent will send the tool}"
+
+Apply this? Reply `yes`, or tell me what to adjust.
+```
+
+Rules for the block:
+- **Restate specifically.** "drop the observability sub-problem and add a rollout-safety one" — never
+  a generic "you want to make a change." If the agent can't restate the request specifically, it
+  doesn't understand it yet: ask a clarifying question instead of guessing a `change_prompt`.
+- **Show the literal request.** The `→ "..."` line is the *exact* string going into the tool
+  (`change_prompt` verbatim, or the anti-goal `text`). This is the whole point — the user is
+  validating the instruction the model will actually send, not a paraphrase of it.
+- **One confirm token.** `yes` applies. Treat `y`, `apply`, `go`, `do it` as aliases; do not display
+  them.
+
+## On the user's reply
+
+- **`yes`** → make the tool call exactly as shown. Do not silently alter the `change_prompt` after
+  confirmation.
+- **An adjustment** ("no, keep observability, just add rollout-safety") → fold it into the
+  `change_prompt`, re-render the block **once** with the revised instruction, and wait again. This is
+  a single re-confirm, **not** an open loop — after the second render, a `yes` applies and any further
+  change is treated as a fresh request (new restate).
+- **`pause` / `stop`** → honor it; do not call the tool.
+
+## Note — "add a question or matter that wasn't there"
+
+There is currently **no MCP tool** to add a *net-new* discovery question or matter that the
+`suggest_discovery_questions` set didn't produce — the user can only accept from the suggested set or
+re-run suggestion with guidance. When that capability ships (a tool to author a custom
+question/matter), it is a mutate-from-free-text action and MUST route through this same pre-flight.
+Until then, this protocol covers the three tools listed above.

package/skills/codex/ritual/references/cli-output-contract.md

@@ -24,6 +24,28 @@ Default user-visible messages should be:
 - free of raw file-by-file recon dumps unless requested
 - formatted for terminal readability: short paragraphs, blank lines between major items, and label/value blocks instead of dense wrapped prose
 
+**Output discipline — never leak internal reasoning or mechanics (load-bearing, worked examples):**
+
+The two failure modes below are the most common leaks. They are forbidden, not discouraged.
+
+1. **Don't editorialize — just ask.** When you ask the user to choose, render the question + the options. Do NOT justify *why* you're asking or how costly getting it wrong is — that's your reasoning, not the user's decision input.
+   - ❌ `"New social commerce experience" maps to several distinct features — picking the wrong one wastes significant scope.`
+   - ❌ `Because this spans three cross-functional tracks, attribution rules have real product decisions baked in.`
+   - ✅ `What would you like to explore?` (then the options + a recommended one)
+
+2. **Silent checks stay silent — never name a tool or narrate plumbing.** Connection/freshness pings, config reads, workspace lookups, and code recon are invisible. Do NOT print "let me ping Ritual", "checking the workspace config", or any `mcp__ritual__*` tool name.
+   - ❌ `Now I'll start the build flow. Let me check the workspace config and ping Ritual simultaneously.`
+   - ❌ `Pinging Ritual to verify the connection…`
+   - ✅ (nothing — run the check silently; the next user-visible line is the actual gate or status)
+
+3. **Don't narrate your process or restate your own instructions.** Loading a spec, fetching a preview, "before presenting", "must print it verbatim", and naming an internal **Step N** are all scratchpad — do them silently and just present the result. The user never sees the machinery between "I have the data" and "here it is."
+   - ❌ `6 recommendations ready. Let me load Step 9's exact rendering spec before presenting.`
+   - ❌ `Now I'll fetch the server-rendered preview — must print it verbatim.`
+   - ❌ `Let me check what the skill says here, then render it.`
+   - ✅ (just present it — the recommendations / the picker / the rail, with no preamble about how you produced it)
+
+Rule of thumb: if a line describes what *you* are doing internally (a tool call, loading a spec, a check, why a question matters, what you're about to render), cut it. The user wants the work and the decision, not your scratchpad. Internal **Step N** labels and artifact names ("rendering spec", "server-rendered preview", "the contract") never appear in user-facing copy.
+
 Use this compact status shape whenever possible:
 
 ```text
@@ -61,7 +83,7 @@ Do not ask for confirmation after safe defaults. State the default and give a li
 
 **[USER PAUSE] policy:** Pause only when the next step would create, approve, delete, implement, accept meaningful cost/time, choose between materially different paths, or resolve ambiguity that code cannot answer. Do not pause for status-only steps, safe defaults, internal recon, silent checks, or no-data outcomes.
 
-**Internal step labels:** Do not expose decimal workflow labels like `Step 1.5`, `Step 7.4.5`, or MCP/tool-step names in user-facing prompts. They are for the skill, not the CLI. Use natural phase language instead: `checking existing explorations`, `choosing a template`, `code recon`, `question picking`, `build brief`, `admin review`, `implementation`, or `sync`. Step numbers are acceptable only in compact progress headings when they help orient the user; avoid them in choice prompts, error messages, and user-facing examples inside this skill.
+**Internal step labels:** Do not expose decimal workflow labels like `Step 1.5`, `Step 7.3.1`, or MCP/tool-step names in user-facing prompts. They are for the skill, not the CLI. Use natural phase language instead: `checking existing explorations`, `choosing a template`, `code recon`, `question picking`, `build brief`, `admin review`, `implementation`, or `sync`. Step numbers are acceptable only in compact progress headings when they help orient the user; avoid them in choice prompts, error messages, and user-facing examples inside this skill.
 
 **Pulse tier labels:** Do not expose raw context-pulse tier identifiers (`RAW_ASK`, `UNDER_SPECIFIED`, `EXPLORED`, `READY`, etc.) in user-facing copy. They are scoring-engine internals, not CLI vocabulary. Translate every appearance into natural-language framing keyed to the phase:
 
@@ -112,19 +134,19 @@ When in doubt, prefer one blank line over none. The cost of a tiny gap is unnoti
 
 **Build progress anchor — load-bearing (never omit, render per surface):** Every TOP-LEVEL user-facing message in `/ritual build` and `/ritual resume` MUST begin with a progress anchor before any other content. The anchor is the user's only "where am I in the flow" signal; dropping it silently is worse than printing it redundantly. The agent was historically inferring the rail from examples and squeezing it out under any pressure — this rule makes it explicit, with the exact rendering chosen per surface so the anchor doesn't wrap badly on narrow chat or duplicate a persistent UI stepper.
 
-**Surface-aware rendering** — the canonical six stages stay constant; only the visual changes:
+**Surface-aware rendering** — the canonical five stages stay constant; only the visual changes:
 
 | Surface | Rendering | When to use |
 |---|---|---|
-| **CLI / terminal** (current default) | Full two-line rail. `Ritual build` on line 1, `✓ Context  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)` on line 2. | Terminal scrollback has no persistent UI — the rail IS the anchor. |
-| **Mobile chat / narrow chat** | Compact one-line chip. `Ritual build · 2/6 Scope`. Optionally add a second line: `Done: Context · Next: Discovery`. | Six-stage rail wraps and looks noisy inside chat bubbles. |
+| **CLI / terminal** (current default) | Full two-line rail. `Ritual build` on line 1, `● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)` on line 2. | Terminal scrollback has no persistent UI — the rail IS the anchor. |
+| **Mobile chat / narrow chat** | Compact one-line chip. `Ritual build · 1/5 Scope`. Optionally add a second line: `Done: Scope · Next: Recommendations`. | Five-stage rail wraps and looks noisy inside chat bubbles. |
 | **Rich app with persistent stepper** | Single-line stage label. `Scope` (or `Phase: Scope`). The app's pinned stepper above the conversation is the primary anchor; messages just need the current label. At phase transitions, resume points, and major decision gates, include the compact mobile-style chip even in rich-app surface for transcript portability. | The persistent UI carries the anchor; redundant chrome in every bubble is noise. |
 
 **How the agent picks the surface:**
 
 - Default to **CLI / terminal** rendering. This SKILL exists primarily to drive CLI surfaces (Claude Code, Cursor, Codex, etc. in their built-in terminals).
 - If the host signals a non-terminal surface via context (mobile-app chat embedding, web-app chat UI, etc.), drop to the compact chip.
-- The rule is: **progress anchor is mandatory; exact visual rendering is surface-specific.** Do NOT force the full six-stage rail when it will wrap.
+- The rule is: **progress anchor is mandatory; exact visual rendering is surface-specific.** Do NOT force the full five-stage rail when it will wrap.
 
 **Applies to:**
 
@@ -163,19 +185,18 @@ The chip's job is "you're still in this phase, this is which item of the series"
 
 | Stage              | Active during…                                                                 |
 |--------------------|--------------------------------------------------------------------------------|
-| `Context`          | Workspace selection, resume/start check, template, knowledge sources, code recon |
-| `Scope`            | Problem frame + sub-problem generation/selection, until scope is locked        |
+| `Scope`            | Silent code recon, problem frame + sub-problem generation/selection, until scope is locked |
 | `Discovery`        | Exploration creation, discovery questions, answers, question picking, answer review |
-| `Recommendations`  | Recommendation generation, review, admin/collaborator acceptance path           |
+| `Recommendations`  | Recommendation generation + review                                              |
 | `Build brief`      | Requirements + build brief generation/review                                   |
 | `Implementation (Your agent)` | Coding, branch/PR work, `sync_implementation`                       |
 
-Note that the FIRST rail stage is `Context`, not `Recon`. `Context` is broader — workspace pick, resume check, template choice, knowledge sources, AND code recon all live there. Use `Code recon` as the SECTION title inside the stage when the active work is repo inspection (see `references/build-flow.md` § Step 3 examples), not as the rail label. There's also a naming hazard: `/ritual recon` was retired as a command surface, so reusing `Recon` at the rail level could imply it's a separate command.
+The FIRST rail stage is `Scope`. **There is no `Context` stage** — workspace pick, resume/start check, template resolution, and **code recon** all happen as **silent plumbing inside Scope**, never as a visible rail stage. Recon runs but is not surfaced to the user by default (see `references/build-flow.md` § Step 3); only narrate repo inspection if the user explicitly asks. Naming hazard: `/ritual recon` was retired as a command surface, so don't reuse `Recon`/`Context` at the rail level.
 
 **Canonical ordering (only the active marker moves):**
 
 ```
-Context → Scope → Discovery → Recommendations → Build brief → Implementation (Your agent)
+Scope → Discovery → Recommendations → Build brief → Implementation (Your agent)
 ```
 
 - Completed stages: `✓`
@@ -185,46 +206,41 @@ Context → Scope → Discovery → Recommendations → Build brief → Implemen
 **Build rail spec (`progressHeader(stage)`) — CLI / terminal rendering:**
 
 ```text
-progressHeader("context") =>
-Ritual build
-● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
-
 progressHeader("scope") =>
 Ritual build
-✓ Context  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 progressHeader("discovery") =>
 Ritual build
-✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 progressHeader("recommendations") =>
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ● Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Scope  ✓ Discovery  ● Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 progressHeader("build-brief") =>
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
+✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
 
 progressHeader("implementation") =>
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
+✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
 ```
 
 **Compact chip spec — mobile chat / narrow chat:**
 
 ```text
-compactChip("context") =>      Ritual build · 1/6 Context
-compactChip("scope") =>        Ritual build · 2/6 Scope
-compactChip("discovery") =>    Ritual build · 3/6 Discovery
-compactChip("recommendations")=> Ritual build · 4/6 Recommendations
-compactChip("build-brief") =>  Ritual build · 5/6 Build brief
-compactChip("implementation")=> Ritual build · 6/6 Implementation (Your agent)
+compactChip("scope") =>        Ritual build · 1/5 Scope
+compactChip("discovery") =>    Ritual build · 2/5 Discovery
+compactChip("recommendations")=> Ritual build · 3/5 Recommendations
+compactChip("build-brief") =>  Ritual build · 4/5 Build brief
+compactChip("implementation")=> Ritual build · 5/5 Implementation (Your agent)
 ```
 
 Optional second line at phase transitions, resumes, and decision gates:
 
 ```text
-Done: Context · Next: Discovery
+Done: Scope · Next: Recommendations
 ```
 
 **Rich-app spec — persistent stepper:**
@@ -283,7 +299,7 @@ Use engineer-facing language in CLI output:
 |---|---|
 | `problemStatement` | scope |
 | `consideration` | sub-problem |
-| `Step 1.5`, `Step 7.4.5`, `Step CP3` | natural labels such as "existing work check", "question picking", "build brief" |
+| `Step 1.5`, `Step 7.3.1`, `Step CP3` | natural labels such as "existing work check", "question picking", "build brief" |
 | raw recon dump | recon digest |
 | "I inferred…" | direct default + override path |
 | **`decisions` / `decision` as a label or count** (e.g. "5 decisions logged", "decision list", "the N decisions you made") | Frame as **the implementation itself**. Recommendations get *implemented*; the artifacts of that implementation are surfaced inline (specific choices, deferrals, files touched) rather than as a labeled count. The underlying API parameter is still `decisions[]`, but the user sees "your implementation" / "what you implemented" / inline content. |
@@ -319,7 +335,7 @@ For no-arg `/ritual build` with zero explorations, do not frame `/ritual context
 
 ```text
 Ritual build
-● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Using workspace: {workspaceName}.
 

package/skills/codex/ritual/references/context-pulse-flow.md

@@ -278,7 +278,6 @@ You're past the recommendation-ready threshold. Generate the brief? (y/N)
 
 Render rules:
 - **Always show reasoning readiness + context debt at the top** (dual framing — the product pitch is about debt going down, but the primary score is the readiness one).
-- **`Context deferred` line is conditional** — only shown when deferred > 0 (CLI Tenet #6 — silence on no-data). Reflects deliberate phase-2 classification from Step 7.4.5; NOT counted as a liability.
 - **State-tier (Context surface) is a separate explicit line** in the full pulse, not folded into the readiness number — so the user can see both the percentage AND its qualitative meaning at a glance.
 - **Bars are 10-cell `▓` / `░`**, rounded to the nearest 10%.
 - **Dimensions printed in fixed weight order.** For `dimensionsVersion=2` (current canonical): Feature clarity → Decision resolution → Code grounding → Reference grounding → Assumption load → Validation readiness. For `dimensionsVersion=1` (legacy back-compat): Feature clarity → Decision resolution → Repo grounding → Assumption safety.