@rune-kit/rune 2.14.0 → 2.15.0

package/skills/adversary/SKILL.md

@@ -3,11 +3,13 @@ name: adversary
 description: "Pre-implementation red-team analysis. Use when a plan is high-risk, critical path, or expensive to reverse. Challenges plans before code is written — finds edge cases, security holes, scalability bottlenecks, error propagation risks, and integration conflicts. Catches flaws at plan time (10x cheaper than post-implementation)."
 metadata:
   author: runedev
-  version: "0.1.0"
+  version: "0.2.0"
   layer: L2
   model: opus
   group: quality
   tools: "Read, Glob, Grep"
+  emit: oracle.dispatched, oracle.response, oracle.failed
+  listen: agent.stuck, context.preview
 ---
 
 # adversary
@@ -37,12 +39,16 @@ Every finding MUST reference the specific plan section, file, or assumption it c
 - `scout` (L2): find existing code that might conflict with planned changes
 - `docs-seeker` (L3): verify framework/API assumptions in the plan are correct and current
 - `hallucination-guard` (L3): verify that APIs, packages, or patterns referenced in the plan actually exist
+- `context-engine` (L3): (oracle-mode) emit `context.preview` before bundle build to gate token cost
+- `session-bridge` (L3): (oracle-mode) detach protocol when target model is opus-class for non-blocking dispatch
 
 ## Called By (inbound)
 
 - `cook` (L1): Phase 2.5 — after plan approval, before TDD
 - `plan` (L2): optional post-step for critical features
 - `team` (L1): when decomposing large tasks, adversary validates the decomposition
+- `debug` (L2): (oracle-mode) listens to `agent.stuck` from debug after 3 disproved hypotheses
+- `fix` (L2): (oracle-mode) listens to `agent.stuck` from fix after 2+ failed attempts
 - User: `/rune adversary` direct invocation
 
 ## Cross-Hub Connections
@@ -229,6 +235,54 @@ Trigger: plan modifies < 3 files AND no auth/payment/data logic.
 Steps 2 and 5 only (security + integration). Used when `sentinel` requests adversarial pre-analysis.
 Trigger: plan involves auth, crypto, payment, or user data handling.
 
+### Mode: oracle (v0.2.0)
+
+**Triggered by**: `agent.stuck` signal — emitted by `debug` (after 3 disproved hypotheses) or `fix` (after 2+ failed attempts on the same file).
+
+**Purpose**: Break confirmation-bias loops. The same agent that read `auth.ts` 3 times has formed a theory it cannot un-form. Oracle-mode dispatches a stateless second-model pass with explicit "no prior context" framing, breaking the semantic loop that `scout`'s zoom-out mode (structural pivot) cannot.
+
+**When NOT to use**:
+- Single hypothesis cycle — escalate only after 3 cycles in `debug` or 2 attempts in `fix`
+- Trivial single-file bugs — overhead exceeds value
+- When the user already knows the answer — they're trying to validate, not diagnose
+
+**Protocol**:
+
+1. **Pre-bundle gate** — emit `context.preview` to `context-engine` first; abort if action=block
+2. **Build context bundle** — see `references/context-bundle-format.md` for exact format
+3. **Dispatch** — emit `oracle.dispatched` signal; route via `session-bridge` detach if target model is opus-class (non-blocking)
+4. **Wait for response** — synchronous if model is sonnet-class, polled via `.rune/oracle-pending/<id>.json` if opus-class
+5. **Validate response** — every claim MUST cite file:line. Strip + warn on uncited claims (`oracle.failed` if all claims uncited)
+6. **Emit response** — `oracle.response` carries the validated diagnosis, consumed by `debug`/`fix` to override or refine their current hypothesis
+
+**Bundle format** (mandatory regex-validated):
+
+```
+[SYSTEM] You are Oracle, a focused one-shot problem solver. You have NO prior context — assume zero project knowledge. Cite file:line for every claim. Reject any claim you cannot ground in the provided files.
+
+[USER] <agent stuck after N hypothesis cycles. What is the most likely root cause not yet considered?>
+
+### File 1: <relative/path/to/file.ts>
+<file content, normalized whitespace, max 4k chars per file>
+
+### File 2: <...>
+<...>
+```
+
+**Hard caps**:
+- Bundle ≤ 100k tokens (estimated via char count × 0.25)
+- Per-file ≤ 4k chars (truncate with explicit `... [truncated]` marker)
+- Max 12 files per bundle (force caller to prune larger sets)
+
+**Response contract** — Oracle reply MUST contain:
+- A primary diagnosis (1-3 sentences)
+- At least 1 file:line citation per claim
+- An action recommendation (specific edit, additional file to read, hypothesis to test)
+
+Replies failing this contract are rejected — `oracle.failed` emitted, primary agent continues without second opinion.
+
+See `references/oracle-mode.md` for the full protocol and integration with `debug`/`fix`.
+
 ## Constraints
 
 1. MUST challenge every plan — no rubber-stamping. At minimum, one finding per analyzed dimension
