@ritualai/cli 0.7.14 → 0.7.15

package/README.md

@@ -6,6 +6,50 @@ Codex, Kiro, Gemini CLI, Windsurf, etc.) to Ritual Cloud via the
 
 Docs: [ritual.work/ritual-mcp/docs/](https://ritual.work/ritual-mcp/docs/)
 
+## AI coding agents: start here
+
+If you are an AI coding agent and a user asked you to "set up Ritual MCP,"
+"install Ritual," or anything similar, follow this script **verbatim**.
+Do not ask the user about their project, their stack, or where to register
+the MCP server — `ritual init` handles all of that.
+
+```text
+1. Do not scaffold the user's app yet.
+
+2. Install or upgrade the CLI:
+     npm install -g @ritualai/cli
+
+3. From the project root, run:
+     ritual init
+
+4. If `init` opens a browser for sign-in, tell the user to complete
+   it. If they are a brand-new user, they will get a verification email
+   — they must click the link. Keep the terminal open while they do.
+   If the loopback times out, re-run `ritual init` once.
+
+5. After `init` reports success, run:
+     ritual doctor
+
+6. Tell the user to fully close and reopen their coding agent so the
+   newly-registered MCP server comes online. Reload / `/clear` is not
+   enough — the agent caches MCP config at startup.
+
+7. Once the user is back in the agent, verify the `ritual` MCP server
+   is connected (in Claude Code: `/mcp`). Only then offer to start
+   product work — typically by running `/ritual build <feature>`.
+```
+
+**Hard rules until `ritual init` succeeds:**
+- Do not ask the user what kind of project they're building.
+- Do not ask which stack to scaffold against.
+- Do not ask whether to register MCP project-local vs user-global — `ritual init` picks the right scope per agent automatically.
+- Do not edit `~/.claude.json`, `.mcp.json`, `.cursor/mcp.json`, or any other agent config file by hand.
+- Do not paste docs URLs into a fetch tool and ask the user to read the rendered marketing site — the bootstrap script above is the authoritative source.
+
+**Only escape hatch:** if the user explicitly declines Ritual setup, or if
+`ritual init` fails twice in a row with the same error, ask the user how
+they'd like to proceed. Don't surface the escape hatch unsolicited.
+
 ## Install
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ritualai/cli",
-	"version": "0.7.14",
+	"version": "0.7.15",
 	"description": "Ritual CLI — scaffold AI coding agent skills + register MCP servers. Connects Claude Code, Cursor, Windsurf, Kiro, Gemini CLI, VS Code/Copilot, and Codex to Ritual Cloud.",
 	"private": false,
 	"license": "Apache-2.0",

package/skills/claude-code/ritual/.ritual-bundle.json

@@ -1,4 +1,4 @@
 {
-  "cliVersion": "0.7.14",
-  "builtAt": "2026-05-15T16:06:46.162Z"
+  "cliVersion": "0.7.15",
+  "builtAt": "2026-05-19T15:51:30.453Z"
 }

package/skills/claude-code/ritual/DESIGN.md

@@ -20,7 +20,7 @@ The split version keeps:
 
 ## Retired `/ritual recon`
 
-`/ritual recon` is intentionally not part of the vNext command surface. Its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and its repo-reading behavior is normal coding-agent behavior in plain English.
+`/ritual recon` is intentionally not part of the Ritual command surface. Its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and its repo-reading behavior is normal coding-agent behavior in plain English.
 
 ## Context packet principle
 

package/skills/claude-code/ritual/SKILL.md

@@ -18,6 +18,36 @@ 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.
 
+## 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.
+
+If this SKILL says *"DO NOT do X"*, your default action is to not do X. You may not override based on your in-the-moment assessment that X would be:
+
+- helpful
+- clearer
+- shorter
+- more convenient
+- *"obviously what the user really wants"*
+- *"a small improvement on top of the SKILL's contract"*
+
+When a local example or your own instinct conflicts with a contract-strength rule, **the contract wins.** Re-read the rule. Trust that the prior version of you also thought the override "feels right" — that's exactly the case the contract exists to prevent.
+
+When two contract-strength rules genuinely conflict (rare): **stop, surface the conflict to the user, and ask which to honor.** Do not improvise a resolution.
+
+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):
+
+- `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.
+
+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.
+
 ## Routing
 
 Parse the first token of the argument:
@@ -28,9 +58,10 @@ Parse the first token of the argument:
 | `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 vNext CLI surface is intentionally **just these four**. Legacy exposed `explore`, `run`, `brief`, `gate`, `spec`, `questions`, `gherkin`, `status`, `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 "status of exp-Y". (`/ritual recon` shipped briefly in PR #174 as a fifth command — retired in this PR 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`, `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
@@ -67,5 +98,31 @@ When the user says things like *"what's the status of exp-X?"*, *"show me the re
 | Kick off / re-run the agentic pipeline | `mcp__ritual__start_agentic_run(exploration_id, …)` |
 | Did anyone implement something on these files? | `mcp__ritual__query_knowledge_graph(sources=[…])` — same plumbing as `/ritual lineage` |
 
-This is intentional. Legacy exposed each of these as its own slash-command (`/ritual status`, `/ritual recs`, `/ritual run`) and the surface area ballooned without adding agent value. In vNext we keep the slash-commands narrow (`build`, `resume`, `lineage`, `context-pulse`) and let the agent fluently call MCP tools for everything else. Do not reintroduce `/ritual recon`: its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and repo-reading behaviors are normal coding-agent behavior in plain English.
+This is intentional. Legacy exposed each of these as its own slash-command (`/ritual recs`, `/ritual run`, etc.) and the surface area ballooned without adding agent value. We keep the slash-commands narrow (`build`, `resume`, `lineage`, `context-pulse`, plus the read-only `status` mirror) and let the agent fluently call MCP tools for everything else. Note: `/ritual status` is the one deliberate exception — it exists as a thin SKILL mirror of the terminal CLI command so users who want an in-chat status check don't have to context-switch to a separate terminal. Do not reintroduce `/ritual recon`: its former workspace-history value is covered by `/ritual resume`; its file-decision-history value is covered by `/ritual lineage`; and repo-reading behaviors are normal coding-agent behavior in plain English.
+
+---
+
+## Before this skill is installed — bootstrap context
+
+This SKILL only governs behavior **after** `ritual init` has run and the
+`/ritual` skill has been copied into the agent's skills directory. Before
+that, the agent has no Ritual-specific instructions in scope.
+
+If you are reading this file by browsing the repo, or as part of a
+post-mortem on why a user's "set up Ritual MCP" request went sideways:
+the **pre-install** instruction surface lives in three places, in priority
+order:
+
+1. **`learn.ritual.work/llms.txt`** — canonical machine-readable bootstrap script. Served as plain text. WebFetch-safe.
+2. **`ritual.work/llms.txt`** — identical bytes to (1). Served from the marketing site so an agent handed any `ritual.work/...` URL can find it without knowing about `learn.ritual.work`.
+3. **`apps/cli/README.md`** in this repo (ships to npmjs.com via `@ritualai/cli`) — has the same "AI coding agents: start here" block at the top.
+
+All three sources must say the same thing. The canonical content is the
+7-step `npm install -g @ritualai/cli` → `ritual init` → `ritual doctor`
+→ restart-agent → verify-MCP → `/ritual build` flow, with explicit
+"do not ask the user about their project until init succeeds" rules.
+
+When updating one, update all three. The cross-repo sync is intentional
+duplication — agents need the bootstrap visible at whichever URL they
+happen to be handed.
 

package/skills/claude-code/ritual/manifest.json

@@ -1,13 +1,13 @@
 [
   {
     "path": "DESIGN.md",
-    "lines": 36,
-    "bytes": 2226
+    "lines": 35,
+    "bytes": 2227
   },
   {
     "path": "SKILL.md",
-    "lines": 72,
-    "bytes": 5915
+    "lines": 102,
+    "bytes": 9156
   },
   {
     "path": "agents/openai.yaml",
@@ -21,8 +21,13 @@
   },
   {
     "path": "references/build-flow.md",
-    "lines": 2466,
-    "bytes": 148766
+    "lines": 2652,
+    "bytes": 165455
+  },
+  {
+    "path": "references/brief-verification-checklist.md",
+    "lines": 169,
+    "bytes": 10820
   },
   {
     "path": "references/cli-output-contract.md",
@@ -46,14 +51,19 @@
   },
   {
     "path": "references/resume-flow.md",
-    "lines": 157,
-    "bytes": 9950
+    "lines": 225,
+    "bytes": 14048
   },
   {
     "path": "references/scoring-fallback.md",
     "lines": 126,
     "bytes": 6494
   },
+  {
+    "path": "references/status-flow.md",
+    "lines": 94,
+    "bytes": 6096
+  },
   {
     "path": "references/ui-ux-checklist.md",
     "lines": 198,

package/skills/claude-code/ritual/references/brief-verification-checklist.md

@@ -0,0 +1,169 @@
+## Brief verification — methodology + output schema
+
+Reference for `/ritual build` Step 10b.5 (the auto-fire verify-brief pass that runs after the build brief is generated, before the user reviews it at the Step 10d gate).
+
+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.
+
+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).
+
+---
+
+### Core principle
+
+**The brief's assertions about cited code must be verified against the actual code before the user is asked to approve them.**
+
+The brief generator hedges this risk passively with phrases like *"these recommendations may deviate if the codebase has a stronger existing pattern."* That hedge is honest but not actionable — it tells the reader to maybe check, without telling anyone to actually do the checking. Step 10b.5 makes the checking happen.
+
+---
+
+### Methodology (chain of thought — execute in this order)
+
+Do NOT skip to the output schema. The schema only gets filled correctly when the analysis upstream is done.
+
+**1. Read the brief end-to-end first.**
+
+Open `BUILD-BRIEF.md`. The sections most likely to contain verifiable assertions:
+
+- **Codebase Anchors** — explicit file/function citations the brief expects you to extend or replace.
+- **RB-N rationale** — review-blocking claims often cite specific primitives ("the existing `X` is insufficient because Y").
+- **Suggested Implementation** — sequencing claims about what's "already present" vs "needs to be added."
+- **Previously Deferred** — references to prior decisions on overlapping files (sourced from KG).
+
+Output of this step: a flat list of every specific code citation the brief makes. **Symbol + file + assertion**. If a section says *"the recommendations may deviate if the codebase has a stronger existing pattern,"* that's exactly the kind of hedge this step exists to resolve — treat it as a high-priority verification target.
+
+**2. Extract the explicit citations.**
+
+For each cited symbol, capture:
+
+- `cited_symbol` — function / class / model field / endpoint name.
+- `cited_file` — file path if mentioned; if not, infer from context (Codebase Anchors usually pairs them).
+- `brief_assertion` — the brief's exact claim about this symbol. One sentence.
+
+Cap the list at **15 citations** (highest-leverage ones first — primitives the RBs depend on, symbols cited in multiple sections). 15 is enough to cover the load-bearing risks; more bloats the verification time without proportional signal.
+
+**3. For each citation, read the actual code.**
+
+Use Grep / Glob / Read. For each cited symbol:
+
+- Find the file (Grep `def {symbol}` / `class {symbol}` / `const {symbol}` / `function {symbol}`).
+- Read the function body / class definition / data shape. Include surrounding context (~10 lines) so callers and conventions are visible.
+- Note line numbers (`cited_lines.start` / `cited_lines.end`) so the finding pins to a stable location.
+
+**Do not fabricate citations.** If `Grep` returns nothing, the verdict is `not_found`, not "I'll infer what it probably does."
+
+**4. Compare brief assertion vs code reality. Assign a verdict per citation.**
+
+Three verdicts:
+
+- **`verified`** — the brief's claim matches what the code actually does. Most common verdict on a well-anchored brief; the agent's recon summary was accurate; the brief generator got it right.
+- **`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.
+
+**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:
+
+```text
+⚠ Verification found {N} contradiction(s) between the brief and the actual code:
+
+  · "{cited_symbol}" — brief says "{brief_assertion}". Code reality:
+    "{code_reality}" (see {cited_file}:{cited_lines}).
+  · ...
+
+Reply `refine` to apply these corrections, `go` to proceed anyway,
+or `drill {N}` to inspect one rec.
+```
+
+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.
+
+---
+
+### Output schema — `BUILD-BRIEF-VERIFICATION.md`
+
+Render exactly the sections below. Every section MUST exist (use `(none)` / `(no contradictions)` for empty cases — do not skip).
+
+```markdown
+<!--
+Generated by Ritual — brief verification pass
+Exploration: https://app.ritualapp.cloud/e/{exploration_id}
+Source brief: BUILD-BRIEF.md
+Do not remove this header.
+-->
+
+# Brief Verification — {exploration name}
+
+## Summary
+
+Verified: {N}   ·   Contradicted: {M}   ·   Not found: {K}
+
+{One-paragraph natural-language summary of the verification result. If
+contradictions exist, lead with the most load-bearing one. If everything
+checked out, state that clearly.}
+
+## ⚠ Contradicted ({M})
+
+(one block per contradicted citation, omit section entirely if M=0)
+
+### `{cited_symbol}` — {cited_file}:{lines.start}-{lines.end}
+
+- **Brief asserts:** "{brief_assertion}"
+- **Code reality:** "{code_reality}"
+- **Evidence (from the file):**
+
+  ```{language}
+  {actual code snippet, ~10 lines}
+  ```
+
+- **Recommendation:** {what should change in the brief — concrete next step}
+
+## ❓ Not found ({K})
+
+(one block per missing citation, omit section entirely if K=0)
+
+### `{cited_symbol}` — cited in {section}
+
+- **Brief asserts:** "{brief_assertion}"
+- **Searched:** {file paths / grep queries the agent tried}
+- **Action:** ask the user whether the cited symbol exists under a different name, or whether the brief is referencing something that was renamed / removed.
+
+## ✅ Verified ({N})
+
+(compact list; one bullet per verified citation; no body required)
+
+- `{cited_symbol}` — {cited_file}:{lines.start}-{lines.end} — brief assertion matches code.
+- ...
+```
+
+---
+
+### What this verification step does NOT do
+
+- **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.
+- **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.
+
+---
+
+### Anti-patterns
+
+- **❌ Fabricating evidence.** Every claim in the output file must trace to a real file + line range that the agent actually Read. If Grep returned nothing, the verdict is `not_found`, NOT "I'll just describe what the function probably does."
+- **❌ Re-deriving the brief.** This step is verification, not authoring. Findings exist on a per-citation basis; the agent does not re-write the brief's framing or add new RBs.
+- **❌ Skipping the step on backend-only features.** Step 10b.5 fires automatically regardless of UI / non-UI shape. UI-shaped features use `references/ui-ux-checklist.md` (Step 10.5) on top of this step for the additional UI-pattern review — but every brief runs through the citation-level verification.
+- **❌ Treating the brief's hedge as authorization to skip.** *"may deviate if codebase has a stronger pattern"* is exactly the case Step 10b.5 exists to resolve. The hedge means "go verify"; don't read it as "no need to verify."
+- **❌ Padding the verified list.** Don't enumerate citations the brief didn't actually make just to inflate the "Verified" count. Only cite what the brief cited.
+
+---
+
+### Failure modes to watch for
+
+- **Brief makes ZERO citations.** Some brief generations are framing-only and don't reference specific symbols. The verification pass should write a summary noting *"the brief makes no specific code citations; no verification possible"* and the gate proceeds normally. Phase 2 will treat this as a brief-quality signal (briefs without citations are harder to verify).
+- **Symbol exists in multiple places.** When Grep finds the symbol in N>1 files, capture the file the brief most likely meant (use Codebase Anchors context as the disambiguator). If still ambiguous, render one finding per match with verdict `not_found` and surface the ambiguity to the user.
+- **Code semantics ≠ visible signature.** A function might be named one thing but documented to do another. Read the docstring + the body; trust the body. If the docstring contradicts the body, that's its own finding (`contradicted` with verdict notes).
+- **Brief assertion is too vague to verify.** *"The auth flow needs hardening"* doesn't cite a specific symbol; not verifiable. Skip; verify only the assertions specific enough to check.