@rune-kit/rune 2.13.0 → 2.15.0

package/skills/journal/references/adr-criteria.md

@@ -0,0 +1,109 @@
+# ADR Criteria — When to Open an ADR
+
+ADRs (Architecture Decision Records) are durable. They survive sessions, codebases, and team turnover. That power has a cost: writing one for every minor pick fills the directory with noise, and the genuinely load-bearing decisions get lost.
+
+The ADR gate ensures that every entry in `.rune/adr/` *earned* its place.
+
+## The 3-criteria gate
+
+An ADR is offered only if **all three** are true:
+
+### 1. Hard to reverse (`reversibility`)
+
+Score 1–5: how expensive is it to change your mind later?
+
+| Score | Description |
+|-------|-------------|
+| 1 | Reversible next sprint (one PR, no migration) |
+| 2 | Reversible this quarter (a few PRs, simple migration) |
+| 3 | Significant cost (data migration, multi-PR rollout) |
+| 4 | Quarter-or-more to reverse (schema change, integration rewrite) |
+| 5 | Practically irreversible (architectural commitment, lock-in to vendor) |
+
+### 2. Surprising without context (`surprisingness`)
+
+Score 1–5: how likely is a future reader to wonder "why did they do it this way?"
+
+| Score | Description |
+|-------|-------------|
+| 1 | Obvious — anyone would do it this way |
+| 2 | Common, but with one minor detail |
+| 3 | Mildly unusual — half of practitioners might pick differently |
+| 4 | Strongly counter to common practice |
+| 5 | Rare or counter-intuitive — without explanation, future engineer would "fix" it |
+
+### 3. Real tradeoff (`tradeoff_strength`)
+
+Score 1–5: how credible were the rejected alternatives?
+
+| Score | Description |
+|-------|-------------|
+| 1 | No real alternative — the obvious thing |
+| 2 | One alternative considered briefly |
+| 3 | 2–3 alternatives evaluated; pick was clear |
+| 4 | Multiple credible alternatives; pick required real analysis |
+| 5 | Genuinely difficult choice; reasonable people disagreed |
+
+### Threshold
+
+```
+score = reversibility + surprisingness + tradeoff_strength    # range 3–15
+open_adr = (score >= 11) AND (each axis >= 3)
+```
+
+The "each axis >= 3" rule prevents single-axis cheating. A decision that's hard-to-reverse but obvious AND has no real alternatives (e.g., "we're using SQL for our SQL database") shouldn't be an ADR even if reversibility=5.
+
+## Counter-test (anti-fake)
+
+Before opening an ADR, the agent MUST be able to fill in **rejected alternatives + why**. If the agent can't name at least one credible alternative *that was actually considered*, the decision wasn't a real tradeoff. Re-classify as a "convention" — record it in CLAUDE.md or a comment, not in `.rune/adr/`.
+
+```
+Rejected alternative: PostgreSQL JSON columns
+Why rejected: schema migrations harder; no JSON-path indexing in the version we use; team's tooling stack favors structured columns.
+```
+
+If you can't write that section, don't open the ADR.
+
+## ADR file naming
+
+Filename includes the score, so future reviewers see at a glance why this one was kept:
+
+```
+.rune/adr/ADR-007-postgres-write-model-s13.md
+.rune/adr/ADR-008-event-sourced-orders-s14.md
+```
+
+Format: `ADR-NNN-<slug>-s<score>.md` where `NNN` is the sequential number and `score` is the 3–15 sum.
+
+## What qualifies (examples)
+
+- **Architectural shape**: "We're using a monorepo." "The write model is event-sourced; the read model is projected into Postgres." (s ≈ 12–14)
+- **Integration patterns between modules**: "Ordering and Billing communicate via domain events, not synchronous HTTP." (s ≈ 11–13)
+- **Technology choices that carry lock-in**: database, message bus, auth provider, deployment target — only the ones that would take a quarter to swap out. (s ≈ 11–14)
+- **Boundary-and-scope decisions**: "Customer data is owned by the Customer module; other modules reference it by ID only." The explicit no-s are as valuable as the yes-s. (s ≈ 10–12 — borderline, judge case-by-case)
+- **Deliberate deviations from the obvious path**: "We're using manual SQL instead of an ORM because X." (s ≈ 11–13 — high surprisingness)
+- **Constraints not visible in the code**: "We can't use AWS because of compliance requirements." (s ≈ 11–13)
+- **Rejected alternatives when the rejection is non-obvious**: considered GraphQL, picked REST for subtle reasons. (s ≈ 10–12 — if rejection is documented elsewhere, may not need ADR)
+
+## What does NOT qualify (examples)
+
+- "We chose lodash over underscore." (reversibility ≤ 2; not surprising; weak tradeoff) — s ≈ 5
+- "This function uses async/await instead of Promises." (reversibility 1; not surprising; convention) — s ≈ 3
+- "We're using TypeScript." (reversibility 5; not surprising; obvious for the stack) — s ≈ 7
+- "We deferred dark mode." (this is a deferral, not a decision — goes to backlog or `.out-of-scope/`) — N/A
+
+## When score is 8–10 (borderline)
+
+Don't auto-open. Ask the user: "This decision scores 9/15 — borderline. Do you want it as an ADR, or is a comment in the code sufficient?" Default to the lighter touch.
+
+## Score gaming detection
+
+The score can be inflated, but the counter-test (rejected alternative) cannot be faked without lying about history. If the agent fills out scores ≥ 4 on each axis but can't name a credible rejected alternative, the gate fails and no ADR is opened.
+
+`audit` later cross-references ADR scores — if the average score across `.rune/adr/` files is < 11, it flags "ADR inflation" as a quality concern.
+
+## Convention vs Decision
+
+Decisions are tradeoffs at fork points. **Conventions are choices everyone makes the same way** — naming, formatting, simple defaults. Conventions go in CLAUDE.md or code style guides, not ADRs.
+
+A test: if you can imagine the team coming back next quarter and saying "yeah obvious, of course we did it this way" — it's a convention. If they'd say "wait, why did we do *that*?" — it's a decision and probably qualifies.

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
@@ -60,6 +60,7 @@ Every review MUST cite at least one specific concern, suggestion, or explicit ap
 - `review` → `test` — untested edge case found → test writes it
 - `review` → `fix` — bug found during review → fix applies correction
 - `review` → `scout` — needs more context → scout finds related code