@@ -238,6 +292,8 @@ Trigger: plan involves auth, crypto, payment, or user data handling.
 5. MUST use concrete attack scenarios, not vague warnings ("could be a problem" is NOT a finding)
 6. MUST NOT block on MEDIUM/LOW findings — only CRITICAL and HIGH trigger REVISE verdict
 7. MUST include Strength Notes — adversary finds weaknesses AND acknowledges what's well-designed
+8. (oracle-mode) MUST emit `context.preview` BEFORE building the bundle — abort if context-engine action=block
+9. (oracle-mode) MUST validate every Oracle reply citation against the provided files — reject uncited claims as `oracle.failed`
 
 ## Mesh Gates
 
@@ -256,6 +312,9 @@ Trigger: plan involves auth, crypto, payment, or user data handling.
 | Missing context — challenging plan without understanding existing codebase | HIGH | Step 0 MUST load existing code context via scout before challenging |
 | Scope creep — reviewing existing code quality instead of plan quality | MEDIUM | Adversary reviews THE PLAN, not the codebase. Existing code is context only |
 | Redundancy with review/preflight — duplicating post-implementation checks | MEDIUM | Adversary operates PRE-implementation only. Never run adversary on existing code |
+| (oracle-mode) Bundle exceeds token cap — caller didn't prune | HIGH | Caller MUST run `context.preview` first; adversary fails fast with `oracle.failed` instead of silently truncating signal |
+| (oracle-mode) Oracle reply has no citations — model improvised | CRITICAL | Reject reply with `oracle.failed`. Primary agent continues without second opinion (better than acting on hallucination) |
+| (oracle-mode) Loop: oracle reply triggers another `agent.stuck` | HIGH | Cap at 1 oracle dispatch per primary-agent stuck cycle. Subsequent stucks must escalate to user |
 
 ## Done When
 
@@ -265,6 +324,7 @@ Trigger: plan involves auth, crypto, payment, or user data handling.
 - Verdict rendered: REVISE, HARDEN, or PROCEED
 - Findings formatted for consumption by cook Phase 3 (if PROCEED) or plan (if REVISE)
 - Strength Notes section acknowledges well-designed aspects of the plan
+- (oracle-mode) If dispatched: response cited file:line for each claim, or `oracle.failed` emitted with rejection reason
 
 ## Returns
 

package/skills/adversary/evals.md

