@ritualai/cli 0.9.6 → 0.11.0

package/skills/vscode/ritual/references/build-flow.md

@@ -85,6 +85,26 @@ Pausing discipline is still load-bearing — every `[USER PAUSE]` later in the f
 
 The table is here so future contributors understand WHY the heads-up mentions Claude Code's Shift+Tab specifically — that's the dominant target client. If we add an elicitation-based picker (see `documents/architecture/selection-cursor-pattern.md` §"Future — MCP elicitation"), the auto-mode concern reduces further because elicitation form-mode requires actual user input regardless of agent mode.
 
+##### Step 0.1 — Parse build-mode flags (load-bearing for Step 9.6, future Audit 2/3 gates)
+
+Per `documents/architecture/audit-suite.md` § 7a, `/ritual build` accepts three audit-mode levels:
+
+```text
+/ritual build <problem>                  → auditMode = 'normal'    (today's behavior, default proceed)
+/ritual build --audited <problem>        → auditMode = 'audited'   (recommend at each gate)
+/ritual build --audit=strict <problem>   → auditMode = 'strict'    (auto-run with 90s/chain time budget)
+```
+
+Aliases the SKILL accepts (for agent-friendly UX):
+- `--audit` (no-equals form, treated identically to `--audited`)
+- `audited` (bareword form, agent-friendly when users type conversationally)
+
+At Step 0 (or whenever the agent first parses the user's `/ritual build` invocation), extract the audit-mode flag and store as `auditMode` in working memory. Default to `'normal'` if no flag present. The audit gate at Step 9.6 (and future Audits 2/3 at Steps 10b.5 + 11.1, ships in PRs B/C) read this variable to choose between three prompt styles.
+
+If the user types `always audit for this build` mid-flow at the Step 9.6 prompt, upgrade `auditMode` from `'normal'` or `'audited'` → `'strict'` for any remaining audit gates in the same session. The upgrade is session-scoped (doesn't persist across `/ritual build` invocations).
+
+Persist `auditMode` to `Exploration.metadata.auditMode` at `create_exploration` time (additive JSONB key — no schema migration) so `/ritual resume <exploration-id>` picks up the same mode the original build started with, and `/ritual lineage <exploration-id>` can render which gates ran + their outcomes.
+
 #### Step 1 — Pick a workspace
 
 Resolution order:
@@ -872,7 +892,7 @@ The user can always come back later with `/ritual context-pulse <exploration>` t
 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)
+- `template_id` — **OPTIONAL.** Per Step 2 (server-side template resolution), the agent does NOT pick a template_id. Omit this field unless the user explicitly passed `--template-id` on the CLI; the server resolves the right template from `user.persona` → `workspace.defaultTemplateId` → system default and uses the same resolution chain `create_exploration` will use at Step 6. Passing it explicitly only matters when overriding the default.
 - `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.
@@ -919,7 +939,8 @@ Only the title line gets the number. Put a blank line between candidates. Do not
 The user may, at the Step 5 problem-statement gate, say something like "rethink the sub-problems" or "the framing is off — show me other angles." When that happens, call `mcp__ritual__refine_considerations` and re-render the sub-problem set + a fresh problem statement. In the default flow this path is unreachable; it exists for the explicit "rethink scope" escape hatch.
 
 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.
+- `workspace_id`, `raw_input`, `sources` — unchanged from the generate call. Critical: pass the SAME `sources` array each iteration so the KG-injected priorContext stays consistent.
+- `template_id` — same rule as Step 4: omit unless the user explicitly overrode it. If you passed `template_id` to the original `generate_considerations` call, pass the same value here for symmetry; otherwise leave it off and let server-side resolution stay consistent across iterations.
 - `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
@@ -939,7 +960,7 @@ 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)
+- `template_id` — OPTIONAL, same rule as Step 4. Omit unless the user explicitly overrode; server resolution stays consistent across `generate_considerations` → `generate_problem_statement` → `create_exploration`.
 - `sources` (the same file-path list passed to generate_considerations — keeps the KG anchor consistent)
 
 Returns a candidate problem statement plus optional follow-up questions and quality scores. For engineering / agentic-coding templates, translate the returned statement into a developer-oriented **problem frame** before showing it. Do not default to "How might we…" unless the selected template is product/design oriented or the user asks for HMW phrasing.
@@ -986,7 +1007,8 @@ Rules:
 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.)
