@rune-kit/rune 2.14.0 → 2.16.0

package/skills/plan/references/vertical-slice.md

@@ -0,0 +1,79 @@
+# Vertical Slice (Tracer-Bullet) Decomposition
+
+**Each slice is a thin path through ALL layers** — schema, API, UI, tests — that produces a demoable, verifiable outcome on its own. Prefer many thin slices over few thick ones.
+
+> Horizontal layers ("all models → all APIs → all UI") look organized but block on the slowest layer. Vertical slices ship in parallel and verify continuously.
+
+## Slice rules
+
+1. **End-to-end, not end-of-end** — every slice touches every layer it needs (schema migration + handler + UI + test). A slice that only adds a database column is not a slice; it's a fragment.
+2. **Demoable on its own** — when the slice is merged, you can demo it (or run a single command to verify). If demoing requires "and now switch to the other PR", the slices were drawn wrong.
+3. **Narrow but complete** — one user story, one happy path, minimal error handling. Edge cases are *separate slices*, not bigger versions of the same slice.
+4. **Independently grabbable** — any developer or agent should be able to pick up Slice N without reading Slice N+1. Dependencies declared explicitly, not implicit.
+
+## Slice types
+
+| Type | Definition | When |
+|------|------------|------|
+| **AFK** | Can be implemented and merged without human interaction. Spec is concrete enough that an agent (or the weakest model) executes it correctly. | Default — prefer wherever possible |
+| **HITL** | Requires human input mid-execution: architectural decisions, design review, copy approval, third-party access (OAuth setup, DNS, payment provider). | Only when AFK is genuinely impossible |
+
+**Bias toward AFK.** A slice marked HITL is friction — every HITL slice blocks the parallel queue. Before marking HITL, ask: can the human input be done ONCE upfront and then the slice is AFK?
+
+## Slice template (per task in a phase file)
+
+```markdown
+### Slice: [verb-led title]
+- **Type**: AFK | HITL
+- **Story**: As a [persona], I want to [action] so that [benefit]
+- **Path through layers**:
+  - Schema: [migration / type addition]
+  - API: [endpoint or function signature]
+  - UI: [component or surface]
+  - Test: [verification approach]
+- **Demoable**: [exact command or click-path that shows it works]
+- **Blocked by**: [slice IDs] | None — can start immediately
+- **Out of scope** (explicit): [what this slice does NOT cover]
+```
+
+## Granularity
+
+Right-sized slice:
+- Fits in one phase file (under the Amateur-Proof 200-line cap)
+- Completable in one session by Sonnet/Haiku
+- Touches 3-7 files total across all layers
+- Has exactly ONE acceptance criterion that proves the path works end-to-end
+
+If a slice has 5+ acceptance criteria → split it. If a slice touches 10+ files → split it. If two slices share 3+ files → merge or sequence them (file overlap = race condition in parallel execution).
+
+## Decomposition checklist
+
+Before approving a slice breakdown, verify:
+
+- [ ] Every slice can be demoed independently
+- [ ] No slice requires another in-flight slice to be merged first (declared deps OK; in-flight overlap NOT OK)
+- [ ] AFK / HITL labels are accurate — HITL slices have a specific blocking input named
+- [ ] Slice count matches granularity rule (3-7 slices for a typical feature; if 1 or 2, slice is too thick; if 15+, too thin)
+- [ ] First slice is the **smallest valuable end-to-end path** — proves the architecture works before scaling
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails |
+|--------------|--------------|
+| Layer-1 slice ("just the database changes") | Not demoable, not verifiable, blocks every downstream slice |
+| Slice with "and the admin UI for it" appended | Hidden second slice — split |
+| 10 acceptance criteria on one slice | Granularity miss — slice is actually a feature |
+| Slice marked HITL because "I might want to review the design" | HITL is for hard blockers, not soft preferences. Use AFK + post-merge review. |
+| First slice is the most complex one ("let's build the hardest part first") | Wrong order. First slice proves architecture; complexity comes later when foundation is verified. |
+
+## Integration with phase planning
+
+Vertical slices map cleanly to phase wave structure:
+
+```
+Phase 1, Wave 1: Slice A (foundation slice — proves architecture end-to-end)
+Phase 1, Wave 2: Slice B, C (parallel — depend on A's contract, not on each other)
+Phase 2, Wave 1: Slice D, E (next layer of slices)
+```
+
+Each slice = one task in a wave. Use `touches[]` / `provides[]` / `requires[]` metadata (see Change Stacking in `plan/SKILL.md`) to detect file overlap between slices in the same wave.

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,13 +1,14 @@
 ---
 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 external input that needs structured intake before action — PR review feedback, code review comments, OR issue tracker items (bug reports, feature requests). PR Review Mode (default) verifies suggestions before implementing. Issue Triage Mode classifies issues into a state machine (ready-for-agent / ready-for-human / needs-info / wontfix) and emits AGENT-BRIEFs for AFK execution. Prevents blind implementation, enforces verification-first discipline."
 metadata:
   author: runedev