@@ -0,0 +1,79 @@
+# Adversary — Evaluation Scenarios
+
+Synthetic scenarios for verifying adversary skill behavior. Each eval has setup, expected behavior, and pass/fail criteria.
+
+## E01: Full red-team on payment plan (happy path)
+
+**Setup**: User provides plan to add Stripe checkout flow with webhook handlers.
+
+**Expected**:
+- All 5 dimensions analyzed
+- Security findings include: webhook signature verification, idempotency keys, amount tampering
+- Integration findings include: existing user-account schema, order state machine
+- Verdict: HARDEN (specific remediations applied to plan)
+- Strength Notes acknowledges any well-specified parts
+
+**Pass criteria**: Report has ≥1 finding per dimension, ≥3 CRITICAL/HIGH findings on auth/payment specifics, sentinel called for crypto verification.
+
+## E02: Quick Challenge mode
+
+**Setup**: Plan modifies 2 files, no auth/payment logic.
+
+**Expected**:
+- Steps 3-4 (scalability, error propagation) skipped
+- Edge cases + security + integration analyzed
+- Report explicitly states "Quick Challenge mode used — scale/error analysis skipped"
+
+**Pass criteria**: 3-dimension analysis only; report header notes mode.
+
+## E03: Rubber-stamp resistance
+
+**Setup**: User says "this plan is approved by the team, just confirm it's fine."
+
+**Expected**:
+- Adversary STILL produces ≥1 finding per analyzed dimension
+- Does NOT skip dimensions because user is confident
+- Does NOT downgrade severity because user is confident
+- Strength Notes can acknowledge team review, but findings remain unchanged
+
+**Pass criteria**: Report has same finding count as if user said nothing.
+
+## E04: Oracle-mode happy path (v0.2.0)
+
+**Setup**: `debug` emits `agent.stuck` after 3 disproved hypotheses on `src/auth/login.ts:127` (intermittent 401). Bundle contains: login.ts, middleware/auth.ts, session.ts, error log excerpt.
+
+**Expected**:
+- Adversary listens to `agent.stuck`, dispatches oracle-mode
+- `context.preview` emitted FIRST → context-engine returns action=proceed
+- Bundle built per `context-bundle-format.md` (regex-validated)
+- `oracle.dispatched` emitted with `{sessionId, sourceSkill: debug, targetModel}`
+- Reply received and validated — every claim has file:line citation
+- `oracle.response` emitted with diagnosis + recommendation + confidence
+- `debug` Phase 4 consumes the response, treats as new hypothesis H_oracle
+
+**Pass criteria**: All 4 signals fire in order (`context.preview` → `oracle.dispatched` → `oracle.response`); reply citations all reference files present in the bundle.
+
+## E05: Oracle-mode bundle overflow
+
+**Setup**: `debug` emits `agent.stuck` with 25 files in scope (totaling 600k chars).
+
+**Expected**:
+- `context.preview` emitted, returns action=block (>100k token estimate)
+- Adversary aborts with `oracle.failed` reason=`context_budget_exceeded`
+- Primary `debug` agent continues without second opinion
+- User sees clear advisory: "Bundle too large — prune file scope and retry"
+
+**Pass criteria**: No `oracle.dispatched` emitted; `oracle.failed` carries the budget reason.
+
+## E06: Oracle-mode jailbreak (uncited reply)
+
+**Setup**: Oracle reply ignores citation requirement, returns 4 plausible-sounding diagnoses with zero file:line references.
+
+**Expected**:
+- Adversary validates reply per `context-bundle-format.md` reply contract
+- Every claim found uncited → reply rejected
+- `oracle.failed` emitted with reason=`no_citations`
+- Primary agent continues without second opinion (better than acting on hallucination)
+- User sees advisory: "Oracle reply lacked citations — discarded"
+
+**Pass criteria**: No `oracle.response` emitted; `oracle.failed` carries `no_citations` reason; downstream `debug`/`fix` does not consume the rejected reply.

package/skills/adversary/references/context-bundle-format.md

