@ritualai/cli 0.11.0 → 0.25.0

package/skills/claude-code/ritual/references/resume-flow.md

@@ -4,7 +4,7 @@
 
 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).
+**Build rail is load-bearing here too.** Every top-level user-facing message in `/ritual resume` MUST begin with the 5-stage build rail per `references/cli-output-contract.md` § Build rail — both during the picker (rail at `● Scope`) and once you teleport into the chosen exploration (rail at whatever stage that exploration is in).
 
 
 ### When to use

package/skills/claude-code/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/codex/ritual/.ritual-bundle.json

@@ -1,4 +1,4 @@
 {
-  "cliVersion": "0.11.0",
-  "builtAt": "2026-05-25T00:20:36.318Z"
+  "cliVersion": "0.25.0",
+  "builtAt": "2026-06-09T00:58:35.759Z"
 }

package/skills/codex/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/codex/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/codex/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

package/skills/codex/ritual/references/brief-verification-checklist.md

@@ -4,7 +4,7 @@ Reference for `/ritual build` Step 10b.5 (the auto-fire verify-brief pass that r
 
 The brief generator runs server-side and **does not have repo access**. It writes assertions about cited files / functions / classes based on the agent's earlier recon summary — which is a text summary, not the actual code. When the brief says *"`is_allowed_to_see` is insufficient — needs token-based access"* but the code actually ships email-allowlist semantics, the contradiction is invisible to the brief generator and to the user reading the brief.
 
-Step 10b.5 closes this gap: **the agent (with repo access) reads the bodies of the specific symbols the brief cites and produces a structured list of findings before the user sees the brief.** Findings flow back into the brief via `refine_build_brief` if any contradictions are detected.
+Step 10b.5 closes this gap: **the agent (with repo access) reads the bodies of the specific symbols the brief cites and produces a structured list of findings before the user sees the brief.** Findings are written to a **separate** file (`BUILD-BRIEF-VERIFICATION.md`) and synced to Ritual's KG via `sync_brief_review` — they are **never** written back into `BUILD-BRIEF.md`. The brief stays the read-only historical artifact Ritual generated; the corrections reach the implementation through plan mode's KG `priorContext`, not through a brief rewrite. (There is **no** `refine_build_brief` tool — it was removed 2026-05-15 and replaced by `sync_brief_review`.)
 
 This is the **non-UI sibling of `references/ui-ux-checklist.md`** (Step 10.5 UX review). Same methodology shape (read brief → identify citations → find in repo → compare → fill schema → surface findings), different targets (functions / data shapes / model fields instead of UI components).
 
@@ -61,13 +61,18 @@ Three verdicts:
 - **`contradicted`** — the brief's claim is **wrong**. The code does something different. This is the verdict that drives a refinement.
 - **`not_found`** — the brief cited a symbol the agent could not locate in the repo. Either the symbol was renamed, deleted, or never existed. Either way: the brief is asserting against a phantom; surface to user.
 
+**Narrating a finding mid-verification — frame it as resolving drift, not as an error.** If you surface a `contradicted` / `not_found` finding in a progress line before the summary, lead with *resolving drift between the brief and the codebase*, then one plain sentence on the drift + where the real pattern lives. A caught gap is the verification doing its job, not a failure to alarm about — don't lead with "X doesn't exist" / "references a function that doesn't exist."
+
+- ❌ `get_core_apps is not in the codebase — the brief's RB-1 references a function that doesn't exist. The actual pattern is direct INSTALLED_APPS manipulation (index + replace), as seen in tests/settings.py.`
+- ✅ `Resolving drift between the brief and the codebase: RB-1 cites get_core_apps, but the repo edits INSTALLED_APPS directly (index + replace — see tests/settings.py). Noting it in the verification.`
+
 **5. Fill the output schema with evidence.**
 
 Write `BUILD-BRIEF-VERIFICATION.md` to disk alongside `BUILD-BRIEF.md`. Use the schema below. **Each finding cites the file + line range + the actual code snippet that justified the verdict.** The user reading this must be able to verify your verification — no hand-waving, no claims without evidence.
 
 **6. If any findings are `contradicted`, surface to the user inline at Step 10d.**
 
-The Step 10d gate normally reads *"Reply `go` to implement, `refine` for edits, `drill {N}` to inspect, `pause` to stop."* When `contradicted` findings exist, the gate's CTA shifts to highlight the contradictions:
+The Step 10d gate is `go` / `drill {N}` / `pause` (plus `ux-review`) — there is **no `refine` action**; the brief is read-only after generation. When `contradicted` findings exist, the gate prepends a summary so the user sees what the agent learned about the brief before deciding:
 
 ```text
 ⚠ Verification found {N} contradiction(s) between the brief and the actual code:
@@ -76,11 +81,12 @@ The Step 10d gate normally reads *"Reply `go` to implement, `refine` for edits,
     "{code_reality}" (see {cited_file}:{cited_lines}).
   · ...
 
-Reply `refine` to apply these corrections, `go` to proceed anyway,
-or `drill {N}` to inspect one rec.
+These are synced to Ritual; plan mode reads them when you `go`.
+Reply `go` to implement (corrections flow in via KG), `drill {N}` to
+inspect, or `pause` to stop.
 ```
 
-The user can `refine` (recommended) — at which point the SKILL calls `refine_build_brief` with the structured findings array, and the LLM produces an updated brief that incorporates the corrections authoritatively. Or `go` if the user has context the agent doesn't (e.g. "yes the brief is wrong but I want to ship it as-is for now"). The decision stays with the user; the agent surfaces the evidence.
+The findings do **not** rewrite the brief. They were already persisted via `sync_brief_review` (a durable `BriefReview` row) at step 5; when the user replies `go`, **plan mode reads the brief + that review via KG `priorContext`** and the implementation incorporates the corrections — without the brief text changing. If the user has context the agent doesn't ("yes the brief is wrong but ship as-is"), `go` proceeds the same way; the corrections are recorded regardless. The only path to *new brief content* is `generate_build_brief` with `force: true` (full regen from changed source data) — used when the underlying recs/requirements actually changed, never to patch a verification finding.
 
 ---
 
@@ -146,7 +152,7 @@ checked out, state that clearly.}
 
 - **Verify everything in the brief.** Only the symbol-citation slice. Pose-level claims, framing, and general direction are out of scope.
 - **Read the full file.** Read enough surrounding context to verify the symbol (~10 lines); not the whole file. Capped at ~15 citations total to keep this fast.
-- **Edit the brief directly.** Step 10b.5 only writes `BUILD-BRIEF-VERIFICATION.md`. The user decides whether to call `refine_build_brief` with the findings at Step 10d (recommended) or proceed with the brief as-is.
+- **Edit the brief directly.** Step 10b.5 only writes the **separate** `BUILD-BRIEF-VERIFICATION.md` and syncs it via `sync_brief_review`. `BUILD-BRIEF.md` is never touched — it stays the read-only historical artifact. Findings reach the implementation through plan mode's KG `priorContext` at Step 11, not through a brief rewrite. (Regenerating from changed source data is a different operation — `generate_build_brief` with `force: true` — not part of this step.)
 - **Persist findings to the KG.** Phase 1 is local-only. Phase 2 (filed at `memory/backlog_brief_verification_findings_kg_promotion.md`) adds the `BriefVerificationFinding` Prisma model + endpoint + priorContext injection so future briefs on overlapping files inherit verified facts.
 
 ---