@rune-kit/rune 2.14.0 → 2.16.0

package/compiler/__tests__/oracle-pending-schema.test.js

@@ -0,0 +1,209 @@
+/**
+ * Oracle-pending record schema (v2.15+) — verify the JSON schema written by
+ * session-bridge detach mode. The pending file in .rune/oracle-pending/<id>.json
+ * is the rendezvous point between adversary (dispatcher) and primary agent
+ * (reattach poller).
+ *
+ * Validates:
+ *   - Required fields present + correct type
+ *   - sessionId pattern: oracle-<unix-ms>-<rand>
+ *   - bundleHash pattern: sha256:<hex>
+ *   - status enum: pending | complete | failed
+ *   - sourceSkill enum: debug | fix | manual
+ *   - Idempotency: same bundleHash returns same sessionId
+ *   - Timeout transition: pending → failed when now > timeoutAt
+ *   - Cleanup: records older than 24h dropped
+ */
+
+import assert from 'node:assert';
+import { describe, test } from 'node:test';
+
+const SESSION_ID_PATTERN = /^oracle-\d+-[a-z0-9]+$/;
+const BUNDLE_HASH_PATTERN = /^sha256:[a-f0-9]{8,64}$/;
+const STATUS_VALUES = new Set(['pending', 'complete', 'failed']);
+const SOURCE_SKILL_VALUES = new Set(['debug', 'fix', 'manual']);
+
+function isIso8601(s) {
+  if (typeof s !== 'string') return false;
+  const d = new Date(s);
+  return !Number.isNaN(d.getTime()) && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(s);
+}
+
+function validatePendingRecord(rec) {
+  const errors = [];
+  if (typeof rec.sessionId !== 'string' || !SESSION_ID_PATTERN.test(rec.sessionId)) errors.push('invalid_sessionId');
+  if (!isIso8601(rec.dispatchedAt)) errors.push('invalid_dispatchedAt');
+  if (typeof rec.triggerSignal !== 'string') errors.push('invalid_triggerSignal');
+  if (!SOURCE_SKILL_VALUES.has(rec.sourceSkill)) errors.push('invalid_sourceSkill');
+  if (typeof rec.targetModel !== 'string') errors.push('invalid_targetModel');
+  if (typeof rec.bundleHash !== 'string' || !BUNDLE_HASH_PATTERN.test(rec.bundleHash))
+    errors.push('invalid_bundleHash');
+  if (!STATUS_VALUES.has(rec.status)) errors.push('invalid_status');
+  if (!isIso8601(rec.timeoutAt)) errors.push('invalid_timeoutAt');
+
+  // Conditional fields
+  if (rec.status === 'complete') {
+    if (rec.responseId === null || typeof rec.responseId !== 'string') errors.push('missing_responseId_when_complete');
+    if (rec.responseExcerpt === null || typeof rec.responseExcerpt !== 'string')
+      errors.push('missing_responseExcerpt_when_complete');
+    if (typeof rec.responseExcerpt === 'string' && rec.responseExcerpt.length > 500)
+      errors.push('responseExcerpt_too_long');
+  }
+  if (rec.status === 'pending') {
+    if (rec.responseId !== null) errors.push('responseId_must_be_null_when_pending');
+    if (rec.responseExcerpt !== null) errors.push('responseExcerpt_must_be_null_when_pending');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function timeoutCheck(record, now) {
+  if (record.status !== 'pending') return record;
+  if (new Date(now).getTime() >= new Date(record.timeoutAt).getTime()) {
+    return { ...record, status: 'failed' };
+  }
+  return record;
+}
+
+function cleanupExpired(records, now, ttlMs = 24 * 60 * 60 * 1000) {
+  return records.filter((r) => new Date(now).getTime() - new Date(r.dispatchedAt).getTime() <= ttlMs);
+}
+
+function buildPending(overrides = {}) {
+  return {
+    sessionId: 'oracle-1714234500-abc123',
+    dispatchedAt: '2026-04-27T12:34:56Z',
+    triggerSignal: 'agent.stuck',
+    sourceSkill: 'debug',
+    targetModel: 'claude-opus-4-7',
+    bundleHash: 'sha256:9f3a4b5c6d7e8f90',
+    status: 'pending',
+    timeoutAt: '2026-04-27T12:44:56Z',
+    responseId: null,
+    responseExcerpt: null,
+    ...overrides,
+  };
+}
+
+describe('Pending record schema', () => {
+  test('valid pending record passes', () => {
+    const result = validatePendingRecord(buildPending());
+    assert.strictEqual(result.valid, true, `unexpected errors: ${result.errors.join(', ')}`);
+  });
+
+  test('valid complete record passes', () => {
+    const result = validatePendingRecord(
+      buildPending({
+        status: 'complete',
+        responseId: 'resp_xyz789',
+        responseExcerpt: 'Root cause: missing await on session refresh in middleware/auth.ts:47',
+      }),
+    );
+    assert.strictEqual(result.valid, true, `unexpected errors: ${result.errors.join(', ')}`);
+  });
+
+  test('valid failed record passes', () => {
+    const result = validatePendingRecord(buildPending({ status: 'failed' }));
+    assert.strictEqual(result.valid, true);
+  });
+
+  test('rejects invalid sessionId pattern', () => {
+    const result = validatePendingRecord(buildPending({ sessionId: 'NotAnOracleId' }));
+    assert.ok(result.errors.includes('invalid_sessionId'));
+  });
+
+  test('rejects invalid bundleHash pattern', () => {
+    const result = validatePendingRecord(buildPending({ bundleHash: 'md5:abc123' }));
+    assert.ok(result.errors.includes('invalid_bundleHash'));
+  });
+
+  test('rejects unknown status', () => {
+    const result = validatePendingRecord(buildPending({ status: 'in_flight' }));
+    assert.ok(result.errors.includes('invalid_status'));
+  });
+
+  test('rejects unknown sourceSkill', () => {
+    const result = validatePendingRecord(buildPending({ sourceSkill: 'review' }));
+    assert.ok(result.errors.includes('invalid_sourceSkill'));
+  });
+
+  test('complete record without responseId is invalid', () => {
+    const result = validatePendingRecord(buildPending({ status: 'complete' }));
+    assert.ok(result.errors.includes('missing_responseId_when_complete'));
+    assert.ok(result.errors.includes('missing_responseExcerpt_when_complete'));
+  });
+
+  test('responseExcerpt > 500 chars rejected', () => {
+    const result = validatePendingRecord(
+      buildPending({ status: 'complete', responseId: 'r', responseExcerpt: 'x'.repeat(501) }),
+    );
+    assert.ok(result.errors.includes('responseExcerpt_too_long'));
+  });
+
+  test('pending record with responseId set is invalid', () => {
+    const result = validatePendingRecord(buildPending({ responseId: 'r1' }));
+    assert.ok(result.errors.includes('responseId_must_be_null_when_pending'));
+  });
+});
+
+describe('Idempotency', () => {
+  test('same bundleHash returns same sessionId on duplicate dispatch', () => {
+    const existing = buildPending({ sessionId: 'oracle-1714234500-abc' });
+    const inbox = [existing];
+
+    const dispatch = (bundleHash) => {
+      const match = inbox.find((r) => r.bundleHash === bundleHash && r.status === 'pending');
+      if (match) return match.sessionId;
+      const newId = `oracle-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      inbox.push(buildPending({ sessionId: newId, bundleHash }));
+      return newId;
+    };
+
+    const id1 = dispatch(existing.bundleHash);
+    const id2 = dispatch(existing.bundleHash);
+    assert.strictEqual(id1, id2);
+    assert.strictEqual(id1, existing.sessionId);
+  });
+});
+
+describe('Timeout transition', () => {
+  test('pending record becomes failed when now > timeoutAt', () => {
+    const record = buildPending({ timeoutAt: '2026-04-27T12:00:00Z' });
+    const after = timeoutCheck(record, '2026-04-27T13:00:00Z');
+    assert.strictEqual(after.status, 'failed');
+  });
+
+  test('pending stays pending when now < timeoutAt', () => {
+    const record = buildPending({ timeoutAt: '2026-04-27T13:00:00Z' });
+    const after = timeoutCheck(record, '2026-04-27T12:30:00Z');
+    assert.strictEqual(after.status, 'pending');
+  });
+
+  test('complete records not affected by timeout check', () => {
+    const record = buildPending({
+      status: 'complete',
+      responseId: 'r',
+      responseExcerpt: 'done',
+      timeoutAt: '2026-04-27T12:00:00Z',
+    });
+    const after = timeoutCheck(record, '2026-04-27T20:00:00Z');
+    assert.strictEqual(after.status, 'complete');
+  });
+});
+
+describe('Cleanup orphaned records', () => {
+  test('records >24h old are dropped', () => {
+    const records = [
+      buildPending({ sessionId: 'oracle-1-fresh', dispatchedAt: '2026-04-27T11:00:00Z' }),
+      buildPending({ sessionId: 'oracle-2-stale', dispatchedAt: '2026-04-25T11:00:00Z' }),
+    ];
+    const remaining = cleanupExpired(records, '2026-04-27T12:00:00Z');
+    assert.strictEqual(remaining.length, 1);
+    assert.strictEqual(remaining[0].sessionId, 'oracle-1-fresh');
+  });
+
+  test('records <24h old are kept', () => {
+    const records = [buildPending({ dispatchedAt: '2026-04-26T13:00:00Z' })];
+    const remaining = cleanupExpired(records, '2026-04-27T12:00:00Z');
+    assert.strictEqual(remaining.length, 1);
+  });
+});

package/compiler/__tests__/skill-description-quality.test.js

@@ -0,0 +1,149 @@
+/**
+ * Skill description quality (v2.15+) — lint validation that every SKILL.md
+ * description is YAML-safe, well-formed, and ambiguous-name skills carry an
+ * explicit "Use when…" routing hint.
+ *
+ * Validates:
+ *   - All descriptions are double-quoted (YAML safety)
+ *   - All descriptions end with `.` or `?`
+ *   - All descriptions are 30-500 chars
+ *   - Specific ambiguous-name skills include "Use when…" clause
+ */
+
+import assert from 'node:assert';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { describe, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = resolve(__dirname, '../..', 'skills');
+
+function listSkills() {
+  return readdirSync(SKILLS_DIR).filter((name) => {
+    const p = join(SKILLS_DIR, name);
+    return statSync(p).isDirectory() && readdirSync(p).includes('SKILL.md');
+  });
+}
+
+function readDescriptionLine(name) {
+  const text = readFileSync(join(SKILLS_DIR, name, 'SKILL.md'), 'utf8');
+  const lines = text.split(/\r?\n/);
+  for (const line of lines.slice(0, 20)) {
+    if (line.startsWith('description:')) return line;
+  }
+  return null;
+}
+
+function extractDescriptionValue(line) {
+  const m = line.match(/^description:\s+"(.+)"\s*$/);
+  if (m) return m[1].replace(/\\"/g, '"');
+  return null;
+}
+
+const AMBIGUOUS_SKILLS_REQUIRING_USE_WHEN = [
+  'ba',
+  'completion-gate',
+  'constraint-check',
+  'doc-processor',
+  'integrity-check',
+  'logic-guardian',
+  'onboard',
+  'preflight',
+  'sentinel-env',
+  'watchdog',
+  'worktree',
+  'hallucination-guard',
+  'mcp-builder',
+];
+
+describe('Skill description format', () => {
+  test('every description is double-quoted (YAML-safe)', () => {
+    const skills = listSkills();
+    const violations = [];
+    for (const name of skills) {
+      const line = readDescriptionLine(name);
+      if (!line) {
+        violations.push(`${name}: no description line found`);
+        continue;
+      }
+      if (!line.match(/^description:\s+"/)) {
+        violations.push(`${name}: description is not double-quoted`);
+      }
+    }
+    assert.strictEqual(violations.length, 0, `Unquoted descriptions:\n${violations.join('\n')}`);
+  });
+
+  test('every description ends with terminal punctuation', () => {
+    const skills = listSkills();
+    const violations = [];
+    for (const name of skills) {
+      const line = readDescriptionLine(name);
+      const val = extractDescriptionValue(line);
+      if (!val) continue;
+      if (!val.match(/[.?]$/)) {
+        violations.push(`${name}: description does not end with . or ?`);
+      }
+    }
+    assert.strictEqual(violations.length, 0, `Bad endings:\n${violations.join('\n')}`);
+  });
+
+  test('every description is 30-500 chars', () => {
+    const skills = listSkills();
+    const violations = [];
+    for (const name of skills) {
+      const line = readDescriptionLine(name);
+      const val = extractDescriptionValue(line);
+      if (!val) continue;
+      if (val.length < 30) violations.push(`${name}: description too short (${val.length} chars)`);
+      if (val.length > 500) violations.push(`${name}: description too long (${val.length} chars)`);
+    }
+    assert.strictEqual(violations.length, 0, `Length violations:\n${violations.join('\n')}`);
+  });
+});
+
+describe('Ambiguous-name skills include "Use when…" routing hint', () => {
+  test('all 13 ambiguous-name skills explicitly state "Use when…"', () => {
+    const violations = [];
+    for (const name of AMBIGUOUS_SKILLS_REQUIRING_USE_WHEN) {
+      const line = readDescriptionLine(name);
+      const val = extractDescriptionValue(line);
+      if (!val) {
+        violations.push(`${name}: description not parseable`);
+        continue;
+      }
+      if (!/Use when/i.test(val)) {
+        violations.push(`${name}: missing "Use when…" clause`);
+      }
+    }
+    assert.strictEqual(violations.length, 0, `Ambiguous-name skills missing "Use when…":\n${violations.join('\n')}`);
+  });
+});
+
+describe('Description integrity', () => {
+  test('YAML escape sequences are well-formed (no orphan \\")', () => {
+    const skills = listSkills();
+    const violations = [];
+    for (const name of skills) {
+      const line = readDescriptionLine(name);
+      if (!line) continue;
+      // Parse the quoted value: count unescaped quotes inside the value
+      const inner = line.replace(/^description:\s+"/, '').replace(/"\s*$/, '');
+      // Every \" should be escaping a quote; bare " inside is invalid
+      let i = 0;
+      let bareQuotes = 0;
+      while (i < inner.length) {
+        if (inner[i] === '\\' && inner[i + 1] === '"') {
+          i += 2;
+          continue;
+        }
+        if (inner[i] === '"') bareQuotes++;
+        i++;
+      }
+      if (bareQuotes > 0) {
+        violations.push(`${name}: ${bareQuotes} unescaped " inside description value`);
+      }
+    }
+    assert.strictEqual(violations.length, 0, `Bare quotes:\n${violations.join('\n')}`);
+  });
+});

package/compiler/adapters/antigravity.js

@@ -8,10 +8,22 @@
  * Antigravity project context: AGENTS.md (+ CLAUDE.md fallback)
  * Antigravity skills dir: .agents/skills/
  * Antigravity skill format: .agents/skills/{name}/SKILL.md
+ *
+ * MODEL TIER MAPPING (v2.15+):
+ * Skill frontmatter `model: opus|sonnet|haiku` (Anthropic naming) is
+ * translated to Gemini provider-correct model names. Antigravity supports
+ * both Gemini and Claude — defaulting to Gemini family since it is the
+ * native model. Unknown tier values pass through.
  */
 
 import { BRANDING_FOOTER } from '../transforms/branding.js';
 
+const MODEL_MAP = {
+  opus: 'gemini-3-pro',
+  sonnet: 'gemini-3-flash',
+  haiku: 'gemini-3-flash-lite',
+};
+
 const TOOL_MAP = {
   Read: 'read the file',
   Write: 'write/create the file',
@@ -46,7 +58,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/claude.js

@@ -2,6 +2,10 @@
  * Claude Code Adapter (Passthrough)
  *
  * No transformation needed — source IS the output.
+ *
+ * MODEL TIER MAPPING (v2.15+):
+ * No-op. Claude Code's Anthropic backend understands `model: opus|sonnet|haiku`
+ * natively, so no translation is required (unlike codex/antigravity/opencode).
  */
 
 export default {

package/compiler/adapters/codex.js

@@ -8,10 +8,21 @@
  * Codex project context: AGENTS.md (equivalent to CLAUDE.md)
  * Codex skills dir: .codex/skills/
  * Codex skill format: .codex/skills/{name}/SKILL.md
+ *
+ * MODEL TIER MAPPING (v2.15+):
+ * Skill frontmatter `model: opus|sonnet|haiku` (Anthropic naming) is
+ * translated to Codex/OpenAI provider-correct model names so the field
+ * is meaningful in the compiled output. Unknown tier values pass through.
  */
 
 import { BRANDING_FOOTER } from '../transforms/branding.js';
 
+const MODEL_MAP = {
+  opus: 'gpt-5-pro',
+  sonnet: 'gpt-5',
+  haiku: 'gpt-5-mini',
+};
+
 const TOOL_MAP = {
   Read: 'read the file',
   Write: 'write/create the file',
@@ -47,7 +58,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/cursor.js

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

package/compiler/adapters/generic.js

@@ -3,10 +3,21 @@
  *
  * For unknown or future platforms. Emits to .ai/rules/ directory.
  * Uses the most portable format possible.
+ *
+ * MODEL TIER MAPPING (v2.15+):
+ * Provider-agnostic — emits semantic tier hints in the markdown header.
+ * Skill frontmatter `model: opus|sonnet|haiku` is translated to
+ * `tier:heavy|mid|light`. The consuming platform resolves the tier.
  */
 
 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',
@@ -37,7 +48,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/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,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.14.0",
+  "version": "2.16.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": {
@@ -16,6 +16,7 @@
     "format": "biome format --write .",
     "ci": "biome check . && node --test compiler/__tests__/*.test.js scripts/__tests__/*.test.js && node compiler/bin/rune.js doctor",
     "version-check": "node scripts/version-sync-check.js",
+    "version-bump": "node scripts/bump-version.js",
     "prepublishOnly": "node scripts/version-sync-check.js"
   },
   "keywords": [