-  version: "1.2.0"
+  version: "1.3.0"
   layer: L2
   model: sonnet
   group: quality
-  tools: "Read, Write, Edit, Glob, Grep"
+  tools: "Read, Write, Edit, Bash, Glob, Grep"
+  emit: triage.classified, agent.brief.ready
   listen: outofscope.match
 ---
 
@@ -17,11 +18,23 @@ metadata:
 
 The counterpart to `review`. While `review` finds issues in code, `review-intake` handles the response when someone finds issues in YOUR code. Enforces a verification-first discipline: understand fully, verify against codebase reality, then act. Prevents the common failure mode of blindly implementing suggestions that break things or don't apply.
 
+## Modes
+
+| Mode | When | Workflow |
+|------|------|----------|
+| **PR Review Mode** (default) | Input is PR comments / code review feedback / external suggestions | Phases 1-6 below — absorb, comprehend, verify, evaluate, respond, implement |
+| **Issue Triage Mode** | Input is issue tracker item (`gh-42`, URL, pasted issue body), or user says "triage" / "process the inbox" | See `references/issue-triage.md` — state machine (needs-triage → ready-for-agent / ready-for-human / needs-info / wontfix) + repro-first for bugs + AGENT-BRIEF emission |
+
+Both modes share Phase 4.5 (Rejection KB Write) — `wontfix-enhancement` from Issue Triage and OUT OF SCOPE from PR Review both write `.out-of-scope/<slug>.md`.
+
 ## Triggers
 
-- `/rune review-intake` — manual invocation when processing feedback
-- Auto-trigger: when `cook` or `fix` receives PR review comments
-- Auto-trigger: when user pastes review feedback into session
+- `/rune review-intake` — manual invocation, PR Review Mode by default
+- `/rune review-intake <issue-ref>` — Issue Triage Mode (issue number, URL, or path)
+- `/rune review-intake --inbox` — Issue Triage Mode batch sweep (unlabeled + needs-triage + needs-info-with-activity)
+- Auto-trigger: when `cook` or `fix` receives PR review comments → PR Review Mode
+- Auto-trigger: when user pastes review feedback into session → PR Review Mode
+- Auto-trigger: when user pastes an issue body or references a ticket → Issue Triage Mode
 
 ## Calls (outbound)
 
