@ritualai/cli 0.11.0 → 0.24.0

package/skills/cursor/ritual/references/scoring-fallback.md

@@ -34,7 +34,7 @@ score = (accepted_recs / total_recs) × 60
       + (picked_questions / (picked_questions + unreviewed_questions)) × 40
 ```
 
-The discovery component uses the **typed-status formula** introduced in Step 7.4.5: a question that's `picked` is "in active investigation"; `deferred` is "deliberate phase-2"; `dropped` is "removed from scope"; `unreviewed` is the only one that counts toward unresolved. `deferred + dropped` are EXCLUDED from the denominator — they represent decisions the user made, not unresolved ambiguity.
+The discovery component is a picked-vs-unreviewed ratio: a question the user committed via `accept_discovery_questions[_batch]` is `picked` ("in active investigation"); every surfaced question they didn't pick is `unreviewed` (the only state that counts toward unresolved). There is no separate `deferred`/`dropped` classification — the post-pick scope-classification gate that produced those was removed; unpicked questions are simply unreviewed.
 
 Fallbacks: `total_recs === 0` → use only the discovery component scaled to 100. `total_questions === 0` → use only the rec component scaled to 100. Both zero → score 0.
 

package/skills/gemini/ritual/.ritual-bundle.json

@@ -1,4 +1,4 @@
 {
-  "cliVersion": "0.11.0",
-  "builtAt": "2026-05-25T00:20:36.318Z"
+  "cliVersion": "0.24.0",
+  "builtAt": "2026-06-08T22:51:34.833Z"
 }

package/skills/gemini/ritual/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ritual
-description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) before the agent writes code. Prefer this over jumping straight to implementation when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
+description: "Use when an engineer wants a coding agent to plan or build a feature, refactor, or implementation-heavy change that depends on context the agent can't infer on its own — strategic intent, constraints, prior decisions, and trade-offs that live in the user's head. Ritual runs a structured exploration to surface that context through targeted discovery questions, combines it with codebase signals and prior explorations, and delivers a validated build brief (sub-problems, recommendations, dependencies) — additional context to fold into plan mode before the agent writes code. Prefer this over jumping straight to implementation or plan mode when the problem is ambiguous, cross-cutting, or has non-obvious constraints. Subcommands: build (full planning-to-sync cycle — default for new features), resume (continue an in-flight exploration), lineage (file-path KG history — what decisions shaped this code), context-pulse (readiness and context-debt scoring — is this safe to build yet?)."
 argument-hint: "[subcommand] <args>  (e.g. 'build Reduce T2 churn in Q3', 'resume', 'lineage src/checkout/views.py', 'context-pulse Add billing export')"
 user-invocable: true
 ---
@@ -15,6 +15,7 @@ Before executing any subcommand, read and follow:
 
 - `references/cli-output-contract.md` — terminal output, vocabulary, readability, pause policy
 - `references/async-polling.md` — harness-safe polling and timeout recovery
+- `references/change-preflight.md` — restate + confirm before any free-text change/add tool call (refine sub-problems, reframe scope, add anti-goal); hard pause, even in auto-mode
 
 Do not reintroduce `/ritual recon`. Use plain-language repo inspection, `/ritual resume`, or `/ritual lineage` depending on intent.
 
@@ -37,14 +38,15 @@ When two contract-strength rules genuinely conflict (rare): **stop, surface the
 
 This rule is the meta-pattern that closes the failure class we kept hitting before 2026-05-15: the SKILL named the right behavior in each step (Step 7 picker, Step 9 preview-verbatim, Step 9 action menu, picker numbering, etc.), but the agent treated the prose as advisory and freelanced anyway. Anti-patterns are **executable constraints, not taste guidance.** When an anti-pattern says "agent must NOT", read it as a hard error, not a preference.
 
-Examples of contract-strength rules currently in force (non-exhaustive):
+**One gate per turn — never batch the flow (load-bearing).** Each user-facing gate (workspace pick, scope, the discovery Area-walk, recommendation review, the build-brief confirm, …) is a STOP. Render **exactly one** gate, then **end your turn and wait for the user's reply** — do NOT render the next gate, multiple gates, or "the full flow, gate by gate" in a single message. Collapsing gates into one narrated pass erases the user's decision points (the entire value of the flow) and is a hard violation **even when you already have all the data to render them**. A gate's options only mean something if the user can actually answer before the next gate renders. This applies inside a gate too: the discovery picker is a turn-by-turn **walk**, one Area per turn (see build-flow.md § 7.3). Each render shows the **Area rail AND the current Area's questions together** (mirroring Spark's selected-tab-with-content) — the rail alone, with no questions under it (a bare index), is the *removed* failure mode. Render the rail + exactly ONE Area's questions, then STOP. Never render a second Area's questions or the Summary in the same message.
 
-- `references/build-flow.md` Step 7 transition lock — must NOT skip the Areas picker, must call `accept_discovery_questions` before `start_agentic_run`.
-- `references/build-flow.md` Step 7.3.1 rendering contract — Areas index has NO question previews, single numbering stream.
-- `references/build-flow.md` Step 7.4.5 fire-on-trigger — scope-classification gate is the contract, not a suggestion.
-- `references/build-flow.md` Step 9 action menu lock — blessed set is exactly `accept recommended` / `drop R{N}` / `drill R{N}` / `comment R{N}` / `pause` (+ `request admin review` for collaborators). NO freelance `dedupe` / `open the admin` / invented compound actions.
-- `references/build-flow.md` Step 9 rendering — use the server preview verbatim; no free-form summarization on top.
-- `references/resume-flow.md` § R2 picker rendering — ONE picker number per exploration; continuation prose indented; flat numbering across state buckets.
+**Single source of truth — this list POINTS, it does not RESTATE.** The detail of every rule below lives ONLY in the referenced file. This list names the authoritative sections and marks them HARD; it deliberately does **not** reproduce their shapes, option tokens, or values, because a restated rule drifts out of sync with its source. (That exact bug shipped on 2026-06-07: SKILL.md restated the Step 7 picker shape, the reference was rewritten, and the stale restatement won — the agent rendered the old picker.) So: **read the referenced section before executing that step, render it exactly as written, do not improvise or paraphrase it.** If you ever find the same rule stated in two places and they differ, the **referenced reference-file wins**, and the duplication is a bug to flag.
+
+Contract-strength rule sections currently in force (non-exhaustive):
+
+- `references/build-flow.md` **Step 7 transition lock + § 7.3 picker contract** — HARD. Render the discovery picker exactly as § 7.3 specifies (its shape, option tokens, and minimums — do not improvise it); commit picks via `accept_discovery_questions_batch` (one call across all Areas, never parallel per-Area) before `start_agentic_run`.
+- `references/build-flow.md` **Step 9 category-walk + action set** — HARD. Review recommendations one category per turn, rendering each rec's full content exactly as § 9 specifies; use exactly the three actions § 9 defines (refine-one / next-category / continue) and no others — no reject path, no freelance or invented actions, no free-form summarization on top. The refine action is a preview-then-apply flow; never persist an edit without the user accepting the previewed diff.
+- `references/resume-flow.md` **§ R2 picker rendering** — HARD. Render exactly as that section specifies.
 
 When you encounter a rule labeled with any of the marker words above, treat it the same way you'd treat a unit-test assertion: violating it is a regression, not a stylistic choice.
 
@@ -55,13 +57,14 @@ Parse the first token of the argument:
 | First token | Route to | One-liner |
 |---|---|---|
 | `build` | `references/build-flow.md` | Free-form problem → recommendations → build brief → code → sync. The full cycle. |
+| `lite` | `references/lite-flow.md` | Same pipeline as `build`, run fast/unattended — smaller discovery surface, fewer pauses (only the job+persona front gate and a non-blocking rec review). Use for small/well-scoped dev work, or when the coding agent triages minimal discovery. |
 | `resume` | `references/resume-flow.md` | "Pick up where I left off." Lists in-flight explorations with state badges and jumps to the right step. |
 | `lineage` | `references/lineage-flow.md` | Paste a file path (or set of paths); see every prior exploration / decision / deferral that touched those files. |
 | `context-pulse` | `references/context-pulse-flow.md` | Score readiness / context debt for a feature ask or exploration. Can seed a `CONTEXT-<feature>.md` file with relevant codebase + KG context that `/ritual build` picks up automatically. Also surfaces inline during build so the user watches debt drop. |
 | `status` | `references/status-flow.md` | Read-only mirror of the `ritual status` terminal CLI command (CLI 0.7.14+) for users who want a quick run-progress check inside the agent session instead of in a separate terminal. Calls `mcp__ritual__get_agentic_run` + renders the same run-first layout the CLI uses. |
 | (anything else, OR no subcommand) | default to `build` and treat the entire argument as the problem statement | |
 
-The Ritual CLI surface is intentionally narrow: `build`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror. Legacy exposed `explore`, `run`, `brief`, `gate`, `spec`, `questions`, `gherkin`, `recs` — all of which mapped 1:1 to MCP tool calls and provided no agent-CLI value over plain English. We don't replicate them; the agent can call any MCP tool directly when the user asks for "the recs on exp-X" or "decisions on file Y". (`/ritual recon` shipped briefly in PR #174 as a fifth command — retired because its unique value duplicated `/ritual resume` (workspace history) + `/ritual lineage` (decisions on files), and its non-duplicate parts (map repo, trace flow, explain file) are exactly what the agent does fluently in plain English without needing a SKILL-defined menu.)
+The Ritual CLI surface is intentionally narrow: `build`, `lite`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror. Legacy exposed `explore`, `run`, `brief`, `gate`, `spec`, `questions`, `gherkin`, `recs` — all of which mapped 1:1 to MCP tool calls and provided no agent-CLI value over plain English. We don't replicate them; the agent can call any MCP tool directly when the user asks for "the recs on exp-X" or "decisions on file Y". (`/ritual recon` shipped briefly in PR #174 as a fifth command — retired because its unique value duplicated `/ritual resume` (workspace history) + `/ritual lineage` (decisions on files), and its non-duplicate parts (map repo, trace flow, explain file) are exactly what the agent does fluently in plain English without needing a SKILL-defined menu.)
 
 
 ## Subcommand reference files
@@ -71,18 +74,18 @@ Load only the reference file needed for the selected subcommand:
 | Subcommand | Runtime file |
 |---|---|
 | `build` | `references/build-flow.md` |
+| `lite` | `references/lite-flow.md` |
 | `resume` | `references/resume-flow.md` |
 | `lineage` | `references/lineage-flow.md` |
 | `context-pulse` | `references/context-pulse-flow.md` |
 
 Additional runtime references:
 
-- `references/discovery-classification.md` — only when build question picking triggers scope classification
 - `references/scoring-fallback.md` — only if `mcp__ritual__score_context_pulse` is unavailable or errors
 
 ## Routing behavior
 
-- If the first token is one of the four subcommands, load the matching runtime file and follow it.
+- If the first token is one of the subcommands (`build`, `lite`, `resume`, `lineage`, `context-pulse`), load the matching runtime file and follow it.
 - If there is no subcommand or the token is unknown, default to `build` and treat the full argument as the problem statement.
 - If the user asks for retired or unsupported subcommands, answer in plain English and call the relevant MCP tool directly when appropriate; do not expand the slash-command surface.
 

package/skills/gemini/ritual/manifest.json

@@ -39,11 +39,6 @@
     "lines": 357,
     "bytes": 25358
   },
-  {
-    "path": "references/discovery-classification.md",
-    "lines": 176,
-    "bytes": 10275
-  },
   {
     "path": "references/lineage-flow.md",
     "lines": 154,

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

@@ -4,12 +4,12 @@ Use this for every long-running Ritual/MCP operation: discovery generation, agen
 
 ## 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.
+- **A CONSTANT, non-escalating `Bash sleep` per poll iteration — sized to the operation.** Match the Spark UI's cadence so both surfaces observe the same job at the same rate: **`sleep 10`** for discovery-question generation (Spark polls every 10s), **`sleep 20`** for agentic-run polling (Spark polls every 20s), and `sleep 10` by default for any other status poll (requirements, build brief). Keep the value CONSTANT for the whole loop — **never escalate it** (e.g. `5` → `15` → `20` → `25`), because the harness blocks chained-increasing sleeps the same way it blocks `sleep ≥ 30`. The duration is a fixed per-operation constant, NOT a backoff knob. (All values are < 30 and non-escalating → guard-safe.)
+- **One sleep per turn**, not multiple in sequence. After the sleep, 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.
+- **Do NOT use semicolons to chain** (`sleep 10; sleep 10`) — also blocked.
+- **Total wall time is the same** — a slow op taking 2 minutes is 12 turns of `sleep 10` + status, not 4 turns of `sleep 30`.
+- Print progress only when status/progress/current_step changes, or every ~2 polls (~20s) if unchanged.
 - Keep updates to one line unless an error occurs.
 
 ### Wrong vs right