@rune-kit/rune 2.22.0 → 2.22.2

package/README.md

@@ -83,9 +83,9 @@ _Methodology: Claude Code CLI headless mode (`claude -p --output-format json`),
 
 ---
 
-## What's New (v2.22.0 — Convergence, Dogfooded)
+## What's New (v2.22.2 — Convergence, Dogfooded)
 
-> **v2.22.0 (2026-07-03):** The v2.21.0 gates went through a live-fire dogfood: fresh executor agents (zero author context) ran `converge` and `verification` Level 3.5 against a fixture with a dead Submit button, a handler-less Export button, a navigation-anchor decoy, and a declared placeholder. **Both gates caught the dead button with file:line evidence and zero false positives** — and the 16 ambiguities the executors reported became spec fixes: converge v0.2.0 adds a `deferred-debt` class (declared design debt can no longer force a false escalation), a `Plan Claims vs Reality` section (tasks marked `[x]` whose code doesn't exist — surfaced first-class), and derived story verdicts; verification v0.7.0 gets FAIL-dominates precedence, per-route reverse checks, and server/static entry-point exemptions. The dogfood fixture itself shipped as the seed of **`npm run eval`** — a behavioral eval harness that runs a fresh headless agent against fixture repos and asserts outcomes, because structural validation can't prove a skill makes an agent behave. Pro `autopilot` v1.6.0 now explicitly runs Phase 6.5 CONVERGE in autonomous mode.
+> **v2.22.2 (2026-07-04):** Patch: `rune setup` now installs tier skills into the Claude Code PLUGIN CACHE (newest version dir) instead of the executing package's own root — npx runs were copying Pro skills into npx's ephemeral cache (invisible to the plugin runtime, 'Unknown skill: rune:autopilot' returned), and source-checkout runs polluted the git tree. **v2.22.1:** tier-hook loader accepts PreCompact + SessionStart lifecycle events — required by Pro hooks v1.2.0 (context-reset). **v2.22.0:** The v2.21.0 gates went through a live-fire dogfood: fresh executor agents (zero author context) ran `converge` and `verification` Level 3.5 against a fixture with a dead Submit button, a handler-less Export button, a navigation-anchor decoy, and a declared placeholder. **Both gates caught the dead button with file:line evidence and zero false positives** — and the 16 ambiguities the executors reported became spec fixes: converge v0.2.0 adds a `deferred-debt` class (declared design debt can no longer force a false escalation), a `Plan Claims vs Reality` section (tasks marked `[x]` whose code doesn't exist — surfaced first-class), and derived story verdicts; verification v0.7.0 gets FAIL-dominates precedence, per-route reverse checks, and server/static entry-point exemptions. The dogfood fixture itself shipped as the seed of **`npm run eval`** — a behavioral eval harness that runs a fresh headless agent against fixture repos and asserts outcomes, because structural validation can't prove a skill makes an agent behave. Pro `autopilot` v1.6.0 now explicitly runs Phase 6.5 CONVERGE in autonomous mode.
 
 ### Previous (v2.21.0 — Convergence)
 

package/compiler/__tests__/hooks-tiers.test.js

@@ -161,6 +161,21 @@ describe('validateManifest', () => {
     });
     assert.strictEqual(m.entries[0].matcher, null);
   });