@@ -36,7 +49,10 @@ The counterpart to `review`. While `review` finds issues in code, `review-intake
 - `cook` (L1): Phase 5 quality gate when external review arrives
 - `review` (L2): when self-review surfaces issues to address
 
-## Workflow
+## Workflow (PR Review Mode)
+
+For Issue Triage Mode, see [references/issue-triage.md](references/issue-triage.md). Both modes converge at Phase 4.5 for rejection KB writes.
+<MUST-READ path="references/issue-triage.md" trigger="when input is an issue tracker item, batch inbox sweep, or user explicitly says 'triage' / 'process the inbox'"/>
 
 ### Phase 1 — ABSORB
 
@@ -245,6 +261,10 @@ How to push back:
 | OUT OF SCOPE verdict with no `.out-of-scope/` file written | HIGH | Phase 4.5 HARD-GATE — oral-only rejections force re-litigation in future sessions |
 | Writing a deferral ("busy this quarter") to `.out-of-scope/` | MEDIUM | Deferrals belong in backlog, not the rejection KB. KB entries must cite durable reasons (scope, tech constraint, strategy) |
 | Creating duplicate `.out-of-scope/` files for the same concept | MEDIUM | Lexical-similarity gate (≥0.7 overlap) — append to existing file's `prior_requests` instead of duplicating |
+| Marking issue `ready-for-agent` without confirmed repro (bugs) | CRITICAL | Issue Triage Mode Step T4 HARD-GATE: bugs MUST attempt reproduction before `ready-for-agent` label. Confirmed repro = strong agent-brief; failed repro = `needs-info` |
+| Auto-applying `wontfix` to an issue without maintainer confirmation | HIGH | Triage recommends, maintainer decides. State changes (label + comment + close) confirmed via Step T3 before Step T6 acts |
+| Posting triage comments without the AI-disclaimer line | MEDIUM | Issue Triage Mode requires `> *This was generated by AI during triage.*` disclaimer prefix on every comment — trust degrades when reporter discovers AI authorship after the fact |
+| Writing `.out-of-scope/` for a `wontfix-bug` (not enhancement) | MEDIUM | Format spec: only enhancement rejections produce KB files. Bug rejections (already fixed, not reproducible, not a bug) get a comment, not a file |
 
 ## Done When
 

package/skills/review-intake/references/issue-triage.md

@@ -0,0 +1,202 @@
+# Issue Triage Mode
+
+A second mode for `review-intake`. The default mode (PR comments) processes inbound review feedback. **Issue Triage Mode** processes inbound issue tracker items (GitHub Issues, Linear tickets, bug reports, feature requests) and routes them through a state machine.
+
+> The standard PR mode answers "should I implement this suggestion?". Issue Triage Mode answers "what state is this issue in, and who should pick it up next?".
+
+## When to use Issue Triage Mode
+
+Activate when input is an **issue** (not a PR review). Triggers:
+
+| Signal | Threshold |
+|--------|-----------|
+| User passes an issue reference (`/rune review-intake gh-42`, URL, or path) | Always |
+| User says "triage", "intake this issue", "process the inbox" | Explicit |
+| User pastes an issue body + comments rather than PR review feedback | Auto-detect — issue has reporter, not reviewer |
+| Batch mode: `/rune review-intake --inbox` queries unlabeled + needs-triage issues | Inbox sweep |
+
+Skip if input is PR review comments → use default PR Review Mode.
+
+## State machine
+
+Two dimensions per issue:
+
+| Category (1 of) | State (1 of) |
+|-----------------|--------------|
+| `bug` | `needs-triage` (unlabeled, never evaluated) |
+| `enhancement` | `needs-info` (waiting on reporter for more detail) |
+|  | `ready-for-agent` (fully specified, AFK agent can execute) |
+|  | `ready-for-human` (specified but needs human judgment — design decision, OAuth setup, copy approval) |
+|  | `wontfix` (explicit decision not to action) |
+
+Every triaged issue carries exactly one category and one state. Conflicts → flag and ask the maintainer before acting.
+
+State transitions (typical):
+
+```
+unlabeled  →  needs-triage  →  needs-info  →  needs-triage (after reporter replies)
+                            →  ready-for-agent
+                            →  ready-for-human
+                            →  wontfix
+```
+
+Maintainer can override at any time (quick state override below).
+
+## Workflow
+
+### Step T1 — Inbox view (if batch mode)
+
+Query the issue tracker for three buckets, oldest first:
+
+1. **Unlabeled** — never triaged
+2. **`needs-triage`** — evaluation in progress
+3. **`needs-info` with reporter activity since last triage notes** — needs re-evaluation
+
+Show counts + one-line summary per issue. Maintainer picks one.
+
+### Step T2 — Gather context (per-issue)
+
+Read the full issue: body, comments, labels, reporter, dates. Parse any prior triage notes so you don't re-ask resolved questions.
+
+Then scan:
+- `CONTEXT.md` — apply project glossary terms in your understanding
+- `docs/adr/` — respect Architecture Decision Records in the affected area
+- `.out-of-scope/*.md` — check for prior rejection that resembles this issue
+
+If the issue matches a prior `.out-of-scope/` entry (≥0.7 lexical overlap), surface it: *"This matches a prior rejection (`<slug>`). Recommend `wontfix` unless circumstances changed."* Wait for maintainer direction.
+
+### Step T3 — Recommend
+
+Tell the maintainer your category + state recommendation with reasoning. Include a brief codebase summary relevant to the issue. Wait for direction. Do not act unilaterally.
+
+### Step T4 — Reproduce (bugs only — HARD-GATE)
+
+<HARD-GATE>
+Bugs MUST attempt reproduction before being marked `ready-for-agent`. A confirmed repro is what makes the agent-brief strong; without it, the agent will guess.
+</HARD-GATE>
+
+Process:
+1. Read the reporter's repro steps
+2. Trace the relevant code via `rune:scout` / `rune:debug`
+3. If the repro is a HTTP request / CLI invocation / browser flow → run it
+4. Report outcome:
+   - **Confirmed repro** with code path → strong `ready-for-agent` signal
+   - **Failed repro** → likely `needs-info` (ask for env, version, exact steps)
+   - **Insufficient detail** → `needs-info` with specific questions
+
+If the bug is multi-component or intermittent, route to `rune:debug` Step 0 (build a feedback loop) instead of guessing.
+
+### Step T5 — Grill (if vague)
+
+If the issue lacks specifics for both bug and enhancement paths, run a grilling pass via `rune:ba` synthesis-mode (Step 1.4):
+- Synthesis-mode reads the issue body + comments as the "rich context"
+- Asks targeted follow-ups ONLY on dimensions with genuine gaps
+- Produces a Requirements Document the agent-brief can cite
+
+### Step T6 — Apply outcome
+
+Match state to action:
+
+| State | Action |
+|-------|--------|
+| `ready-for-agent` | Post AGENT-BRIEF comment on issue (use `rune:context-pack` agent-brief variant — see `context-pack/references/agent-brief.md`). Apply `ready-for-agent` label. |
+| `ready-for-human` | Post AGENT-BRIEF + explicit "why this can't be delegated" reason (judgment call, external access, design decision, manual testing). Apply `ready-for-human` label. |
+| `needs-info` | Post triage notes (template below). Apply `needs-info` label. |
+| `wontfix` (bug) | Post a polite explanation comment, then close. **No `.out-of-scope/` write** — bug rejections (already fixed, not reproducible, not a bug) get a comment, not a KB file. |
+| `wontfix` (enhancement) | Trigger Phase 4.5 (existing) — write `.out-of-scope/<slug>.md`, link from a comment, then close. |
+| `needs-triage` | Apply the role. Optional comment if there's partial progress. |
+
+Every comment posted by triage MUST start with the disclaimer:
+
+```
+> *This was generated by AI during triage.*
+```
+
+### Step T7 — Quick state override
+
+If the maintainer says "move #42 to ready-for-agent", trust them and apply the state directly. Confirm what you're about to do (label changes, comment, close), then act. Skip grilling. If moving to `ready-for-agent` without a grilling session, ask whether they want to write an agent-brief.
+
+## Templates
+
+### Needs-info comment
+
+```markdown
+> *This was generated by AI during triage.*
+
+## Triage Notes
+
+**What we've established so far:**
+- [point 1]
+- [point 2]
+
+**What we still need from you (@reporter):**
+- [specific, actionable question 1]
+- [specific, actionable question 2]
+```
+
+Capture everything resolved during grilling under "established so far" so the work isn't lost. Questions must be specific and actionable, not "please provide more info".
+
+### Ready-for-agent comment
+
+```markdown
+> *This was generated by AI during triage.*
+
+(AGENT-BRIEF block — see `context-pack/references/agent-brief.md`)
+```
+
+### Wontfix-bug comment
+
+```markdown
+> *This was generated by AI during triage.*
+
+Closing as wontfix:
+- [Reason: already fixed in #X / not reproducible / not a bug — explain briefly]
+- [If "not reproducible": link the failed repro evidence]
+- [If user disagrees: reopen and provide new details]
+```
+
+### Wontfix-enhancement comment (links to .out-of-scope/)
+
+```markdown
+> *This was generated by AI during triage.*
+
+Closing as wontfix. Recorded in `.out-of-scope/<slug>.md` for future reference.
+
+[1-line summary of the durable reason — full reasoning lives in the file]
+```
+
+## Resuming a previous triage session
+
+If prior triage notes exist on the issue, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.
+
+## State machine output (per issue triaged)
+
+```yaml
+issue: <id>
+category: bug | enhancement
+state: needs-triage | needs-info | ready-for-agent | ready-for-human | wontfix
+repro: confirmed | failed | insufficient-info | n/a   # bugs only
+agent_brief_posted: true | false
+out_of_scope_written: <slug>.md | null
+```
+
+This payload travels alongside the existing Verdicts table when emit `triage.classified` fires.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails |
+|--------------|--------------|
+| Marking `ready-for-agent` without confirmed repro (bugs) | Agent guesses, fixes wrong thing, bug returns |
+| Auto-applying `wontfix` without maintainer confirmation | Triage recommends; only maintainer decides |
+| Re-asking questions already answered in prior triage notes | Wastes reporter trust; read existing notes first |
+| Writing `.out-of-scope/` for bug rejections | Per format spec, only enhancement rejections produce KB files |
+| Posting triage comments without the AI-generated disclaimer | Reporter assumes human voice; trust degrades when caught |
+| Quick state override without confirmation summary | "Move to ready-for-agent" can mean "label only" or "label + brief" — confirm before acting |
+
+## Integration with Phase 4.5 (existing)
+
+Phase 4.5 (Rejection KB Write) already exists in `review-intake/SKILL.md` for OUT OF SCOPE verdicts in PR Mode. In Issue Triage Mode, `wontfix-enhancement` outcome triggers the **same** Phase 4.5 — no duplicate logic. The slug, lexical-similarity check, and write procedure are identical.
+
+## Required external tools
+
+- `gh` CLI (GitHub Issues) OR Linear MCP — without an issue-tracker integration, Issue Triage Mode falls back to local-only mode: maintainer pastes the issue body, triage produces classification + draft comments, maintainer copies the comments back to the tracker manually.

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.