@ritualai/cli 0.5.0 → 0.7.1

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

@@ -0,0 +1,1449 @@
+## /ritual build
+
+Walks the engineer from a free-form problem statement to vetted, accepted Ritual recommendations using the vNext MCP tool surface.
+
+Output: a fully-closed loop — **exploration in COMPLETE state, recommendations accepted (or explicitly handed off to an admin), build brief generated, code implemented, and `sync_implementation` called to register the result in the knowledge graph**. The engineer stays in the driver's seat through concise status updates and explicit pauses only at real decision gates.
+
+### Vocabulary mapping (engineer-tone)
+
+The Ritual data model uses product-research terminology. This skill translates to engineer-natural terms when speaking to the user. The underlying API still uses original names — keep this table mental when you read tool inputs / outputs:
+
+| User-facing term (the skill says) | Tool field name (the API uses) |
+|---|---|
+| **scope** | `problemStatement` |
+| **sub-problem** | `consideration` |
+| **matter** | `matter` (no rename — already the right word) |
+| **discovery question** | `question` |
+| **recommendation** | `recommendation` |
+
+When the user says "tighten the scope," call `generate_problem_statement(...)` with their refinement. When you tell the user "I picked these sub-problems," you mean the items you put in `considerations[]`. The tools don't change; only the language to the user does.
+
+
+### Runtime contracts
+
+Before running this flow, apply `references/cli-output-contract.md` and `references/async-polling.md`. Keep raw recon internal, pass the `codebase_context_packet` downstream, and show the user only the compact `recon_digest`.
+
+### When to use
+
+- The user describes a new feature, refactor, migration, or implementation-heavy change that needs planning before coding
+- The user wants the coding agent to gather codebase context, prior decisions, sub-problems, discovery questions, recommendations, and a build brief before implementation
+- The user describes a problem they want explored ("we need to figure out X", "let's scope Y", "I want recommendations on Z")
+- The user wants the full pipeline — sub-problems → scope → discovery → recommendations → build brief — not just one step
+- The user runs `/ritual build` from inside a repo that already has explorations in the workspace — the resume path (Step 1.5) decides whether to continue an existing exploration or start a new one based on the per-exploration state badge
+
+When **not** to use:
+- The user already has a specific exploration id and just wants a quick status check — call `get_exploration` directly
+- The user wants to *implement* a feature from a build brief that's already been generated and accepted — that's a separate downstream coding-agent task (the build brief itself is the input)
+
+### Workflow — 13 steps (Steps 10-13 cover the build-brief → implement → sync close-the-loop phase; unpicked considerations are preserved as later candidates by default)
+
+Use explicit **[USER PAUSE]** only at decision gates. Pause when the user must choose among options, approve creation or acceptance, resolve ambiguity, authorize implementation, accept cost/time, or provide missing non-code context. Do **not** pause for status-only steps, safe defaults, internal recon, or silent checks.
+
+---
+
+### CLI and async guardrails
+
+Follow `references/cli-output-contract.md` for terminal output, dense-list formatting, user-facing vocabulary, and the no-internal-step-label rule. Follow `references/async-polling.md` for every long-running server operation.
+
+#### Step 1
+#### Step 1 — Pick a workspace
+
+Resolution order:
+
+1. **Project-bound workspace (preferred).** Check for a `.ritual/config.json` at the project root (you can use the Read tool — the file is a small JSON with `workspaceId` + `workspaceName`). If it exists, that's the workspace this repo is bound to. Use it without pausing.
+
+   User-visible:
+
+   > Using workspace: **{workspaceName}** from `.ritual/config.json`.
+   > Override with `workspace: list`.
+
+   Pause only if the file is missing/malformed, the workspace cannot be accessed, or the user explicitly asks to switch.
+2. **List existing project workspaces.** If no `.ritual/config.json`, call `mcp__ritual__list_workspaces` — this returns project-type workspaces (the General workspace is excluded by default; agents never use it). Present as a numbered list (id, name). **[USER PAUSE]** for selection.
+3. **Create a new one if none exist or user wants a fresh one.** Call `mcp__ritual__create_workspace` with a name — convention is to name it after the repo (basename of cwd, or origin remote). Confirm the name with the user first. **[USER PAUSE]**
+
+Store `workspace_id` for the rest of the flow.
+
+If you created a new workspace, persist the binding to `.ritual/config.json` so future runs in this repo skip the workspace-selection prompt. Write it yourself if you have filesystem write access; otherwise show the user the JSON and have them save it.
+
+**`.ritual/config.json` is committed to the repo — it is shared, not per-user.** Same model as `.eslintrc.json` or `tsconfig.json`: it binds this codebase to a Ritual workspace + pins team-level defaults (workspaceId, defaultTemplateId). Everyone working on this repo wants the same values. Per-user state (PATs, auth tokens) lives in `~/.config/ritual/` and never in this file.
+
+When you write the config, also write `.ritual/.gitignore` if it doesn't already exist so any future per-user state files in this directory get ignored while `config.json` itself stays tracked:
+
+```
+# .ritual/.gitignore — auto-generated by the SKILL.
+# config.json is repo-shared and meant to be committed (workspace
+# binding + team defaults). Per-user state files go below.
+*
+!.gitignore
+!config.json
+```
+
+When you later see `.ritual/config.json` in `git status` output (modified or untracked), it's correct to commit it — don't ask the user whether it's per-user state; this comment is the answer.
+
+#### Step 1.1 — No-arg `/ritual build` entry
+
+If the user invokes `/ritual build` with no problem statement, set `raw_input = null` and **do not ask for a problem statement before checking the workspace**. A no-arg build is often a continuation or next-work discovery intent, so `resume` and `suggest high-leverage work` must remain available.
+
+After workspace selection, proceed into the existing-exploration check below. User-facing copy should avoid internal step labels and should offer these paths when applicable:
+
+```text
+I can help you continue existing work or find the next high-leverage thing.
+
+{existing exploration summary, if any}
+
+Reply with:
+- a number/name to resume
+- `suggest` to have me look for high-leverage candidates from repo + workspace history
+- a feature/problem description to start fresh
+- `none` to exit
+```
+
+If there are **zero existing explorations** and `raw_input = null`, do not say "starting fresh" and do not advance to template selection yet. Ask for the feature/problem first:
+
+```text
+No existing explorations in this workspace yet.
+
+What would you like to build or explore? Describe the feature/problem, or run
+`/ritual context-pulse <ask>` first if you want a readiness check before planning.
+```
+
+If the user replies `suggest` but the workspace has no prior explorations, explain that suggestions need prior workspace signal and ask for a feature/problem instead.
+
+#### Step 1.5 — Resume vs start (cognitive-debt check)
+
+**Skip this step ONLY if you just created the workspace in Step 1 (no explorations possible yet).** Otherwise: before generating new sub-problems, check whether the user's intent might already be covered — partially or fully — by an existing exploration in this workspace.
+
+The cost of skipping this step is high: an engineer mid-loop on a feature ends up with two parallel explorations on the same problem, the build brief grounds on the wrong one, and the knowledge graph gets diluted with near-duplicate decisions.
+
+Steps:
+
+1. **Fetch the workspace's exploration list.** Call `mcp__ritual__list_explorations(workspace_id)`. Default returns each exploration with an `implementationStatus` block — the state badge tells you where each one stands without needing per-exploration follow-ups.
+
+2. **Filter to recent + relevant.** Sort by most recently updated. Drop archived. Cap at 5 in the user-facing summary (the rest stay available if asked).
+
+3. **Group by state badge** and surface to the user with a single message. Do not mention `Step 1.5` in the CLI.
+
+   If `raw_input` is present, frame this as an overlap/continuation check before starting fresh:
+
+   > I see {N} exploration{s} already in this workspace:
+   >
+   > **{state_glyph} {state_label}**
+   > - **{name}** — {short scope summary, first 80 chars of problemStatement}
+   >   - {recommendationCount} rec{s} ({accepted}/{total} approved), {decisionsCount} decision{s} logged, {openDeferralsCount} open deferral{s}
+   >   - {state-specific call-to-action — see table below}
+   >
+   > Recommended: resume one if it matches this work.
+   > Reply with a number/name to resume, `suggest` to find high-leverage candidates from repo + workspace history, or `proceed` to start fresh.
+
+   If `raw_input = null`, frame this as the user's no-arg start screen:
+
+   > I can help you continue existing work or find the next high-leverage thing.
+   >
+   > **{state_glyph} {state_label}**
+   > - **{name}** — {short scope summary, first 80 chars of problemStatement}
+   >   - {recommendationCount} rec{s} ({accepted}/{total} approved), {decisionsCount} decision{s} logged, {openDeferralsCount} open deferral{s}
+   >   - {state-specific call-to-action — see table below}
+   >
+   > Reply with:
+   > - a number/name to resume
+   > - `suggest` to have me look for high-leverage candidates from repo + workspace history
+   > - a feature/problem description to start fresh
+   > - `none` to exit
+
+   State badge → user-facing label + call-to-action:
+
+   | Glyph | State | User-facing label | Suggested next action |
+   |---|---|---|---|
+   | 📍 | `in_progress` | "still in discovery" | "Continue discovery" |
+   | 💬 | `awaiting_admin` | "waiting on admin to accept recommendations" | "Show recommendations for admin review" |
+   | ✅ | `ready` | "ready to implement" | "Generate the build brief and start coding" |
+   | 🛠 | `in_flight` | "implementation in progress" | "Resume — generate or refresh the build brief on remaining work" |
+   | ✓ | `done` | "fully shipped" | "Nothing to do here — start a new exploration if this is new scope" |
+   | ⚠ | `implemented_ahead` | "code shipped before admin acceptance" | "Surface to user — ask admin to review the implementation against the un-accepted recs, or update the recs to match what shipped" |
+
+   The `implemented_ahead` callout is load-bearing: it means a collaborator implemented a recommendation while it was still in `draft` or `pending_review`, and the snapshot column froze that timeline. The user (typically an admin) should know about this BEFORE you do anything else.
+
+4. **[USER PAUSE]** — wait for the user to pick resume / suggest / fresh / abort, or to provide a new feature/problem description.
+
+5. **If the user picks "resume":**
+   - Set `exploration_id` to the picked exploration.
+   - Use the state badge to decide which step to jump to (see "Suggested next action" column above).
+   - Skip ahead in this skill — don't re-run Steps 2-9 for an exploration that already has them done.
+   - For `ready` or `in_flight` states, jump directly to Step 10 (build brief generation).
+   - For `awaiting_admin`, jump to Step 9 (review + accept). Only an admin can move it forward; collaborators see the recs and proceed only if they're explicitly authorized to implement ahead.
+   - For `implemented_ahead`, surface the situation to the user and ask what to do — typically the admin reconciles by either approving the recs post-hoc (no code change needed) or updating the recs to match shipped reality.
+   - **For `done` or `in_flight` — branch-existence sanity check FIRST.** *(CLI Tenet #9 — sanity-check the world before trusting the database.)* The state badge is computed from `ImplementationRecord` rows in the KG. If the KG was seeded from synthetic/bootstrap data (a common state in early pilot deployments), the record can assert a PR/branch that doesn't exist in this repo. Before treating the exploration as ✓ shipped, verify:
+
+     ```bash
+     # If implementationRecord.branch is set:
+     git rev-parse --verify "origin/${implementationRecord.branch}" 2>/dev/null \
+       || git rev-parse --verify "${implementationRecord.branch}" 2>/dev/null
+
+     # If implementationRecord.prNumber is set (and `gh` is available):
+     gh pr view "${implementationRecord.prNumber}" --json state 2>/dev/null
+     ```
+
+     If neither resolves, surface this to the user as a single-action proposal (CLI Tenet #2):
+
+     > 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)**
+
+     Don't paint 3-4 options ("treat as done / treat as fresh / inspect the KG row / something else") — one decisive proposal with a yes/no/correct-me escape hatch. If yes: jump to Step 10 (build brief). If no/correct-me: take the user's input as ground truth and update the next move accordingly.
+
+   - **For `ready` or `in_flight` — implementation footprint check FIRST.** *(Same shape as `/ritual resume` Step R3.5.)* The KG can't distinguish "brief generated, no code yet" from "mid-implementation, unsynced" from "implementation was started and then dropped" — all three look like `ready` because no `ImplementationRecord` exists until `sync_implementation` is called. Run the footprint probes using the `Ritual-Exploration: <id>` commit trailer mandated by Tenet #14:
+
+     ```bash
+     git log --all --grep="Ritual-Exploration: ${exploration_id}" --oneline 2>/dev/null
+     git rev-parse --verify "feat/${exploration_slug}" 2>/dev/null
+     gh pr list --search "Ritual-Exploration: ${exploration_id}" --state all --json number,state,headRefName 2>/dev/null
+     ```
+
+     The **dropped-work case** is the load-bearing one: `git log --all` finds attributed commits, but the branch is gone AND no PR exists. Without this check, the agent silently regenerates the brief and the user loses a day of work that was still recoverable from the reflog. Surface as:
+
+     > ⚠ 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?
+
+     Full decision table for all footprint shapes (mid-implementation, open PR, merged-but-unsynced, orphan-only, etc.) is in `/ritual resume` Step R3.5. Apply that table here verbatim when resuming via this path.
+
+6. **If the user picks "start fresh":** continue to Step 2 normally. The new exploration will sit alongside the existing ones; they're independent rows in the workspace.
+
+6b. **If the user picks `suggest` / "help me find the highest-leverage thing":**
+
+   This path is for the "I have context but no concrete problem yet" case. The agent does a light workspace scan FIRST so suggestions land on real codebase and prior-deferral signals, not generic advice. This is **not** focused feature recon because no problem has been selected yet; focused recon still happens after the user picks a candidate.
+
+   Steps:
+
+   a. **Run a light workspace scan** (15-30 seconds of work, faster than Step 3's focused recon):
+      - Glob top-level structure (README, package.json/setup.py, top dirs)
+      - Skim 3-5 most-load-bearing files
+      - Build a 5-10 line workspace scan summary: architecture shape, active modules, obvious seams, open deferral hotspots, and files tied to recent Ritual implementations
+      - Collect a sources[] array — the file paths you actually read, 5-10 entries
+
+   b. **Tell the user** what you found and that you're sourcing suggestions:
+
+      > Reading the codebase: {recon summary, ≤ 8 lines}
+      >
+      > Now asking the workspace for high-leverage problem candidates…
+
+   c. **Call `mcp__ritual__suggest_high_leverage_problems`:**
+
+      ```
+      {
+        workspace_id,
+        codebase_recon_summary: <the workspace scan summary from step a>,
+        sources: <the file paths from step a>
+      }
+      ```
+
+      One LLM call (~3-5 seconds). Returns up to 4 candidates with title, summary, rationale citing a specific signal (deferral, prior decision, etc.), and referencesPriorWork.
+
+   d. **Surface the candidates** as a numbered list, with the rationale prominent — that's what makes the suggestion auditable. Use the readability-first dense-list shape from the Developer-facing output contract, not compact wrapped paragraphs. Each candidate should have a blank line before the next candidate and labeled blocks for `Why high-leverage:` and `Touches:`:
+
+      ```text
+      Based on this workspace's state, here are {N} candidates ranked by leverage:
+
+      1. {candidate.title}
+
+      {candidate.summary}
+
+      Why high-leverage:
+      {candidate.rationale — cite the specific RB, deferral, prior decision, shipped PR, or file-level signal.}
+
+      Touches:
+      {referencesPriorWork — list exploration names/ids, PRs, RB ids, or deferrals. Wrap if long.}
+
+
+      2. {candidate.title}
+
+      {candidate.summary}
+
+      Why high-leverage:
+      {candidate.rationale}
+
+      Touches:
+      {referencesPriorWork}
+
+
+      Pick 1, 2, 3, or 4. Or say none and describe what you want directly.
+      ```
+
+      If one candidate would resume an existing in-flight exploration rather than create a duplicate, add a short note after the picker:
+
+      ```text
+      Note on #{N}:
+      There's already an in-flight exploration for {RB/problem}. If you pick it, route into
+      `/ritual resume` on that exploration rather than creating a duplicate.
+      ```
+
+   e. **[USER PAUSE]** — wait for the pick.
+
+   f. **If the user picks one (1-N):**
+      - Set the chosen candidate's `summary` as the `raw_input` for the rest of the flow.
+      - **Skip Step 1.5 step 8 (overlap check)** — the user just picked from system suggestions explicitly grounded in workspace state; a fresh overlap pass would be redundant noise.
+      - Continue to Step 2 (template selection).
+
+   g. **If the user says "none" / "let me describe":** continue to Step 2 normally; treat as if they had originally picked "start fresh" with no raw_input yet (they'll provide one at Step 3-4 time).
+
+   h. **If `suggestions` came back empty** (LLM produced nothing or workspace was too sparse): tell the user "I couldn't find anything to suggest — let's start with something you describe" and continue to Step 2.
+
+7. **If there are zero existing explorations** in the workspace:
+
+   - If `raw_input` is present: skip the user pause entirely. Say one line ("No existing explorations in this workspace — starting fresh.") and move to Step 2.
+   - If `raw_input = null`: pause and ask what they want to build/explore before moving to Step 2. Use the no-arg copy from Step 1.1.
+
+   Don't run the suggester from an empty workspace — there's no priors signal yet, and the user opening Ritual for the first time has stronger user-driven intent than the suggester could offer.
+
+8. **Before the user commits to "start fresh"** — if they DID say "start fresh" (or there were no existing explorations to resume) — run a **semantic overlap check** against the workspace. This catches the case where what the user is describing is a near-duplicate of something that already exists, BEFORE they burn LLM cost on Steps 4-5:
+
+   Call `mcp__ritual__check_exploration_overlap(workspace_id, raw_input)`. Pass the user's full natural-language description of what they want to explore as `raw_input` — the SAME text you'd later pass to `generate_considerations`.
+
+   The response:
+
+   ```
+   {
+     candidates: [{
+       explorationId, name, problemStatement,
+       jaccardScore, llmConfidence, llmRationale
+     }],
+     totalCandidatesScanned: number
+   }
+   ```
+
+   - **If `candidates.length === 0`**: silently proceed to Step 2. Don't mention the overlap check happened. The whole point of the two-tier filter is silence in the common case.
+
+   - **If `candidates.length > 0`**: surface a callout BEFORE moving to Step 2:
+
+     > ⚠ **What you're describing may overlap with existing explorations in this workspace:**
+     >
+     > {for each candidate (in order, strongest first):}
+     > **{candidate.name}** *(LLM confidence: {Math.round(candidate.llmConfidence * 100)}%)*
+     > - *"{candidate.problemStatement first 120 chars, no ellipsis padding}..."*
+     > - Why I think it overlaps: {candidate.llmRationale}
+     > - URL: `https://dev.ritualapp.cloud/e/{candidate.explorationId}`
+     > {endfor}
+     >
+     > **Choose:**
+     > 1. **Resume one of these instead** — give me the number, I'll jump to the right step based on its state.
+     > 2. **Proceed anyway** — I'll create a new exploration. The relationship to these {N} won't be lost — when `related_exploration_ids` is supported it'll be captured automatically.
+     > 3. **Show me one in detail first** — give me the number, I'll fetch its full state before you decide.
+
+   - If the user picks (1): treat the chosen one as the resumed exploration (same as Step 1.5 step 5 above — jump to the right downstream step based on the state badge).
+   - If the user picks (2): continue to Step 2. Future PR will populate `related_exploration_ids` on the new exploration so the linkage is preserved.
+   - If the user picks (3): show the full exploration via `mcp__ritual__get_exploration` + `get_recommendations` if any exist, then loop back to the choose prompt.
+
+   **Calibration:** the threshold for surfacing is conservative — the agent is biased toward "miss not false-flag" (you'd rather silently skip a real overlap than noisily prompt the user when there isn't one). If you DO see this prompt, take it seriously — it's likely there's real overlap.
+
+#### Step 2 — Template selection
+
+Templates shape the structure of considerations, the problem statement, and the final deliverable artifact (PRD, spec, brief, etc.). A `/ritual build` flow from inside a coding agent usually wants an engineering-flavored template, but the user must retain an easy override path.
+
+Resolution order:
+
+1. **Project-pinned default (preferred).** Check `.ritual/config.json` for a `defaultTemplateId` field. If present, the project has a pinned team template — use it without pausing.
+
+   User-visible:
+
+   > Template
+   > Using **{templateName}** from `.ritual/config.json`.
+   > Override anytime with `template: list` or `template: {name}`.
+
+2. **Pick a recommended default + offer alternatives.** If no `.ritual/config.json` pin exists, call `mcp__ritual__list_templates`. From the response, pick the first template matching this fallback chain:
+   - Name matches `/Feature Specification.*Agentic Coding/i` — canonical default for code-aware builds
+   - Name matches `/Technical Detail PRD/i`
+   - Name matches `/Engineering Spec|Technical (Detail|Spec)/i`
+   - First SYSTEM-type template in the list (last resort)
+
+   User-visible as a **[USER PAUSE]**:
+
+   > Template
+   > Recommended: **{templateName}** — {short description}
+   >
+   > Reply `go`, `list`, or `template: {name}`.
+
+3. **If the user types `list`:** present a numbered menu of all SYSTEM-type templates. Skip CUSTOM templates by default to avoid menu sprawl unless the user gives a specific custom id/name. Each line: `{N}. {name} — {short description}`. Wait for a number selection.
+
+4. **If the user types `template: {name}` or picks one by name:** find the case-insensitive partial match in the template list. If ambiguous, show only the matching options and ask which one. If no match, show the SYSTEM template menu.
+
+5. **Remember `template_id`.** It passes through every subsequent phase — `generate_considerations`, `refine_considerations`, `generate_problem_statement`, `refine_problem_statement`, and ultimately `create_exploration`. The API uses it to load template-specific anti-patterns + focus keywords into the LLM prompt, so it materially shapes output quality.
+
+6. **Track role silently; surface only the operational default.** Infer `role` from the selected template and carry it forward for:
+   - recommendation tone
+   - sibling exploration cap
+   - Step 8 run-mode default
+
+   Do **not** explain the inference or ask for role confirmation by default.
+
+   User-visible after the template is selected:
+
+   > Defaulting to **{role}** flow. Override with `role: product`, `role: design`, etc.
+
+   Recognized roles (use the role keyword the API returns, not a paraphrase):
+   - `engineering` — code-aware, technical depth
+   - `product` — PRDs, product briefs, market positioning
+   - `design` — UX research, design briefs
+   - `marketing` — campaigns, launch plans, GTM
+   - `delivery` — sprint plans, release plans
+   - `operations` — SOWs, ops planning
+
+   Pause only if:
+   - the template name is ambiguous,
+   - the user explicitly questions the role,
+   - the chosen role changes a costly or irreversible path,
+   - or no pinned/recommended default exists.
+
+   If the user corrects the role (e.g. "actually I'm building a PRD"), update internal role tracking. Do **not** re-pick the template unless the user explicitly asks to change it.
+
+7. **Suggest persistence only when useful.** If you picked a default from the template list and the user accepted with `go` rather than choosing a different one, suggest:
+
+   > Want me to pin this template for future `/ritual build` runs in this repo? I can add `"defaultTemplateId": "{id}"` to `.ritual/config.json`.
+
+   If the user says yes, write the field while preserving existing keys. This is a TEAM pin — `.ritual/config.json` is committed to the repo per Step 1, so the whole team picks up the same default.
+
+Proceed to Step 3 once a template is selected. No extra confirmation is required after a pinned template or an accepted default.
+
+#### Step 3 — Code reconnaissance
+
+**Skip only if the user explicitly asks ("just generate, don't read the code") OR if you're operating outside a codebase context.**
+
+Before generating considerations, gather codebase context so the sub-problems land specific to *this* code, not generic. The goal is not to show the user every fact you found; the goal is to ground downstream MCP calls and expose only decision-relevant findings in the CLI.
+
+##### 3.0 — Check for a pre-build context seed
+
+Before doing fresh recon, check whether the user already seeded one via `/ritual context-pulse`. Glob for `CONTEXT-*.md` at the repo root.
+
+If a `CONTEXT-<slug>.md` is found AND its `## The ask` section close-matches the current `raw_input`:
+
+- **Use it to seed `codebase_context_packet`.** Parse the file's `## Candidate files` list — those become the seed for `sources[]`. Parse `## Prior KG context` as evidence inside the packet, not as final prioritization.
+- **Skip fresh recon** unless the seed is stale or obviously incomplete. If you skip fresh recon, still normalize the seed into the packet structure below before calling MCP tools.
+- **Surface a compact note**:
+  > Code recon
+  > Found `CONTEXT-<slug>.md` from `/ritual context-pulse`.
+  > Using {N} candidate files + {M} prior KG decisions as the recon base. Override with `recon: refresh`.
+- Proceed directly to 3.2.
+
+If no seed file is found, OR the seed's `## The ask` doesn't match the current `raw_input`, do fresh recon. For mismatch, mention the ignored seed in one line and do not delete it.
+
+##### 3.1 — Fresh recon
+
+1. **Read the README + top-level project structure.** Use `ls` / Glob to see top-level files. Identify the language, framework, key directories, and likely entry points.
+
+2. **Glob for relevance.** Derive patterns from the user's problem. Examples:
+   - User says "auth flow" → `**/auth/**`, `**/login*`, `**/user*`, `**/session*`
+   - User says "checkout" → `**/checkout/**`, `**/cart/**`, `**/order/**`, `**/payment*`
+   - User says "notifications" → `**/notif*`, `**/email/**`, `**/sms/**`, `**/push/**`
+   Cap at ~15 hits per pattern.
+
+3. **Skim 3–5 most-relevant files.** For each, read the first ~100 lines + scan for class/function names. Triangulate whether the behavior lives there or calls into another area.
+
+4. **Build three recon artifacts.**
+
+   A. `raw_recon_notes` — internal evidence only
+   - files read and why they were selected
+   - symbols/classes/functions inspected
+   - relevant comments, schema details, tests, migrations, and config
+   - KG hits, prior deferrals, and prior implementation references
+   - uncertain observations, false leads, and things not found
+   - do **not** show this by default and do **not** pass it as the main MCP planning input
+
+   B. `codebase_context_packet` — downstream planning input
+   - this is the synthesized artifact passed into `raw_input`, context pulses, and any MCP field named `recon_context`
+   - it helps MCP understand what the coding agent observed locally without deciding the final considerations itself
+   - separate factual observations from agent hypotheses
+   - include confidence levels for hypotheses
+   - use neutral labels like `agent_observed_scope_pressure` or `candidate_scope_pressure`, not `priority_considerations`
+   - never present the packet as authoritative; MCP/tooling decides final sub-problems, recommendations, and scope
+
+   C. `recon_digest` — user-visible, compact
+   - 3–6 bullets max
+   - key surfaces, hard constraints, scope corrections, and next action
+   - avoid quoting code comments unless they are load-bearing
+   - avoid listing every file read
+
+   `codebase_context_packet` structure:
+
+   ```markdown
+   --- Codebase context packet ---
+
+   ## User intent
+   {verbatim or lightly normalized ask}
+
+   ## Observed relevant surfaces
+   - `path` — observed role in this feature or constraint
+   - `path` — observed extension point, lifecycle, model, or integration seam
+
+   ## Evidence
+   - `path:symbol` — factual observation from code
+   - Prior Ritual signal: {exploration / PR / RB / deferral}, if available
+   - Missing or not-found evidence when it corrects the user's framing
+
+   ## Agent hypotheses
+   - This may make {candidate area} important because {evidence-backed reason}
+     Confidence: low / medium / high
+
+   ## Agent-observed scope pressure
+   - Privacy / lifecycle / migration / compatibility / async / ownership / testing risk
+   - Only include pressure that intersects with the feature intent and code evidence
+
+   ## Scope corrections
+   - The ask says X, but the code suggests Y
+   - Missing fields, renamed concepts, or assumptions the code contradicts
+
+   ## Open questions for discovery
+   - Questions the code cannot answer and the user/Ritual exploration should resolve
+   ```
+
+   Example `codebase_context_packet` excerpt:
+
+   ```markdown
+   ## Observed relevant surfaces
+   - `apps/conversions/abstract_models.py` — append-only conversion event model; lifecycle changes are modeled as follow-up rows.
+   - `apps/conversions/outbox.py` — async publish/retry surface; payload shape may affect erasure semantics.
+   - `apps/order/models.py` — raw guest email appears to live on the order side, not in conversion events.
+
+   ## Agent hypotheses
+   - Erasure semantics may need to cover both mutable raw PII and append-only pseudonymous digests.
+     Confidence: high; supported by model fields and schema comments.
+   - Outbox purge/replay behavior may be a scope pressure because retries can outlive the original conversion write.
+     Confidence: medium; verify worker idempotency before scoping implementation.
+
+   ## Scope corrections
+   - No `guest_session_id` column was found in the inspected conversion models; scope may need to use the actual guest attribution identifiers.
+   ```
+
+   Example `recon_digest`:
+
+   ```text
+   Code recon complete
+
+   Key surfaces:
+   - `apps/conversions/abstract_models.py` — append-only conversion events.
+   - `apps/conversions/outbox.py` — async publish/retry lifecycle.
+   - `apps/order/models.py` — raw guest email surface.
+
+   Constraint:
+   - Erasure likely needs to handle mutable raw PII separately from pseudonymous conversion digests.
+
+   Scope correction:
+   - I did not find `guest_session_id` in the inspected models.
+
+   Next: attach PRDs/tickets if they should shape scope, or proceed.
+   ```
+
+##### 3.2 — Surface the digest and continue
+
+Surface only `recon_digest` by default. Do **not** dump `raw_recon_notes` or the full `codebase_context_packet` to the CLI unless the user asks for detail.
+
+Pause only if:
+- recon contradicts the user's stated scope,
+- there are multiple plausible implementation areas and choosing wrong would waste work,
+- a legal/product/business constraint is required before generation,
+- the user explicitly asked to review recon before continuing.
+
+If no pause is needed, proceed to Step 3.5. The user still has a cheap escape hatch: `recon: detail`, `recon: refresh`, or a correction in plain English.
+
+**Pulse (Step 3 done):** Emit a pulse line — repo grounding just moved meaningfully (sources collected, agent inspected files, possibly KG hits). Compute per `/ritual context-pulse` § Step CP3 and render compact unless this is the FIRST pulse of the build flow, in which case use full.
+
+##### 3.3 — Compose augmented `raw_input`
+
+Compose the augmented `raw_input` for Step 4 from:
+- the user's original problem (verbatim, top)
+- the full `codebase_context_packet`, under `--- Codebase context packet ---`
+- any user correction or added constraint from code recon
+
+Do not pass unsynthesized `raw_recon_notes` as the primary planning input. Step 3 is the difference between generic considerations and considerations grounded in actual code, patterns, risks, and open questions. Keep `raw_recon_notes` internally for auditability; pass the packet downstream for planning.
+
+##### 3.4 — Collect the `sources` array
+
+Collect the file paths you actually read and consider load-bearing for this problem — exactly as they appear in the repo (e.g. `"apps/checkout/views.py"`, not `"./apps/checkout/views.py"` or absolute paths). This list is passed alongside `raw_input` to `generate_considerations`, `generate_problem_statement`, `query_knowledge_graph`, context pulses, and `generate_build_brief` so the API can anchor priorContext consistently.
+
+Keep the list focused. 5–10 is the sweet spot; >20 dilutes the KG signal.
+
+#### Step 3.5 — Stage knowledge sources (PRDs / tickets / transcripts / etc.)
+
+The codebase recon you just did handles the *code* grounding. Most real features ALSO have non-code context — PRDs, Jira/Linear tickets, design specs, meeting transcripts, Slack threads, customer-research notes — that get paraphrased into the problem statement and lose detail. Step 3.5 ingests those as first-class **knowledge sources** attached to the exploration BEFORE generating sub-problems, so the priorContext you'll see in Step 4 (`generate_considerations`) and downstream is grounded in what the user actually brought, not the paraphrase.
+
+##### 3.5.1 — Prompt the user only when useful
+
+Knowledge sources are a feature multiplier, not a mandatory gate. Ask for PRDs/tickets/designs/transcripts only when at least one of these is true:
+
+- the ask is ambiguous or cross-functional,
+- context-pulse / Reference Grounding is low,
+- the user mentioned a PRD, ticket, design, chat, customer request, or meeting,
+- the feature has legal, privacy, billing, permissions, enterprise, analytics, migration, or compliance constraints,
+- code recon found implementation surfaces but not product intent.
+
+When triggered, surface a single ask (CLI Tenet #2 — one recommended action with a cheap escape):
+
+> Any PRDs, tickets, designs, transcripts, or chat excerpts that should shape this? Paste paths / URLs now, or say `skip`.
+
+Wait for the user to either provide refs or skip.
+
+If none of the triggers apply, do **not** block. Print a non-blocking line and proceed:
+
+> Proceeding with codebase context only. Paste a PRD/ticket anytime before discovery if it should shape the scope.
+
+##### 3.5.2 — Read the content
+
+For each item the user provided, use the agent's local tools to obtain the text content. Different routes by what the user supplied:
+
+| What the user provided | What to do |
+|---|---|
+| Local file path (PDF, markdown, txt, png, pptx, docx) | `Read` the file. For binary files (PDF/image/pptx) the agent's Read tool returns extracted text or visual description; for text files just read the bytes. |
+| URL (Confluence / Notion / Jira / Linear / public web) | `WebFetch` the URL to get the text content. |
+| Pasted text | Use the pasted text directly. |
+| Local directory | `Glob` for likely docs (`*.md`, `*.pdf`, `*.docx`), then Read each. Cap at 5 files unless user says otherwise. |
+
+Detect each item's **`source_content_type`** from format + content cues:
+
+- Filename + content shape: `prd.md` with "Problem statement" → `PRD`; `*.pdf` with "Slide 1" markers → could be `PRD` or `SPEC` depending on body; user research notes with multiple speakers + timestamps → `TRANSCRIPT`.
+- URL host: `*.atlassian.net` / `linear.app` / GitHub issue URL → `TICKET`; generic blog/docs URL → `URL`; Slack/Discord export → `CHAT`.
+- Content signal: presence of `endpoints` / `paths:` / `openapi:` → `SPEC`; image binary → `IMAGE`; multi-speaker + timestamps → `TRANSCRIPT`.
+- If ambiguous: prefer the broader category (`DOC` over `OTHER`; ask user when in doubt for high-leverage items).
+
+##### 3.5.3 — Stage each source for registration after exploration creation
+
+For each item, create a staged source record in working memory. Do **not** call `mcp__ritual__add_knowledge_source` yet because no `exploration_id` exists until exploration creation.
+
+Staged record shape:
+
+```json
+{
+  "source_content_type": "PRD | TICKET | URL | CHAT | TRANSCRIPT | SPEC | DOC | IMAGE | OTHER",
+  "content": "<full text content the agent obtained>",
+  "title": "<explicit title | first H1 | filename | TYPE from date>",
+  "source_url": "<original URL if applicable>",
+  "source_path": "<original local path if applicable>",
+  "origin_feature": "DISCOVERY"
+}
+```
+
+Surface only a staging summary:
+
+> Staged **{title}** ({source_content_type}) for this exploration. I'll register it after the exploration is created; the content is already in my context for planning.
+
+##### 3.5.4 — Update the augmented `raw_input` + score impact
+
+The content the agent collected in Step 3.5.2 also gets folded into the augmented `raw_input` for Step 4's `generate_considerations` so the LLM sees the references inline:
+
+```
+{original user problem}
+
+--- Codebase context ---
+{codebase_context_packet from Step 3}
+
+--- Reference context (provided by user) ---
+[PRD — billing-export.md]
+{first ~2000 chars of content, marked with type + title}
+
+[TRANSCRIPT — billing planning sync 2026-05-09]
+{...}
+
+[TICKET — LINEAR-1234]
+{...}
+```
+
+Cap the inline reference context at ~10000 chars total (priority: PRD/SPEC > TRANSCRIPT/TICKET > CHAT/DOC > URL > IMAGE). Longer refs stay accessible via `get_knowledge_source` after extraction completes, but for THIS build the inline summary keeps the LLM call bounded.
+
+##### 3.5.5 — Pulse impact
+
+Each registered knowledge source contributes to **Repo Grounding** (which, despite the name, covers BOTH code grounding from Step 3 AND reference grounding from Step 3.5 — the dimension will be split in MVP-2). For MVP-1 scoring (per `/ritual context-pulse` § CP3):
+
+- Repo Grounding gets +5 points per registered knowledge source, capped at +15 total (so 3+ refs is the cap).
+- Combined with code-recon signals already in the dimension, Repo Grounding stays in the 0-100 range.
+- After Step 3.5 completes, fire the standard Step 3 pulse — the user will see Repo Grounding jump if they attached refs.
+
+##### 3.5.6 — Skip path
+
+If the user says "skip" / "none" / "later", proceed silently to Step 4. Do NOT pressure for more — refs are a feature multiplier, not a requirement.
+
+The user can always come back later with `/ritual context-pulse <exploration>` to see the current Reference Grounding score, OR drag refs in mid-flow (e.g. at Step 8 if the agentic run surfaces a question that a PRD would have answered).
+
+#### Step 4 — Generate sub-problems
+
+##### 4.1 First draft
+
+Call `mcp__ritual__generate_considerations` with:
+- `workspace_id`
+- `raw_input` (the user's problem + the Step 3 `codebase_context_packet` + any reference context, concatenated as described above)
+- `template_id` (the one picked in Step 2 — should always be set by this point)
+- `sources` (the file path list from Step 3 step 7 — file-path strings only, e.g. `["apps/checkout/views.py", ...]`)
+
+LLM call, ~5–10s. Returns 5–6 sub-problems — different framing axes the system should investigate. Track each one as `{ text, version: 1 }` in your working memory.
+
+The coding agent's packet is context, not authority. Do not pre-rank or collapse the generated sub-problems based only on the agent hypotheses. Let MCP/template/KG output determine the candidate considerations; use the packet to make them specific, evidenced, and grounded.
+
+**If the response includes `kg_context_used` with `implementationCount > 0`:** surface this to the user BEFORE presenting the considerations. It's the visible signal that prior team decisions shaped this draft.
+
+> Reading the codebase I overlapped with 3 prior Ritual explorations on these files:
+>  - **"Anonymous checkout opt-in"** (shipped 2026-04-12) — 2 decisions, 1 deferral
+>  - **"Payment-method routing"** (shipped 2026-03-22) — 4 decisions
+>  - **"Session-data persistence"** (shipped 2026-02-08) — 1 decision
+>
+> I factored those into the sub-problems below.
+
+If `implementationCount === 0`: don't mention the KG check (silent — would just be noise on a cold KG).
+
+**[USER PAUSE]** Present as a numbered list and ask which to include:
+
+> Sub-problems the system identified (v1):
+>
+> 1. {sub-problem 1}
+> 2. {sub-problem 2}
+> ...
+>
+> Which should we factor into the scope? Pick any subset, "all", or ask for a different framing (e.g. "make them more technical", "drop the measurement angle", "focus on enterprise").
+
+##### 4.2 Iteration loop
+
+If the user asks for a refinement (anything that isn't "all" / specific picks / "these are good"):
+
+Call `mcp__ritual__refine_considerations` with:
+- `workspace_id`, `raw_input`, `template_id`, `sources` — unchanged from the generate call. Critical: pass the SAME `sources` array each iteration so the KG-injected priorContext stays consistent.
+- `change_prompt`: the user's request verbatim
+- `selected`: items from prior versions the user kept (track `{ text, from_version }`, send just `text`)
+- `dismissed`: items the user explicitly rejected
+- `session_id`: omitted on the first refinement; pass the `session_id` from the previous refine response on subsequent ones to chain context
+
+Track the new items as `{ text, version: N+1 }`. Present **alongside** the prior versions, not replacing them — the user can mix selections across versions.
+
+Loop until the user says "these are good" or picks a subset.
+
+**Critical**: never re-call `generate_considerations` for a refinement. That endpoint is stateless and re-rolls a fresh seed; you'll lose what the user just told you. The whole point of `refine_*` is the LLM sees the iteration context.
+
+Store the final picked sub-problems for Step 5 — they go into `considerations[]`.
+
+#### Step 5 — Generate scope
+
+##### 5.1 First draft
+
+Call `mcp__ritual__generate_problem_statement` with:
+- `workspace_id`
+- `raw_input` (same augmented version from Step 4)
+- `considerations` (the picks from Step 4)
+- `template_id` (same as Step 4 — the one picked in Step 2)
+- `sources` (the same file-path list passed to generate_considerations — keeps the KG anchor consistent)
+
+Returns a polished "How might we ..." style scope (typically <800 chars) plus optional follow-up questions and quality scores. Treat this as **v1** of the problem statement.
+
+If the response includes `kg_context_used` with `implementationCount > 0`, prepend a note to the scope presentation:
+
+> *(Grounded in {N} prior implementation{s}: {top match name}, …)*
+
+**[USER PAUSE]** Present and ask:
+
+> Here's the scope (v1):
+>
+> > **{generated scope}**
+>
+> Looks good? Want to tighten / broaden / change the audience / focus on a specific tier? Or "ship it" to lock it in.
+
+##### 5.2 Iteration loop
+
+If the user asks for a refinement:
+
+Call `mcp__ritual__refine_problem_statement` with:
+- `workspace_id`, `raw_input`, `considerations`, `template_id`, `sources` — unchanged. (Same `sources` as the original generate call — keeps the KG anchor stable.)
+- `previous_problem_statement`: the FULL TEXT of the current best draft (the v1 you just showed)
+- `change_prompt`: the user's request verbatim ("tighten and drop the audience clause")
+- `version`: optional label like `"v2"` — purely for telemetry
+- `session_id`: omitted on the first refinement; chain on subsequent ones
+
+The returned text becomes `v2`. Show it. The user can iterate v2 → v3 → ... by calling refine again with `previous_problem_statement` set to the latest draft.
+
+**Critical**: each refinement's `previous_problem_statement` is the LATEST draft, not the original v1. Otherwise the LLM keeps refining the same starting point and the user can't compose multiple refinements ("tighter, AND drop the audience clause, AND make it past-tense").
+
+When the user accepts ("ship it" / "looks good"), store the final text as `problem_statement` for Step 6.
+
+**Pulse (Step 5 done):** Emit a pulse — feature clarity just jumped (problem statement accepted; actor / behavior / acceptance signals are now scorable). Compute per `/ritual context-pulse` § Step CP3. Render full if this crosses Raw ask → Under-specified, else compact.
+
+#### Step 6 — Create the exploration
+
+Generate a short name (≤60 chars) from the scope — typically the noun phrase, not the full HMW. E.g. "Reduce T2 customer churn in Q3" → name `T2 churn reduction (Q3)`.
+
+**[USER PAUSE]** "I'll create the exploration as **T2 churn reduction (Q3)**. Proceed?"
+
+Call `mcp__ritual__create_exploration` with:
+- `workspace_id`
+- `name`
+- `problem_statement` (the scope from Step 5)
+- `agentic: false` — **do NOT** pass `agentic: true`. We want explicit per-step control so the user gets to pick discovery questions in Step 7. Auto-agentic skips that.
+
+Store `exploration_id`. Show the URL:
+
+> Exploration created. Track progress at https://dev.ritualapp.cloud/e/{exploration_id}
+
+##### 6.1 — Promote the pre-build seed (if one was consumed in Step 3.0)
+
+If Step 3.0 consumed a `CONTEXT-<slug>.md` seed file, promote it into the exploration's artifact trail now that an exploration id exists. Move + rename the file from `CONTEXT-<slug>.md` to `.ritual/exploration-notes/<exploration-id>.md` using the Bash tool:
+
+```bash
+mkdir -p .ritual/exploration-notes
+git mv CONTEXT-<slug>.md .ritual/exploration-notes/<exploration-id>.md 2>/dev/null \
+  || mv CONTEXT-<slug>.md .ritual/exploration-notes/<exploration-id>.md
+```
+
+Surface to the user as a one-line note:
+
+> Promoted `CONTEXT-<slug>.md` → `.ritual/exploration-notes/<exploration-id>.md` so it stays tied to this exploration.
+
+This keeps the repo root clean (CLI Tenet #1 — files for reference, not clutter) and preserves the seed's content for future `/ritual lineage` or audit lookups. The file remains git-tracked at the new path.
+
+If `git mv` fails (file wasn't tracked yet): use plain `mv` instead — same outcome, the user just commits the move whenever they next commit.
+
+#### Step 6.5 — Preserve unpicked considerations without cluttering the workspace
+
+Unpicked or dismissed considerations are useful signal, but automatically creating sibling explorations can clutter the workspace. Do **not** fork sibling explorations by default.
+
+Default behavior:
+
+1. If `dismissed[]` or unpicked considerations are empty, skip silently.
+2. If there are unpicked considerations, preserve them in working memory as `phase_later_candidates[]` for the current build.
+3. Append the concise set to the build brief's `recon_context` payload under a heading like `Explicit phase/later candidates from discovery` so they can appear in **Phase Candidates / Deferrable Items** if relevant. Keep the base of `recon_context` as the `codebase_context_packet`, not raw notes.
+4. Surface at most one compact line:
+
+   > Saved {N} unpicked sub-problem{s} as later candidates for the brief.
+
+Only call `mcp__ritual__fork_sibling_explorations` when the user explicitly asks to save separate tracks, or when an unpicked item maps cleanly to a known open deferral / existing exploration and the user confirms.
+
+If sibling creation is confirmed, call:
+
+```
+{
+  primary_exploration_id: <id from Step 6>,
+  unpicked_considerations: dismissed.map(d => d.text)
+}
+```
+
+Then summarize the created siblings in the dense-list format. Do not pause after creation; return to the primary build flow.
+
+#### Step 7 — Discovery questions
+
+Longest phase because generation is async + the user picks per-matter.
+
+##### 7.1 — Kick off
+
+Call `mcp__ritual__suggest_discovery_questions(exploration_id)`. Returns immediately with `task_id`. Tell the user:
+
+> Generating discovery questions for each matter… 30-120 seconds.
+
+##### 7.2 — Poll until ready
+
+Loop:
+- Call `mcp__ritual__get_discovery_state(exploration_id)`
+- If `ready: false`, wait 5 seconds, poll again
+- If `ready: true`, exit loop
+
+Don't poll faster than every 5 seconds. Follow the global polling rule above: single `Bash sleep 5` per iteration and a one-line update every ~3 polls (~15s).
+
+##### 7.3 — Present matters and collect picks
+
+The state contains `matters[]`, each with `id`, `name`, and `questions[]`. Walk through them **one matter at a time**:
+
+> **{matter.name}** — {matter.questions.length} discovery questions:
+>
+> 1. {question 1}
+> 2. {question 2}
+> ...
+>
+> Which should the agent investigate? Pick any subset, "all", or "skip" to skip this matter.
+
+**[USER PAUSE]** Wait per matter.
+
+##### 7.4 — Commit picks per-matter
+
+For each matter where the user picked at least one question, call `mcp__ritual__accept_discovery_questions` with:
+- `state_id` (from the discovery state)
+- `matter_id`
+- `question_ids[]` (the picks for THIS matter)
+
+This MUST be one call per matter — the API enforces per-matter atomicity. Don't bundle across matters.
+
+##### 7.4.5 — Classify unpicked areas when the signal warrants it
+
+After question picking, check for scope mismatch only when one of these triggers fires:
+
+- Pick-rate < 40%
+- Matter coverage <= 50%
+- Pick-rate = 100%
+- Picks concentrate heavily in one matter while the scope spans several concerns
+
+If no trigger fires, proceed silently to anti-goals.
+
+If a trigger fires, summarize the pattern in plain language and ask the user to classify unpicked areas:
+
+```text
+How should I treat the unpicked areas?
+
+1. Out of scope — tighten the current scope around what you picked.
+2. Later phase — keep the broad scope, but mark unpicked areas as phase-later candidates.
+3. Open questions — keep the broad scope and treat unpicked areas as context debt.
+4. Pick more — return to question picking before continuing.
+```
+
+Use `references/discovery-classification.md` for the branch handlers, pulse templates, and no-discrimination case. Do not preview score deltas in the question-picking menu; let the pulse explain the consequence after the user chooses.
+
+For Branch 2, append an exact block to `recon_context` before build brief generation:
+
+```markdown
+## Explicit phase-later candidates
+
+These were intentionally deferred by the user during discovery. They are not context debt. Include them in the Build Brief under "Phase Candidates / Deferrable Items."
+
+- {matter/question}
+  Reason: {user choice or inferred dependency}
+  Related RB/source: {optional}
+```
+
+
+##### 7.5 — Optional: capture out-of-scope items
+
+If the user mentioned things they DON'T want investigated ("don't touch enterprise SSO", "skip pricing"), capture them as anti-goals.
+
+Call `mcp__ritual__set_anti_goals(exploration_id, [{ text, reason? }, ...])`.
+
+Skip silently if no anti-goals were mentioned.
+
+**Pulse (Step 7.4 done — and again after 7.5 if anti-goals were set):** Emit a pulse — decision resolution and (if 7.5 ran) assumption safety just moved. Compact format unless this crosses Under-specified → Exploration-safe.
+
+#### Step 8 — Run the agentic pipeline (role-aware pause point)
+
+The agentic pipeline runs sourcing → answers → recommendations. Two run modes are supported (2026-05-12, PR 4):
+
+**Mode A — Full agentic to recommendations (DEFAULT for engineering / delivery / operations / marketing roles, and the **skip** path):**
+
+Call `mcp__ritual__start_agentic_run` with:
+- `scope_type: 'exploration'`
+- `exploration_id`
+
+Runs through sourcing → answers → recommendations end-to-end. Typical runtime: 3-8 minutes. Poll, show progress, proceed to Step 9 when COMPLETED.
+
+**Mode B — Stop after answers (RECOMMENDED DEFAULT for product / PRD / design roles):**
+
+For PRD-style flows the user often wants to iterate on the v1 answers before recommendations are synthesized — the answers ARE the substance of the PRD; refining them lifts rec quality dramatically.
+
+Call `mcp__ritual__start_agentic_run` with:
+- `scope_type: 'exploration'`
+- `exploration_id`
+- `stop_after: 'answers'`
+
+The pipeline halts after Phase 3 (answering). Run lands in `PAUSED_FOR_REVIEW`. Continue with Step 8.5 instead of Step 9.
+
+**Which mode to offer:**
+
+Use the **role** inferred at Step 2 step 6b:
+- `engineering`, `delivery`, `operations` → default Mode A; offer Mode B as opt-in
+- `product`, `design`, `marketing` → default Mode B; offer Mode A as opt-in
+- Otherwise → ask the user
+
+Phrase the offer plainly. For product roles:
+
+> I'll start the agentic pipeline. Two options:
+>
+> 1. **Stop after answers** *(recommended for PRD)* — I'll generate v1 answers for each matter (~3-5 min). You review and refine each one before I run recommendations. Highest-quality PRD output but takes longer overall.
+> 2. **Skip the pause — run all the way to recommendations** — fastest end-to-end (~3-8 min). You can still edit answers later in the web UI, but recs will already exist.
+>
+> Pick 1 or 2.
+
+For engineering roles, flip the order — Mode A first.
+
+**Common behavior for both modes:**
+
+Poll `mcp__ritual__get_agentic_run(run_id)` using the standard async polling rule: one `Bash sleep 5` per iteration, then a fresh status call. Print progress only when `progress_pct` or `current_step` changes, or every ~15 seconds if the status is unchanged:
+
+> Agentic run: {progress_pct}% — {current_step}
+
+When `status` is `COMPLETED`: continue to Step 9.
+When `status` is `COMPLETED_WITH_ERRORS`: tell the user, but proceed — partial recommendations may still be useful.
+When `status` is `FAILED`: surface the error message, ask if they want to retry (`start_agentic_run` again with same exploration_id) or stop.
+When `status` is `PAUSED_FOR_REVIEW` (Mode B only): continue to Step 8.5.
+
+If user wants to abort mid-flight: `mcp__ritual__cancel_agentic_run(run_id)`.
+
+#### Step 8.5 — Agent-driven per-answer iteration (Mode B only)
+
+When the pipeline pauses at `PAUSED_FOR_REVIEW`, the exploration is at step `REVIEWING_ANSWERS`. Every matter's questions have v1 answers + at least one clarifying question per consideration, but nothing has been committed for recommendation generation yet.
+
+**The agent walks the user through each question one at a time.** For each question:
+
+1. **Fetch the state.** Call `mcp__ritual__get_answer_state({ question_id })`. Returns:
+   - The question text
+   - The current draft answer (v1)
+   - The considerations (sub-aspects) with their chat sessions
+   - The latest assistant message per consideration — this is the **first clarifying question** the answer engine already generated during Phase 3
+
+2. **Present to the user.** Two choices, that's it (no "skip"):
+
+   > **Question {N} of {total}** — *{matter.name}*
+   >
+   > **Q:** {question.text}
+   >
+   > **v1 answer:**
+   > {currentDraft, first 400 chars …}
+   >
+   > **My follow-up:** {first consideration's latest assistant message}
+   >
+   > Two options:
+   > 1. **submit** — you're happy with v1; lock it in and move to the next question
+   > 2. **iterate** — answer my follow-up OR tell me what's wrong with v1 (free-text). I'll regenerate.
+
+3. **Branch on user's choice:**
+
+   - **If "submit":** call `mcp__ritual__submit_answer({ question_id })`. The question advances to COMPLETED. Move to the next question's Step 8.5 loop iteration.
+
+   - **If "iterate" (any free-text reply):** call `mcp__ritual__iterate_answer({ consideration_id, message: user_text })`. The answer engine:
+       - Persists the user message in the consideration's chat
+       - Generates a new AI response (which is either the next clarifying question OR a recognition that the answer is now complete)
+       - The new response is **automatically KG-aware** as of PR 5: the answer engine reads the exploration's persisted `sources` and pulls in relevant prior decisions + open deferrals when forming the next question
+
+     **Loop back to step 2 with the updated state.** Fetch fresh state via `get_answer_state` (the considerations array now reflects the new chat message + AI response), show v_N+1, prompt again. Cap at ~5 iterations per consideration before suggesting "let's submit and move on" — keeps cost bounded.
+
+4. **When ALL questions are submitted:** call `mcp__ritual__resume_agentic_run({ run_id })`. Pipeline runs Phase 4 (submit all answers — the per-question submits above already advanced individual questions, but submit_all_answers is the canonical batch checkpoint) + Phase 5 (recommendations). Poll as in Step 8. When `status` becomes `COMPLETED`, continue to Step 9.
+
+**Skip-the-iteration escape hatch:** the user can say "just resume" at any point. Call `resume_agentic_run` immediately. Recs generate from whatever state the answers are in (whether v1 or partially iterated). Equivalent to having picked Mode A from the start, just with the option to iterate later via the web UI.
+
+**Abandon:** `cancel_agentic_run(run_id)`. The exploration stays at `REVIEWING_ANSWERS` — the user can come back later and either resume or start fresh.
+
+**Performance note:** each iteration is 1 LLM call (~3-5s). For 20 questions × 2 iterations average × 1 call = 40 LLM calls (~$0.04). The skip path is ~$0. Bounded by user choice per-question.
+
+**Pulse (Step 8 done):** Emit a pulse — decision resolution moved significantly (answers complete, draft recommendations now exist). Render full if this crosses Under-specified → Exploration-safe, else compact.
+
+#### Step 9 — Review and accept recommendations (role-aware)
+
+Call `mcp__ritual__get_recommendations(exploration_id)`. Response is an array of recommendations with id, title, status, content, reasoning.
+
+**Role model — load-bearing**: only **admins** can accept recommendations (call `accept_recommendations`). **Collaborators** can read, comment, and proceed to implement, but they cannot move recs from `draft`/`pending_review` to `approved`. Respect this so a collaborator running `/ritual build` doesn't hit a 403 mid-flow and lose context.
+
+If you don't already know the user's role on this workspace, prefer the workspace member endpoint or cached role from `/ritual init`. When unavailable, ask plainly: *"Are you the workspace admin or a collaborator?"* Do not attempt acceptance blindly unless the user explicitly says to accept.
+
+Present recommendations in a compact, scannable form and give one recommended action:
+
+```text
+Recommendations ready: {N}
+
+1. {title}
+
+{one-line summary}
+
+2. {title}
+
+{one-line summary}
+
+Recommended: accept all and generate the build brief.
+Reply `accept`, `detail 2`, or `hold`.
+```
+
+If the user asks for detail, show the requested recommendation's `content` and `reasoning_chain` if present, then return to the same `accept / detail / hold` prompt. Do not ask a second confirmation after the user says `accept` unless statuses are mixed, rejected, or the user is not an admin.
+
+**Branch A — user IS an admin and says `accept`:**
+
+Call `mcp__ritual__accept_recommendations(exploration_id)`. Response includes counts (`promoted`, `alreadyApproved`, `skipped`, `transitionedToComplete`). Show:
+
+> Accepted {N} recommendations. Exploration is COMPLETE.
+> View: https://dev.ritualapp.cloud/e/{exploration_id}
+
+**Pulse (recommendations accepted):** Emit a pulse — this is almost always a state-tier crossing into **Recommendation-ready**. Render full.
+
+Continue to Step 9.5.
+
+**Branch B — user is a collaborator (no admin acceptance available):**
+
+Tell the user explicitly:
+
+> These recommendations are still in **{status — draft / pending_review}**. Only an admin can formally accept them.
+>
+> Recommended: keep going and generate the build brief. When we sync implementation later, Ritual will record that it shipped ahead of admin acceptance. An admin can reconcile later.
+>
+> Reply `continue`, `hold for admin`, or `detail {N}`.
+
+If the user picks `continue`, proceed to Step 9.5. The `sync_implementation` call in Step 12 will automatically snapshot the rec status via the A1.5 column.
+
+#### Step 9.5 — Wait for requirements (auto-triggered by Step 9)
+
+`accept_recommendations` fires requirement generation **fire-and-forget** the moment it succeeds. By the time you reach this step, generation is already in flight (or done, for fast LLM calls). The brief in Step 10 needs requirements ready, so wait here.
+
+Steps:
+
+1. **Tell the user once** that requirements are being generated:
+
+   > Generating requirements for the build brief… usually 20-60s.
+
+2. **Poll `mcp__ritual__get_requirement_set_status(exploration_id)` every ~5s.** The response shape:
+
+   ```
+   {
+     exists: boolean,
+     status: 'GENERATING' | 'READY' | 'FAILED' | null,
+     icp, startedAt, completedAt, errorMessage
+   }
+   ```
+
+   Polling rules in this harness:
+   - Use a **single `Bash sleep 5`** call per poll iteration — don't chain sleeps or use `sleep ≥30`. The harness blocks chained sleeps; one short sleep per turn dodges that AND keeps the user-facing progress feel live.
+   - **Update the user every ~3 polls (~15s)** with a "still generating…" line so they know you haven't stalled.
+
+3. **Exit conditions:**
+
+   | Response | Action |
+   |---|---|
+   | `status === 'READY'` | Proceed to Step 10 |
+   | `exists === false` (still null) for 3+ polls (~15s) | The fire-and-forget hasn't reached the DB yet, OR Branch B was just hit (no LLM call yet). After ~15s either keep polling OR proceed to Step 10 — the API auto-triggers generation inline if the set is still missing when the brief is requested (adds ~30s to the brief call but never hard-fails). |
+   | `status === 'GENERATING'` | Keep polling |
+   | `status === 'FAILED'` | Surface `errorMessage` to the user; offer to retry by calling `generate_build_brief` directly (which will auto-trigger a fresh generation), OR by hitting `POST /requirements?force=true` via the web UI |
+
+4. **Special case — Branch B from Step 9 (collaborator did NOT call accept_recommendations):** there's no fire-and-forget auto-trigger because accept never ran. Skip the polling entirely and let Step 10's auto-trigger handle requirement generation inline. The brief call will take ~30s longer than it otherwise would.
+
+5. When `status === 'READY'`, tell the user one line ("Requirements ready, generating the build brief…") and continue to Step 10.
+
+#### Step 10 — Generate the build brief
+
+The Build Brief is the markdown document the engineer reads RIGHT BEFORE writing code. It bridges accepted recommendations + synthesized requirements with the implementation. Sections:
+
+- **READ THIS FIRST — These Will Block Review If Missing** (RB-numbered table of must-haves)
+- **Goal** (1-2 sentences, restated for code-time clarity)
+- **Required Outcomes** (specific, testable)
+- **Suggested Implementation** (high-level approach + the trade-offs the agent considered)
+- **Codebase Anchors** (file paths + existing patterns to extend, grounded in Step 3's recon)
+- **Previously Deferred — Worth Addressing?** (only present when `sources` overlap prior implementations with open deferrals)
+- **Phase Candidates / Deferrable Items** (what to intentionally punt for v2)
+
+##### 10a — Call `generate_build_brief`
+
+Call `mcp__ritual__generate_build_brief` with:
+
+- `exploration_id`
+- `icp` (optional — defaults to the exploration template's primary ICP, then PM; pass `TECH_PM` for engineering-flavored explorations)
+- `recon_context` — the Step 3 `codebase_context_packet` plus any explicit phase/later candidates from discovery. Do not pass raw recon notes. This grounds "Codebase Anchors" in real file paths while keeping agent hypotheses auditable and non-authoritative.
+- `sources` — the **same** file-path array passed to `generate_considerations` and `generate_problem_statement` in Steps 4–5. Critical for KG consistency: the brief's "Previously Deferred" section only populates when overlapping prior implementations exist on these files.
+
+Returns the brief markdown + an `id` + `kgContextUsed` block. The brief is **idempotent on (exploration, icp)** — same recommendation+requirement hashes return the cached READY row. Pass `force: true` only when a prompt-version update requires re-generation.
+
+##### 10b — Timeout-recovery polling (CLI Tenet #8)
+
+`generate_build_brief` can take **30–90s** in the cold-start case: the API auto-triggers RequirementSet generation inline (~30s) if one doesn't exist, then synthesizes the brief on top (~20-60s). MCP clients enforce a hard **30s timeout** on the request — you will sometimes see a local-timeout error while the server-side work is still running.
+
+**Don't give up and don't blindly regenerate.** Instead, fall back to status polling:
+
+1. On timeout/error from `generate_build_brief`, call `mcp__ritual__get_build_brief_status(exploration_id, icp)` immediately.
+2. Poll every **~5s** for up to **2min** total. Polling rule (CLI Tenet #7): a single `Bash sleep 5` call per turn — the harness blocks chained sleeps and `sleep ≥ 30`. Update the user with a "still generating…" line every ~3 polls (~15s).
+3. Exit conditions:
+
+   | Response | Action |
+   |---|---|
+   | `exists === false` for 3+ polls (~15s) | The fire-and-forget never landed — try calling `generate_build_brief` once more (it will likely succeed now that requirements are ready). |
+   | `status === 'GENERATING'` | Keep polling. |
+   | `status === 'READY'` | Read `content` field — proceed to Step 10c as if generate had completed. |
+   | `status === 'FAILED'` | Surface `errorMessage` to the user. Propose a single action (CLI Tenet #2): *"The brief failed: {errorMessage}. Retry with a fresh generation? (y/N)"*. On yes: call `generate_build_brief` again with `force: true`. |
+
+You can ALSO call `get_build_brief_status` **proactively** before `generate_build_brief` — if `exists === true && status === 'READY'` and the hashes haven't changed, you've saved a write-tool roundtrip. Tradeoff: tiny read cost for skipping a maybe-slow write.
+
+##### 10c — Write to `BUILD-BRIEF.md` + CLI summary (CLI Tenet #1, #5)
+
+When the brief content is in hand (from generate OR polling), **don't dump 300 lines of markdown into the terminal**. The brief belongs in a file the user can open, search, share, and revisit; the CLI surface is for the decision.
+
+1. **Write the markdown to `BUILD-BRIEF.md`** in the repo root (or `.ritual/BUILD-BRIEF.md` if the repo prefers tooling artifacts out of the top level — check `.gitignore` first). Prepend a Ritual attribution header before writing:
+
+   ```markdown
+   <!--
+   Generated by Ritual
+   Exploration: https://dev.ritualapp.cloud/e/{exploration_id}
+   Build brief id: {brief_id}
+   Do not remove this header; it preserves implementation lineage.
+   -->
+   ```
+
+   If a `BUILD-BRIEF.md` already exists:
+   - **Same exploration** (recommendationsHash matches the cached row): silent overwrite + one-line note in the summary that you refreshed it.
+   - **Different exploration**: surface a confirm: *"A `BUILD-BRIEF.md` already exists from exploration `{previous_exploration_name}`. Overwrite with brief for `{this_exploration_name}`? (y/N, or save-to-`BUILD-BRIEF-{slug}.md`)"*. (CLI Tenet #11 — confirm before destructive.)
+
+2. **Print a compact CLI summary** — the top-of-mind information plus a single line pointing at the file:
+
+   ```
+   ✓ Build brief ready — {exploration_name} ({N} recs accepted, {M} requirements)
+     BUILD-BRIEF.md ({line_count} lines, {file_kb_size} KB)
+
+   Goal: {first line of Goal section, ≤ 100 chars}
+
+   Top review-blockers (must address):
+     RB-001 — {RB-001 title} → {one-line "what's required"}
+     RB-002 — {RB-002 title} → {one-line "what's required"}
+     RB-003 — {RB-003 title} → {one-line "what's required"}
+
+   Top codebase anchors:
+     {path1} — {pattern to extend, ≤ 60 chars}
+     {path2} — {pattern to extend, ≤ 60 chars}
+     {path3} — {pattern to extend, ≤ 60 chars}
+
+   {ONLY IF Previously Deferred section is non-empty:}
+   ⚠ {N} previously-deferred item{s} overlap this scope — see "Previously Deferred" section in BUILD-BRIEF.md
+   ```
+
+   Rules for the summary (CLI Tenets #3, #6):
+   - **Cap RBs and anchors at top 3 each.** Engineers don't read 12-row tables in terminals.
+   - **Omit any section that's empty.** No "Previously Deferred: none" lines — just don't render that line.
+   - If `kgContextUsed.implementationCount > 0`, append one line above the goal: *"Grounded in {N} prior implementation{s}: {top match name}, …"* (CLI Tenet #4 — cite the specific signal).
+
+3. **Offer to open the file** (CLI Tenet #10 — OS-aware affordances, available not mandatory):
+
+   ```bash
+   # Detect, in order: VS Code on PATH, JetBrains `idea` on PATH, $EDITOR set, macOS `open` available.
+   command -v code >/dev/null && code BUILD-BRIEF.md
+   command -v idea >/dev/null && idea BUILD-BRIEF.md
+   [ -n "$EDITOR" ] && "$EDITOR" BUILD-BRIEF.md
+   command -v open >/dev/null && open BUILD-BRIEF.md   # macOS
+   ```
+
+   If any of these are detectable, offer: *"Open `BUILD-BRIEF.md` in your editor? (y/N)"* — single yes/no, never a 4-way picker. If none are detectable, omit the offer entirely; the path is still clickable in most terminals.
+
+##### 10d — Confirm and proceed (CLI Tenet #2, #12)
+
+End Step 10 with a single recommended action plus a cheap escape hatch — never a 3-way option bloom.
+
+> Open `BUILD-BRIEF.md` and skim the RBs + anchors. **Ready to implement?** (y / refine the brief / drill into one item)
+
+Branch by user response:
+
+- **y / proceed / yes**: continue to Step 11.
+- **refine**: ask what's off, then call `generate_build_brief` with `force: true` after applying their feedback to the exploration (typically a recommendation re-accept or a requirement adjustment via the web UI).
+- **drill into X**: open the specific section in the markdown, discuss inline, then loop back to "Ready to implement?".
+
+**Pulse (Step 10 done):** Emit a pulse — this often crosses into **Implementation-ready** (90%+). Render full when that crossing happens — *"safe to code"* is the celebration line. If still below 90% (e.g. brief flagged residual debt), surface that in the pulse line itself and propose addressing it before coding.
+
+#### Step 11 — Implement
+
+This step happens **inside** the same `/ritual build` chat if the agent is also the coding agent (Claude Code / Cursor / etc.), or hand-off if the user is implementing themselves.
+
+##### 11.0 — Branch strategy (CLI Tenet #13)
+
+**Never commit to `main` / `master` from an agent workflow.** Before writing a single line of code:
+
+1. Check for uncommitted user work:
+   ```bash
+   git status --porcelain
+   ```
+   If there are unrelated user changes, pause before editing and ask whether to keep working on this branch, stash, or abort. Do not overwrite or mix with user work silently.
+
+2. Check the current branch:
+   ```bash
+   git branch --show-current
+   ```
+
+3. If on `main` / `master` / `trunk` / `develop` (or any branch named in the repo's default-branch protections): **create a feature branch FIRST.** Do not ask whether to commit to trunk. Branch creation is free and reversible. Naming heuristic:
+   - `feat/<exploration-slug>` when the slug is short (≤ 4 words)
+   - `ritual/<exploration-short-id>` as a fallback (e.g. `ritual/exp-7a2b9c`)
+   - If the user already named one in chat ("call it `feat/conversions-tracking`"), use that.
+
+   User-visible:
+
+   > Created branch `{branch}` for this Ritual implementation.
+   > Override with `branch: <name>` before implementation begins.
+
+4. If already on a feature branch and the working tree is clean or only contains this flow's changes: stay there. Don't switch.
+
+**Never offer "commit to `main` directly" as an option in any user prompt.**
+
+##### 11.1 — Implement
+
+1. Take the build brief as input.
+2. Use the standard coding-loop tools (Edit/Write/Bash/etc.) to make the code change.
+3. Run tests, lint, build per the repo's conventions.
+4. Track each architectural decision as you go — the input to Step 12's `sync_implementation` call. Per decision, write down: `area`, `choice`, `alternatives_considered`, `rationale`, `source_recommendation_id` (the RB-N or recommendation id the decision implements). This is what makes lineage queryable later — don't skip it.
+
+##### 11.2 — Commit (CLI Tenet #14 — Ritual attribution)
+
+Commit on the feature branch from 11.0. One-or-many commits is fine; conventional-commit prefixes preferred (`feat:`, `fix:`, `test:`, etc.). Include a Ritual footer on the FINAL commit of the implementation so the trace from code → exploration is visible in `git log`:
+
+```
+feat(<area>): <one-line headline>
+
+<short body — what changed, why, key trade-off>
+
+Ritual-Exploration: <exploration_id>
+Ritual-Exploration-Url: https://dev.ritualapp.cloud/e/<exploration_id>
+Ritual-RBs-Satisfied: RB-1, RB-2, RB-7
+```
+
+Intermediate commits can skip the footer. The final commit IS the linkage anchor.
+
+##### 11.3 — Post-implementation summary (CLI Tenet #1 — files for detail, CLI for decisions)
+
+**Don't dump a per-file changelog into the chat.** The full diff lives in `git diff <branch>..HEAD` and the eventual PR body. The CLI summary should be **≤ 8 lines** and surface only what's load-bearing for the user's next decision:
+
+```
+✓ Implementation done — {exploration name}
+  Branch: {branch}, {N} commits, {M} files changed
+  Tests: {tests_added} added, all passing
+  RBs satisfied: {comma-joined list of RB-N from the brief, ALL or a count}
+  Open deferrals logged for Step 12: {count}
+
+Next: push + open PR? (y / show me what changed / abort)
+```
+
+If the user picks "show me what changed", THEN run `git diff --stat HEAD~N..HEAD` or open per-file diffs interactively — on request, not by default.
+
+##### 11.4 — Push + PR (single recommended action)
+
+If the user says "y" / "push" / "open PR":
+
+1. `git push -u origin <branch>` (single command, no `--force` ever in this flow).
+2. Build the PR body from the template below (CLI Tenet #14).
+3. `gh pr create --base <default-branch> --title <…> --body <…>`.
+4. Surface the PR URL to the user.
+
+**PR body template:**
+
+```markdown
+## Summary
+
+<2-3 lines max, derived from the build brief's Goal section>
+
+## RBs satisfied
+
+| RB | Title | Where |
+|---|---|---|
+| RB-1 | <title from brief> | <key file/module> |
+| RB-2 | <title from brief> | <…> |
+| … | | |
+
+## Test plan
+
+- <one bullet per test file / suite added>
+- <coverage notes if non-trivial>
+
+## Exploration
+
+- Exploration: [<exploration name>](https://dev.ritualapp.cloud/e/<exploration_id>)
+- Build brief: see `BUILD-BRIEF.md` (committed in this PR for reviewer reference)
+- Deferrals intentionally punted: <count, with one-line each>
+
+---
+
+🪷 Generated via [Ritual](https://ritual.work) — closing the loop with `sync_implementation` after merge.
+```
+
+If the user is implementing manually: hand off the brief + the branch-strategy note ("create a feature branch off `main` — don't commit to trunk"), tell them you'll be ready to run `sync_implementation` when they're done.
+
+#### Step 12 — Close the loop with `sync_implementation`
+
+##### 12.0 — What this step does (in product terms)
+
+Before asking for permission, frame the call in language the user can act on. `sync_implementation` is not just an API call — it's the moment the workspace's knowledge graph absorbs what you just shipped. From the user's POV:
+
+> I'm about to log this implementation into the workspace's knowledge graph. After this:
+> - The exploration's state flips to ✓ done (or ⚠ implemented-ahead if any recs weren't approved when shipped).
+> - The {N} architectural decisions you made get linked back to the recommendations that motivated them — so future `/ritual build` calls touching `{first 2 files}` will see your decisions as priorContext.
+> - The {M} open deferrals you intentionally punted get logged with their reasons — peers can see them in `/ritual lineage` on these files later.
+>
+> **OK to log? (y / hold off / let me adjust the decision list first)**
+
+This framing replaces "I need to call sync_implementation, OK?" — which is jargon. The user should know what they're approving in product terms (CLI Tenet #4 — cite the specific signal).
+
+##### 12.1 — Make the call
+
+Call `mcp__ritual__sync_implementation` with:
+- `workspace_id`, `exploration_id`
+- `repo`, `branch`, `pr_url`, `pr_number`, `pr_status`
+- `commits[]` — each with `sha`, `message`, `timestamp`, `files_changed`
+- `decisions[]` — each with `area`, `choice`, `alternatives_considered[]`, `rationale`, optionally `source_recommendation_id` (anchor each decision to the rec it implements when possible — this is what enables future "shipped X to satisfy rec Y" queries)
+- `deferrals[]` — for things you intentionally punted (`rb_id`, `description`, `reason`, `severity`, `related_files[]`, `related_modules[]`)
+- `gate_verdict`, `adherence_rate` — your own self-reported quality signals
+
+The A1.5 snapshot column auto-captures each linked recommendation's status at the moment of sync — so if you implemented while the rec was still `draft` (Branch B in Step 9), the timeline is preserved automatically.
+
+When sync_implementation succeeds, the response includes:
+
+- `decisions: [{ decisionId, area, choice, recommendationStatusAtImplementation }, ...]` — IDs of every architectural decision logged + the rec-status snapshot (A1.5)
+- `deferrals: [{ deferralId, rbId, severity }, ...]` — IDs of every deferral
+- `decisionsCount`, `deferralsCount` — totals for the summary line
+- `webUrl` — clickable link to the exploration's implementation record in the web UI
+
+**Surface ALL of this to the user**, not just "ok logged." This is the visible signal that the loop closed. Format:
+
+> ✓ Logged implementation for **{exploration name}**
+>   - {decisionsCount} decision{s} registered: {first 2 decisions, e.g. "auth: OAuth not SAML; data-model: tenant-scoped indexes"}
+>   - {deferralsCount} deferral{s} registered: {first 1, e.g. "[major] Rate-limit per-tenant — out of scope for v1"}
+>   - View: {webUrl}
+>
+> Future `/ritual build` calls touching `{first 2 of filesChanged}` will now see this implementation in their priorContext block.
+
+If any decision's `recommendationStatusAtImplementation` is NOT `approved` (i.e. the Branch B path), add a callout:
+
+> ⚠ {M} decision{s} implemented while their source recommendation was still in **{status}** — the exploration now shows `implemented_ahead`. An admin should review + accept the recs to close the gap.
+
+The closing sentence is the most important one: it tells the user **what just happened in the system** in product-level terms. Without it, sync_implementation feels like a write-only black hole. With it, the user understands they just contributed to the workspace's memory.
+
+**If `sync_implementation` fails:** do not drop the structured implementation data. Write the intended payload to `.ritual/pending-sync/<exploration-id>.json` and tell the user exactly what was not logged.
+
+User-visible:
+
+> `sync_implementation` failed: {error summary}
+> Saved the intended sync payload to `.ritual/pending-sync/<exploration-id>.json`.
+> Retry later with the same payload; no implementation decisions were lost.
+
+Create `.ritual/pending-sync/` if needed. Keep the pending-sync file git-tracked unless the repo has a different convention for generated workflow state.
+
+#### Step 13 — Optional follow-up
+
+If they want to check the state at any time, point them at:
+
+> `ritual graph status` (in their CLI) — shows the workspace's current KG counts + recent implementations.
+
+Or: re-run `/ritual build` in this workspace later — the existing-work check will surface this exploration with its new `done` state badge, and any future build whose `sources` overlap will pull in the decisions + deferrals you just logged as priorContext.
+
+### Failure modes & recovery
+
+**Discovery generation hangs (>5 min polling without `ready: true`)**: ask the user — wait longer? retry (`suggest_discovery_questions` again, new task)? or skip discovery entirely (proceed to Step 8 without picked questions)?
+
+**Agentic run fails or stalls**: surface the error, offer retry or stop.
+
+**Discovery state ready=true with zero matters**: rare but possible if the LLM produced a malformed state. Retry by calling `suggest_discovery_questions` again.
+
+**LLM-cost / quota errors (HTTP 429)**: tell the user explicitly. Do NOT auto-retry — quota issues need a human decision (different model tier, wait, top up).
+
+### Tools used
+
+This subcommand exclusively uses vNext MCP tools, in the order they appear:
+
+1. `mcp__ritual__list_workspaces` (Step 1)
+2. `mcp__ritual__create_workspace` (Step 1, only if no workspace exists)
+3. `mcp__ritual__list_explorations` (Step 1.5 — resume vs start, with state badges)
+4. `mcp__ritual__suggest_high_leverage_problems` (Step 1.5 step 6b — option 3, "help me find the highest-leverage thing")
+5. `mcp__ritual__check_exploration_overlap` (Step 1.5 step 8 — pre-creation overlap detection before "start fresh")
+6. `mcp__ritual__list_templates` (Step 2)
+7. `mcp__ritual__generate_considerations` (Step 4)
+8. `mcp__ritual__refine_considerations` (Step 4.2, iteration only)
+9. `mcp__ritual__generate_problem_statement` (Step 5)
+10. `mcp__ritual__refine_problem_statement` (Step 5.2, iteration only)
+11. `mcp__ritual__create_exploration` (Step 6)
+12. `mcp__ritual__fork_sibling_explorations` (Step 6.5 — optional only when the user explicitly asks to save separate sibling tracks)
+13. `mcp__ritual__suggest_discovery_questions` (Step 7.1)
+14. `mcp__ritual__get_discovery_state` (Step 7.2)
+15. `mcp__ritual__accept_discovery_questions` (Step 7.4)
+16. `mcp__ritual__set_anti_goals` (Step 7.5, optional)
+17. `mcp__ritual__start_agentic_run` (Step 8 — accepts `stop_after='answers'` for PRD/product flows)
+18. `mcp__ritual__get_agentic_run` (Step 8 / Step 8.5 polling)
+19. `mcp__ritual__cancel_agentic_run` (Step 8, only on user abort)
+20. `mcp__ritual__resume_agentic_run` (Step 8.5, only when stop_after='answers' was used)
+20a. `mcp__ritual__get_answer_state` (Step 8.5 per-question read)
+20b. `mcp__ritual__iterate_answer` (Step 8.5 — user picked "iterate")
+20c. `mcp__ritual__submit_answer` (Step 8.5 — user picked "submit")
+21. `mcp__ritual__get_recommendations` (Step 9)
+22. `mcp__ritual__accept_recommendations` (Step 9, admin branch only — fires requirement gen fire-and-forget)
+23. `mcp__ritual__get_requirement_set_status` (Step 9.5 polling)
+24. `mcp__ritual__generate_build_brief` (Step 10a)
+24a. `mcp__ritual__get_build_brief_status` (Step 10b — timeout-recovery polling, OR proactive cache-hit check before 10a)
+24b. `mcp__ritual__add_knowledge_source` (Step 3.5 — register PRDs / tickets / transcripts / etc. provided by the user)
+24c. `mcp__ritual__list_knowledge_sources` (used inline by Step 3.5 to show already-attached refs on resume; also called by `/ritual context-pulse` CP2 for Reference Grounding count)
+25. `mcp__ritual__sync_implementation` (Step 12)
+
+31 of the 40 vNext tools. The other 9 (`ping`, `get_exploration`, `list_agentic_runs`, `add_collaborator`, `check_anti_goals`, `query_knowledge_graph`, `get_workspace_overview`, `get_knowledge_source`, `remove_knowledge_source`) are situational, not part of the linear build flow.
+
+### After this subcommand
+
+When `/ritual build` completes, the exploration is in COMPLETE state with accepted recommendations AND a build brief has been generated AND (if the agent implemented in-chat) `sync_implementation` has been called. The full close-the-loop cycle now lives inside this skill — there's no separate downstream `/ritual-builder-spec` step required.
+
+Variants:
+- Admin runs the whole flow: Steps 1 → 13, no handoff.
+- Collaborator runs the build flow: Steps 1 → 13 with Step 9 Branch B (no admin acceptance available); the resulting exploration shows `⚠ implemented_ahead` until an admin reconciles.
+- Resume mid-flow: the existing-work check surfaces explorations with state badges and jumps directly to the right phase. (Or, for the "I just want to pick up" intent, see `/ritual resume` below.)
+
+---