@rune-kit/rune 2.14.0 → 2.15.0

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"

package/skills/surgeon/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: surgeon
-description: Incremental refactorer. Use within a rescue workflow after safeguard has set up safety nets. Refactors ONE module per session using proven patterns — Strangler Fig, Branch by Abstraction, Expand-Migrate-Contract.
+description: "Incremental refactorer. Use within a rescue workflow after safeguard has set up safety nets. Refactors ONE module per session using proven patterns — Strangler Fig, Branch by Abstraction, Expand-Migrate-Contract."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/team/SKILL.md

@@ -11,6 +11,7 @@ metadata:
   group: orchestrator
   tools: "Read, Write, Edit, Bash, Glob, Grep"
   emit: phase.complete
+  listen: context.preview
 ---
 
 # team
@@ -285,6 +286,8 @@ Mark todo[1] `completed`.
 
 Mark todo[2] `in_progress`.
 
+**3a-pre. Oracle reattach sweep.** Before merge coordination, glob `.rune/oracle-pending/*.json`. For any worker stream that emitted `oracle.dispatched` during Phase 2, invoke `session-bridge --reattach <sessionId>`. Worker streams with `status=pending` past their `timeoutAt` are unblocked via `oracle.failed` so coordination can proceed. Workers with `status=complete` consume the response before merge.
+
 **3a. Check for file conflicts.**
 
 ```

package/skills/trend-scout/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trend-scout
-description: Scan market trends, competitor activity, and emerging patterns. Monitors Product Hunt, GitHub Trending, HackerNews, and social platforms.
+description: "Scan market trends, competitor activity, and emerging patterns. Monitors Product Hunt, GitHub Trending, HackerNews, and social platforms."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/video-creator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: video-creator
-description: Video content planning. Writes narration scripts, storyboards, shot lists, and asset checklists. Saves plan to marketing/video-plan.md.
+description: "Video content planning. Writes narration scripts, storyboards, shot lists, and asset checklists. Saves plan to marketing/video-plan.md."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/watchdog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: watchdog
-description: Post-deploy monitoring. Checks if deployed app is healthy — HTTP status, response times, error detection, and smoke test report.
+description: "Post-deploy monitoring. Use when verifying a deployed app is healthy after deploy or launch — auto-fires from launch/deploy. Checks HTTP status, response times, error detection, and smoke test report."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/worktree/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: worktree
-description: "Git worktree lifecycle management. Creates isolated workspaces for parallel development, manages branches, handles cleanup. Called by team and cook for parallel isolation."
+description: "Git worktree lifecycle management. Use when team needs parallel isolated workspaces for multi-stream development, or when an experiment must not touch the main working tree. Creates isolated workspaces, manages branches, handles cleanup. Called by team and cook."
 user-invocable: false
 metadata:
   author: runedev