@ritualai/cli 0.7.9 → 0.7.10

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

@@ -63,6 +63,176 @@ Do not ask for confirmation after safe defaults. State the default and give a li
 
 **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.
 
+**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:
+
+| Raw tier | User-facing phrasing |
+|---|---|
+| `RAW_ASK` | `initial ask + code recon` or `scope not locked yet` |
+| `UNDER_SPECIFIED` | `still under-specified` or `discovery in progress` |
+| `EXPLORED` | `explored — recommendations under review` |
+| `READY` | `ready for build brief` |
+
+Use the parenthetical form when the surrounding sentence is the readiness/debt summary, for example: `Pulse: Reasoning Readiness ~35% · Context Debt 65% (scope not locked yet)`. The standalone form is acceptable in headings or status badges, e.g. `Phase: code recon`.
+
+**Surface-aware continuation prompts:** Do NOT tell users to "Press Enter" inside `/ritual build` or `/ritual resume` when running in an agent chat surface (Claude Code, Cursor, Codex, etc.). Chat agents cannot reliably observe empty input — pressing Enter typically inserts a newline or sends nothing visible, and the agent has no callback for "user pressed Enter and didn't type anything." Telling the user to do that creates a stuck-flow trap.
+
+| Surface | Continuation contract |
+|---|---|
+| **Agent chat** (`/ritual build`, `/ritual resume`, anywhere this SKILL drives the conversation) | Use an explicit reply token. The token IS the visible CTA. Empty input is NOT a valid proceed signal. |
+| **Real interactive CLI** (`ritual init`, `ritual login`, `ritual whoami`, etc. — code calling `prompt(...)` against a real TTY) | `Press Enter` is fine; the CLI is actually reading stdin and an empty line is a meaningful signal. |
+
+**Visible reply tokens per phase** (single visible CTA each — accept aliases internally but don't list them all):
+
+| Phase | Visible token | Accepted aliases (internal) |
+|---|---|---|
+| Generate / proceed | `go` | `g`, `generate`, `continue`, `skip`, `none`, `next` |
+| Accept the problem frame | `use` | `lock`, `l`, `go`, `continue`, `next` |
+| Run discovery → recommendations | `run` | `r`, `go`, `continue`, `next` |
+| Stop mid-flow | `pause` | `stop`, `cancel`, `exit` |
+
+Why one visible token (not three): the user is in a decision moment, scanning. `Reply use to accept` is cleaner than `Press Enter or type lock or l or go or continue to accept`. Aliases are kindness; the displayed CTA is clarity.
+
+**Why we demoted `lock`:** "lock" sounds final/irrevocable for a problem frame that is, in practice, very much iterable. `use` carries the right tone ("use this frame and continue"). Keep `lock` as a backwards-compat alias for users who learned the older copy; just don't display it.
+
+**Vertical spacing — readable density:** User-facing messages get cramped fast when sections run together. The agent must render top-level user-facing messages with the following blank-line discipline so the eye can scan in glances:
+
+| Between | Blank line? |
+|---|---|
+| Rail header → section title | ✅ one |
+| Section title → body paragraph | ✅ one |
+| Body paragraph → bullet list | ✅ one |
+| Labeled section → next labeled section (`Repo signals:` → `Constraint:`) | ✅ one |
+| Labeled section → its own bullets | ❌ none (label belongs ON TOP of its bullets) |
+| Bullet → next bullet in the same list | ❌ none |
+| Body content → pulse line | ✅ one |
+| Pulse line → `Next:` block | ✅ one |
+| Sub-view divider (e.g. landing → first per-matter view in the same message) | ✅ one + `────...` rule + ✅ one |
+
+When in doubt, prefer one blank line over none. The cost of a tiny gap is unnoticeable; the cost of dense crammed prose is real reader friction. Do NOT insert two blank lines in a row — that creates dead space and breaks visual rhythm.
+
+**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 | 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. |
+| **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.
+
+**Applies to:**
+
+- phase starts (a new stage opens)
+- decision gates (the user is about to choose)
+- recon summaries
+- generated scope / question / recommendation / brief summaries
+- resume handoff points
+- completion states
+- any user-facing pause prompt that closes a phase
+
+**Does NOT apply to:**
+
+- short polling keepalives (`Still generating…`)
+- one-line follow-up acknowledgements inside the same phase (`Got it.` / `Saved.`)
+- direct answers to user clarifying questions inside an ongoing exchange
+- **sub-views inside a phase that iterate** (per-matter pickers in Discovery, per-recommendation reviews in Recommendations, per-answer iterations, etc.) — render the full rail once at the phase landing, then use a lightweight **in-phase chip** on subsequent sub-views
+
+Soft rule of thumb: if the message is a top-level "here's where you are + what to do next," emit the rail. If it's a within-turn ack, a status heartbeat, or the next iteration of a sub-view the user is already cycling through, use the in-phase chip (or nothing) instead.
+
+**In-phase chip** (for iterating sub-views inside a phase that has already shown the full rail):
+
+```text
+Discovery — area 2 of 4: {matter.name}
+```
+
+Or for per-recommendation review in Step 9:
+
+```text
+Recommendations — 3 of 7: {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.
+
+**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        |
+| `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`                       |
+
+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.
+
+**Canonical ordering (only the active marker moves):**
+
+```
+Context → Scope → Discovery → Recommendations → Build brief → Implementation (Your agent)
+```
+
+- Completed stages: `✓`
+- Current stage: `●`
+- Future stages: `○`
+
+**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)
+
+progressHeader("discovery") =>
+Ritual build
+✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
+
+progressHeader("recommendations") =>
+Ritual build
+✓ Context  ✓ Scope  ✓ Discovery  ● Recommendations  ○ Build brief  ○ Implementation (Your agent)
+
+progressHeader("build-brief") =>
+Ritual build
+✓ Context  ✓ Scope  ✓ Discovery  ✓ Recommendations  ● Build brief  ○ Implementation (Your agent)
+
+progressHeader("implementation") =>
+Ritual build
+✓ Context  ✓ 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)
+```
+
+Optional second line at phase transitions, resumes, and decision gates:
+
+```text
+Done: Context · Next: Discovery
+```
+
+**Rich-app spec — persistent stepper:**
+
+The host app pins a stepper above the conversation; the message only carries the stage label as a top-line header (e.g. `Scope` or `Phase: Scope`). At phase transitions, resumes, and decision gates, include the compact chip in the body even on rich-app surface so the transcript reads cleanly when exported.
+
+All `/ritual build` and `/ritual resume` top-level messages in `references/build-flow.md` anchor to this spec — when a stage transitions, the existing examples advance the marker per the canonical ordering. If you need to rename a stage in the future, update this table first; everything else follows.
+
 
 ### CLI experience cheat-sheet
 
@@ -81,7 +251,7 @@ This skill drives a CLI surface where the user reads every line you print. Keep
 
 When you need to wait for async server work (requirements generation, build brief generation), this harness has hard rules:
 
-- **Use a single `Bash sleep 5` per poll iteration.** The harness blocks chained sleeps (`sleep 5; sleep 5`) and any `sleep ≥ 30`.
+- **Use a single `Bash sleep 5` per poll iteration. ALWAYS 5. Never escalate.** The harness blocks chained sleeps (`sleep 5; sleep 5`), any `sleep ≥ 30`, AND successive `sleep N` calls across turns at increasing N (e.g. `sleep 5` → `sleep 15` → `sleep 20` — also blocked). Don't try to "back off" by raising the sleep value when the operation is slow; the duration is a constant.
 - **Between polls, take a fresh turn.** The model wakes up every 5s, makes a status call, decides whether to continue or exit. The user sees progress every 5 seconds; total wall time is the same.
 - **Update the user every ~3 polls (~15s)** with a one-line "still generating…" — don't go silent for a minute.
 - **For genuinely long waits (>5 min)**, use the harness's `Monitor` tool with an `until <check>; do sleep 2; done` pattern rather than the standard poll loop.
@@ -94,11 +264,14 @@ After **Steps 3, 5, 7.4, 8, 9, and 10**, emit a one-line **context pulse** showi
 
 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: `Pulse: 72% readiness · 28% debt · +24% (decision resolution)`
+- **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
 - 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.
+
 The user can also invoke `/ritual context-pulse` directly anytime mid-flow to get a full breakdown.
 
 
@@ -164,9 +337,9 @@ Before the list exists, say:
 ```text
 Next: we'll generate a list of suggested problems to pick from.
 
-Press Enter or type `g` to generate the list.
+Reply `go` to generate the list.
 Or paste files/text/URLs to attach context first.
-Type `pause` to stop here.
+Reply `pause` to stop here.
 ```
 
 When showing generated sub-problems, never print versioned sub-problem headings. Use:
@@ -205,11 +378,11 @@ References:
 - {RB/decision/exploration label} — {one-line meaning}
   Source: {exploration title or id}{ optional URL if available}
 
-Press Enter or type `lock` to use this frame and review discovery questions.
+Reply `use` to use this frame and review discovery questions.
 Or reply with edits, e.g. `tighten`, `broaden`, `focus on outbox`, `drop dashboard`, or `pause`.
 ```
 
-Accept empty input, `lock`, `l`, `go`, `continue`, or `next` as lock/proceed.
+Visible CTA is `use`. Accept `lock`, `l`, `go`, `continue`, or `next` as backwards-compat aliases (do not display them). Per § Surface-aware continuation prompts, do NOT treat empty input as proceed inside agent chat.
 
 ### Engineering run mode
 
@@ -218,8 +391,8 @@ For engineering / agentic-coding templates, do not offer answers-only review and
 ```text
 Next: run discovery through recommendations.
 
-Press Enter or type `run` to continue.
-Type `pause` to stop here.
+Reply `run` to continue.
+Reply `pause` to stop here.
 ```
 
 ### Shipped work visibility

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

@@ -123,7 +123,7 @@ Sub-steps:
    <!-- Ritual context seed — generated {ISO date} -->
    <!-- Refreshed at {ISO datetime UTC} -->  <!-- updated every re-pulse; bias toward freshness -->
    <!-- Generated by /ritual context-pulse "{feature description}" -->
-   <!-- Pulse: {readiness}% reasoning readiness / {debt}% context debt — surface: {state-tier} -->
+   <!-- Pulse: Reasoning Readiness {readiness}% · Context Debt {debt}% — surface: {state-tier} -->
 
    # Context: {feature description}
 
@@ -248,10 +248,10 @@ Two visual modes, picked by context. The label terminology is tiered:
 | **Context Debt** | Both modes — inverse score | The product category framing |
 | **Context surface:** | Full-pulse state-tier label | The 5-tier classification (Raw ask / Under-specified / Exploration-safe / Recommendation-ready / Implementation-ready) |
 
-**Compact pulse** — single line, used by default for inline mid-`/ritual build` pulses when nothing dramatic happened this step. Uses shorthand `readiness` to keep the line tight:
+**Compact pulse** — single line, used by default for inline mid-`/ritual build` pulses when nothing dramatic happened this step. Uses the full capitalized labels (NOT shorthand) for consistency with the full pulse and the docs:
 
 ```
-Pulse: 72% readiness · 28% debt · +24% (decision resolution)
+Pulse: Reasoning Readiness 72% · Context Debt 28% · +24% (decision resolution)
 ```
 
 **Full pulse** — with bars + spelled-out labels, used when:

package/skills/gemini/ritual/references/discovery-classification.md

@@ -89,7 +89,7 @@ How should I treat the unpicked areas?
 3. Emit post-choice pulse — **reuse the same dominant-theme phrase** that appeared in the analysis paragraph + Option 1's prompt, so the user sees their choice acknowledged in the exact words they read:
    ```
    ✓ Tightened the problem statement around {dominant theme — same phrase as analysis paragraph + Option 1 prompt}.
-     Pulse: {readiness}% readiness · {debt}% debt · +{delta}% (feature clarity ↑ from narrower scope)
+     Pulse: Reasoning Readiness {readiness}% · Context Debt {debt}% · +{delta}% (feature clarity ↑ from narrower scope)
    ```
    Concrete example matching the django-oscar GDPR exploration: *"✓ Tightened the problem statement around data structure, storage, immutability, and retention categories."* — names what survived, not abstract *"the structural picks"*.
 
@@ -99,7 +99,7 @@ How should I treat the unpicked areas?
 3. Emit post-choice pulse — **note the second-field label is `deferred`, not `debt`**:
    ```
    ✓ {N} unpicked questions marked as phase-2 candidates.
-     Pulse: {readiness}% readiness · {deferred}% deferred · +{delta}% (decision resolution ↑ from deliberate deferral)
+     Pulse: Reasoning Readiness {readiness}% · Phase-later {deferred}% · +{delta}% (decision resolution ↑ from deliberate deferral)
    ```
    The `deferred` label (instead of `debt`) is load-bearing — deliberate sequencing is NOT a liability, and the pulse line should reflect that. Same number, different character.
 4. At Step 10c (build brief generation), the deferred matters MUST appear in the brief's *"Phase Candidates / Deferrable Items"* section. The agent appends the `deferred[]` set to the `generate_build_brief` `recon_context` payload as supplementary "explicit phase-2 candidates set by the user during discovery." The main `recon_context` payload remains the `codebase_context_packet`.
@@ -110,7 +110,7 @@ How should I treat the unpicked areas?
 3. Emit post-choice pulse — uses the `debt` label:
    ```
    ✓ {N} unpicked questions marked as context debt.
-     Pulse: {readiness}% readiness · {debt}% debt · +0% (open questions remain unresolved)
+     Pulse: Reasoning Readiness {readiness}% · Context Debt {debt}% · +0% (open questions remain unresolved)
    ```
    Avoid words like *"status quo"* — phrase it as a state, not a non-event.
 4. The next `/ritual context-pulse` will surface the unresolved questions as top debt sources.

package/skills/gemini/ritual/references/resume-flow.md

@@ -4,6 +4,8 @@
 
 Output: the user lands on the right step of an existing exploration's `/ritual build` flow — no new exploration created, no fresh-start path offered.
 
+**Build rail is load-bearing here too.** Every top-level user-facing message in `/ritual resume` MUST begin with the 6-stage build rail per `references/cli-output-contract.md` § Build rail — both during the picker (rail at `● Context`) and once you teleport into the chosen exploration (rail at whatever stage that exploration is in).
+
 
 ### When to use
 

package/skills/kiro/ritual/references/async-polling.md

@@ -2,18 +2,52 @@
 
 Use this for every long-running Ritual/MCP operation: discovery generation, agentic runs, requirement generation, build brief generation, and future async status surfaces.
 
-## Standard poll loop
-
-- Use a single `Bash sleep 5` per poll iteration.
-- Do not chain sleeps (`sleep 5; sleep 5`).
-- Do not use `sleep >= 30`.
-- Between polls, take a fresh turn: sleep, call status, decide continue/exit.
-- Print progress only when status/progress/current_step changes, or every ~3 polls (~15s).
+## Standard poll loop — single short sleep per turn, never escalate
+
+- **`Bash sleep 5` per poll iteration. Always 5. Never escalate.** Even if the operation has been running for minutes, the value stays `5`. The reason: the harness blocks "chained shorter sleeps" — successive `sleep N` calls across turns at increasing N (e.g. `sleep 5` → `sleep 15` → `sleep 20` → `sleep 25`) trip the same guard as `sleep 30+`. Treat the sleep duration as a constant, NOT a backoff knob.
+- **One sleep per turn**, not multiple in sequence. After `sleep 5`, take a fresh turn → call the status tool → decide continue or exit.
+- **`sleep ≥ 30` is hard-blocked**, regardless of context.
+- **Do NOT use semicolons to chain** (`sleep 5; sleep 5`) — also blocked.
+- **The user sees progress every 5 seconds, total wall time is the same.** A slow operation taking 2 minutes is 24 turns of `sleep 5` + status, not 4 turns of `sleep 30`.
+- Print progress only when status/progress/current_step changes, or every ~3 polls (~15s) if unchanged.
 - Keep updates to one line unless an error occurs.
 
-## Long waits
+### Wrong vs right
+
+**Wrong** (this is what trips the harness — note each call is a separate turn, the sleep duration creeps up):
+
+```
+Turn 1:  Bash sleep 5   → status: still running
+Turn 2:  Bash sleep 15  → status: still running           ← creeping up
+Turn 3:  Bash sleep 20  → status: still running           ← creeping up
+Turn 4:  Bash sleep 25  → BLOCKED ✗ "standalone sleep 25"
+```
+
+The harness sees the pattern and blocks. The error message literally says: *"Do not chain shorter sleeps to work around this block."*
+
+**Right** — sleep stays at 5s every iteration; the loop ends when status reports done:
+
+```
+Turn 1:  Bash sleep 5   → status: still running
+Turn 2:  Bash sleep 5   → status: still running
+Turn 3:  Bash sleep 5   → status: still running
+Turn 4:  Bash sleep 5   → status: still running
+...
+Turn N:  Bash sleep 5   → status: COMPLETED  → exit loop
+```
+
+User-facing: print `Still generating… ({percent}% if available)` every ~3 turns (~15s) when status hasn't changed, ONE line per progress change otherwise.
+
+## Long waits — when polling >5 min, use Monitor + `until` loop instead
+
+For genuinely long waits (>5 minutes), DO NOT keep the standard poll loop running for that long — switch to the harness's `Monitor` tool with an `until <check>; do sleep 2; done` pattern. The `until` loop is one Bash call that internally checks + sleeps + retries, so it doesn't trip the "chained successive sleeps across turns" guard.
+
+```bash
+# Inside a Monitor / single Bash call — NOT chained across turns.
+until [ "$(curl -s ...status... | jq -r .status)" = "COMPLETED" ]; do sleep 2; done
+```
 
-For genuinely long waits (>5 minutes), use the harness's `Monitor` tool with an `until <check>; do sleep 2; done` pattern rather than the standard poll loop.
+Pair this with `run_in_background: true` if appropriate — start the long-running watch, get a task id back, check on it later via TaskOutput rather than blocking the conversation.
 
 ## Timeout recovery