@ritualai/cli 0.7.8 → 0.7.9

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

@@ -39,12 +39,63 @@ When **not** to use:
 
 Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must choose among options, approve creation or acceptance, resolve ambiguity, authorize implementation, accept cost/time, or provide missing non-code context. Do **not** pause for status-only steps, safe defaults, internal recon, or silent checks.
 
+**Pauses are not optional even in auto-mode.** See Step 0 below — when the host agent has auto-accept / bypass-permissions enabled, the SKILL must still honor every `[USER PAUSE]` as a hard stop. Inferring an answer from context, choosing a default, or pressing on without an actual user reply defeats the build flow's value: Ritual is producing aligned recommendations because the human shaped the inputs, not because the agent guessed plausibly.
+
 ---
 
 ### CLI and async guardrails
 
 Follow `references/cli-output-contract.md` for terminal output, dense-list formatting, user-facing vocabulary, and the no-internal-step-label rule. Follow `references/async-polling.md` for every long-running server operation.
 
+#### Step 0 — Permission mode check (pre-flight)
+
+Before any tool call on a fresh `/ritual build` invocation, check whether the host coding agent is running in **auto-accept** or **bypass-permissions** mode. Different agents call this different things, but the behavioral signature is the same: the agent has been told it can skip per-action confirmations and keep moving.
+
+Why this matters: `/ritual build` is built around ~5 real human decisions (workspace, scope, discovery question picks, recommendation acceptance, implementation approval). Each is a `[USER PAUSE]` later in this flow. Auto-mode collapses those gates — the agent defaults each answer and races through. The resulting exploration looks normal but doesn't reflect the user's judgment, which is the entire reason `/ritual build` exists rather than going straight to code.
+
+How to detect (per-agent):
+
+| Agent | Indicator |
+|---|---|
+| **Claude Code** | TUI footer shows `auto-accept edits` or `bypass permissions`. Toggled with **Shift+Tab**. |
+| **Cursor** | "Auto" / "Yolo" toggle in the Composer/Agent panel. |
+| **Codex** | `--full-auto` CLI flag or the equivalent setting in the IDE extension. |
+| **Kiro** | Per-server `autoApprove[]` arrays in `mcp.json`, plus any global "auto" toggle in the Agent panel. |
+| **Windsurf / VS Code Copilot / Gemini CLI** | Each has its own auto-accept mode in settings. |
+
+If the agent cannot detect this with confidence (the indicator surface differs by version), default to **asking the user** at the start of every `/ritual build`. The check is cheap; a wasted build is not.
+
+**If auto-mode is on (or you're uncertain), surface this before Step 1:**
+
+```text
+Heads up — looks like your coding agent is in auto-mode for this session.
+
+Ritual's build flow needs ~5 real decisions from you across the next
+20–30 minutes:
+  · which workspace to use
+  · how to scope the problem
+  · which discovery questions matter for your case
+  · which recommendations to accept
+  · whether the build brief is ready to implement
+
+Auto-mode tends to speed past these. The output will look like a
+normal Ritual exploration but won't actually reflect your input —
+the recommendations will be plausible-but-not-yours.
+
+──────────────────────────────────────────────────────────────────
+Recommended: turn off auto-mode before continuing.
+  · Claude Code: Shift+Tab to cycle back to "default"
+  · Other agents: see your agent's settings or CLI flag
+──────────────────────────────────────────────────────────────────
+
+1. Pause — I'll turn off auto-mode, then say "go"
+2. Continue anyway (I want speed over alignment for this run)
+```
+
+**[USER PAUSE — required, do not auto-answer]** Wait for an actual user message before proceeding.
+
+Regardless of which option the user picks, treat every subsequent `[USER PAUSE]` in this flow as a hard stop. Do not infer answers from context, do not pick a "reasonable default," do not press on without an actual user reply. The user picking option 2 means *they accept the trade-off* — it does NOT grant you permission to auto-answer the gates that come next.
+
 #### Step 1
 #### Step 1 — Pick a workspace
 
@@ -102,7 +153,7 @@ If there are **zero existing explorations** and `raw_input = null`, do not say "
 
 ```text
 Ritual build
-● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation
+● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Using workspace: {workspaceName}.
 
@@ -137,7 +188,7 @@ Steps:
    >
    > **{state_glyph} {state_label}**
    > - **{name}** — {short scope summary, first 80 chars of problemStatement}
-   >   - {recommendationCount} rec{s} ({accepted}/{total} approved), {decisionsCount} decision{s} logged, {openDeferralsCount} open deferral{s}
+   >   - {recommendationCount} rec{s} ({accepted}/{total} approved{implementationSegment}), {openDeferralsCount} open deferral{s}
    >   - {state-specific call-to-action — see table below}
    >
    > Recommended: resume one if it matches this work.
@@ -149,7 +200,7 @@ Steps:
    >
    > **{state_glyph} {state_label}**
    > - **{name}** — {short scope summary, first 80 chars of problemStatement}
-   >   - {recommendationCount} rec{s} ({accepted}/{total} approved), {decisionsCount} decision{s} logged, {openDeferralsCount} open deferral{s}
+   >   - {recommendationCount} rec{s} ({accepted}/{total} approved{implementationSegment}), {openDeferralsCount} open deferral{s}
    >   - {state-specific call-to-action — see table below}
    >
    > Reply with:
@@ -158,6 +209,20 @@ Steps:
    > - a feature/problem description to start fresh
    > - `none` to exit
 
+   **`{implementationSegment}` resolution rule** — derive from `implementationStatus.implementationRecord` on the listing response:
+
+   | Condition | Render |
+   |---|---|
+   | No `ImplementationRecord` | `` (empty — drop the segment) |
+   | Has record but `prUrl` is null | ` · synced (no PR linked)` |
+   | `prStatus = merged` | ` · implemented in PR #{prNumber}` |
+   | `prStatus = open` or `draft` | ` · implementing in PR #{prNumber} [{prStatus}]` |
+   | `prStatus = closed` (not merged) | ` · abandoned (PR #{prNumber} closed)` |
+
+   In markdown-rendering agents, hyperlink `PR #{prNumber}` to `prUrl` so users can click through. In plaintext agents, append `prUrl` on the next line.
+
+   **Rationale** — promotes recommendations to the visible noun and folds the previously-separate "decisions logged" count into the recommendation lifecycle. `Implemented` means "this exploration's approved recs shipped as code, here's the PR" — a stronger user-facing signal than a raw decision count. Decisions still exist as the underlying KG primitive (and are still surfaced explicitly by `/ritual lineage`), but they're no longer a headline concept in the build/resume status line.
+
    State badge → user-facing label + call-to-action:
 
    | Glyph | State | User-facing label | Suggested next action |
@@ -427,7 +492,7 @@ If a `CONTEXT-<slug>.md` is found AND its `## The ask` section close-matches the
 - **Surface a compact note**:
   > Code recon
   > Found `CONTEXT-<slug>.md` from `/ritual context-pulse`.
-  > Using {N} candidate files + {M} prior KG decisions as the recon base. Override with `recon: refresh`.
+  > Using {N} candidate files + {M} related prior exploration{s} as the recon base. Override with `recon: refresh`.
 - Proceed directly to 3.2.
 
 If no seed file is found, OR the seed's `## The ask` doesn't match the current `raw_input`, do fresh recon. For mismatch, mention the ignored seed in one line and do not delete it.
@@ -691,22 +756,24 @@ LLM call, ~5–10s. Returns 5–6 sub-problems — different framing axes the sy
 
 The coding agent's packet is context, not authority. Do not pre-rank or collapse the generated sub-problems based only on the agent hypotheses. Let MCP/template/KG output determine the candidate considerations; use the packet to make them specific, evidenced, and grounded.
 
-**If the response includes `kg_context_used` with `implementationCount > 0`:** surface this to the user BEFORE presenting the considerations. It's the visible signal that prior team decisions shaped this draft.
+**If the response includes `kg_context_used` with `implementationCount > 0`:** surface this to the user BEFORE presenting the considerations. It's the visible signal that prior shipped work shaped this draft.
 
 > Reading the codebase I overlapped with 3 prior Ritual explorations on these files:
->  - **"Anonymous checkout opt-in"** (shipped 2026-04-12) — 2 decisions, 1 deferral
->  - **"Payment-method routing"** (shipped 2026-03-22) — 4 decisions
->  - **"Session-data persistence"** (shipped 2026-02-08) — 1 decision
+>  - **"Anonymous checkout opt-in"** (shipped 2026-04-12) · 1 open deferral
+>  - **"Payment-method routing"** (shipped 2026-03-22)
+>  - **"Session-data persistence"** (shipped 2026-02-08)
 >
 > I factored those into the sub-problems below.
 
+(Drop the per-exploration decision count from this listing — recommendations + ship status are the user-facing signals, not decision counts. Keep `· N open deferral{s}` when `deferrals > 0` since open deferrals are scope-warning notes the user cares about. If `deferrals === 0`, just show `(shipped {date})` with no trailing segment.)
+
 If `implementationCount === 0`: don't mention the KG check (silent — would just be noise on a cold KG).
 
 **[USER PAUSE]** Present as `Problems to solve for`, never as versioned sub-problem headings:
 
 ```text
 Ritual build
-✓ Context  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation
+✓ Context  ● Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Problems to solve for
 
@@ -839,7 +906,7 @@ Store `exploration_id`. Move the progress header from Scope to Discovery:
 
 ```text
 Ritual build
-✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation
+✓ Context  ✓ Scope  ● Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Exploration created. Track progress at https://dev.ritualapp.cloud/e/{exploration_id}
 
@@ -916,16 +983,49 @@ The state contains `matters[]`, each with `id`, `name`, and `questions[]`. Walk
 ```text
 Discovery area: {matter.name}
 
-Pick the questions Ritual should answer before recommendations.
-Choose `all`, numbers like `1,3`, or `skip`.
+  1. {question 1}
+  2. {question 2}
+  ...
+
+Pick the questions Ritual should answer for this area. Reply with:
 
-1. {question 1}
-2. {question 2}
-...
+  ·  `suggest` — help me pick the top 3–4 highest-leverage questions for this area
+  ·  numbers like `1,3,5` — pick specifically
+  ·  `skip` — this area isn't relevant to the current scope
 ```
 
 **[USER PAUSE]** Wait per matter.
 
+###### "suggest" handling
+
+When the user replies `suggest` for a matter, propose which questions to send to `accept_discovery_questions` rather than asking again. Selection rule:
+
+- **Pick the top 3–4 questions most likely to shape the recommendations** based on the problem statement, the locked sub-problems from Step 4, and the codebase recon context from Step 3. Bias toward questions whose absence would force later stages to invent consequential facts.
+- If the matter has **fewer than 4 questions**, pick all of them.
+- If the matter has **4 to 7 questions**, pick 3.
+- If the matter has **8+ questions**, pick 4.
+
+After picking, tell the user which ones were suggested so they can see and override:
+
+```text
+Suggested picks for "{matter.name}":
+  ✓ {question N} — {one-line why this matters}
+  ✓ {question M} — {one-line why this matters}
+  ✓ {question P} — {one-line why this matters}
+
+Reply `redo` to suggest a different set, `numbers` to override (e.g. `2,5,7`), or `next` to continue.
+```
+
+`next` is the default — if the user just hits enter or says "looks good," proceed. Do not pause for explicit confirmation if the user already said `suggest`; the assist is the action, not a preview the user has to re-approve.
+
+###### "skip" handling
+
+Treat the matter as not requiring questions. Don't call `accept_discovery_questions` for it. The unpicked questions feed Step 7.4.5's classification check.
+
+###### Removed: `all` (the old fourth option)
+
+The legacy `all` shortcut was removed because in practice it produced low-signal selections — picking everything is indistinguishable from not discriminating, which makes Reasoning Readiness scoring less meaningful at the boundary and pushes recommendation generation against a noisy answer set. Users who really did mean "everything" can still type the full number list (e.g. `1,2,3,4,5`) — but that requires conscious intent rather than a one-keystroke default. If you see a SKILL or external reference still mentioning `all`, it's stale.
+
 ##### 7.4 — Commit picks per-matter
 
 For each matter where the user picked at least one question, call `mcp__ritual__accept_discovery_questions` with:
@@ -1338,7 +1438,7 @@ Intermediate commits can skip the footer. The final commit IS the linkage anchor
 **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:
 
 ```
-✓ Implementation done — {exploration name}
+✓ Implementation done (your agent) — {exploration name}
   Branch: {branch}, {N} commits, {M} files changed
   Tests: {tests_added} added, all passing
   RBs satisfied: {comma-joined list of RB-N from the brief, ALL or a count}
@@ -1399,12 +1499,12 @@ Before asking for permission, frame the call in language the user can act on. `s
 
 > I'm about to log this implementation into the workspace's knowledge graph. After this:
 > - The exploration's state flips to ✓ done (or ⚠ implemented-ahead if any recs weren't approved when shipped).