+
+  test('accepts PreCompact and SessionStart lifecycle events without matcher', () => {
+    // Pro hooks manifest v1.2.0 wires context-reset on both — Free must load it (was rejected pre-v2.22.1)
+    const m = validateManifest({
+      tier: 'pro',
+      entries: [
+        { id: 'context-reset-precompact', event: 'PreCompact', command: 'node context-reset.cjs' },
+        { id: 'context-reset-sessionstart', event: 'SessionStart', command: 'node context-reset.cjs' },
+      ],
+    });
+    assert.strictEqual(m.entries.length, 2);
+    assert.strictEqual(m.entries[0].event, 'PreCompact');
+    assert.strictEqual(m.entries[0].matcher, null);
+    assert.strictEqual(m.entries[1].event, 'SessionStart');
+  });
 });
 
 describe('loadTierManifest + locateTierManifest', () => {

package/compiler/__tests__/setup.test.js

@@ -5,7 +5,13 @@ import { platform as osPlatform, tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, test } from 'node:test';
 import { resolveTier } from '../commands/hooks/tiers.js';
-import { detectTiers, formatSetupResult, installTierSkills, runSetup } from '../commands/setup.js';
+import {
+  detectTiers,
+  formatSetupResult,
+  installTierSkills,
+  resolveSkillInstallRoot,
+  runSetup,
+} from '../commands/setup.js';
 
 let tmpRoot;
 
@@ -366,6 +372,9 @@ describe('runSetup — Pro skill installation (regression: rune:autopilot Unknow
       projectRoot,
       runeRoot,
       args: { here: true, preset: 'gentle', tier: 'pro' },
+      // Pin the install target — without this, resolveSkillInstallRoot would
+      // target the REAL plugin cache on dev machines (test side-effect).
+      skillTarget: runeRoot,
     });
 
     assert.deepStrictEqual(result.tiers, ['pro']);
@@ -481,3 +490,43 @@ describe('formatSetupResult', () => {
     assert.match(out, /⚠ \.\.\/escape: rejected: unsafe directory name/);
   });
 });
+
+describe('resolveSkillInstallRoot', () => {
+  let home;
+
+  beforeEach(async () => {
+    home = await mkdtemp(path.join(tmpdir(), 'rune-home-'));
+  });
+
+  afterEach(async () => {
+    await rm(home, { recursive: true, force: true });
+  });
+
+  test('targets the NEWEST plugin-cache version dir when the cache exists', async () => {
+    // npx/source-checkout executions must NOT install into their own runeRoot
+    // when a plugin cache exists — the plugin runtime only reads the cache.
+    const cache = path.join(home, '.claude', 'plugins', 'cache', 'rune-kit', 'rune');
+    await mkdir(path.join(cache, '2.17.1', 'skills'), { recursive: true });
+    await mkdir(path.join(cache, '2.22.1', 'skills'), { recursive: true });
+    await mkdir(path.join(cache, '2.9.0', 'skills'), { recursive: true });
+
+    const target = resolveSkillInstallRoot('/some/npx/ephemeral/root', { homedir: home });
+    assert.strictEqual(target.source, 'plugin-cache');
+    assert.strictEqual(target.root, path.join(cache, '2.22.1'));
+  });
+
+  test('ignores cache version dirs without a skills/ folder', async () => {
+    const cache = path.join(home, '.claude', 'plugins', 'cache', 'rune-kit', 'rune');
+    await mkdir(path.join(cache, '2.22.1', 'skills'), { recursive: true });
+    await mkdir(path.join(cache, '2.23.0'), { recursive: true }); // half-installed, no skills/
+
+    const target = resolveSkillInstallRoot('/fallback', { homedir: home });
+    assert.strictEqual(target.root, path.join(cache, '2.22.1'));
+  });
+
+  test('falls back to runeRoot when no plugin cache exists', async () => {
+    const target = resolveSkillInstallRoot('/plain/rune/root', { homedir: home });
+    assert.strictEqual(target.source, 'rune-root');
+    assert.strictEqual(target.root, '/plain/rune/root');
+  });
+});

package/compiler/commands/hooks/tiers.js

@@ -78,7 +78,18 @@ export function compareSemver(a, b) {
 }
 
 /** Valid event names a manifest entry may declare. */
