@ritualai/cli 0.6.0 → 0.7.1

package/skills/cursor/ritual/references/discovery-classification.md

@@ -0,0 +1,175 @@
+# Discovery classification reference
+
+Loaded only when `/ritual build` question picking triggers scope classification.
+
+##### 7.4.5 — Scope Classification Check (conditional)
+
+When the user picks discovery questions, the gap between **what the problem statement asks about** and **what the user actually chose to investigate** is the agent's first concrete read on whether the scope is genuinely narrow, deliberately sequenced, or under-engaged. This step makes that gap visible — but ONLY when the signal warrants it.
+
+**Design principle (locked):** *Don't make the user optimize the score. Let the score explain what just happened.* The menu asks a plain product question; the pulse confirms the consequence afterward. Never preview deltas inside the choice menu.
+
+###### Per-question typed status
+
+Once Step 7.4 lands, the agent tracks an in-session status for every surfaced question. Statuses are ephemeral (not persisted to the DB yet — that's a follow-up); they carry through this `/ritual build` session only:
+
+| Status | Meaning |
+|---|---|
+| **`picked`** | User selected for active investigation (passed to `start_agentic_run`) |
+| **`deferred`** | Deliberate phase-2 candidate; surfaces in build brief's "Phase Candidates" section. NOT context debt. |
+| **`dropped`** | Removed from scope; problem statement gets narrowed to exclude this concern. |
+| **`unreviewed`** | Default state for every surfaced question until the user classifies it. Counts toward debt if the user proceeds to Step 8 without resolving. |
+
+`picked` is set automatically by the per-matter accept calls in 7.4. The other three are set by the Step 7.4.5 branches below.
+
+###### Conditional trigger
+
+Step 7.4.5 fires **only** when at least one of these holds — otherwise proceed silently to 7.5:
+
+- **Pick-rate < 40%** (picked / total_surfaced)
+- **Matter coverage ≤ 50%** (matters with ≥ 1 pick / total matters)
+- **Pick-rate = 100%** (no-discrimination signal — see "no-discrimination case" below)
+- **Concentration heuristic**: a single matter holds ≥ 60% of the picks while the problem statement spans multiple distinct concerns
+
+If none hold, the user's scope intent is already obvious; don't add a check. Continue to Step 7.5.
+
+###### Signal mapping
+
+Before surfacing the prompt, the agent maps which problem-statement concerns are covered by the picks. Concerns are derived from the problem statement's noun-phrases (loose keyword-match against matter names is sufficient for MVP; LLM-rated mapping is a follow-up). For each unpicked matter, identify which problem-statement concern(s) it represents.
+
+Output the analysis in plain language — three paragraphs (data → qualitative pattern → gap statement). Em-dash separating stats reads better than parenthetical. Example with real numbers (from the django-oscar GDPR exploration testing):
+
+```
+You picked 8 of 73 questions across 4 of 8 matters — an 11% pick-rate
+with 50% matter coverage.
+
+Your picks concentrate on the structural foundation: what the data is,
+where it lives, immutability, and retention categories.
+
+Your problem statement also mentions erasure mechanics, scheduled cleanup
+jobs, DSAR APIs, and audit observability. Those areas are currently
+unpicked.
+```
+
+The **dominant theme phrase** ("structural foundation: what the data is, where it lives, immutability, and retention categories" in the example) is computed once here and reused in Option 1's prompt below — that keeps the user's decision concrete instead of abstract.
+
+###### The 4-option prompt (plain language only — no score previews)
+
+Reuse the dominant-theme phrase from the analysis paragraph in Option 1 so the user reads the *narrowed scope* in product terms before deciding, not after.
+
+```
+How should I treat the unpicked areas?
+
+1. Out of scope — tighten the problem statement around {dominant theme
+   from analysis paragraph: e.g. "data structure, storage, immutability,
+   and retention categories"}.
+   Unpicked concerns are dropped from the current HMW.
+
+2. Later phase — keep the broad scope, but mark unpicked matters as
+   phase-2 candidates surfaced in the build brief.
+   Use this when the unpicked work depends on the picked foundation
+   being settled first.
+
+3. Open questions — keep the broad scope and treat unpicked areas as
+   context debt to revisit.
+
+4. Pick more — return to Step 7.3 and add picks before continuing.
+```
+
+**Copy notes:**
+- "the current HMW" (not "the HMW") — Branch 1 is present-cycle, not permanent. Reduces commitment-anxiety.
+- "treat unpicked areas as context debt" (not "Unpicked counts as context debt") — grammatical, less terse.
+- Option 2's "Use this when..." stays as a separate declarative sentence — less leading than a parenthetical, but still teaches the right sequencing intuition.
+- Option 4 uses "return to" not "loop back to" — cleaner agent voice.
+
+###### Per-branch handlers
+
+**Branch 1 — Out of scope (tighten):**
+1. Mark all unpicked questions across all matters as `dropped`.
+2. Call `mcp__ritual__refine_problem_statement` with `change_prompt`: *"Narrow the scope to focus only on {comma-joined matter names of picked matters}. Drop concerns related to {comma-joined names of dropped matters}."*
+3. Emit post-choice pulse — **reuse the same dominant-theme phrase** that appeared in the analysis paragraph + Option 1's prompt, so the user sees their choice acknowledged in the exact words they read:
+   ```
+   ✓ Tightened the problem statement around {dominant theme — same phrase as analysis paragraph + Option 1 prompt}.
+     Pulse: {readiness}% readiness · {debt}% debt · +{delta}% (feature clarity ↑ from narrower scope)
+   ```
+   Concrete example matching the django-oscar GDPR exploration: *"✓ Tightened the problem statement around data structure, storage, immutability, and retention categories."* — names what survived, not abstract *"the structural picks"*.
+
+**Branch 2 — Later phase (defer):**
+1. Mark all unpicked questions across all matters as `deferred`.
+2. No problem statement change (broad scope preserved).
+3. Emit post-choice pulse — **note the second-field label is `deferred`, not `debt`**:
+   ```
+   ✓ {N} unpicked questions marked as phase-2 candidates.
+     Pulse: {readiness}% readiness · {deferred}% deferred · +{delta}% (decision resolution ↑ from deliberate deferral)
+   ```
+   The `deferred` label (instead of `debt`) is load-bearing — deliberate sequencing is NOT a liability, and the pulse line should reflect that. Same number, different character.
+4. At Step 10c (build brief generation), the deferred matters MUST appear in the brief's *"Phase Candidates / Deferrable Items"* section. The agent appends the `deferred[]` set to the `generate_build_brief` `recon_context` payload as supplementary "explicit phase-2 candidates set by the user during discovery." The main `recon_context` payload remains the `codebase_context_packet`.
+
+**Branch 3 — Open questions (debt):**
+1. Mark all unpicked questions as `unreviewed` (their default state — no change).
+2. No problem statement change.
+3. Emit post-choice pulse — uses the `debt` label:
+   ```
+   ✓ {N} unpicked questions marked as context debt.
+     Pulse: {readiness}% readiness · {debt}% debt · +0% (open questions remain unresolved)
+   ```
+   Avoid words like *"status quo"* — phrase it as a state, not a non-event.
+4. The next `/ritual context-pulse` will surface the unresolved questions as top debt sources.
+
+**Branch 4 — Pick more (loop):**
+1. No status change.
+2. No pulse.
+3. Surface the unpicked matters in a numbered list grouped by matter:
+   ```
+   Returning to question picking. Unpicked matters and questions:
+
+   M5 — Erasure Anonymization Contract (10 questions)
+   M6 — Scheduled Cleanup Idempotency (8 questions)
+   M7 — DSAR Attribution Interfaces (9 questions)
+   M8 — Compliance Audit Observability (8 questions)
+
+   Pick any subset. Same per-matter accept flow as Step 7.4.
+   ```
+4. After new picks land, re-evaluate the trigger conditions. If still met, fire 7.4.5 again. Otherwise proceed to 7.5.
+
+###### The no-discrimination case (100% pick-rate)
+
+If trigger fired because pick-rate = 100% (user picked every question), the prompt shape is gentler — there's no "unpicked areas" to classify. Instead:
+
+```
+You picked everything (73/73 questions).
+
+That may mean every question is genuinely relevant — the breadth is real.
+Or it may mean we haven't narrowed the investigation yet. Pick one:
+
+1. Proceed broadly — run all questions through the agentic pipeline. The
+   build brief will be wide; recommendations cover everything.
+
+2. Sharper first pass — let me suggest 5-10 highest-leverage questions
+   that would give you the most signal per LLM call. The rest become
+   phase-2 candidates.
+```
+
+If user picks (1): proceed silently to Step 7.5. No pulse change.
+If user picks (2): agent ranks the 73 questions by leverage (LLM call OR heuristic: questions earlier in each matter tend to be foundational), surfaces the top 5-10, user re-confirms picks, others become `deferred`. Fall back to Branch 2's behavior.
+
+###### Two-score model in the pulse (CP3 update)
+
+Once Step 7.4.5 has run, the `/ritual context-pulse` Step CP3 formula reads from the typed-status counts:
+
+- **Decision Resolution (current scope):** `picked / (picked + unreviewed)`. Excludes `deferred` + `dropped`. Reaches near-100% if the user classified everything (picked, deferred, or dropped) — judgment rewarded.
+- **Total-problem Coverage:** `(picked + deferred + dropped) / total`. Shows how much of the original surfaced space has been *classified at all*, regardless of how. Surfaces in the full pulse as an annotation; `unreviewed` count is the implicit debt.
+
+Compact pulse continues to lead with the single readiness · {debt|deferred} · delta line per the per-branch templates above. Full pulse adds the breakdown:
+
+```
+Reasoning readiness:  72%
+Context debt:         12%  (4 questions unreviewed)
+Context deferred:     16%  (12 questions phase-2 candidates)
+Context surface:      Recommendation-ready
+```
+
+When `Context deferred` is zero, omit that line (CLI Tenet #6 — silence on no-data).
+
+###### After Step 7.4.5 completes
+
+Continue to Step 7.5 (anti-goals capture) per the existing flow.

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

@@ -0,0 +1,152 @@
+## /ritual lineage
+
+**"Show me the history on these files."** The user gives the agent a file path (or a directory, or a set of paths) and the agent surfaces every prior exploration, recommendation, decision, and deferral that touched those files — pulled from the workspace's knowledge graph.
+
+Output: a per-file timeline of decisions + deferrals + the explorations they came from, with PR numbers + dates + status snapshots. The user reads this **before** they make code changes to avoid re-litigating a settled decision or re-introducing a known deferral.
+
+
+### When to use
+
+- Engineer is about to touch a file they don't know the history of — *"who's been here? what did they decide? what did they punt?"*
+- Code review: reviewer wants to know the lineage of a suggested change.
+- Onboarding: new engineer wants to understand why a module exists in its current shape.
+- Pre-implementation: planning a refactor; want to surface deferrals that might block the new approach.
+
+When **not** to use:
+- The user wants to start a new exploration → that's `/ritual build`.
+- The user wants a workspace-wide tour (no specific files in mind) → just ask the agent in plain English; the codebase + KG are reachable via the standard MCP read tools (`list_explorations`, `query_knowledge_graph`, etc.).
+
+### Input shapes
+
+The lineage flow accepts paths several ways — pick the one that best matches what the user provided:
+
+| What the user gave you | What to do |
+|---|---|
+| `lineage src/checkout/views.py` | Single explicit file path |
+| `lineage src/checkout/views.py src/oscar/apps/order/models.py` | Multiple explicit paths |
+| `lineage src/checkout/` | Directory — `Glob` it for source files (cap at ~20 to keep the query bounded) |
+| `lineage` (no arg) | **Infer from context.** Use, in order: (a) files the user has been discussing this session, (b) files in their most recent `git diff HEAD~1..HEAD` or `git status`, (c) ask the user explicitly |
+| `lineage <pasted file contents>` | The user pasted code, not a path. Try `Grep` for a unique-looking signature line to locate the file, OR ask which file it's from |
+
+For the "no arg" case, surface what you're going to query before you query it:
+
+> I'll look up lineage on these files (from your recent edits):
+> - `src/checkout/views.py`
+> - `src/oscar/apps/order/models.py`
+> - `src/oscar/apps/order/utils.py`
+>
+> Proceed? **(y / change the list / abort)**
+
+CLI Tenet #2 — one recommended action, single escape hatch.
+
+### Workflow
+
+#### Step L1 — Resolve files
+
+Given the user's input shape, produce a final `sources[]` array of file paths. Normalize relative-to-repo-root (the KG stores paths that way).
+
+If the list ends up empty (e.g. directory glob matched nothing, or the user's pasted code can't be located): surface a clear message and exit — *"I couldn't resolve any files to look up. Try giving me an explicit path."*
+
+#### Step L2 — Query the knowledge graph
+
+Call `mcp__ritual__query_knowledge_graph(workspace_id, sources=[paths])`. This is the same tool `/ritual build`'s Steps 4 / 5 / 10 use for KG injection — the difference here is the user-facing output is the QUERY RESULT, not silent priorContext.
+
+The response shape includes:
+- `decisions[]` — each with `area`, `choice`, `sourceRecommendationId`, `recommendationStatusAtImplementation`, `relatedFiles[]`, `createdAt`, `explorationId`, `explorationName`, `prNumber`/`prUrl` (from the linked `ImplementationRecord`)
+- `deferrals[]` — each with `rbId`, `description`, `severity`, `reason`, `relatedFiles[]`, `createdAt`, `explorationId`, `explorationName`, `status` (open / addressed / dismissed)
+- `implementationCount` — totals per file (handy for the summary line)
+
+Read-tier, no LLM cost. Snappy (single DB query).
+
+#### Step L3 — Render the per-file timeline
+
+Start with a compact summary header:
+
+```text
+Lineage found for {files_with_lineage}/{total_files} files:
+- {D} decisions
+- {F} open deferrals
+- {I} prior implementations
+```
+
+Omit any zero-valued line except when all counts are zero.
+
+For each file in `sources[]`, render a compact timeline:
+
+```
+src/oscar/apps/checkout/views.py
+  · 2026-05-12 — Decision: gateway-form branching (RB-6)
+    from "Guest checkout → registration attribution"
+    PR #5012 · status when shipped: approved
+  · 2026-04-28 — Deferral: rate-limit per-tenant [major]
+    from "Multi-tenant rate limiting"
+    Open · 14 days old · "out of scope for v1; revisit when traffic >100req/s/tenant"
+  · 2026-03-15 — Decision: session-cookie checkout state
+    from "Anonymous checkout v1"
+    PR #4827 · status when shipped: approved
+
+  Touched by 1 open deferral · 2 logged decisions
+
+src/oscar/apps/order/models.py
+  · 2026-04-30 — Decision: snapshot vs FK on order.user
+    from "Guest checkout → registration attribution"
+    PR #5012 · status when shipped: approved
+
+  Touched by 0 open deferrals · 1 logged decision
+
+src/oscar/apps/order/utils.py
+  · (no lineage logged — this file hasn't been touched by a Ritual exploration yet)
+```
+
+Rules for the output (CLI Tenets #1, #3, #6):
+
+- **Sort each file's events newest-first.** Engineers care most about the latest decision.
+- **One-line-per-event in the listing**, with a 1-line "rationale" or "reason" subline only when present and short. Don't paste full RB descriptions inline — surface the headline and let the user drill in if they want.
+- **Cap each file at the 5 most recent events.** If there are more, add a footer: *"… 8 more events on this file. Drill in? (y/N)"*. Surface only on user request.
+- **Silence on no-data per file** — if a file has zero events, emit one line acknowledging that (so the user knows the file was checked, not skipped). Don't render empty event lists.
+- **Highlight open deferrals.** They're the actionable signal: code about to be changed may collide with something the prior exploration explicitly deferred.
+
+If `kgContextUsed.implementationCount === 0` across all files (no lineage anywhere), say so plainly and exit:
+
+> No lineage found for these files in this workspace.
+>
+> Likely reasons:
+> - These files have not gone through Ritual yet.
+> - Prior work was not synced with `sync_implementation`.
+>
+> Next: proceed normally, or start `/ritual build` if this work should become part of workspace memory.
+
+#### Step L4 — Single recommended next step
+
+End with one cheap call-to-action (CLI Tenet #12). The right action depends on what the lineage showed:
+
+| Lineage shape | Recommended next step |
+|---|---|
+| Open deferrals touching files the user is about to change | *"⚠ {N} open deferral{s} overlap your scope. Before you write code: want me to surface the full deferral context (`/ritual build` brief with `sources` set to these files)?"* |
+| Decisions shipped recently (< 30 days) the user might collide with | *"Recent decisions on these files. Want me to fetch the full build brief from the source exploration? (it's still cached)"* |
+| Old, stable decisions only | *"Lineage looks settled. Anything else, or are you good to proceed?"* |
+| No lineage | *"Nothing on these files yet. Drag in different files or start a fresh `/ritual build` exploration if you want to log this work into the workspace."* |
+
+### Tools used
+
+Single-tool subcommand:
+
+1. `mcp__ritual__query_knowledge_graph` (Step L2 — the whole flow hangs on this)
+2. Agent filesystem tools (`Glob`, `Read`) for resolving directory inputs / pasted-code inputs in Step L1.
+
+Optional onward calls if the user pivots to action (Step L4):
+- `mcp__ritual__generate_build_brief` if they want the full brief with deferrals surfaced
+- `mcp__ritual__get_exploration` if they want to drill into one of the source explorations
+
+No new MCP tools required. `/ritual lineage` is a thin formatter over `query_knowledge_graph`.
+
+### Relationship to `/ritual build`'s priorContext block
+
+Same underlying data, opposite direction:
+
+- **Inside `/ritual build`**: lineage flows in as *silent priorContext* — the LLM sees prior decisions + deferrals when synthesizing considerations / problem statement / build brief. The user never sees the raw KG query.
+- **As `/ritual lineage`**: lineage IS the experience. The agent surfaces the raw KG query, formatted, to the user. No LLM synthesis on top.
+
+When a user is mid-`/ritual build` and wants to drill into one of the prior implementations the brief mentioned, that's the natural moment to suggest: *"Want me to run `/ritual lineage` on these files for full context?"*
+
+---

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

@@ -0,0 +1,156 @@
+## /ritual resume
+
+**"Pick up where I left off."** Promotes `/ritual build`'s Step 1.5 ("resume vs start") to a first-class command for users who already know they want to continue something, not start fresh.
+
+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.
+
+
+### When to use
+
+- The user types `/ritual resume` with no args (the common case): they want to see their in-flight explorations and pick one.
+- The user types `/ritual resume <exploration_id_or_name>`: they already know which one; jump straight to its right step.
+- A user came back to the repo after time away and isn't sure what they had going.
+
+When **not** to use:
+- The user wants to start something new → that's `/ritual build`.
+- The user wants to understand the workspace at a higher level (no specific exploration in mind) → just ask the agent in plain English (*"walk me through this workspace"* / *"trace the auth flow"*) — no slash-command needed.
+
+### Workflow
+
+#### Step R1 — Pick a workspace
+
+Same as `/ritual build` Step 1. Project-pinned workspace from `.ritual/config.json` is preferred. If no pin and the user has multiple workspaces, ask which one.
+
+If the workspace has **zero explorations**: tell the user politely and pivot.
+
+> No in-flight explorations in this workspace yet. Want me to start a fresh one? **Run `/ritual build <your problem>`.**
+
+End the flow here. Don't bounce them into `/ritual build` automatically — explicit user intent beats implicit handoff.
+
+#### 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.
+
+If exactly one in-flight exploration is recent and clearly the likely target, lead with it instead of forcing a picker:
+
+> Likely resume target:
+> **{name}** — last touched {time}. Next: {natural-language next action}.
+>
+> Resume this? (Y/n, or `list`)
+
+If there are multiple plausible targets, group by state badge and show:
+
+> Here's what you have in flight in **{workspace.name}**:
+>
+> **📍 still in discovery** (1)
+> - **{name}** — {first 80 chars of problemStatement}
+>   *Last touched {N} {days/hours} ago. Next: continue sub-problem generation.*
+>
+> **💬 waiting on admin to accept recommendations** (2)
+> - **{name}** — {…}
+>   *Last touched {N} days ago. Next: admin reviews + accepts in Step 9.*
+> - **{name}** — {…}
+>   *…*
+>
+> **✅ ready to implement** (1)
+> - **{name}** — {…}
+>   *Last touched {N} days ago. Next: generate the build brief.*
+>
+> **Which one do you want to resume? (give me the number/name, or "none" to exit)**
+
+State badge → user-facing label + suggested next step (same table as `/ritual build` Step 1.5):
+
+| Glyph | State | User-facing label | Jump to |
+|---|---|---|---|
+| 📍 | `in_progress` | "still in discovery" | Continue discovery |
+| 💬 | `awaiting_admin` | "waiting on admin to accept recommendations" | Admin review |
+| ✅ | `ready` | "ready to implement" | Generate the build brief |
+| 🛠 | `in_flight` | "implementation in progress" | Refresh the build brief on remaining work |
+| ✓ | `done` | "fully shipped" | Suggest `/ritual lineage` on the files OR `/ritual drift` (when shipped) to check for new changes since |
+| ⚠ | `implemented_ahead` | "code shipped before admin acceptance" | Surface to user, ask admin to reconcile |
+
+Silence on no-data (CLI Tenet #6): if a state bucket is empty, don't render it. Don't print "**🛠 implementation in progress** (0)".
+
+#### Step R3 — Branch-existence sanity check (`done` / `in_flight` only)
+
+Same as `/ritual build` Step 1.5 step 5's CLI Tenet #9 check. Before treating an exploration as ✓ done, verify the implementation record's branch / PR actually exists locally or remotely:
+
+```bash
+git rev-parse --verify "origin/${implementationRecord.branch}" 2>/dev/null \
+  || gh pr view "${implementationRecord.prNumber}" --json state 2>/dev/null
+```
+
+If neither resolves, surface as a single-action proposal:
+
+> Note: per the KG this is shipped on `{branch}` (PR #{num}), but I don't see that branch in this repo or remote. The implementation record may be bootstrap/synthetic data.
+>
+> Treat as ready-to-implement-for-real? **(y/N, or tell me what's actually shipped)**
+
+#### Step R3.5 — Implementation footprint check (`ready` / `in_flight` only)
+
+The KG can't distinguish "brief generated, no code yet" from "implementation done but not yet synced" from "implementation was started and then dropped." All three look like state `ready` (or `in_flight`) because no `ImplementationRecord` row exists yet — that's only written on `sync_implementation`.
+
+When the KG asserts `ready` or `in_flight`, do a **footprint check** using the `Ritual-Exploration: <id>` commit trailer mandated by Tenet #14 (Step 11.2). The trailer is a stable anchor in git history that survives branch deletion (lives in reflog for ~30 days) and persists across machines via push.
+
+Run these probes:
+
+```bash
+# Probe A — any commits anywhere in this repo's git history attributed to this exploration?
+git log --all --grep="Ritual-Exploration: ${exploration_id}" --oneline 2>/dev/null
+
+# Probe B — the heuristic feature-branch from Step 11.0 (try both naming conventions)
+git rev-parse --verify "feat/${exploration_slug}" 2>/dev/null
+git rev-parse --verify "ritual/${exploration_short_id}" 2>/dev/null
+git rev-parse --verify "origin/feat/${exploration_slug}" 2>/dev/null
+
+# Probe C — any PR (open, closed, or merged) attributed to this exploration?
+gh pr list --search "Ritual-Exploration: ${exploration_id}" --state all --json number,state,title,headRefName,mergedAt 2>/dev/null
+```
+
+Cross-reference findings against the KG state:
+
+| KG state | Footprint found | What happened | What to surface |
+|---|---|---|---|
+| `ready` | None | User hasn't started coding | "Brief ready, no code yet. Pick up at Step 11 (Implement)?" |
+| `ready` | Branch + commits with trailer | Mid-implementation, unsynced | "I see {N} commits on `{branch}` attributed to this exploration. Continue coding, run the gate, or `sync_implementation` now?" |
+| `ready` | Open PR with trailer | PR open, awaiting review/merge | "PR #{N} is open ({state}, {head_ref}). Wait for merge, or sync the current state of the branch?" |
+| `ready` | Merged PR with trailer, no impl record | PR merged but `sync_implementation` was skipped | "PR #{N} merged on {date} but `sync_implementation` was never called. Want me to sync from the PR now? *(this is the `/ritual sync <pr-url>` backlog flavor — for now, walk the user through Step 12 manually using the PR's commits + decisions.)*" |
+| `ready` | **Only orphan commits in `git log --all` (no live branch / no live PR)** | **Work was dropped — branch deleted, reset, or stashed-then-discarded** | "⚠ I see {N} commits attributed to this exploration in your git history from {N} days ago, but the branch is gone and no PR was opened. Looks like the implementation was started and dropped. Want me to: **(a)** show you the orphan commits so you can recover them (`git cherry-pick`), OR **(b)** start fresh implementation from the brief?" |
+| `in_flight` | Branch + commits match KG `branch` field | Implementation in progress (normal mid-loop state) | Continue per the state badge's suggested next step (refresh brief on remaining work). |
+| `in_flight` | KG says branch X, but Probe B says different branch Y carries the commits | Branch was renamed/rebased after KG was last updated | "KG says `{x}` but I see Ritual-attributed commits on `{y}`. Update the KG branch name, or use `{y}` for the rest of this flow?" |
+
+**The dropped-work case (row 5) is the load-bearing one.** Without this check, the user re-runs `/ritual build` and the agent silently regenerates the brief, never telling the user they lost a day of work that's still recoverable from the reflog.
+
+**Skip the probes when:**
+
+- The exploration was just created in this same session — no time to have orphan commits.
+- The user just synced (the `done` / `in_flight` state badge was set within the last few minutes).
+- The exploration is in a state where the footprint check doesn't apply (`in_progress`, `awaiting_admin`, `implemented_ahead`).
+
+#### Step R4 — Jump to the right `/ritual build` step
+
+Once the user picks (and the sanity check passes), invoke the `/ritual build` flow internally with `exploration_id` set and skip ahead to the step the badge maps to. **Don't re-prompt for workspace, template, scope, considerations, or problem statement** — that work already exists on the exploration.
+
+End the flow with the same "next step" prompt `/ritual build` would have at that step. The user sees `/ritual resume` as a thin shortcut; behind the scenes it just teleports them into `/ritual build`'s middle.
+
+### Tools used
+
+Read-tier subset of `/ritual build`'s tools:
+
+1. `mcp__ritual__list_workspaces` (R1, fallback only)
+2. `mcp__ritual__list_explorations` (R2 — the core read)
+3. `mcp__ritual__get_exploration` (R3, to fetch the `implementationRecord` for the branch check)
+4. Whatever `/ritual build` would use from the jump-in step onward (R4)
+
+No new MCP tools required. `/ritual resume` is a thin orchestration over what already exists.
+
+### Relationship to `/ritual build` Step 1.5
+
+They share the same logic. The difference is **user intent at invocation time**:
+
+- `/ritual build` is "I'm starting something" — Step 1.5 is a *check* ("oh wait, you might already have this") before going further.
+- `/ritual resume` is "I'm continuing something" — there's no fresh-start path; if the user really wants fresh, they exit and run `/ritual build`.
+
+Result: the same MCP calls, the same state-badge table, but different framing for the user. Two clear front doors instead of one ambiguous one.
+
+---

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

@@ -0,0 +1,125 @@
+# Context pulse fallback scoring reference
+
+Loaded only if `mcp__ritual__score_context_pulse` is unavailable, errors, or the MCP server is older than the canonical scoring API. Server-side scoring remains authoritative for new pulses.
+
+#### Step CP3 — Compute the dimensions (fallback only)
+
+Skip this step when the preferred path (CP2 — `score_context_pulse`) succeeded — the server returns identical dimension scores. This is the specification for the **fallback path** and the canonical reference for what the server-side scoring engine computes.
+
+Use this deterministic table. Each dimension scores 0–100; final score is the weighted sum.
+
+**Scoring model versions:**
+
+- **v1 (MVP-1 / MVP-2 PR 1)** — 4 dimensions: Feature Clarity 30%, Decision Resolution 30%, Repo Grounding 25%, Assumption Safety 15%.
+- **v2 (MVP-2 PR 2, current canonical)** — 6 dimensions, repo split + assumption reframe + validation readiness added. Weights below.
+
+The server returns `dimensionsVersion` on every pulse so callers know which shape they're reading. Old pulses retain their original version; new pulses use the current canonical model.
+
+##### Feature Clarity — 25% (kept across versions)
+
+| Signal (parse the exploration's `problemStatement`) | Points |
+|---|---:|
+| Problem statement is non-empty + ≥ 50 chars | 20 |
+| Actor / target user is named (heuristic: pronouns like "user", "admin", "engineer", or a named role) | 15 |
+| Desired behavior is described (verb phrase like "export", "view", "configure") | 15 |
+| Acceptance criteria are present (heuristic: bulleted "should" / "must" / "given/when/then") | 25 |
+| Non-goals or constraints are present | 10 |
+| Edge cases are mentioned | 10 |
+| Success metric is mentioned (numbers, time bounds, error rates) | 5 |
+
+##### Decision Resolution — 20% (kept across versions; weight reduced from 30%)
+
+```
+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.
+
+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.
+
+##### Code Grounding — 15% (v2 — split from Repo Grounding)
+
+| Signal | Points |
+|---|---:|
+| `sources[]` array on the exploration is non-empty (≥ 3 paths) | 25 |
+| ≥ 5 paths (deeper recon) | 15 |
+| `query_knowledge_graph(sources).implementationCount > 0` (prior impls touch overlapping files) | 30 |
+| Decisions logged on overlapping files (KG `decisions[]` non-empty) | 20 |
+| Deferrals on overlapping files surfaced (KG `deferrals[]` returned) | 10 |
+
+##### Reference Grounding — 10% (v2 — split from Repo Grounding)
+
+| Signal | Points |
+|---|---:|
+| `mcp__ritual__list_knowledge_sources` returns ≥ 1 KnowledgeSource attached | 25 per ref, cap 75 (3 refs) |
+| At least one ref has `extractionStatus = COMPLETED` (Pass 1 snippets exist; the source is queryable) | +25 |
+
+Lower weight than Code Grounding because a single high-quality PRD gets the user to a meaningful baseline; diminishing returns past 3 since more refs add review surface area without making the feature clearer.
+
+##### Assumption Load — 10% (v2 — reframed from Assumption Safety)
+
+**Inverted semantic: HIGH = MORE assumptions (worse).** The readiness composer uses `(100 - load)` internally so the weighted sum stays "high readiness = good." Inversion is intentional — load is what the user can act on (reduce it), whereas "safety" was passive.
+
+User-facing render rule: never show Assumption Load as a positive progress bar without labeling that lower is better. Prefer `Assumption load: 30% (lower is better)` or render the inverted readiness contribution instead. Do not make a higher Assumption Load visually look like progress.
+
+| Signal | Load |
+|---|---:|
+| No anti-goals declared at all | 80 base |
+| 1–2 anti-goals (some explicit boundaries) | 50 base |
+| 3+ anti-goals (boundaries are mapped) | 20 base |
+| Each assumption-flag word in the problem statement: `assume`, `assuming`, `presumably`, `probably`, `should be`, `expected to` | +5 each, cap +20 |
+
+##### Validation Readiness — 20% (v2 — NEW)
+
+Testability. Can an engineer reading this know how to verify success? This dimension catches problem statements that sound clear but leave acceptance ambiguous.
+
+| Signal (parse `problemStatement`) | Points |
+|---|---:|
+| AC bullets (should/must/given-when-then) | 25 |
+| Quantitative success metric (%, ms, p95, etc.) | 25 |
+| Explicit expected output / response shape (`returns`, `renders`, `output`, `format`, `schema`) | 20 |
+| Failure / error mode handling (`rollback`, `retry`, `abort`, `failure`, `timeout`, `crash`) | 15 |
+| Edge case enumeration (`edge case`, `never`, `already`, `missing`, `conflict`, `partial`) | 15 |
+
+**Contradiction Risk** is reserved for MVP-2 PR 3 (`--explain` flag) — it requires an LLM call in the hot path, which is intentionally outside the deterministic guarantee of CP3.
+
+#### Step CP4 — Compose the final score
+
+**v2 (current canonical):**
+
+```
+readiness = round(
+  0.25 × feature_clarity
+  + 0.20 × decision_resolution
+  + 0.15 × code_grounding
+  + 0.10 × reference_grounding
+  + 0.10 × (100 - assumption_load)    ← inverted
+  + 0.20 × validation_readiness
+)
+
+debt = 100 - readiness
+```
+
+**v1 (legacy back-compat — only computed when scoring a v1 pulse for trend continuity):**
+
+```
+readiness = round(
+  0.30 × feature_clarity
+  + 0.30 × decision_resolution
+  + 0.25 × repo_grounding
+  + 0.15 × assumption_safety
+)
+```
+
+The server populates BOTH sets of typed columns + the canonical `breakdown` JSON on every v2 write, so analytics queries against the legacy columns still work.
+
+State tier lookup:
+
+| Readiness | State | Recommended next action |
+|---:|---|---|
+| 0–30 | Raw ask | Frame the problem first. |
+| 30–55 | Under-specified | Run discovery. |
+| 55–75 | Exploration-safe | Get to recommendations. Don't implement yet. |
+| 75–90 | Recommendation-ready | Generate the build brief, then implement. |
+| 90+ | Implementation-ready | Safe to code. |

package/skills/gemini/ritual/DESIGN.md

@@ -0,0 +1,35 @@
+# Ritual skill design notes
+
+This file is for humans reviewing or maintaining the Ritual skill. Runtime instructions live in `SKILL.md` and `references/*.md`.
+
+## Product intent
+
+Ritual helps coding agents avoid jumping straight into implementation when the feature depends on context the agent cannot infer on its own: strategic intent, constraints, prior decisions, trade-offs, and non-obvious scope boundaries.
+
+The workflow surfaces that context through targeted discovery questions, combines it with codebase signals and prior explorations, and produces a validated build brief before code is written.
+
+## Why split the skill
+
+The previous monolithic `SKILL.md` mixed runtime instructions with design rationale, fallback formulas, version history, and long branch handlers. That made it harder for an agent to follow the right path at runtime.
+
+The split version keeps:
+
+- `SKILL.md` as a dispatcher/control plane
+- `references/*` as runtime procedure files loaded only when needed
+- `DESIGN.md` as rationale and maintenance notes
+
+## 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.
+
+## Context packet principle
+
+The coding agent should contribute local codebase understanding, but not decide final scope itself. After recon, it produces a `codebase_context_packet` containing facts, evidence, hypotheses, confidence, scope pressure, corrections, and open questions. MCP/tooling remains responsible for generating and ranking final sub-problems and scope.
+
+## Context pulse principle
+
+Context pulse answers: can a reasoning system act safely on this yet? The primary user-facing score is Reasoning Readiness; Context Debt is the inverse. Server-side scoring is canonical for new pulses. Fallback formulas are only for older MCP servers or error recovery.
+
+## Host assumptions
+
+Designed primarily for Claude Code-style coding-agent sessions with filesystem, git, shell, and MCP access. Adapt commands as needed for Cursor or other agents with equivalent tools.