-> - The {N} architectural decisions you made get linked back to the recommendations that motivated them — so future `/ritual build` calls touching `{first 2 files}` will see your decisions as priorContext.
+> - The implementation gets linked back to the recommendations it implements — so future `/ritual build` calls touching `{first 2 files}` will see this implementation as priorContext.
 > - The {M} open deferrals you intentionally punted get logged with their reasons — peers can see them in `/ritual lineage` on these files later.
 >
-> **OK to log? (y / hold off / let me adjust the decision list first)**
+> **OK to log? (y / hold off / let me adjust the list first)**
 
-This framing replaces "I need to call sync_implementation, OK?" — which is jargon. The user should know what they're approving in product terms (CLI Tenet #4 — cite the specific signal).
+This framing replaces "I need to call sync_implementation, OK?" — which is jargon. The user should know what they're approving in product terms (CLI Tenet #4 — cite the specific signal). Note the vocabulary rule in `cli-output-contract.md` — do not surface "decisions" / "{N} decisions" as a user-facing label here; frame the moment as logging the **implementation** itself.
 
 ##### 12.1 — Make the call
 
@@ -1428,15 +1528,17 @@ When sync_implementation succeeds, the response includes:
 **Surface ALL of this to the user**, not just "ok logged." This is the visible signal that the loop closed. Format:
 
 > ✓ Logged implementation for **{exploration name}**
