@ritualai/cli 0.24.0 → 0.36.8

package/skills/cursor/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
@@ -116,8 +138,8 @@ When in doubt, prefer one blank line over none. The cost of a tiny gap is unnoti
 
 | 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, `● Job  ○ 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: Job, Scope · Next: Recommendations`. | Six-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:**
@@ -151,80 +173,106 @@ Soft rule of thumb: if the message is a top-level "here's where you are + what t
 Discovery — area 2 of 4: {matter.name}
 ```
 
-Or for per-recommendation review in Step 9:
+Or for a single-recommendation drill view in Step 9:
 
 ```text
-Recommendations — 3 of 7: {recommendation title}
+Recommendations · R{N} — {recommendation title}
 ```
 
 The chip's job is "you're still in this phase, this is which item of the series" — orientation without the full chrome.
 
+**Forward-pointing CTAs (load-bearing):** every advancing option at a `[USER PAUSE]` gate must name its DESTINATION in user language — never a bare "to continue" / "to proceed". Two accepted shapes:
+
+- inline parenthetical on the action line: `proceed (generate the {Deliverable})`
+- spelled-out reply line: ``Reply `proceed` to frame the problem (sub-problems + problem statement), or …``
+
+Canonical destinations (use these; don't improvise):
+
+| Gate | Advancing token | Destination phrase |
+|---|---|---|
+| Job gate (0.7) | `proceed` | frame the problem (sub-problems + problem statement) |
+| Problem frame (5) | `use` | review discovery questions |
+| Suggested-12 landing (7.3.1) | `proceed` | run discovery with these 12 (commits the set; run confirmation follows) |
+| Expert-walk summary (7.4) | `commit` | run discovery → recommendations (~a few minutes) |
+| Run gate (8) | `run` | source answers → generate recommendations |
+| Recommendations (9/9.1) | `proceed` | generate the {Deliverable} (the job's deliverable name from the rail) |
+| Audit gate (9.6.1) | `proceed` | skip the audit and generate the {Deliverable} |
+| Brief gate (10d) | `go` | implement in your agent |
+| Plan handoff (11.0.5) | `ready` | generate the implementation plan |
+
+`{Deliverable}` = the rail's stage-5 name (deliverable-named rail). The destination phrase, the rail's next stage, and what actually happens next must tell ONE story.
+
+**Universal advance alias:** `proceed` is silently accepted at EVERY advancing gate, mapped to that gate's primary token (`use`, `run`, `commit`, `go`, `ready`, …) — the user only ever needs one word. It is NOT displayed as an extra option. Exception already specified elsewhere: at the discovery pick gate an ambiguous `proceed` means **accept shortlist**, never accept-all. `next` is NOT a universal alias — it has gate-local meaning in the discovery Area walk (expert mode).
+
 **Canonical stage table (single source of truth):**
 
 | 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        |
+| `Job`              | The Step 0.7 Job gate — server-side classification of the user's raw ask (`classify_work_item`) + the user's confirmation of the job to be done; active until the user proceeds |
+| `Scope`            | Problem frame + sub-problem generation/selection, until scope is locked; the silent grounding recon runs at the lock→create boundary |
 | `Discovery`        | Exploration creation, discovery questions, answers, question picking, answer review |
-| `Recommendations`  | Recommendation generation, review, admin/collaborator acceptance path           |
-| `Build brief`      | Requirements + build brief generation/review                                   |
-| `Implementation (Your agent)` | Coding, branch/PR work, `sync_implementation`                       |
+| `Recommendations`  | Recommendation generation + review                                              |
+| `{Deliverable}`    | **Named for the job's deliverable** — the `deliverableTemplate` returned at the Job gate (e.g. `Launch Brief`, `PRD`, `Service Build Brief`; `Build brief` for the generic `build-feature`). Covers requirements + deliverable generation/review. |
+| `Implementation (Your agent)` | **Development-function jobs ONLY.** Coding, branch/PR work, `sync_implementation`. Non-development jobs (e.g. `create-launch-brief`) OMIT this stage — their rail has FIVE stages and ends at the deliverable. |
 
-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 `Job` — the Step 0.7 Job gate (classification + confirmation of the job to be done; on resume paths the gate is skipped and the rail opens with `Job` already `✓`). **There is no `Context` stage** — workspace pick, resume/start check, and template resolution all happen as **silent plumbing inside Scope**, never as a visible rail stage. The grounding **code recon** runs silently AFTER the frame locks (build-flow § Step 5.7) and is not surfaced by default; 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)
+Job → Scope → Discovery → Recommendations → {Deliverable} → Implementation (Your agent — development jobs only)
 ```
 
