@ritualai/cli 0.24.0 → 0.36.8

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/codex/ritual/.ritual-bundle.json

@@ -1,4 +1,5 @@
 {
-  "cliVersion": "0.24.0",
-  "builtAt": "2026-06-08T22:51:34.833Z"
+  "cliVersion": "0.36.8",
+  "builtAt": "2026-06-12T04:36:24.525Z",
+  "skillsHash": "49c0dd37dafd"
 }

package/skills/codex/ritual/SKILL.md

@@ -3,6 +3,7 @@ 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) — 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
+stamp: 49c0dd37dafd
 ---
 
 # /ritual
@@ -19,6 +20,13 @@ Before executing any subcommand, read and follow:
 
 Do not reintroduce `/ritual recon`. Use plain-language repo inspection, `/ritual resume`, or `/ritual lineage` depending on intent.
 
+**Skill freshness (once per session, silent unless stale):** this file's frontmatter may carry a
+`stamp:` value (injected when the bundle was built — absent on dev/source copies). On the FIRST
+`mcp__ritual__ping` of a session, pass it as `skill_stamp`. If the response says
+`skillFreshness: "stale"`, relay its one-line hint ("Skill update available — run
+`ritual init --skills-only` to refresh") exactly once, no pause, and continue with the current flow.
+No stamp, or `in-sync`/`unknown` → say nothing. Never block on this.
+
 ## Contract strength — load-bearing for all subcommands
 
 Every section in this SKILL or its reference files labeled **load-bearing**, **forbidden behavior**, **anti-pattern**, **rendering contract**, or **fire-on-trigger** is **contract-strength**, not guidance.

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.
 
 ---