@rune-kit/rune 2.13.0 → 2.15.0

package/compiler/adapters/openclaw.js

@@ -26,10 +26,22 @@
  *
  * Reference codex-imagen repo (darkamenosa/codex-imagen) documents the
  * de-facto in-the-wild convention this adapter formalizes.
+ *
+ * MODEL TIER MAPPING (v2.15+):
+ * OpenClaw is provider-agnostic — emits semantic tier hints in the
+ * markdown header. Skill frontmatter `model: opus|sonnet|haiku` is
+ * translated to `tier:heavy|mid|light`. The OpenClaw runtime resolves
+ * the tier to its configured provider model.
  */
 
 import { BRANDING_FOOTER } from '../transforms/branding.js';
 
+const MODEL_MAP = {
+  opus: 'tier:heavy',
+  sonnet: 'tier:mid',
+  haiku: 'tier:light',
+};
+
 const TOOL_MAP = {
   Read: 'read_file',
   Write: 'write_file',
@@ -60,7 +72,9 @@ export default {
   },
 
   generateHeader(skill) {
-    return `# rune-${skill.name}\n\n> Rune ${skill.layer} Skill | ${skill.group}\n\n`;
+    const translatedModel = skill.model ? MODEL_MAP[skill.model] || skill.model : null;
+    const modelSuffix = translatedModel ? ` | model: ${translatedModel}` : '';
+    return `# rune-${skill.name}\n\n> Rune ${skill.layer} Skill | ${skill.group}${modelSuffix}\n\n`;
   },
 
   generateFooter() {

package/compiler/adapters/opencode.js

@@ -16,10 +16,22 @@
  *
  * @see https://opencode.ai/docs/skills/
  * @see https://opencode.ai/docs/agents/
+ *
+ * MODEL TIER MAPPING (v2.15+):
+ * OpenCode is provider-agnostic — emits semantic tier hints rather than
+ * concrete model names. Skill frontmatter `model: opus|sonnet|haiku` is
+ * translated to `tier:heavy|mid|light`. The OpenCode IDE resolves the
+ * tier to its configured provider model.
  */
 
 import { BRANDING_FOOTER } from '../transforms/branding.js';
 
+const MODEL_MAP = {
+  opus: 'tier:heavy',
+  sonnet: 'tier:mid',
+  haiku: 'tier:light',
+};
+
 const TOOL_MAP = {
   Read: 'read the file',
   Write: 'write/create the file',
@@ -55,7 +67,11 @@ export default {
 
   generateHeader(skill) {
     const desc = (skill.description || '').replace(/"/g, '\\"');
-    return ['---', `name: rune-${skill.name}`, `description: "${desc}"`, '---', '', ''].join('\n');
+    const lines = ['---', `name: rune-${skill.name}`, `description: "${desc}"`];
+    const translatedModel = skill.model ? MODEL_MAP[skill.model] || skill.model : null;
+    if (translatedModel) lines.push(`model: ${translatedModel}`);
+    lines.push('---', '', '');
+    return lines.join('\n');
   },
 
   generateFooter() {

package/compiler/adapters/windsurf.js

@@ -3,6 +3,10 @@
  *
  * Emits .md rule files for .windsurf/rules/ directory.
  * Uses prose references for cross-skill mesh (no @file support).
+ *
+ * MODEL TIER MAPPING (v2.15+):
+ * No-op. Windsurf's Anthropic API integration understands `model: opus|sonnet|haiku`
+ * natively. No translation required.
  */
 
 import { BRANDING_FOOTER } from '../transforms/branding.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.13.0",
-  "description": "62-skill mesh for AI coding assistants — runtime auto-discipline via native hooks (Claude/Cursor/Windsurf/Antigravity), 5-layer architecture, 215+ connections, multi-platform compiler.",
+  "version": "2.15.0",
+  "description": "63-skill mesh for AI coding assistants — runtime auto-discipline via native hooks (Claude/Cursor/Windsurf/Antigravity), 5-layer architecture, 215+ connections, multi-platform compiler.",
   "type": "module",
   "bin": {
     "rune": "./compiler/bin/rune.js"

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
@@ -30,6 +31,7 @@ Comprehensive project health audit across 8 dimensions (7 project + 1 mesh analy
 - `dependency-doctor` (L3): Phase 1 — vulnerability scan and outdated dependency check
 - `sentinel` (L2): Phase 2 — security audit (OWASP Top 10, secrets, config)
 - `autopsy` (L2): Phase 3 — code quality and complexity assessment
+- `improve-architecture` (L2): Phase 3.5 — architecture sub-score (depth / leverage / locality across top modules)
 - `perf` (L2): Phase 4 — performance regression check
 - `db` (L2): Phase 5 — database health dimension (schema, migrations, indexes)
 - `journal` (L3): record audit date, overall score, and verdict

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"