+The rail is **deliverable-named and function-shaped** (2026-06-11): stage 5 carries the job's own deliverable name, and stage 6 exists only for development-function jobs. The timeline is the promise — a Launch Brief job promises a Launch Brief, not a code handoff. Before the job is confirmed (the Job gate itself), render the PROPOSED classification's deliverable; a correction updates the rail on the next render.
+
 - Completed stages: `✓`
 - Current stage: `●`
 - Future stages: `○`
 
-**Build rail spec (`progressHeader(stage)`) — CLI / terminal rendering:**
+**Build rail spec (`progressHeader(stage, jtbd)`) — CLI / terminal rendering.** `{Deliverable}` below = the job's `deliverableTemplate`; the `Implementation` stage renders only for development-function jobs.
 
-```text
-progressHeader("context") =>
-Ritual build
-● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+Development job (e.g. `build-backend-service` → `Service Build Brief`; generic `build-feature` → `Build brief`):
 
-progressHeader("scope") =>
+```text
+progressHeader("job") =>
 Ritual build
-✓ Context  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+● Job  ○ Scope  ○ Discovery  ○ Recommendations  ○ {Deliverable}  ○ Implementation (Your agent)
 
-progressHeader("discovery") =>
+progressHeader("deliverable") =>
 Ritual build
-✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Job  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● {Deliverable}  ○ Implementation (Your agent)
 
-progressHeader("recommendations") =>
+progressHeader("implementation") =>
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ● Recommendations  ○ Build brief  ○ Implementation (Your agent)
+✓ Job  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ {Deliverable}  ● Implementation (Your agent)
+```
 
-progressHeader("build-brief") =>
-Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
+Non-development job (e.g. `create-launch-brief` → `Launch Brief`) — FIVE stages, no Implementation:
 
-progressHeader("implementation") =>
+```text
+progressHeader("deliverable") =>
 Ritual build
-✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ✓ Build brief  ● Implementation (Your agent)
+✓ Job  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● Launch Brief
 ```
 
+Intermediate stages (scope/discovery/recommendations) advance the markers identically in both shapes.
+
 **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)
+development job (N/6):           non-development job (N/5):
+compactChip("job")            => Ritual build · 1/6 Job        | 1/5 Job
+compactChip("scope")          => Ritual build · 2/6 Scope      | 2/5 Scope
+compactChip("discovery")      => Ritual build · 3/6 Discovery  | 3/5 Discovery
+compactChip("recommendations")=> Ritual build · 4/6 Recommendations | 4/5 Recommendations
+compactChip("deliverable")    => Ritual build · 5/6 {Deliverable}   | 5/5 {Deliverable}
+compactChip("implementation") => Ritual build · 6/6 Implementation (Your agent)   (dev only)
 ```
 
 Optional second line at phase transitions, resumes, and decision gates:
 
 ```text
-Done: Context · Next: Discovery
+Done: Job, Scope · Next: Recommendations
 ```
 
 **Rich-app spec — persistent stepper:**