->   - {decisionsCount} decision{s} registered: {first 2 decisions, e.g. "auth: OAuth not SAML; data-model: tenant-scoped indexes"}
+>   - Implemented: {first 2 area:choice pairs from the `decisions[]` payload, e.g. "auth: OAuth not SAML; data-model: tenant-scoped indexes"}
 >   - {deferralsCount} deferral{s} registered: {first 1, e.g. "[major] Rate-limit per-tenant — out of scope for v1"}
 >   - View: {webUrl}
 >
 > Future `/ritual build` calls touching `{first 2 of filesChanged}` will now see this implementation in their priorContext block.
 
-If any decision's `recommendationStatusAtImplementation` is NOT `approved` (i.e. the Branch B path), add a callout:
+The `Implemented:` line surfaces a representative slice of WHAT got implemented (concrete area:choice pairs from the underlying `decisions[]` payload) rather than a labeled count. Per the vocabulary rule in `cli-output-contract.md`: the word "decisions" is not surfaced as a user-facing label; the artifacts ARE the signal.
+
+If any anchor's `recommendationStatusAtImplementation` is NOT `approved` (i.e. the Branch B path), add a callout — still frame in implementation/recommendation terms:
 
-> ⚠ {M} decision{s} implemented while their source recommendation was still in **{status}** — the exploration now shows `implemented_ahead`. An admin should review + accept the recs to close the gap.
+> ⚠ {M} of the recommendations were implemented while still in **{status}** state — the exploration now shows `implemented_ahead`. An admin should review + accept the recs to close the gap.
 
 The closing sentence is the most important one: it tells the user **what just happened in the system** in product-level terms. Without it, sync_implementation feels like a write-only black hole. With it, the user understands they just contributed to the workspace's memory.
 