+- `review` → `improve-architecture` — when reviewer flag mentions "shallow", "wrapper", "indirection", or pass-through pattern
 - `review` ← `fix` — complex fix requests self-review
 - `review` → `sentinel` — security-critical code → sentinel deep scan
 

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 code review feedback, PR comments, or external suggestions before implementing any changes. Prevents blind implementation, enforces verification-first discipline."
 metadata:
   author: runedev
-  version: "1.1.0"
+  version: "1.2.0"
   layer: L2
   model: sonnet
   group: quality
-  tools: "Read, Glob, Grep"
+  tools: "Read, Write, Edit, Glob, Grep"
+  listen: outofscope.match
 ---
 
 # review-intake
@@ -137,6 +138,24 @@ gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies \
   -f body="Fixed — [description]"
 ```
 
+### Phase 4.5 — Rejection KB Write (when verdict = OUT OF SCOPE)
+
+For every item with verdict `OUT OF SCOPE`, write a durable record to `.out-of-scope/`. Oral-only rejections leave no trace and force re-litigation in future sessions.
+
+<HARD-GATE>
+Every OUT OF SCOPE verdict MUST produce a `.out-of-scope/<slug>.md` file (or append to an existing one).
+A rejection without a written record is a rejection that didn't happen.
+</HARD-GATE>
+
+**Procedure**:
+
+1. Generate `slug` from the rejected concept (kebab-case, lowercase, max 40 chars, recognizable without opening the file).
+2. Lexical-similarity check: `Glob` `.out-of-scope/*.md`, parse each frontmatter's `concept` + `aliases`, compute overlap with the new slug's tokens. If any existing concept has ≥0.7 overlap → APPEND to that file's `prior_requests` list instead of creating a new one.
+3. If new file: write the format from [`ba/references/out-of-scope-format.md`](../ba/references/out-of-scope-format.md) — YAML frontmatter (concept / aliases / decision: rejected / rejected_at / rejected_by: review-intake / prior_requests / revisit_if) + Markdown body (concept name, "Why out of scope" reasoning, "What would change our mind" signals).
+4. The reasoning MUST be substantive — not "we don't want this" but *why*. Reference project scope, technical constraints, or strategic decisions. Reject deferrals ("we're busy") — those don't belong here.
+
+Only **enhancement** rejections produce `.out-of-scope/` entries. Bug rejections (won't fix because already fixed / not reproducible / not a bug) get a comment on the issue, not a KB file.
+
 ### Phase 6 — IMPLEMENT
 
 Execute in priority order: P0 → P1 → P2 → P3 → P4.
@@ -223,6 +242,9 @@ How to push back:
 | Implementing 4/6 items, leaving 2 unclear | HIGH | HARD-GATE: all-or-nothing comprehension |
 | Performative agreement masking misunderstanding | MEDIUM | Banned phrases list + restate-in-own-words requirement |
 | Fixing tests instead of code to make review pass | HIGH | Defer to `fix` constraints: fix CODE, not TESTS |
+| 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 |
 
 ## Done When
 
@@ -231,6 +253,7 @@ How to push back:
 - Verdicts assigned (correct/pushback/yagni/defer)
 - Approved items implemented in priority order
 - Tests pass after each individual fix
+- Every OUT OF SCOPE verdict has produced a `.out-of-scope/<slug>.md` file (new or appended)
 - Review Intake Report emitted
 
 ## Returns

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/scout/SKILL.md

@@ -3,12 +3,13 @@ name: scout
 description: "Fast codebase scanner. Use when any skill needs codebase context. Finds files, patterns, dependencies, project structure. Pure read-only — never modifies files."
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L2
   model: haiku
   group: creation
   tools: "Read, Glob, Grep"
   emit: codebase.scanned
+  listen: agent.stuck
 ---
 
 # scout
@@ -117,6 +118,36 @@ Scout's default is "max 10 file reads" — but the real question is whether addi
 3. Find existing tests with `Glob`: `**/*.test.*`, `**/*.spec.*`, `**/test_*`
 4. Determine test framework: `jest.config.*`, `vitest.config.*`, `pytest.ini`
 
+### Phase 4.5: Zoom-Out Mode
+
+Triggered by `mode="zoom-out"` from the caller, OR auto-triggered by listening on `agent.stuck` signal (emitted by `fix` after 2+ failed attempts on the same file, or by `debug` after 3+ disproved hypothesis cycles).
+
+When activated, scout produces a 3-layer ascent map:
+
+| Layer | What it includes | Cap |
+|-------|------------------|-----|
+| L0 (target) | The stuck file's symbols + immediate imports | unlimited |
+| L1 (siblings) | Files in the same directory + their public exports | 8 files |
+| L2 (callers/neighbors) | Modules that import L0's exports + neighboring modules in the same domain | 8 modules |
+
+Output is a Mermaid diagram, NOT just a file list — visual is the value-add when an agent is stuck.
+
+```mermaid
+graph LR
+  target[src/auth/login.ts]:::stuck
+  target --> dep1[crypto.compare]
+  target --> dep2[db.users.get]
+  caller1[src/routes/auth.ts] --> target
+  caller2[src/middleware/protect.ts] --> target
+  sibling1[src/auth/refresh.ts] -.same-dir.- target
+  sibling2[src/auth/logout.ts] -.same-dir.- target
+  classDef stuck fill:#ff6b6b
+```
+
+**Bounded** — L2 ascent caps at 8 modules. If exceeded, collapse to "showing top 8 by import-frequency". Never blow past the cap silently.
+
+After emitting the map, scout returns to its normal Phase 6 (Generate Report) with the zoom-out section as the primary output.
+
 ### Phase 5: Codebase Map (Optional)
 
 When called by `cook`, `team`, `onboard`, or `autopsy` (skills that need full project understanding), generate a structured codebase map:
@@ -204,6 +235,7 @@ None — pure scanner using Glob, Grep, Read, and Bash tools directly. Does not
 - `docs` (L2): scan codebase structure for documentation generation
 - `logic-guardian` (L2): scan business logic modules for protection mapping
 - `adversary` (L2): scan codebase before red-team analysis
+- `improve-architecture` (L2): re-scan target module + callers when input context is stale
 
 ## Output Format
 

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.

package/skills/session-bridge/references/detach-protocol.md

@@ -0,0 +1,111 @@
+# Detach Protocol — session-bridge oracle-mode integration
+
+## Purpose
+
+Decouple the primary AI agent from slow heavy-model second-opinion calls so the agent can continue with adjacent work instead of blocking 1-10 minutes on Opus-class reasoning.
+
+## State Machine
+
+```
+                  oracle.dispatched
+                        │
+                        ▼
+                  ┌──────────┐
+                  │ pending  │◄────────┐
+                  └──────────┘         │
+                   │     │             │ poll (no timeout)
+                   │     │             │
+       reply       │     │  timeout    │
+       arrives     │     │  exceeded   │
+                   ▼     ▼             │
+            ┌──────────┐ ┌──────────┐  │
+            │ complete │ │  failed  │  │
+            └──────────┘ └──────────┘  │
+                   │           │       │
+                   │           │       │
+                   ▼           ▼       │
+              consumed      cleaned    │
+              (caller       up after   │
+               reads        24h        │
+               response)               │
+                                       │
+              ┌────────────────────────┘
+              │
+        reattach poll
+        (every phase boundary)
+```
+
+## File Layout
+
+```
+.rune/
+└── oracle-pending/
+    ├── oracle-1714234500-abc123.json   # active dispatch
+    ├── oracle-1714234600-def456.json   # active dispatch
+    └── oracle-1714150000-old.json      # >24h, will be cleaned next session start
+```
+
+One file per dispatch. No master index — directory listing IS the queue.
+
+## Dispatch Flow (D1-D4)
+
+1. **D1 Receive**: `oracle.dispatched` arrives with `{sessionId, triggerSignal, sourceSkill, targetModel, bundleHash}`.
+
+2. **D2 Idempotency**: Glob `.rune/oracle-pending/*.json`. If any pending record matches `bundleHash` → return its `sessionId` to caller. Skip D3-D4.
+
+3. **D3 Write record**: Create `<sessionId>.json` with full schema. `status=pending`, `timeoutAt = dispatchedAt + 10min` (configurable via `RUNE_ORACLE_TIMEOUT_SEC`).
+
+4. **D4 Return control**: Caller (`adversary`) returns the sessionId to its parent (`debug`/`fix`). Parent agent emits its non-blocking continuation marker and resumes adjacent work.
+
+## Reattach Flow (D5)
+
+Called by `cook` Phase 4 (between tasks) or `team` workstream coordinator (before next worker dispatch):
+
+```
+session-bridge --reattach <sessionId>
+```
+
+Returns one of:
+- `{ status: "complete", responseExcerpt: "...", responseId: "..." }` — primary agent consumes the reply
+- `{ status: "pending", remainingMs: 234000 }` — primary agent works on next independent task, polls again next phase boundary
+- `{ status: "failed", reason: "timeout" | "rejected" | "no_citations" }` — primary agent continues without second opinion
+
+After `complete` is consumed, the record is renamed `<sessionId>.consumed.json` and removed at next cleanup.
+
+## Cleanup Flow (D6)
+
+On every session start (load-mode entry), session-bridge scans `.rune/oracle-pending/`:
+- For each `*.json` file: read `dispatchedAt`. If `now - dispatchedAt > 24h`, delete the file
+- Log cleanup count to `session-log.md` (e.g. "cleaned 3 orphaned oracle-pending records")
+
+## Concurrency Considerations
+
+**Single primary agent** (typical Claude Code session): no concurrency concern. Sequential reads/writes.
+
+**Multi-agent (`team` parallel workstreams)**: each workstream may have its own pending record. Idempotency in D2 prevents two workers from dispatching the same bundle. Different bundles produce different sessionIds → no collision.
+
+**File-system write atomicity**: write to `<sessionId>.json.tmp` first, then `fs.rename` to final name (atomic on POSIX, atomic-enough on NTFS for our purposes).
+
+## Failure Modes
+
+| Symptom | Likely Cause | Recovery |
+|---------|--------------|----------|
+| Duplicate sessionIds in directory | Hash collision (unlikely) or clock skew | sessionId includes timestamp; collision in same millisecond = caller's bug |
+| Pending record never reaches `complete` | Network failure, model timeout | D5 detects `timeoutAt` exceeded → emit `oracle.failed` reason=`timeout` |
+| Pending record JSON corrupt | Disk full mid-write | D5 read fails → log warning, treat as `failed` reason=`corrupt`, primary continues |
+| Cleanup deletes record while reattach polling | TOCTOU race | D6 only deletes records >24h old; active dispatches (<10min) safe |
+
+## Configuration
+
+Environment variables (all optional):
+
+- `RUNE_ORACLE_TIMEOUT_SEC` — override default 600s timeout
+- `RUNE_ORACLE_PENDING_DIR` — override `.rune/oracle-pending/` location
+- `RUNE_ORACLE_CLEANUP_HOURS` — override default 24h orphan threshold
+
+## Why Filesystem (vs in-memory queue)
+
+1. **Survives session restart** — if Claude Code session is reloaded mid-dispatch, the pending record is still there
+2. **No new infra** — no Redis, no SQLite, no external service
+3. **Inspectable** — user can `cat .rune/oracle-pending/*.json` to debug
+4. **Cross-process safe** — `team` parallel workstreams in different processes can coordinate via file system

package/skills/skill-forge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-forge
-description: Use when creating new Rune skills, editing existing skills, or verifying skill quality before deployment. Applies TDD discipline to skill authoring — test before write, verify before ship.
+description: "Use when creating new Rune skills, editing existing skills, or verifying skill quality before deployment. Applies TDD discipline to skill authoring — test before write, verify before ship."
 metadata:
   author: runedev
   version: "1.8.0"

package/skills/slides/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: slides
-description: Generate Marp-compatible slide decks from structured JSON schema. Converts context into presentations for tech talks, sprint demos, and tutorials.
+description: "Generate Marp-compatible slide decks from structured JSON schema. Converts context into presentations for tech talks, sprint demos, and tutorials."
 metadata:
   author: runedev
   version: "0.1.0"