+- `workspace_id`, `raw_input`, `considerations`, `sources` — unchanged. (Same `sources` as the original generate call — keeps the KG anchor stable.)
+- `template_id` — same rule as Step 4 / Step 5.1: omit unless the user explicitly overrode; if you passed it to the original `generate_problem_statement` call, pass the same value here for symmetry.
 - `previous_problem_statement`: the FULL TEXT of the current best draft
 - `change_prompt`: the user's request verbatim
 - `version`: optional telemetry only; do not show version labels to the user
@@ -1016,7 +1038,7 @@ Call `mcp__ritual__create_exploration` with:
 - `workspace_id`
 - `name`
 - `problem_statement` (the scope from Step 5)
-- `template_id` — **REQUIRED.** Pass the same `template_id` used in Steps 4 and 5 (the one established in Step 2 from `personaSlug` / `defaultTemplateId` / picker). The exploration must carry this forward so downstream `start_agentic_run`, `get_recommendations`, and `generate_build_brief` load the right template-specific anti-patterns + focus keywords into the LLM prompts. Skipping `template_id` here silently falls back to the API default, which produces generic recs that don't match the persona's scope contract — the symptom is brief sections that don't align with what the user was promised at Step 2 ("For this feature, we'll work through: scope · non-goals · requirements …"). Always include it; the MCP tool accepts it (see `apps/mcp/src/mcp/tools/create-exploration.tool.ts:78`).
+- `template_id` — **OPTIONAL.** Per Step 2, omit by default. The server resolves from `explicit dto.templateId → workspace.defaultTemplateId → user.persona → first SYSTEM template`, then forks the resolved template into a per-exploration Template row atomically inside this same `create_exploration` request. Pass `template_id` ONLY when the user explicitly overrides on the CLI (`/ritual build --template-id <id>`). If you passed `template_id` to Step 4's `generate_considerations`, pass the same value here so the LLM prompt context the considerations were generated under matches the exploration's stamped template. Do NOT read `.ritual/config.json` or invent a `template_id` from persona — the server does the resolution.
 - `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`. Move the progress header from Scope to Discovery:
@@ -1048,6 +1070,33 @@ This keeps the repo root clean (CLI Tenet #1 — files for reference, not clutte
 
 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.
 
+##### 6.2 — Register staged knowledge sources (load-bearing)
+
+If Step 3.5 staged any knowledge sources in working memory (PRDs / tickets / transcripts / etc.), register them NOW that `exploration_id` exists. The staging step deliberately deferred the MCP call because `add_knowledge_source` requires an exploration to attach to — this is where the deferral resolves.
+
+For each staged record from § 3.5.3, call `mcp__ritual__add_knowledge_source` with:
+
+- `exploration_id` (from Step 6)
+- `source_content_type` (from the staged record)
+- `content` (the full text the agent obtained)
+- `title` (from the staged record)
+- `source_url` / `source_path` (whichever applies, optional)
+- `origin_feature: 'DISCOVERY'`
+
+Fire these in parallel — they're independent inserts + async extraction kickoffs. Cap concurrency at 5 if the user staged more than that (rare).
+
+Surface a single compact summary after all registrations resolve:
+
+> Attached {N} knowledge source{s} to the exploration: {comma-separated titles, truncated to 80 chars total}. Extraction running in the background.
+
+**Failure handling:** if any `add_knowledge_source` call fails (network / 4xx / 5xx), retry once. On a second failure, surface a one-line note and continue — do NOT block the build flow on a knowledge-source registration failure:
+
+> ⚠ Couldn't register `{title}` ({error in 1 sentence}). The exploration is still usable; you can re-add the ref later with `/ritual context-pulse <exploration> --add-ref {path}`.
+
+**Skip path:** if Step 3.5 was skipped (user said "skip" / "none" / "later"), there are no staged records and this step is a silent no-op. Do NOT prompt the user again — they already declined at Step 3.5.
+
+**Why this lives at 6.2, not inside `create_exploration`:** sources are deliberately decoupled from the exploration row so a partial source-registration failure doesn't block exploration creation. Step 6 must always succeed if the underlying validation passes; Step 6.2 is best-effort on top.
+
 #### 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.
@@ -1969,7 +2018,176 @@ Steps:
 
 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.
+5. When `status === 'READY'`, tell the user one line ("Requirements ready…") and continue to Step 9.6 (if anti-goals exist) OR directly to Step 10 (if no anti-goals, audit step is skipped silently).
+
+#### Step 9.6 — Audit the recommendations + requirements against declared anti-goals (load-bearing — audit-repair loop)
+
+Run a constraint-survival audit on the typed Recommendation + Requirement substrate BEFORE brief generation. The audit answers the question: *"Did the anti-goal directives the user declared actually constrain the recs+reqs, or are they decorative?"* — the R4 operator (constraint-perturbation) applied to the (anti-goals, recs+reqs, R4) triple per the audit-triple-framing rule.
+
+**Why this is load-bearing**: an inert anti-goal — declared but not actually constraining anything in the recs+reqs — propagates downstream as an unconstrained brief. By Step 11 (implementation) it's too late; the agent codes against a substrate whose forbidden states were never enforced. The audit catches inert directives at the upstream typed substrate where the fix is cheap (rec content edit), not at the brief markdown where the fix is expensive (full regen).
+
+**Skip condition**: if the exploration has zero anti-goals (`set_anti_goals` was never called OR all anti-goals are `confidence < 0.4`) OR no APPROVED recommendations exist OR the latest RequirementSet isn't READY, skip this step silently and continue to Step 10. The audit tool returns 404 in any of those cases; check the substrate state first if unsure.
+
+**Build modes** (per `documents/architecture/audit-suite.md` § 7a) — the gate prompt below renders differently depending on which mode flag the user invoked:
+
+| Mode | Prompt behavior | Default on enter |
+|---|---|---|
+| bare `/ritual build` | Compact opt-in: "Reply `audit` or `proceed`" | `proceed` |
+| `/ritual build --audited` | Elevated: "Recommended: run constraint-survival audit. Reply `audit`, `proceed`, or `always audit for this build`" | Awaits user input (no implicit default) |
+| `/ritual build --audit=strict` | Audit auto-runs; user sees results + repair menu, not the gate prompt | N/A (no gate prompt rendered) |
+
+`auditMode` is read from working memory (set at Step 0 from the user's invocation flags). Mid-flow, `always audit for this build` upgrades the session to `--audit=strict` behavior for any remaining audit gates (Audit 2 at Step 10b.5, Audit 3 at Step 11.1 — both PR B/C).
+
+**Strict mode time budget**: each audit chain runs up to 3 iterations of verifier calls (~5-15s per iteration × 3 = ~15-45s typical). Hard wall-clock cap of 90s per chain — on timeout, the gate degrades to `--audited` behavior (surface findings, let user decide rather than block the build).
+
+### Step 9.6.1 — Render the gate prompt (mode-aware)
+
+**For `bare` mode:**
+
+```text
+Recommendations + requirements are ready. Optional constraint-survival audit available.
+
+Reply `audit` to run, or `proceed` to skip to brief generation.
+```
+
+**For `--audited` mode:**
+
+```text
+Recommendations + requirements are ready.
+
+Recommended: run constraint-survival audit before brief generation.
+This checks whether anti-goals survived into the recs + requirements.
+
+Reply `audit`, `proceed`, or `always audit for this build`.
+```
+
+**For `--audit=strict` mode:** SKIP the prompt; jump directly to Step 9.6.2 (run the audit).
+
+### Step 9.6.2 — Run the audit (when chosen or in strict mode)
+
+Render:
+
+```text
+Auditing recs + requirements against {N} declared anti-goal{s}…
+```
+
+Call `mcp__ritual__audit_recommendations({ exploration_id })` with the default config (threshold mode, 80% acceptance threshold, max 3 iterations). The response shape:
+
+```json
+{
+  "chain_id": "ac-...",
+  "audit_status": "ok" | "needs_attention" | "blocked",
+  "iteration": 1,
+  "findings": [
+    {
+      "repair_id": "ri-...",
+      "after_audit_id": "...",
+      "severity": "blocker" | "high" | "medium" | "low",
+      "directive_text": "Audit log must be append-only.",
+      "status": "inert" | "omitted" | "weakened" | "contradicted",
+      "gap_kind": "global_inert" | "local_gap" | "weak_coupling" | "contradiction",
+      "affected_entities": [{"entity_type": "recommendation", "entity_id": "..."}],
+      "message": "Anti-goal #2 is referenced but not by the entity it most-applies-to — ...",
+      "auto_dispatchable": true | false
+    }
+  ],
+  "summary": {
+    "total_constraints": 7,
+    "survival_rate_percent": 57,
+    "by_severity": { "blocker": 1, "high": 0, "medium": 2, "low": 0 },
+    "by_gap_kind": { "global_inert": 1, "local_gap": 2, "weak_coupling": 0, "contradiction": 0 }
+  },
+  "decision_reason": "...",
+  "attestation_digest": "sha256:...",
+  "next_step_hint": "..."
+}
+```
+
+### Step 9.6.3 — Render the findings + repair-action menu
+
+Render based on `audit_status`:
+
+**`audit_status: "ok"`** — survival rate met threshold AND no blockers. Render one line and proceed silently to Step 10:
+
+```text
+✓ Audit passed: {survival_rate_percent}% of {total_constraints} anti-goals preserved. Chain accepted.
+```
+
+**`audit_status: "needs_attention"` or `"blocked"`** — surface the findings inline so the user sees them before deciding:
+
+```text
+⚠ Audit — {iteration} of {max_iterations} — {audit_status}
+
+  {survival_rate_percent}% of {total_constraints} anti-goals preserved.
+  Findings ({findings.length} total):
+    {for each finding, severity-prefixed (⛔ blocker / ⚠ high / · medium / · low):}
+    {severity_glyph} {repair_id} — {directive_text}
+       status: {status} · gap: {gap_kind} · affects: {affected_entities.length} entit{ies/y}
+       {message[:120]}…
+
+Reply:
+  · `resolve all`              — apply all auto-dispatchable repairs, re-audit
+                                  (recommended — your config has blocker findings
+                                   set to always_resolve)
+  · `resolve {repair_id}`      — apply a single repair (good for inspection)
+  · `waive {repair_id}: <reason>`
+                                — record explicit acceptance of one finding;
+                                  document the gap and continue
+  · `accept`                   — accept current substrate, document all remaining
+                                  findings as gaps (BLOCKED while any
+                                  blocker-severity finding remains; the chain
+                                  config enforces this)
+  · `show chain`               — render the full audit chain trail
+                                  (calls get_audit_chain)
+  · `pause`                    — stop here; resume via /ritual resume
+```
+
+**On `resolve all`** — for each `auto_dispatchable: true` finding, call `mcp__ritual__apply_repair({ repair_id, chain_id, after_audit_id })`. Each call returns:
+
+```json
+{
+  "action_id": "ra-...",
+  "action": "apply",
+  "status": "applied",
+  "next_iteration_id": "...",
+  "hint": "Re-audit ran (SurvivalReport ...). Call get_audit_chain with chain_id=... to see the updated trail and whether the chain accepted."
+}
+```
+
+Apply-repair is sequential per finding; the server runs the next audit iteration inline after each successful apply, so just call them in order. After the last `auto_dispatchable: true` finding, call `mcp__ritual__get_audit_chain({ chain_id })` to fetch the final state and re-render the loop UX with the new survival rate. If `chain_status === 'accepted'` after this round, proceed to Step 10; otherwise re-render the findings (the chain may have iterated and produced new findings the next iteration surfaces).
+
+**On `resolve {repair_id}`** — single-finding apply. Same dispatch shape; render the next iteration's findings on completion.
+
+**On `waive {repair_id}: <reason>`** — `apply_repair({ repair_id, chain_id, after_audit_id, action: 'waive', waive_reason: '<reason>' })`. No re-audit; render confirmation + return to the loop UX.
+
+**On `accept`** — only allowed when no `blocker`-severity findings remain (the L1 tool returns `audit_status: "blocked"` while they do). Surface a single confirm: *"Accepting substrate with {findings.length} documented gap(s). Proceed?"* On yes, proceed to Step 10. The audit chain's final state is recorded; future `/ritual lineage` on this exploration surfaces the chain trail + the gaps the user explicitly accepted.
+
+**On `show chain`** — render the full trail (iterations + repairs + status) from `get_audit_chain`. Keep it compact: one line per iteration + one line per repair. Then re-render the loop UX so the user can pick their next action.
+
+**On `pause`** — stop here. Chain stays `in_progress`; resume via `/ritual resume`.
+
+**On `halt_unresolvable`** (chain reached `max_iterations` with unresolved must-resolve findings) — the L1 tool returns `audit_status: "blocked"` and the chain is terminated. Surface:
+
+```text
+⛔ Audit halted after {max_iterations} iterations — {n_blockers} blocker(s) unresolved.
+
+The repair loop didn't converge. Options:
+  · `extend max-iterations <N>`  — re-run the audit with a higher cap (creates a new chain)
+  · `force accept`               — proceed to Step 10 with the substrate as-is; remaining
+                                   blockers are recorded on the chain trail but no longer
+                                   gate the build flow
+  · `pause`                      — stop here for human review
+```
+
+**Special: contradiction-class findings** — when a finding has `gap_kind: "contradiction"`, it surfaces as `auto_dispatchable: false`. The repair (`replace_recommendation`) IS implemented and CAN be applied via `apply_repair {repair_id}`, but `resolve all` skips it because replacing a rec is a structural change worth explicit user consent. The SKILL should render contradiction findings with an explicit "needs review" prefix:
+
+```text
+⛔ {repair_id} — CONTRADICTION — {directive_text}
+   A rec actively violates this directive. `replace_recommendation` will regenerate the rec
+   under the constraint. Confirm by replying `resolve {repair_id}` explicitly.
+```
+
+**Verifier-generator separation**: the audit's verifier model is automatically resolved by the server to a different family than whichever model generated the recs — agents don't need to manage this; it's enforced at the API. The audit's attestation digest records both model ids for post-hoc auditability.
 
 #### Step 10 — Generate the build brief
 
@@ -2660,7 +2878,7 @@ This subcommand exclusively uses Ritual MCP tools, in the order they appear:
 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")
 5a. `mcp__ritual__archive_exploration` (Step 1.5 step 6a — soft-delete a duplicate/misfire when user picks `delete N` from the resume menu)
-6. `mcp__ritual__list_templates` (Step 2)
+6. ~~`mcp__ritual__list_templates`~~ — **REMOVED 2026-05-21 (CLI 0.9.0+).** Step 2 is now server-side template resolution; the tool is no longer registered on the MCP surface. Do not call it. See Step 2 § "Rewritten 2026-05-21" for the rationale.
 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)
@@ -2684,11 +2902,16 @@ This subcommand exclusively uses Ritual MCP tools, in the order they appear:
 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)
 24d. `mcp__ritual__sync_brief_review` (Step 10b.5 — sync `BUILD-BRIEF-VERIFICATION.md` to KG; AND Step 10.5 — sync `UX-REVIEW.md` to KG)