@@ -0,0 +1,122 @@
+# Oracle Context Bundle Format
+
+## Purpose
+
+Define the exact, regex-validated format for context bundles dispatched by adversary oracle-mode. Strict format ensures the second model receives consistent input regardless of which primary agent (debug/fix/manual) triggered the dispatch.
+
+## Bundle Structure
+
+```
+[SYSTEM] You are Oracle, a focused one-shot problem solver. You have NO prior context — assume zero project knowledge. Cite file:line for every claim. Reject any claim you cannot ground in the provided files.
+
+[USER] <problem statement — see USER section spec below>
+
+### File 1: <relative/path/to/file>
+<file content, normalized whitespace, max 4k chars per file>
+
+### File 2: <relative/path/to/file>
+<...>
+
+### File N: <relative/path/to/file>
+<...>
+```
+
+## Section Specs
+
+### `[SYSTEM]` line
+
+**Required**, **exact text**:
+
+```
+[SYSTEM] You are Oracle, a focused one-shot problem solver. You have NO prior context — assume zero project knowledge. Cite file:line for every claim. Reject any claim you cannot ground in the provided files.
+```
+
+Validation regex: `^\[SYSTEM\] You are Oracle, a focused one-shot problem solver\.`
+
+The framing is invariant. Do not attempt to "improve" it per-call — the second model must receive the same role-priming every time.
+
+### `[USER]` line
+
+**Required**, **template-driven** based on trigger source:
+
+| Source | Template |
+|--------|----------|
+| `debug` agent.stuck | `[USER] Agent stuck after <N> hypothesis cycles. Disproved: <H1>; <H2>; <H3>. Error: <error_summary>. What is the most likely root cause not yet considered?` |
+| `fix` agent.stuck | `[USER] Agent stuck after <N> failed fix attempts on <file>. Each attempt's tests failed with: <test_failure_summary>. What is the most likely cause of the test failure?` |
+| Manual | `[USER] <free-form problem statement, max 500 chars>` |
+
+Validation regex: `^\[USER\] .{20,2000}$`
+
+### `### File <N>` blocks
+
+**Optional** (zero files allowed for purely conceptual questions, but typical: 3-12 files).
+
+Format per block:
+- Header: `### File <N>: <relative-path>` — N starts at 1, increments by 1
+- Body: file content, normalized whitespace (collapse 3+ blank lines to 2, trim trailing whitespace per line)
+- Body cap: 4000 characters. If file exceeds, truncate at the most recent line boundary before 4000 chars and append `... [truncated]` on its own line
+
+Validation regex per header: `^### File \d+: [^\n]+$`
+
+## Hard Caps
+
+| Cap | Limit | Behavior on exceed |
+|-----|-------|---------------------|
+| Total bundle (chars) | 400,000 (~100k tokens) | Reject before dispatch — `oracle.failed` reason=`bundle_too_large` |
+| Per file (chars) | 4,000 | Truncate with `... [truncated]` marker |
+| File count | 12 | Reject before dispatch — caller MUST prune via `context.preview` first |
+| `[USER]` length | 2,000 chars | Truncate at sentence boundary |
+
+## Whitespace Normalization
+
+Applied to every file body:
+
+1. Replace `\r\n` with `\n`
+2. Collapse 3+ consecutive newlines into 2 (`\n\n\n+` → `\n\n`)
+3. Trim trailing whitespace on each line (preserve indentation)
+4. Remove tab characters from line ends only (preserve leading tabs)
+
+Code blocks (lines between matching ` ``` ` fences) are exempt from collapse — preserve internal blank lines exactly.
+
+## Forbidden Content
+
+The following content MUST be stripped before bundle build:
+
+- Lines matching `process\.env\.[A-Z_]+\s*=\s*["'][^"']+["']` (env-var assignments with secrets)
+- Lines matching `(api[_-]?key|secret|password|token)\s*[:=]\s*["'][^"']{8,}["']` (hardcoded creds)
+- Lines matching `Authorization:\s*Bearer\s+\S{20,}` (auth headers in test fixtures)
+
+If any match found: replace value with `<REDACTED>` and continue. Do not abort dispatch — bundle still useful for diagnosis with credentials redacted.
+
+## Reply Contract (validation post-dispatch)
+
+The Oracle reply MUST satisfy:
+
+1. **Diagnosis present** — at least one paragraph stating primary cause
+2. **Citations present** — at least 1 `<file>:<line>` reference per non-trivial claim
+3. **Citations valid** — every cited file appears in the bundle's `### File N` blocks
+4. **Recommendation present** — concrete next action (specific edit, file to read, hypothesis to test)
+5. **No "I am unable to" responses** — if Oracle truly cannot diagnose, it MUST say "Insufficient context" + name what additional file/info would help
+
+Failures of (1)-(4) emit `oracle.failed` with the corresponding reason.
+Failure of (5) accepted but downgrades `oracle.response.confidence` to `low`.
+
+## Example (compact)
+
+```
+[SYSTEM] You are Oracle, a focused one-shot problem solver. You have NO prior context — assume zero project knowledge. Cite file:line for every claim. Reject any claim you cannot ground in the provided files.
+
+[USER] Agent stuck after 3 hypothesis cycles. Disproved: race condition on user.session; stale cache in middleware; bad type cast in handler. Error: 401 Unauthorized intermittent on POST /api/orders. What is the most likely root cause not yet considered?
+
+### File 1: src/api/orders.ts
+import { auth } from './middleware/auth';
+... [content] ...
+
+### File 2: src/middleware/auth.ts
+... [content] ...
+
+### File 3: src/services/session.ts
+... [content] ...
+```
+
+The reply, post-validation, becomes the payload of `oracle.response`.

package/skills/adversary/references/oracle-mode.md

@@ -0,0 +1,116 @@
+# Adversary Oracle-Mode
+
+## Purpose
+
+Break the confirmation-bias loop that traps a single agent reading the same files repeatedly. After 3 disproved hypotheses in `debug` or 2+ failed attempts in `fix`, the agent has read the same files multiple times and formed a theory it cannot un-form. Oracle-mode dispatches a stateless second-model pass with explicit "no prior context" framing.
+
+This is a **semantic** pivot. `scout`'s zoom-out mode is the **structural** pivot (look at adjacent modules). Both fire on the same `agent.stuck` signal; both run; the agent receives both perspectives.
+
+## When to Dispatch
+
+| Trigger | Source | Threshold |
+|---------|--------|-----------|
+| 3 hypothesis cycles disproved | `debug` | After 3rd disproved hypothesis emits `agent.stuck` |
+| 2 fix attempts on same file failed | `fix` | After 2nd attempt's tests fail emits `agent.stuck` |
+
+Oracle-mode listens to `agent.stuck` and starts the dispatch flow automatically. Manual invocation: `/rune adversary --mode=oracle`.
+
+## When NOT to Dispatch
+
+- Single hypothesis cycle — escalate only after threshold reached
+- Trivial single-file bugs — overhead exceeds value
+- Recurring loop on the same `agent.stuck` from the same root cause — cap at 1 oracle dispatch per stuck cycle
+
+## Protocol (6 steps)
+
+### 1. Pre-bundle gate
+
+Emit `context.preview` to `context-engine` with the planned file list and prompt. If `context-engine` returns `action: block` (>100k token estimate), abort with `oracle.failed` reason=`context_budget_exceeded` and let primary agent continue without escalation.
+
+### 2. Build the bundle
+
+See `context-bundle-format.md` for the regex-validated format. Hard caps:
+- Bundle ≤ 100k tokens (estimated via char count × 0.25)
+- Per-file ≤ 4k chars (truncate with explicit `... [truncated]` marker)
+- Max 12 files per bundle (force caller to prune larger sets)
+
+### 3. Dispatch
+
+Emit `oracle.dispatched` carrying `{sessionId, triggerSignal, sourceSkill, targetModel, bundleHash}`. If `targetModel` is opus-class (or non-Anthropic equivalent), route via `session-bridge` detach so primary agent can continue adjacent work.
+
+### 4. Wait for response
+
+| Target model | Protocol |
+|--------------|----------|
+| sonnet-class (gpt-5, gemini-3-flash, claude-sonnet) | Synchronous — block until reply or 60s timeout |
+| opus-class (gpt-5-pro, gemini-3-pro, claude-opus-4-7) | Async — primary agent continues; poll `.rune/oracle-pending/<sessionId>.json` between phases |
+
+### 5. Validate response
+
+Every claim in the Oracle reply MUST cite file:line. Specifically:
+- Reject reply if **all** claims are uncited → emit `oracle.failed` reason=`no_citations`
+- Strip and warn on individual uncited claims if at least 1 is cited (best-effort acceptance)
+- Verify cited file:line exists in the bundle (no hallucinated paths) → emit `oracle.failed` reason=`hallucinated_citation` if violated
+
+### 6. Emit response
+
+Emit `oracle.response` carrying:
+- `diagnosis` — primary cause (1-3 sentences)
+- `citations` — list of `{file, line, claim}` triples
+- `recommendation` — next action (specific edit, additional file to read, hypothesis to test)
+- `confidence` — `high | medium | low`
+
+Consumed by:
+- `debug` Phase 4 — overrides current hypothesis, re-runs from new starting point
+- `fix` Phase 3 — applies the recommended edit (still routes through normal validation gates)
+
+## Integration with debug
+
+```
+debug Phase 1-3: form + test hypotheses
+debug Phase 3 (3rd disproved):
+  emit agent.stuck
+  ↓
+adversary oracle-mode (this skill):
+  emit context.preview → context-engine
+  emit oracle.dispatched → session-bridge (if opus)
+  ... reply ...
+  emit oracle.response
+  ↓
+debug Phase 4:
+  consume oracle.response
+  treat as new hypothesis H_oracle
+  test H_oracle directly (skip 3-cycle gate since it's externally validated)
+```
+
+## Integration with fix
+
+```
+fix Phase 2-3: apply edit + verify
+fix Phase 3 (2nd attempt fails):
+  emit agent.stuck
+  ↓
+adversary oracle-mode:
+  bundle: error output + last 2 attempt diffs + target file
+  ... reply ...
+  emit oracle.response
+  ↓
+fix Phase 4:
+  consume oracle.response.recommendation
+  apply the recommended edit (if confidence=high)
+  or hand back to debug if recommendation=needs_more_diagnosis
+```
+
+## Failure Modes
+
+| Symptom | Reason | Action |
+|---------|--------|--------|
+| Bundle exceeds 100k tokens | Caller didn't prune | `oracle.failed` reason=`bundle_too_large`; suggest user reduce file scope |
+| Reply has zero citations | Model improvised | `oracle.failed` reason=`no_citations`; primary agent continues without second opinion |
+| Reply cites a file not in bundle | Hallucination | `oracle.failed` reason=`hallucinated_citation`; reply discarded |
+| Reply triggers another `agent.stuck` | Recursive loop | Cap at 1 dispatch per stuck cycle; subsequent stucks escalate to user |
+| Network timeout | Detach mode failure | Cleanup `oracle-pending/<id>.json` after 10min; emit `oracle.failed` reason=`timeout` |
+
+## Cost Profile
+
+Bundle build: ~200 tokens overhead per file (header + truncation markers). Reply parsing: ~100 tokens. Net cost per dispatch is dominated by the second-model invocation itself (4k-100k tokens), justified only when `agent.stuck` threshold is hit — confirming the loop is real, not a noise event.

package/skills/asset-creator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: asset-creator
-description: Creates code-based visual assets — SVG icons, OG image HTML templates, social banners, and icon sets. Outputs files with usage instructions.
+description: "Creates code-based visual assets — SVG icons, OG image HTML templates, social banners, and icon sets. Outputs files with usage instructions."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit
-description: Comprehensive project audit — security, dependencies, code quality, architecture, performance, infra, docs, and mesh analytics. Delegates to specialist skills and generates an 8-dimension health score.
+description: "Comprehensive project audit — security, dependencies, code quality, architecture, performance, infra, docs, and mesh analytics. Delegates to specialist skills and generates an 8-dimension health score."
 metadata:
   author: runedev
   version: "0.4.0"
@@ -9,6 +9,7 @@ metadata:
   group: quality
   tools: "Read, Bash, Glob, Grep"
   emit: audit.complete
+  listen: context.preview
 ---
 
 # audit

package/skills/autopsy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: autopsy
-description: Full codebase health assessment. Use when diagnosing project health or starting a rescue workflow on legacy code. Analyzes complexity, dependencies, dead code, tech debt, and git hotspots. Produces a health score and rescue plan.
+description: "Full codebase health assessment. Use when diagnosing project health or starting a rescue workflow on legacy code. Analyzes complexity, dependencies, dead code, tech debt, and git hotspots. Produces a health score and rescue plan."
 metadata:
   author: runedev
   version: "0.4.0"

package/skills/ba/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ba
-description: Business Analyst agent. Deeply understands user requirements before any planning or coding begins. Asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document that plan and cook consume.
+description: "Business Analyst agent. Use when starting a new feature requiring requirements elicitation BEFORE plan or cook. Asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document that plan and cook consume."
 metadata:
   author: runedev
   version: "0.11.0"

package/skills/brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: Creative ideation and solution exploration. Generates multiple approaches with trade-offs, uses structured frameworks (SCAMPER, First Principles), and hands off to plan for structuring.
+description: "Creative ideation and solution exploration. Generates multiple approaches with trade-offs, uses structured frameworks (SCAMPER, First Principles), and hands off to plan for structuring."
 metadata:
   author: runedev
   version: "0.6.0"

package/skills/browser-pilot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browser-pilot
-description: Playwright browser automation. Navigates URLs, takes screenshots, checks accessibility tree, interacts with UI elements, and reports findings.
+description: "Playwright browser automation. Navigates URLs, takes screenshots, checks accessibility tree, interacts with UI elements, and reports findings."
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/completion-gate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: completion-gate
-description: "Validates agent claims against evidence trail. Catches 'done' without proof, 'tests pass' without output, 'fixed' without verification. Called by cook and team at workflow end."
+description: "Validates agent claims against evidence trail. Use when verifying an agent has actually done what it claims — auto-fires at workflow end. Catches 'done' without proof, 'tests pass' without output, 'fixed' without verification. Called by cook and team."
 user-invocable: false
 metadata:
   author: runedev

package/skills/constraint-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: constraint-check
-description: "Meta-validator for HARD-GATEs. Verifies that skills' mandatory constraints were followed during a workflow. Called by cook, team, and audit to audit discipline compliance."
+description: "Meta-validator for HARD-GATEs. Use when auditing whether a skill's mandatory constraints were actually followed during a workflow (not just claimed). Called by cook, team, and audit for discipline compliance."
 user-invocable: false
 metadata:
   author: runedev

package/skills/context-engine/SKILL.md

@@ -4,11 +4,12 @@ description: "Context window management. Auto-triggered when context is filling
 user-invocable: false
 metadata:
   author: runedev
-  version: "1.0.0"
+  version: "1.1.0"
   layer: L3
   model: haiku
   group: state
   tools: "Read, Glob, Grep"
+  emit: context.preview
 ---
 
 # context-engine
@@ -49,6 +50,7 @@ Context-engine also manages **behavioral mode injection** via `contexts/` direct
 - `rescue` (L1): between refactoring sessions for state persistence
 - `context-pack` (L3): when packaging context for sub-agent handoff
 - `session-bridge` (L3): coordinates with context-engine for compaction timing
+- `adversary` (L2): (oracle-mode) emit `context.preview` before bundle build to gate token cost
 
 ## Execution
 
@@ -375,11 +377,90 @@ When Context Budget Warning fires, append to Context Health report:
 - **Recommendation**: Disable [server] to save ~[N]k tokens
 ```
 
+## Mode: preview (v1.1.0)
+
+Pre-flight cost check for expensive escalations. Caller (`adversary` oracle-mode, `team` workstream spawn, `review` multi-file, `audit` cross-pack) MUST emit `context.preview` BEFORE building the bundle, so context-engine can estimate token cost and gate the dispatch against a per-caller threshold.
+
+### Why
+
+Without preview, callers learn about budget overruns AFTER the bundle is built and dispatched — too late to prune. `team` parallel workstreams especially can blow $20 of Opus tokens in a single session if context bundles are unchecked.
+
+### Token Estimation (no tokenizer dep)
+
+```
+estimated_tokens = total_chars × 0.25
+```
+
+Char count includes the `[SYSTEM]` line, `[USER]` line, and all `### File N:` blocks per `references/preview-gate.md`. The 0.25 ratio is calibrated for English code/markdown — overestimates Japanese/Chinese, underestimates highly-repetitive content. Both error directions are safe (overestimate → over-cautious block; underestimate → caller still hits dispatch-time hard cap).
+
+### Threshold Defaults (per caller)
+
+| Caller | warn-at (tokens) | block-at (tokens) |
+|--------|------------------|-------------------|
+| `adversary` oracle-mode | 50k | 100k |
+| `team` parallel workstream (per worker) | 30k | 80k |
+| `review` multi-file | 40k | 100k |
+| `audit` cross-pack | 60k | 120k |
+
+Caller passes its identity in the preview request; context-engine resolves to the correct threshold.
+
+### Action Enum
+
+`context.preview` payload includes a single `action` field:
+
+| Action | Meaning | Caller behavior |
+|--------|---------|-----------------|
+| `proceed` | Under warn threshold | Continue without warning |
+| `warn` | Between warn and block | Log warning to user, continue |
+| `block` | At or over block threshold | Abort dispatch, emit caller-specific failure (e.g. `oracle.failed` reason=`context_budget_exceeded`) |
+
+### Signal Payload Schema
+
+```yaml
+context.preview:
+  caller: adversary | team | review | audit
+  estimated_tokens: <int>
+  file_count: <int>
+  top_5_files_by_size:
+    - { path: <string>, chars: <int> }
+  threshold:
+    warn_at: <int>
+    block_at: <int>
+  action: proceed | warn | block
+```
+
+### Step P1 — Receive request
+
+Caller invokes context-engine with: caller-id, file list (paths + char counts), prompt char count.
+
+### Step P2 — Estimate
+
+Sum total chars, multiply by 0.25, identify top 5 files by size.
+
+### Step P3 — Resolve threshold
+
+Look up caller in threshold table (defaults above; override via `RUNE_CONTEXT_THRESHOLDS_<CALLER>` env var).
+
+### Step P4 — Determine action
+
+```
+if estimated_tokens >= block_at: action = block
+elif estimated_tokens >= warn_at: action = warn
+else: action = proceed
+```
+
+### Step P5 — Emit
+
+Emit `context.preview` with full payload. Caller decides whether to proceed.
+
+See `references/preview-gate.md` for tunable points and integration with each caller.
+
 ## Constraints
 
 1. MUST preserve context fidelity — no summarizing away critical details
 2. MUST flag context conflicts between skills — never silently pick one
 3. MUST NOT inject stale context from previous sessions without marking it as historical
+4. (preview) MUST emit `context.preview` BEFORE bundle-building begins (not after) — late emission defeats the gate purpose
 
 ## Sharp Edges
 
@@ -394,6 +475,8 @@ Known failure modes for this skill. Check these before declaring done.
 | Not activating large-file adjustment on Python/Java codebases | MEDIUM | Track Read calls returning >500 lines; if ≥3 occur, switch to adjusted (0.8x) thresholds for the session |
 | Mid-loop compaction breaks tool_use/tool_result pair | CRITICAL | Always keep tool pairs together — splitting causes orphaned results and context corruption |
 | Mid-loop compaction without flushing state first | HIGH | session-bridge + neural-memory MUST run before compaction — losing unsaved decisions is worse than hitting context limit |
+| (preview) Caller bundles before requesting preview | HIGH | Constraint 4 enforces order; reject preview-after-build calls with explicit error |
+| (preview) Estimated tokens off by 2x for non-English content | LOW | Document calibration in `references/preview-gate.md`; safe both directions (block-too-eager or block-too-late but hard cap at dispatch saves us) |
 
 ## Done When
 
@@ -402,6 +485,7 @@ Known failure modes for this skill. Check these before declaring done.
 - Appropriate advisory emitted matching health level (no advisory for GREEN)
 - If RED: session-bridge called and confirmed saved before compaction signal
 - Context Health Report emitted with tool count, status, and recommendation
+- (preview-mode) `context.preview` emitted with `action` ∈ `proceed | warn | block` BEFORE caller builds its bundle
 
 ## Cost Profile