@ritualai/cli 0.11.0 → 0.24.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

@@ -61,7 +61,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:
 
@@ -283,7 +283,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. |

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.