-24b. `mcp__ritual__add_knowledge_source` (Step 3.5 — register PRDs / tickets / transcripts / etc. provided by the user)
+24b. `mcp__ritual__add_knowledge_source` (Step 6.2 — register staged knowledge sources after `create_exploration` returns `exploration_id`; staging happens at Step 3.5)
 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)
+24e. `mcp__ritual__audit_recommendations` (Step 9.6 — start an audit chain on the (anti-goals, typed recs+reqs, R4) triple; cli 0.10.0+)
+24f. `mcp__ritual__apply_repair` (Step 9.6 — apply or waive a structured repair instruction returned by an audit iteration; cli 0.10.0+)
+24g. `mcp__ritual__get_audit_chain` (Step 9.6 — fetch the full chain trail for review/lineage; cli 0.10.0+)
 25. `mcp__ritual__sync_implementation` (Step 12)
 
-33 of the 44 Ritual MCP tools. The other 11 (`ping`, `get_exploration`, `list_agentic_runs`, `add_collaborator`, `check_anti_goals`, `query_knowledge_graph`, `get_workspace_overview`, `get_knowledge_source`, `remove_knowledge_source`, `get_recommendation_attestation`, `score_context_pulse`) are situational, not part of the linear build flow.
+35 of the 46 Ritual MCP tools (cli 0.10.0+: the 3 new audit tools — `audit_recommendations`, `apply_repair`, `get_audit_chain` — joined the linear flow at Step 9.6 (audit-suite.md § Audit 1)). The other 11 (`ping`, `get_exploration`, `list_agentic_runs`, `add_collaborator`, `check_anti_goals`, `query_knowledge_graph`, `get_workspace_overview`, `get_knowledge_source`, `remove_knowledge_source`, `get_recommendation_attestation`, `score_context_pulse`) are situational, not part of the linear build flow.
+
+**Note on `check_anti_goals` vs `audit_recommendations`:** these are distinct tools. `check_anti_goals` is the older, single-shot validation tool (read-tier; one LLM call, no chain rows) used ad-hoc to validate a proposal against an exploration's current anti-goal set. `audit_recommendations` (cli 0.10.0+, write-tier) starts a stateful `AuditChain` that runs R4 (constraint-perturbation) against a brief, produces structured `SurvivalReport` + `RepairInstruction` rows, and supports the apply/waive repair loop. Use `check_anti_goals` for one-shot proposal validation; use `audit_recommendations` for chain-tracked constraint-survival audits of a brief.
 
 ### After this subcommand