@@ -258,16 +306,40 @@ When you need to wait for async server work (requirements generation, build brie
 
 This rule applies to: Step 9.5 (`get_requirement_set_status`), Step 10b (`get_build_brief_status` on timeout), and any future status-poll surface.
 
+<!-- skill-options:no-gate-change: pulse render gains a delta + next-lift line; no decision gate, option, or pause is added or changed -->
+
 #### Inline pulses — surface reasoning readiness climbing as context debt drops
 
 After **Steps 3, 5, 7.4, 8, 9, and 10**, emit a one-line **context pulse** showing how the score moved. This is the visible encouragement loop — the user watches **reasoning readiness** climb (or equivalently, **context debt** drop) with each step instead of just feeling like the agent is asking for more inputs.
 
 The pulse rule and visual specs live in the [§ /ritual context-pulse](#ritual-context-pulse) section below — see *Step CP5 — visual modes*. TL;DR:
 
-- **Compact (single line)** is the default. Use the full capitalized labels — `Reasoning Readiness` and `Context Debt` — NOT lowercase `readiness` / `debt`:
-  - `Pulse: Reasoning Readiness 72% · Context Debt 28% · +24% (decision resolution)`
-- **Full (with bars + Reasoning Readiness / Context Debt / Context Surface labels)** when crossing a state-tier boundary, jumping ≥15%, or regressing
-- The pulse line goes BEFORE the existing "next step" prompt for that step — it's an additive line, not a replacement
+The pulse has TWO parts, and they sit in DIFFERENT places — the score at the top of the message (status: where you are), and the **lift bridge** immediately above the action line (motivation: why your next move matters).
+
+  ```text
+  Pulse: Reasoning Readiness 58% · Context Debt 42% · +3% (scope locked)
+
+  {…the step's content…}
+
+  Most of the gap left is unsettled design decisions — that's exactly what
+  the next step, discovery, resolves.
+  Reply  proceed (run discovery → recommendations)  ·  expert  ·  pause
+  ```
+
+  - **Score line** (top of the message). Full capitalized labels — `Reasoning Readiness` and `Context Debt`, NOT lowercase. The **`· +N%` delta is MANDATORY** on every pulse after the first (the first pulse has no prior, so it shows just the baseline + reason). The delta is the visible-progress signal — never drop it. Show `+0%` honestly if a step didn't move the score, and `−N%` on a regression (rare; render full then).
+  - **Lift bridge** (ONE sentence, immediately ABOVE the action/CTA line — NOT under the score). This is the load-bearing piece: it turns the score into a reason to proceed. Three requirements:
+    1. **Plain language for the gap — NEVER the internal dimension name.** The lowest dimension from `score_context_pulse`'s breakdown picks the message, but the user sees what it MEANS, not the label:
+       | lowest dimension (internal) | what the user reads (plain) |
+       |---|---|
+       | `decisionResolution` | the design decisions aren't settled yet |
+       | `repoGrounding` | the plan isn't grounded in your code yet |
+       | `assumptionSafety` | some assumptions are still unverified |
+       | `featureClarity` | what exactly to build is still fuzzy |
+    2. **Name the NEXT STEP as the resolver, explicitly.** The bridge must make clear that the action the user is about to take is what closes the gap — `that's exactly what the next step, discovery, resolves` / `code recon next grounds it` / `the build brief locks those down`. The bridge and the forward-CTA below it name the SAME move — one story.
+    3. **Terse + declarative** — no `now let me help you improve this` assistant/affect register (`cli-experience-tenets.md`).
+    On the LAST scoreable step (Step 10, implementation-ready), there's no further lift — the bridge becomes the readiness statement: `The brief is your build path — implement when ready.`
+- **Full (with bars + Reasoning Readiness / Context Debt / Context Surface labels)** when crossing a state-tier boundary, jumping ≥15%, or regressing. Full mode keeps the same `+N%` delta on the score line and the same lift bridge above the CTA.
+- The score line goes near the top of the step's message; the lift bridge goes right before the action line. Both are additive, not replacements.
 - Prefer `mcp__ritual__score_context_pulse` (one canonical server-side call, persisted for trend reporting); fall back to deterministic agent-side counts only if the tool errors. No LLM call in the hot path either way.
 
 **Why full labels (load-bearing):** Users read `28% debt` as a vague accounting number. They read `Context Debt 28%` as a named concept with weight — the same name they'd see in `/ritual context-pulse`'s full view, in the score breakdown, in the docs. Consistency across compact and full forms means the user doesn't have to translate.
@@ -319,7 +391,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)
+✓ Job  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Using workspace: {workspaceName}.