@@ -1446,9 +1548,44 @@ User-visible:
 
 > `sync_implementation` failed: {error summary}
 > Saved the intended sync payload to `.ritual/pending-sync/<exploration-id>.json`.
-> Retry later with the same payload; no implementation decisions were lost.
+> Retry later with the same payload; nothing about your implementation was lost.
+>
+> (Run `/ritual resume` later to see + retry pending syncs.)
+
+Create `.ritual/pending-sync/` if needed. **Ensure the directory is gitignored** — the saved payload contains `decisions[].rationale` text the user typed and commit-level data that shouldn't end up in shared repo history. On the first failed sync, also write `.ritual/pending-sync/.gitignore` with `*` so the directory itself is committed but its contents aren't (gives teammates the breadcrumb that pending syncs exist without leaking contents):
+
+```bash
+mkdir -p .ritual/pending-sync
+[ -f .ritual/pending-sync/.gitignore ] || echo '*' > .ritual/pending-sync/.gitignore
+[ -f .ritual/pending-sync/.gitignore ] && ! grep -q '^!\.gitignore$' .ritual/pending-sync/.gitignore && echo '!.gitignore' >> .ritual/pending-sync/.gitignore
+```
+
+That two-line `.gitignore` (`*` then `!.gitignore`) follows the standard pattern: ignore everything in this directory EXCEPT the gitignore file itself. Most teams already use this idiom for `.cache/`, `node_modules/`, etc.
+
+##### 12.2 — Staleness check before retry
+
+When retrying a pending sync from `.ritual/pending-sync/<id>.json`, the user may have committed more code since the failure. The saved payload's `commits[]` is a frozen snapshot — re-uploading it after additional commits land would mis-attribute the new work as "not part of this exploration."
+
+Before re-invoking `sync_implementation` on a saved payload:
+
+1. Read the payload's `commits[]` (each has a `sha`).
+2. Run `git log --pretty=format:%H` against the payload's `branch`.
+3. Compare: if there are commit SHAs in `git log` that AREN'T in the payload's `commits[]`, the payload is stale.
+
+If stale, surface to the user:
+
+> ⚠ This pending sync was saved {N} day(s) ago. Since then you've added {M} more commit(s) to `{branch}` that aren't in the saved payload.
+>
+> Retrying as-is would log a partial picture (decisions from when the failure happened, but missing the {M} new commits).
+>
+> Options:
+>   1. **Retry as-is** — log what was saved; you can sync the new commits in a follow-up.
+>   2. **Regenerate** — re-run Step 12 from scratch with the current state; discards the saved payload.
+>   3. **Show me** — print the {M} new commits so I can decide.
+
+**[USER PAUSE — required, do not auto-answer]** Wait for response. Option 2 is usually right when there's been substantive work; option 1 is fine for small follow-up commits the user wants attributed to the next sync.
 
