@rune-kit/rune 2.14.0 → 2.15.0

package/skills/context-engine/references/preview-gate.md

@@ -0,0 +1,139 @@
+# Context Preview Gate
+
+## Purpose
+
+Pre-flight cost check for expensive escalations. Before any caller bundles a large context for dispatch (oracle-mode second-opinion, parallel workstream spawn, multi-file review, cross-pack audit), `context-engine` emits `context.preview` with a token-cost estimate and an action recommendation. The caller decides whether to proceed, warn, or abort.
+
+## Why
+
+Without a preview gate:
+- Callers learn about budget overruns only after dispatch — too late to prune
+- `team` parallel workstreams can blow $20 of Opus tokens silently
+- Users have no way to enforce per-call cost ceilings
+
+With the preview gate:
+- Costs are visible at decision time, not bill time
+- Per-caller thresholds enforce different budgets per use case
+- Hard `block` action prevents accidental runaway
+
+## Token Estimation
+
+```
+estimated_tokens = total_chars × 0.25
+```
+
+Where `total_chars` includes:
+- The bundle's `[SYSTEM]` line
+- The `[USER]` problem statement
+- Every `### File N: <path>` header
+- Every file body (post-truncation, post-redaction)
+
+The `0.25` ratio is calibrated for English code/markdown:
+
+| Content type | Calibration |
+|--------------|-------------|
+| English code (TypeScript/Python/JS) | accurate ±10% |
+| English markdown / docs | accurate ±5% |
+| Japanese / Chinese / Korean | underestimates by 30-50% |
+| Highly-repetitive (lots of imports) | overestimates by 20-30% |
+
+Both error directions are safe:
+- Overestimate → over-cautious block, caller can manually override
+- Underestimate → caller still hits the dispatch-time hard cap (e.g. adversary's 100k token limit) and aborts with `oracle.failed`
+
+## Threshold Defaults
+
+| Caller | warn-at | block-at | Rationale |
+|--------|---------|----------|-----------|
+| `adversary` oracle-mode | 50,000 | 100,000 | Single-shot diagnosis; 100k matches second-model context budget |
+| `team` parallel workstream (per worker) | 30,000 | 80,000 | Per-worker; total may be 5x if 5 workers spawn |
+| `review` multi-file | 40,000 | 100,000 | Code review benefits from breadth; cap protects opus budget |
+| `audit` cross-pack | 60,000 | 120,000 | Audit is intentionally broad; raised cap reflects intent |
+
+### Override
+
+Set environment variables to override per-caller thresholds:
+
+```
+RUNE_CONTEXT_THRESHOLDS_ADVERSARY=warn:60000,block:120000
+RUNE_CONTEXT_THRESHOLDS_TEAM=warn:40000,block:100000
+RUNE_CONTEXT_THRESHOLDS_REVIEW=warn:50000,block:130000
+RUNE_CONTEXT_THRESHOLDS_AUDIT=warn:80000,block:150000
+```
+
+## Action Decision
+
+```
+if estimated_tokens >= block_at:
+    action = "block"
+elif estimated_tokens >= warn_at:
+    action = "warn"
+else:
+    action = "proceed"
+```
+
+## Caller Integration
+
+### `adversary` oracle-mode
+
+```
+Phase 0 (pre-bundle): emit context.preview { caller: adversary, files: [...], prompt: "..." }
+  context-engine returns { action: "proceed" }     → continue with bundle build
+  context-engine returns { action: "warn" }        → log warning, continue
+  context-engine returns { action: "block" }       → abort, emit oracle.failed reason=context_budget_exceeded
+```
+
+### `team` parallel workstream
+
+```
+Phase 2 ASSIGN (per worker): emit context.preview { caller: team, files: [...] }
+  proceed → spawn worker
+  warn    → log warning, spawn worker
+  block   → reduce worker scope or split into 2 smaller workers
+```
+
+### `review` multi-file
+
+```
+Entry step: emit context.preview { caller: review, files: [...] }
+  proceed → run review
+  warn    → log warning, run review
+  block   → ask user to narrow file scope (e.g. specific subdirectory)
+```
+
+### `audit` cross-pack
+
+```
+Entry step: emit context.preview { caller: audit, files: [...] }
+  proceed → run audit
+  warn    → log warning, run audit
+  block   → reduce audit scope (e.g. one pack at a time)
+```
+
+## Signal Payload
+
+```yaml
+context.preview:
+  caller: adversary | team | review | audit
+  estimated_tokens: 73000
+  file_count: 8
+  top_5_files_by_size:
+    - { path: "src/auth/login.ts", chars: 12400 }
+    - { path: "src/middleware/auth.ts", chars: 9800 }
+    - { path: "src/services/session.ts", chars: 8200 }
+    - { path: "tests/auth.test.ts", chars: 6100 }
+    - { path: "src/types/user.ts", chars: 4500 }
+  threshold:
+    warn_at: 50000
+    block_at: 100000
+  action: warn
+```
+
+## Failure Modes
+
+| Symptom | Reason | Mitigation |
+|---------|--------|------------|
+| Caller bundles before preview | Caller didn't follow contract | context-engine rejects late preview requests with explicit error |
+| Estimate way off for non-English content | Tokenizer ratio assumes English | Document limitation; safe both directions due to dispatch-time hard cap |
+| Block action ignored by caller | Caller bug | Each caller's Done When MUST verify `action != block` before dispatch |
+| Threshold env-var malformed | User typo | context-engine logs warning, falls back to default |

package/skills/cook/SKILL.md

@@ -384,6 +384,7 @@ If the coder model needs info from other phases, it's in the Cross-Phase Context
 4. Run tests after each significant change — if fail → debug and fix
    - **Python async** (if async-first flagged): no blocking calls in async functions — `time.sleep` → `asyncio.sleep`, `requests` → `httpx.AsyncClient`, use `asyncio.gather()` for parallel I/O
 5. If stuck → invoke `rune:debug` (max 3 debug↔fix loops). Fixes outside plan scope require user approval (R4).
+   - **Oracle reattach check** — between tasks, glob `.rune/oracle-pending/*.json`. For any record with `status=pending`, invoke `session-bridge --reattach <sessionId>`. If `complete` → consume the response (route to debug/fix per `sourceSkill`). If `pending` → continue with next independent task. If `failed` → continue without second opinion.
 6. **Re-plan check** — evaluate before Phase 5: max debug loops hit? out-of-scope files changed? new dep changes approach? user scope change? If any fire → invoke `rune:plan` with delta context, get user approval before resuming.
 7. **Approach Pivot Gate** — if re-plan ALSO fails:
 

package/skills/db/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: db
-description: Database workflow specialist. Generates migration files with rollback scripts, detects breaking schema changes, and validates query parameterization.
+description: "Database workflow specialist. Generates migration files with rollback scripts, detects breaking schema changes, and validates query parameterization."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: Root cause analysis for bugs and unexpected behavior. Traces errors through code, uses structured reasoning, and hands off to fix when cause is found. Core of the debug↔fix mesh.
+description: "Root cause analysis for bugs and unexpected behavior. Traces errors through code, uses structured reasoning, and hands off to fix when cause is found. Core of the debug↔fix mesh."
 metadata:
   author: runedev
   version: "1.1.0"
@@ -9,7 +9,7 @@ metadata:
   group: development
   tools: "Read, Bash, Glob, Grep"
   emit: bug.diagnosed, agent.stuck
-  listen: tests.failed
+  listen: tests.failed, oracle.response
 ---
 
 # debug
@@ -21,8 +21,9 @@ Root cause analysis ONLY. Debug investigates — it does NOT fix. It traces erro
 <HARD-GATE>
 Do NOT fix the code. Debug investigates only. Any code change is out of scope.
 If root cause cannot be identified after 3 hypothesis cycles:
-- Emit `agent.stuck` signal — `scout` zoom-out mode may surface the broader module map that's hiding the root cause
-- Escalate to `rune:problem-solver` for structured 5-Whys or Fishbone analysis
+- Emit `agent.stuck` signal — `scout` zoom-out mode surfaces broader module map (structural pivot); `adversary` oracle-mode dispatches a stateless second-model pass (semantic pivot); both fire in parallel
+- If `oracle.response` arrives with confidence=high and cites file:line, treat as new hypothesis H_oracle and test directly (skip 3-cycle gate — it's externally validated)
+- Otherwise, escalate to `rune:problem-solver` for structured 5-Whys or Fishbone analysis
 - Or escalate to `rune:sequential-thinking` for multi-variable analysis
 - Report escalation in the Debug Report with all evidence gathered so far
 </HARD-GATE>
@@ -46,6 +47,7 @@ If root cause cannot be identified after 3 hypothesis cycles:
 - `browser-pilot` (L3): capture browser console errors, network failures, visual bugs
 - `sequential-thinking` (L3): multi-variable root cause analysis
 - `neural-memory` (L3): after root cause found — capture error pattern for future recognition
+- `adversary` (L2): on `agent.stuck` — oracle-mode dispatches stateless second-model pass to break confirmation-bias loop (parallel with scout zoom-out)
 
 ## Called By (inbound)
 

package/skills/dependency-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dependency-doctor
-description: Dependency health management. Detects package manager, checks outdated packages and vulnerabilities, and produces a prioritized update plan.
+description: "Dependency health management. Detects package manager, checks outdated packages and vulnerabilities, and produces a prioritized update plan."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-description: Design system reasoning. Maps product domain to style, palette, typography, and platform-specific patterns. Generates .rune/design-system.md as the shared design contract for all UI-generating skills.
+description: "Design system reasoning. Maps product domain to style, palette, typography, and platform-specific patterns. Generates .rune/design-system.md as the shared design contract for all UI-generating skills."
 metadata:
   author: runedev
   version: "0.5.0"

package/skills/doc-processor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doc-processor
-description: Generate and parse office documents — PDF, DOCX, XLSX, PPTX, CSV. Pure format utility for creating reports, exporting data, and processing uploaded documents.
+description: "Generate and parse office documents — PDF, DOCX, XLSX, PPTX, CSV. Use when creating reports, exporting tabular data, or processing uploaded office files. NOT for project documentation (use docs)."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs
-description: Auto-generate and maintain project documentation. Creates README, API docs, architecture docs, changelogs, and keeps them in sync with code changes. The "docs are never outdated" skill.
+description: "Auto-generate and maintain project documentation. Creates README, API docs, architecture docs, changelogs, and keeps them in sync with code changes. The \"docs are never outdated\" skill."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/docs-seeker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-seeker
-description: Find documentation for APIs, libraries, and error messages. Looks up official docs, changelog entries, and migration guides.
+description: "Find documentation for APIs, libraries, and error messages. Looks up official docs, changelog entries, and migration guides."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/fix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fix
-description: Apply code changes and fixes. Writes implementation code, applies bug fixes, and verifies changes with tests. Core action hub in the development mesh.
+description: "Apply code changes and fixes. Writes implementation code, applies bug fixes, and verifies changes with tests. Core action hub in the development mesh."
 metadata:
   author: runedev
   version: "1.0.0"
@@ -9,7 +9,7 @@ metadata:
   group: development
   tools: "Read, Write, Edit, Bash, Glob, Grep"
   emit: code.changed, agent.stuck
-  listen: bug.diagnosed, review.issues, preflight.blocked, security.blocked
+  listen: bug.diagnosed, review.issues, preflight.blocked, security.blocked, oracle.response
 ---
 
 # fix
@@ -41,6 +41,7 @@ If unsure whether the test is wrong or the implementation is wrong → call `run
 - `hallucination-guard` (L3): verify imports after code changes
 - `scout` (L2): find related code before applying changes
 - `neural-memory` (L3): after fix verified — capture fix pattern (cause → solution)
+- `adversary` (L2): on `agent.stuck` after 2+ failed attempts — oracle-mode dispatches stateless second-model pass to break confirmation-bias loop
 
 ## Called By (inbound)
 
@@ -142,7 +143,7 @@ When fix is called repeatedly (e.g., by cook Phase 4, or iterative fix loops), t
 **Thresholds:**
 - **>20% WTF-likelihood**: STOP fixing. Report current state to cook/user with: "Quality decay detected — continued fixes risk introducing more bugs than they resolve. {N} fixes applied, {score}% risk. Recommend: commit current progress, re-assess remaining issues."
 - **Hard cap: 30 fixes per session** — regardless of score. After 30, STOP and report.
-- **2+ consecutive fixes on the same file all failed**: emit `agent.stuck` signal (listened by `scout` zoom-out mode). Receiving agents may zoom out to the surrounding module map to recover bigger-picture context.
+- **2+ consecutive fixes on the same file all failed**: emit `agent.stuck` signal. `scout` zoom-out mode (structural pivot) and `adversary` oracle-mode (semantic pivot via stateless second-model dispatch) both listen and fire in parallel. If `oracle.response` arrives with confidence=high, apply its recommended edit (still routes through normal validation gates).
 
 **Reset conditions:** WTF-likelihood resets to 0% when:
 - User explicitly says "continue fixing"

package/skills/git/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git
-description: Specialized git operations — semantic commits, PR descriptions, branch management, conflict resolution guidance. Replaces ad-hoc git commands with a dedicated, convention-aware utility.
+description: "Specialized git operations — semantic commits, PR descriptions, branch management, conflict resolution guidance. Replaces ad-hoc git commands with a dedicated, convention-aware utility."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/hallucination-guard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hallucination-guard
-description: Verify AI-generated imports, API calls, and packages actually exist. Catches phantom functions, non-existent packages, and slopsquatting attacks.
+description: "Verify AI-generated imports, API calls, and packages actually exist. Use when finishing AI-generated code that introduces new imports or external API calls — auto-fires after fix/cook to catch phantom functions, non-existent packages, and slopsquatting attacks."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/integrity-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: integrity-check
-description: "Verify integrity of persisted state, skill outputs, and context bus data. Detects prompt injection, memory poisoning, identity spoofing, and adversarial payloads in .rune/ files and agent outputs. Called by sentinel, team, and session-bridge."
+description: "Verify integrity of persisted state, skill outputs, and context bus data. Use when validating .rune/ files or sub-agent outputs against prompt injection, memory poisoning, identity spoofing, or adversarial payloads. Called by sentinel, team, session-bridge."
 user-invocable: false
 metadata:
   author: runedev

package/skills/journal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: journal
-description: Persistent state tracking and Architecture Decision Records across sessions. Use when recording a decision, ADR, or progress that must survive session boundaries. Manages progress state, module health, dependency graphs, and ADRs for any workflow.
+description: "Persistent state tracking and Architecture Decision Records across sessions. Use when recording a decision, ADR, or progress that must survive session boundaries. Manages progress state, module health, dependency graphs, and ADRs for any workflow."
 metadata:
   author: runedev
   version: "0.4.0"

package/skills/logic-guardian/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: logic-guardian
-description: Protects complex business logic from accidental deletion or overwrite. Maintains a logic manifest, enforces pre-edit gates, and validates post-edit diffs.
+description: "Protects complex business logic from accidental deletion or overwrite. Use when editing payment, trading, state-machine, or other load-bearing business logic where a single deleted line can cause silent data corruption. Maintains a logic manifest, enforces pre-edit gates, validates post-edit diffs."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/marketing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: marketing
-description: Create marketing assets and execute launch strategy. Generates landing copy, social banners, SEO meta, blog posts, and video scripts.
+description: "Create marketing assets and execute launch strategy. Generates landing copy, social banners, SEO meta, blog posts, and video scripts."
 metadata:
   author: runedev
   version: "0.6.0"

package/skills/mcp-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mcp-builder
-description: Build Model Context Protocol servers from specifications. Generates tool definitions, resource handlers, and test suites for MCP servers in TypeScript or Python (FastMCP).
+description: "Build Model Context Protocol servers from specifications. Use when creating an MCP server for a tool, resource, or service that AI agents should access. Generates tool definitions, resource handlers, and test suites in TypeScript or Python (FastMCP)."
 metadata:
   author: runedev
   version: "0.5.0"

package/skills/onboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onboard
-description: Auto-generate project context for AI sessions. Scans codebase, creates CLAUDE.md and .rune/ setup so every future session starts with full context.
+description: "Auto-generate project context for AI sessions. Use when starting on a new repo for the first time, or when CLAUDE.md / .rune/ context is missing or stale. Scans codebase and creates the setup so every future session starts with full context."
 metadata:
   author: runedev
   version: "0.4.0"

package/skills/perf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: perf
-description: Performance regression gate. Detects N+1 queries, sync-in-async, missing indexes, memory leaks, and bundle bloat before they reach production.
+description: "Performance regression gate. Detects N+1 queries, sync-in-async, missing indexes, memory leaks, and bundle bloat before they reach production."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: Create structured implementation plans from requirements. Produces master plan + phase files for enterprise-scale project management. Master plan = overview (<80 lines). Phase files = execution detail (<150 lines each). Each session handles 1 phase. Uses opus for deep reasoning.
+description: "Create structured implementation plans from requirements. Produces master plan + phase files for enterprise-scale project management. Master plan = overview (<80 lines). Phase files = execution detail (<150 lines each). Each session handles 1 phase. Uses opus for deep reasoning."
 metadata:
   author: runedev
   version: "1.5.0"

package/skills/preflight/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: preflight
-description: Pre-commit quality gate that catches "almost right" code. Goes beyond linting — checks logic correctness, error handling, regressions, and completeness.
+description: "Pre-commit quality gate that catches 'almost right' code. Use when about to commit — auto-fires before commit to validate logic correctness, error handling, regressions, and completeness. Goes beyond linting."
 metadata:
   author: runedev
   version: "1.1.0"

package/skills/research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: research
-description: Web search and external knowledge lookup. Gathers data on technologies, libraries, best practices, and competitor solutions.
+description: "Web search and external knowledge lookup. Gathers data on technologies, libraries, best practices, and competitor solutions."
 metadata:
   author: runedev
   version: "0.4.0"

package/skills/retro/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: retro
-description: Engineering retrospective. Analyzes commit history, work patterns, and code quality metrics with trend tracking. Per-person breakdowns, shipping streaks, and actionable improvements. Use when asked for "retro", "weekly review", "what did we ship", or "engineering retrospective".
+description: "Engineering retrospective. Analyzes commit history, work patterns, and code quality metrics with trend tracking. Per-person breakdowns, shipping streaks, and actionable improvements. Use when asked for \"retro\", \"weekly review\", \"what did we ship\", or \"engineering retrospective\"."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review
-description: Code quality review — patterns, security, performance, correctness. Finds bugs, suggests improvements, triggers fix for issues found. Escalates to opus for security-critical code.
+description: "Code quality review — patterns, security, performance, correctness. Finds bugs, suggests improvements, triggers fix for issues found. Escalates to opus for security-critical code."
 metadata:
   author: runedev
   version: "1.1.0"
@@ -9,7 +9,7 @@ metadata:
   group: development
   tools: "Read, Glob, Grep"
   emit: review.complete, review.issues
-  listen: code.changed, docs.updated
+  listen: code.changed, docs.updated, context.preview
 ---
 
 # review

package/skills/review-intake/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-intake
-description: Use when receiving code review feedback, PR comments, or external suggestions before implementing any changes. Prevents blind implementation, enforces verification-first discipline.
+description: "Use when receiving code review feedback, PR comments, or external suggestions before implementing any changes. Prevents blind implementation, enforces verification-first discipline."
 metadata:
   author: runedev
   version: "1.2.0"

package/skills/safeguard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: safeguard
-description: Build safety nets before refactoring. Use when running surgeon or any risky refactor that needs a rollback point. Creates characterization tests, boundary markers, config freezes, and rollback points.
+description: "Build safety nets before refactoring. Use when running surgeon or any risky refactor that needs a rollback point. Creates characterization tests, boundary markers, config freezes, and rollback points."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/scaffold/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scaffold
-description: Autonomous project bootstrapper. Generates complete project from a description — structure, code, tests, docs, config. Orchestrates ba → plan → design → fix → test → docs → git in one pipeline. The "0 to production-ready" skill.
+description: "Autonomous project bootstrapper. Generates complete project from a description — structure, code, tests, docs, config. Orchestrates ba → plan → design → fix → test → docs → git in one pipeline. The \"0 to production-ready\" skill."
 metadata:
   author: runedev
   version: "0.1.0"

package/skills/sentinel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sentinel
-description: Automated security gatekeeper. Blocks unsafe code before commit — secret scanning, OWASP top 10, dependency audit, permission checks. A GATE, not a suggestion.
+description: "Automated security gatekeeper. Blocks unsafe code before commit — secret scanning, OWASP top 10, dependency audit, permission checks. A GATE, not a suggestion."
 metadata:
   author: runedev
   version: "1.0.0"

package/skills/sentinel-env/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sentinel-env
-description: Environment-aware pre-flight check. Validates OS, runtime versions, installed tools, port availability, env vars, and disk space BEFORE coding starts. Prevents "works on my machine" failures. Like sentinel but for the environment, not the code.
+description: "Environment-aware pre-flight check. Use when starting work in a new environment, switching machines, or when 'works on my machine' bugs surface. Validates OS, runtime versions, installed tools, port availability, env vars, and disk space BEFORE coding starts. Like sentinel but for the environment, not the code."
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/session-bridge/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: session-bridge
-description: Universal context persistence across sessions. Auto-saves decisions, conventions, and progress to .rune/ files. Loads state at session start. Use when any skill makes architectural decisions or establishes patterns that must survive session boundaries.
+description: "Universal context persistence across sessions. Auto-saves decisions, conventions, and progress to .rune/ files. Loads state at session start. Use when any skill makes architectural decisions or establishes patterns that must survive session boundaries."
 metadata:
   author: runedev
-  version: "0.7.0"
+  version: "0.8.0"
   layer: L3
   model: haiku
   group: state
   tools: "Read, Write, Edit, Glob, Grep"
-  listen: phase.complete, checkpoint.request
-  emit: invariants.loaded
+  listen: phase.complete, checkpoint.request, oracle.dispatched
+  emit: invariants.loaded, oracle.failed
 ---
 
 # session-bridge
@@ -40,6 +40,7 @@ Solve the #1 developer complaint: context loss across sessions. Session-bridge a
 - `context-engine` (L3): save state before compaction
 - `context-pack` (L3): coordinate state for sub-agent handoff
 - `neural-memory` (L3): sync key decisions back to `.rune/` files after Capture Mode
+- `adversary` (L2): (oracle-mode) detach protocol when target model is opus-class for non-blocking dispatch
 
 ## State Files Managed
 
@@ -540,11 +541,86 @@ At Load Mode Step 1, after checking `.rune/*.md` existence, also check for `.run
 - **Remaining tasks**: [count]
 ```
 
+## Detach Mode (v0.8.0)
+
+Triggered by `oracle.dispatched` from `adversary` oracle-mode. Decouples the primary agent from a slow heavy-model call so the agent can continue adjacent work while the second model reasons.
+
+**Why**: Opus-class reasoning takes 1-10 minutes wall time. Synchronous waits kill primary-agent throughput, especially in `team` parallel workstreams.
+
+### Step D1 — Receive dispatch
+
+When `oracle.dispatched` arrives, payload contains:
+- `sessionId` — caller-provided unique id
+- `triggerSignal` — `agent.stuck` or manual
+- `sourceSkill` — `debug` | `fix` | manual
+- `targetModel` — concrete model name (e.g. `gpt-5-pro`, `gemini-3-pro`, `claude-opus-4-7`)
+- `bundleHash` — sha256 of the bundled context (idempotency key)
+
+### Step D2 — Idempotency check
+
+Look up `.rune/oracle-pending/<sessionId>.json` AND any pending file with matching `bundleHash`. If a pending record with status=`pending` and the same `bundleHash` exists, **return the existing sessionId** — do NOT dispatch a duplicate.
+
+### Step D3 — Write pending record
+
+Create `.rune/oracle-pending/<sessionId>.json`:
+
+```json
+{
+  "sessionId": "oracle-1714234500-abc123",
+  "dispatchedAt": "2026-04-27T12:34:56Z",
+  "triggerSignal": "agent.stuck",
+  "sourceSkill": "debug",
+  "targetModel": "claude-opus-4-7",
+  "bundleHash": "sha256:9f3a...",
+  "status": "pending",
+  "timeoutAt": "2026-04-27T12:44:56Z",
+  "responseId": null,
+  "responseExcerpt": null
+}
+```
+
+`timeoutAt` defaults to `dispatchedAt + 10min`.
+
+### Step D4 — Return control to caller
+
+Caller (`adversary`) receives the sessionId and returns to the primary orchestrator. Primary agent (`cook`/`team`) continues adjacent phases.
+
+### Step D5 — Reattach (called by primary agent between phases)
+
+Invocation: `session-bridge --reattach <sessionId>` (or via `oracle.dispatched` listen → poll).
+
+Behavior:
+1. Read `.rune/oracle-pending/<sessionId>.json`
+2. If `status=complete` → return `responseExcerpt` to caller, mark record as consumed
+3. If `status=pending` AND `now >= timeoutAt` → set `status=failed`, emit `oracle.failed` reason=`timeout`
+4. If `status=pending` AND `now < timeoutAt` → return `not_ready` to caller, primary agent works on next independent task
+
+### Step D6 — Cleanup
+
+On every session start, scan `.rune/oracle-pending/` for records older than 24h. Delete them — they are orphaned.
+
+### Pending Record Schema
+
+| Field | Type | Required |
+|-------|------|----------|
+| sessionId | string (matches `^oracle-\d+-[a-z0-9]+$`) | yes |
+| dispatchedAt | ISO 8601 timestamp | yes |
+| triggerSignal | string | yes |
+| sourceSkill | enum: `debug` \| `fix` \| `manual` | yes |
+| targetModel | string | yes |
+| bundleHash | string (matches `^sha256:[a-f0-9]{8,64}$`) | yes |
+| status | enum: `pending` \| `complete` \| `failed` | yes |
+| timeoutAt | ISO 8601 timestamp | yes |
+| responseId | string \| null | yes (null until status=complete) |
+| responseExcerpt | string ≤500 chars \| null | yes |
+
 ## Constraints
 
 1. MUST save decisions, conventions, and progress — not just a status line
 2. MUST verify saved context can be loaded in a fresh session — test the round-trip
 3. MUST NOT overwrite existing bridge data without merging
+4. (Detach) MUST be idempotent — same sessionId or bundleHash returns existing record, never dispatches twice
+5. (Detach) MUST clean up orphaned pending records (age >24h) on session start
 
 ## Sharp Edges
 
@@ -560,6 +636,9 @@ Known failure modes for this skill. Check these before declaring done.
 | Learnings JSONL grows unbounded | MEDIUM | Auto-compact at 100 entries — keep only latest-winner per key+type |
 | Checkpoint stale after code changes | MEDIUM | Checkpoint includes git state — if branch/commit differ at resume, warn user that checkpoint may be outdated |
 | Multiple checkpoints overwrite each other | LOW | By design — only one active checkpoint. Resolved ones archived with date suffix |
+| (Detach) Pending file orphaned forever — process crashed mid-dispatch | MEDIUM | Step D6 cleanup runs every session start; records >24h auto-deleted |
+| (Detach) Two adversary calls dispatch same bundle simultaneously | MEDIUM | Step D2 idempotency: bundleHash-keyed lookup returns existing sessionId |
+| (Detach) Reattach polls indefinitely without timeout | HIGH | Step D5 enforces `timeoutAt` — exceeded → emit `oracle.failed` reason=`timeout`, free the primary agent |
 
 ## Done When (Save Mode)
 
@@ -590,6 +669,14 @@ Known failure modes for this skill. Check these before declaring done.
 - checkpoint.md written to .rune/
 - Checkpoint Saved report emitted
 
+## Done When (Detach Mode)
+
+- Pending record written to `.rune/oracle-pending/<sessionId>.json` with valid schema
+- Idempotency verified: duplicate bundleHash returned existing sessionId, no duplicate dispatch
+- Reattach API returns `complete` / `pending` / `failed` based on record status + timeout
+- Orphan cleanup runs at session start (records >24h deleted)
+- `oracle.failed` emitted with `reason=timeout` if timeoutAt exceeded
+
 ## Cost Profile
 
 ~100-300 tokens per save. ~500-1000 tokens per load. Always haiku. Negligible cost.