-const VALID_EVENTS = new Set(['UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'statusLine']);
+const VALID_EVENTS = new Set([
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'Stop',
+  'statusLine',
+  'PreCompact',
+  'SessionStart',
+]);
+
+/** Lifecycle events where `matcher` is optional (PreCompact matches manual|auto, SessionStart matches startup|resume — both default to all when omitted). */
+const MATCHER_OPTIONAL_EVENTS = new Set(['statusLine', 'Stop', 'PreCompact', 'SessionStart']);
 
 /** Tier names must be simple lowercase identifiers. Blocks `../../etc` and similar traversal. */
 const TIER_NAME_RE = /^[a-z][a-z0-9-]{0,31}$/;
@@ -178,7 +189,7 @@ export function validateManifest(manifest, source = '<memory>') {
     if (raw.matcher !== undefined && typeof raw.matcher !== 'string') {
       throw new Error(`${where}: 'matcher' must be a string if present`);
     }
-    if (raw.event !== 'statusLine' && raw.event !== 'Stop' && !raw.matcher) {
+    if (!MATCHER_OPTIONAL_EVENTS.has(raw.event) && !raw.matcher) {
       throw new Error(`${where}: '${raw.event}' requires a 'matcher' string (e.g. 'Edit|Write' or '.*')`);
     }
     if (raw.globs !== undefined && !Array.isArray(raw.globs)) {

package/compiler/commands/setup.js

@@ -20,7 +20,7 @@
  *   3. Well-known paths: `D:/Project/Rune/Pro`, `~/rune-pro`, etc.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { cp, readdir, readFile, rm } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -28,6 +28,43 @@ import { createInterface } from 'node:readline';
 import { installHooks } from './hooks/install.js';
 import { resolveTier, TIER_ENV_VARS } from './hooks/tiers.js';
 
+/**
+ * Resolve where tier skills should actually be installed so the Claude Code
+ * plugin runtime SEES them.
+ *
+ * `runeRoot` is the root of whichever rune.js is executing — which is the
+ * WRONG target in two common cases:
+ *   - `npx @rune-kit/rune setup` → runeRoot is npx's ephemeral cache; skills
+ *     copied there are invisible to the plugin runtime (and soon deleted)
+ *   - running from a source checkout → skills are copied into the git repo,
+ *     polluting the MIT source tree with paid-tier content
+ *
+ * The plugin runtime reads `~/.claude/plugins/cache/rune-kit/rune/<ver>/skills/`.
+ * If that cache exists, target its NEWEST version dir; otherwise fall back to
+ * runeRoot (plugin-cache executions land here anyway — cache is runeRoot).
+ *
+ * @param {string} runeRoot
+ * @param {{ homedir?: string }} [opts] — injectable for tests
+ * @returns {{ root: string, source: 'plugin-cache' | 'rune-root' }}
+ */
+export function resolveSkillInstallRoot(runeRoot, opts = {}) {
+  const home = opts.homedir || os.homedir();
+  const cacheRoot = path.join(home, '.claude', 'plugins', 'cache', 'rune-kit', 'rune');
+  if (existsSync(cacheRoot)) {
+    const versions = readdirSync(cacheRoot)
+      .filter((d) => /^\d+\.\d+\.\d+$/.test(d) && existsSync(path.join(cacheRoot, d, 'skills')))
+      .sort((a, b) => {
+        const [a1, a2, a3] = a.split('.').map(Number);
+        const [b1, b2, b3] = b.split('.').map(Number);
+        return b1 - a1 || b2 - a2 || b3 - a3;
+      });
+    if (versions.length > 0) {
+      return { root: path.join(cacheRoot, versions[0]), source: 'plugin-cache' };
+    }
+  }
+  return { root: runeRoot, source: 'rune-root' };
+}
+
 export const WELL_KNOWN_TIER_PATHS = {
   pro: ['D:/Project/Rune/Pro', path.join(os.homedir(), 'rune-pro'), path.join(os.homedir(), 'Project', 'Rune', 'Pro')],
   business: [
@@ -41,7 +78,7 @@ export const WELL_KNOWN_TIER_PATHS = {
  * @param {{ projectRoot: string, runeRoot: string, args: object }} opts
  * @returns {Promise<{ scope: string, tiers: string[], preset: string, written: boolean, files: string[], notes: string[], skillResults: Array<{tier: string, installed: string[], skipped: Array<{skill: string, reason: string}>, reason: string|null}> }>}
  */
-export async function runSetup({ projectRoot, runeRoot, args = {} }) {
+export async function runSetup({ projectRoot, runeRoot, args = {}, skillTarget: skillTargetOverride }) {
   const detected = detectTiers(projectRoot);
 
   // Scope resolution
@@ -89,10 +126,14 @@ export async function runSetup({ projectRoot, runeRoot, args = {} }) {
     dry: args.dry,
   });
 
-  // Install tier skill files into <runeRoot>/skills/ so Claude Code (and any
-  // plugin-aware platform) discovers them alongside Free skills. Without this
+  // Install tier skill files where the plugin runtime actually LOOKS — the
+  // Claude Code plugin cache when present, runeRoot otherwise. Without this
   // step, paid tiers ship hooks only — `rune:autopilot` returns "Unknown skill"
   // because Pro/skills/autopilot/ is invisible to the plugin runtime.
+  const skillTarget =
+    typeof skillTargetOverride === 'string'
+      ? { root: skillTargetOverride, source: 'override' }
+      : (skillTargetOverride ?? resolveSkillInstallRoot(runeRoot));
   const skillResults = [];
   for (const tier of tiers) {
     try {
@@ -100,7 +141,7 @@ export async function runSetup({ projectRoot, runeRoot, args = {} }) {
       const skillResult = await installTierSkills({
         tier,
         tierManifest,
-        runeRoot,
+        runeRoot: skillTarget.root,
         dry: args.dry,
       });
       skillResults.push(skillResult);
@@ -116,6 +157,7 @@ export async function runSetup({ projectRoot, runeRoot, args = {} }) {
     preset,
     detected,
     skillResults,
+    skillTarget,
     ...result,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.22.0",
+  "version": "2.22.2",
   "description": "65-skill mesh for AI coding assistants — runtime auto-discipline via native hooks (Claude/Cursor/Windsurf/Antigravity), 5-layer architecture, 204 connections + 43 signals, multi-platform compiler. converge (L3) scans spec vs code so dead-button/frontend-only implementations can't ship.",
   "type": "module",
   "bin": {

package/skills/preflight/SKILL.md

@@ -3,7 +3,7 @@ name: preflight
 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.2.0"
+  version: "1.2.1"
   layer: L2
   model: sonnet
   group: quality
@@ -209,7 +209,7 @@ If a domain hook flags BLOCK, the overall preflight verdict is BLOCK regardless
 | `openapi.*`, `*.graphql`, `*.proto` | API Contract | Breaking changes flagged, version bumped, deprecated fields documented |
 | `docs/policies/*`, `PRIVACY*`, `TERMS*` | Legal/Compliance | No placeholder text, review date current, practice matches policy |
 | `**/billing*`, `**/payment*`, `**/invoice*` | Financial | Decimal precision correct, currency locale-aware, no hardcoded rates |
-| `*.tsx`, `*.jsx`, `*.svelte`, `*.vue`, `components/*` | UI/Frontend | Design token compliance, animation a11y, touch targets, visual hierarchy |
+| `*.tsx`, `*.jsx`, `*.svelte`, `*.vue`, `*.html` (with script/template content), `components/*` | UI/Frontend | Design token compliance, animation a11y, touch targets, visual hierarchy |
 | `skills/*/SKILL.md`, `extensions/*/PACK.md` | Rune Skill | Frontmatter valid, all required sections present, word count within layer budget |
 | `*.test.*`, `*.spec.*`, `__tests__/*` | Test Quality | No `.skip`/`.only` left in, assertions present (not empty tests), no hardcoded timeouts |
 
@@ -225,7 +225,7 @@ For each detected domain, run its checks on the relevant files in the diff:
 
 #### UI/Frontend Domain Checks
 
-When UI/Frontend hook is triggered, run these checks on all `.tsx`/`.jsx`/`.svelte`/`.vue` files in the diff.
+When UI/Frontend hook is triggered, run these checks on all `.tsx`/`.jsx`/`.svelte`/`.vue`/`.html` files in the diff (plain `.html` counts when it carries interactive markup or inline scripts — a vanilla-JS page is still a UI).
 
 **Preamble — load design contract**: If `.rune/design-system.md` exists, read it once. Apply the project's **Scale Minimums** block over the defaults below (e.g., a project declaring `body ≥18px` should flag 16px body text). If the file is absent, use defaults and emit a LOW advisory: "No `.rune/design-system.md` — run `rune design` to lock visual decisions."