-Create `.ritual/pending-sync/` if needed. Keep the pending-sync file git-tracked unless the repo has a different convention for generated workflow state.
+If the saved payload's `commits[]` matches current git state, proceed silently to the retry.
 
 #### Step 13 — Optional follow-up
 

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

@@ -113,9 +113,12 @@ Use engineer-facing language in CLI output:
 | `Step 1.5`, `Step 7.4.5`, `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. |
 
 Internal step labels are allowed inside reference docs and implementation notes. Translate them before showing text to users.
 
+**Why the `decisions` rule (2026-05-13):** Earlier copy surfaced `5 decisions logged` and `Decision: <text>` as status badges. Users read those as a parallel concept to recommendations, which inflated the cognitive surface. The lifecycle the user actually tracks is `recommendation → approved → implemented`. The decision artifacts exist (and are still surfaced explicitly by `/ritual lineage`, where decision-on-file archeology IS the subcommand's purpose), but they are NOT a headline concept in `/ritual build` or `/ritual resume`. When the user is about to authorize `sync_implementation`, frame the moment as "log this implementation" — not "log these N decisions."
+
 ## Dense list format
 
 When showing high-leverage candidates, recommendations, lineage events, or other dense lists, use labeled blocks:
@@ -143,7 +146,7 @@ For no-arg `/ritual build` with zero explorations, do not frame `/ritual context
 
 ```text
 Ritual build
-● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation
+● Context  ○ Scope  ○ Discovery  ○ Recommendations  ○ Build brief  ○ Implementation (Your agent)
 
 Using workspace: {workspaceName}.
 

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

@@ -27,6 +27,51 @@ If the workspace has **zero explorations**: tell the user politely and pivot.
 
 End the flow here. Don't bounce them into `/ritual build` automatically — explicit user intent beats implicit handoff.
 
+#### Step R1.5 — Check for pending syncs (if any)
+
+Before showing the in-flight exploration list, glance at `.ritual/pending-sync/` to surface any `sync_implementation` calls that failed in past sessions. These are the cleanest "you left something undone" signal — more concrete than an exploration's state badge alone.
+
+Quick scan:
+
+```bash
+ls .ritual/pending-sync/*.json 2>/dev/null
+```
+
+If the directory doesn't exist or has no `.json` files: proceed silently to R2. Most invocations land here.
+
+If there ARE pending syncs:
+
+1. Read each `.json` file. Extract `explorationId`, `branch`, `commits[].sha` count, and the file's mtime ("saved Xd ago").
+
+2. For each, do a **quick staleness probe** — same shape as `/ritual build` Step 12.2:
+
+   ```bash
+   # In the payload's branch, are there commits not in payload.commits[]?
+   git log {branch} --pretty=format:%H 2>/dev/null
+   ```
+
+3. Surface the list before the regular exploration picker:
+
+   ```text
+   You have {N} pending sync{s} from past sessions:
+
+     1. **{exploration name}**
+        Saved {Xd} ago · {commitsCount} commit{s} · branch `{branch}`
+        {stalenessBadge}   ← "✓ still current" | "⚠ {M} new commits since save"
+
+     2. ...
+
+   Resolve before resuming? (Y/n)
+   ```
+
+   **[USER PAUSE — required, do not auto-answer]** Wait for reply.
+
+4. If user says **yes**: for each pending sync (in order), apply the same flow as `/ritual build` Step 12.2's staleness check — retry as-is / regenerate / show new commits. Once resolved, delete the corresponding `.ritual/pending-sync/<id>.json` (succeeded) or leave it for later (deferred). Then continue to R2.
+
+5. If user says **no**: proceed to R2 silently. The pending syncs aren't going anywhere; the user can clear them later via `/ritual resume` again.
+
+The point: a pending sync is a stronger signal than "this exploration's state badge says ready" because the user's own code-tracking failed mid-flight. Surfacing them first means the user resolves obviously-broken state before being asked to pick a new thing to work on.
+
 #### Step R2 — Surface in-flight explorations with state badges
 
 Call `mcp__ritual__list_explorations(workspace_id)`. Sort by most-recently-updated. Drop archived. Cap at 5 in the user-facing summary.