@rune-kit/rune 2.12.0 → 2.12.3

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

@@ -4,12 +4,14 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promis
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
 import * as antigravity from '../adapters/hooks/antigravity.js';
 import { installHooks } from '../commands/hooks/install.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import { uninstallHooks } from '../commands/hooks/uninstall.js';
 
-const RUNE_ROOT = path.resolve(import.meta.dirname, '..', '..');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNE_ROOT = path.resolve(__dirname, '..', '..');
 const RULES_DIR = '.antigravity/rules';
 
 let tmpRoot;

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

@@ -4,12 +4,14 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promis
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
 import * as cursor from '../adapters/hooks/cursor.js';
 import { installHooks } from '../commands/hooks/install.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import { uninstallHooks } from '../commands/hooks/uninstall.js';
 
-const RUNE_ROOT = path.resolve(import.meta.dirname, '..', '..');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNE_ROOT = path.resolve(__dirname, '..', '..');
 const RULES_DIR = '.cursor/rules';
 
 let tmpRoot;

package/compiler/__tests__/hooks-doctor-tier.test.js

@@ -0,0 +1,214 @@
+/**
+ * Doctor tier-coverage check — warns when a tier's hooks are installed on
+ * Claude but missing on other detected platforms, or when required env vars
+ * are unset so installed hooks would fail at runtime.
+ *
+ * Checks are advisory (WARN) — never block the doctor pipeline.
+ */
+
+import assert from 'node:assert';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, test } from 'node:test';
+import { listDetectedTiers } from '../commands/hooks/tiers.js';
+import { checkTierCoverage } from '../doctor.js';
+
+const PRO_MANIFEST = {
+  name: 'Rune Pro Hooks',
+  description: 'Pro tier hooks',
+  tier: 'pro',
+  version: '1.0.0',
+  requires: ['RUNE_PRO_ROOT'],
+  entries: [
+    {
+      id: 'context-inject',
+      skill: 'context-inject',
+      event: 'UserPromptSubmit',
+      matcher: '.*',
+      command: 'node "${RUNE_PRO_ROOT}/hooks/run-hook.cjs" context-inject',
+    },
+    {
+      id: 'context-sense',
+      skill: 'context-sense',
+      event: 'PreToolUse',
+      matcher: 'Edit|Write',
+      command: 'node "${RUNE_PRO_ROOT}/hooks/run-hook.cjs" context-sense',
+    },
+  ],
+};
+
+let tmpRoot;
+let tierRoot;
+let originalRunePro;
+
+async function seedTierRoot(tier, manifest) {
+  const dir = await mkdtemp(path.join(tmpdir(), `rune-doc-${tier}-`));
+  await mkdir(path.join(dir, 'hooks'), { recursive: true });
+  await writeFile(path.join(dir, 'hooks', 'manifest.json'), JSON.stringify(manifest, null, 2));
+  return dir;
+}
+
+async function seedPlatform(root, platform) {
+  const map = {
+    claude: { dir: '.claude', settings: true },
+    cursor: { dir: '.cursor/rules' },
+    windsurf: { dir: '.windsurf/workflows' },
+    antigravity: { dir: '.antigravity/rules' },
+  };
+  const spec = map[platform];
+  await mkdir(path.join(root, spec.dir), { recursive: true });
+  if (spec.settings) {
+    await writeFile(path.join(root, '.claude', 'settings.json'), '{}');
+  }
+}
+
+async function seedTierHooksOn(root, platform, tier) {
+  if (platform === 'claude') {
+    const settingsPath = path.join(root, '.claude', 'settings.json');
+    const settings = {
+      hooks: {
+        UserPromptSubmit: [
+          {
+            matcher: '.*',
+            hooks: [
+              { type: 'command', command: 'node "${RUNE_' + tier.toUpperCase() + '_ROOT}/hooks/run-hook.cjs" ctx' },
+            ],
+          },
+        ],
+      },
+    };
+    await mkdir(path.dirname(settingsPath), { recursive: true });
+    await writeFile(settingsPath, JSON.stringify(settings, null, 2));
+    return;
+  }
+  const dirs = {
+    cursor: path.join(root, '.cursor/rules'),
+    windsurf: path.join(root, '.windsurf/workflows'),
+    antigravity: path.join(root, '.antigravity/rules'),
+  };
+  const ext = { cursor: '.mdc', windsurf: '.md', antigravity: '.md' }[platform];
+  const dir = dirs[platform];
+  await mkdir(dir, { recursive: true });
+  await writeFile(path.join(dir, `rune-${tier}-context-inject${ext}`), '# tier hook\n');
+}
+
+beforeEach(async () => {
+  tmpRoot = await mkdtemp(path.join(tmpdir(), 'rune-doctor-tier-'));
+  tierRoot = await seedTierRoot('pro', PRO_MANIFEST);
+  originalRunePro = process.env.RUNE_PRO_ROOT;
+  process.env.RUNE_PRO_ROOT = tierRoot;
+});
+
+afterEach(async () => {
+  if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true });
+  if (tierRoot) await rm(tierRoot, { recursive: true, force: true });
+  if (originalRunePro === undefined) delete process.env.RUNE_PRO_ROOT;
+  else process.env.RUNE_PRO_ROOT = originalRunePro;
+});
+
+describe('listDetectedTiers', () => {
+  test('returns empty array when no tier env vars set and no monorepo sibling', async () => {
+    delete process.env.RUNE_PRO_ROOT;
+    const result = await listDetectedTiers(tmpRoot);
+    assert.deepStrictEqual(result, []);
+  });
+
+  test('returns Pro tier when RUNE_PRO_ROOT resolves', async () => {
+    const result = await listDetectedTiers(tmpRoot);
+    assert.strictEqual(result.length, 1);
+    assert.strictEqual(result[0].tier, 'pro');
+    assert.strictEqual(result[0].found, true);
+    assert.strictEqual(result[0].requiresOk, true);
+    assert.deepStrictEqual(result[0].requiresMissing, []);
+  });
+
+  test('reports requiresMissing when env var gets unset after locate', async () => {
+    // Manifest locates via a secondary path (env set at locate, unset at requires check).
+    // Simulate by forcing a manifest with extra required env.
+    const extraReq = { ...PRO_MANIFEST, requires: ['RUNE_PRO_ROOT', 'SOME_OTHER_VAR'] };
+    await writeFile(path.join(tierRoot, 'hooks', 'manifest.json'), JSON.stringify(extraReq, null, 2));
+    const result = await listDetectedTiers(tmpRoot);
+    assert.strictEqual(result[0].requiresOk, false);
+    assert.deepStrictEqual(result[0].requiresMissing, ['SOME_OTHER_VAR']);
+  });
+});
+
+describe('checkTierCoverage', () => {
+  test('silent when no tiers detected', async () => {
+    delete process.env.RUNE_PRO_ROOT;
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    assert.strictEqual(result.checks.length, 0);
+    assert.strictEqual(result.warnings.length, 0);
+  });
+
+  test('silent when tier detected but no platform dirs exist', async () => {
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    assert.strictEqual(result.checks.length, 0);
+    assert.strictEqual(result.warnings.length, 0);
+  });
+
+  test('pass when Pro installed on every detected platform', async () => {
+    await seedPlatform(tmpRoot, 'claude');
+    await seedPlatform(tmpRoot, 'cursor');
+    await seedTierHooksOn(tmpRoot, 'claude', 'pro');
+    await seedTierHooksOn(tmpRoot, 'cursor', 'pro');
+
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    const tierCheck = result.checks.find((c) => c.name === 'Tier coverage');
+    assert.ok(tierCheck, 'should emit a tier-coverage check');
+    assert.strictEqual(tierCheck.status, 'pass');
+    assert.strictEqual(result.warnings.length, 0);
+  });
+
+  test('warns when Pro on Claude but missing on detected Cursor', async () => {
+    await seedPlatform(tmpRoot, 'claude');
+    await seedPlatform(tmpRoot, 'cursor');
+    await seedTierHooksOn(tmpRoot, 'claude', 'pro');
+    // Cursor platform seeded but NO pro-prefixed files — the gap we want to catch.
+
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    const tierCheck = result.checks.find((c) => c.name === 'Tier coverage');
+    assert.strictEqual(tierCheck.status, 'warn');
+    assert.strictEqual(result.warnings.length >= 1, true);
+    const msg = result.warnings.join('\n');
+    assert.match(msg, /pro/);
+    assert.match(msg, /cursor/);
+    assert.match(msg, /rune hooks install/);
+  });
+
+  test('warns when tier manifest requires unset env var', async () => {
+    await seedPlatform(tmpRoot, 'claude');
+    await seedTierHooksOn(tmpRoot, 'claude', 'pro');
+    // Rewrite manifest to add a req that is definitely unset.
+    const extraReq = { ...PRO_MANIFEST, requires: ['RUNE_PRO_ROOT', 'DOCTOR_TIER_MISSING_ENV'] };
+    await writeFile(path.join(tierRoot, 'hooks', 'manifest.json'), JSON.stringify(extraReq, null, 2));
+
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    const envWarn = result.warnings.find((w) => w.includes('DOCTOR_TIER_MISSING_ENV'));
+    assert.ok(envWarn, `expected missing-env warning, got: ${result.warnings.join('\n')}`);
+    assert.match(envWarn, /pro/);
+    assert.match(envWarn, /will FAIL at runtime/);
+  });
+
+  test('no false-positive: Pro on Cursor alone (no Claude dir) is not a gap', async () => {
+    await seedPlatform(tmpRoot, 'cursor');
+    await seedTierHooksOn(tmpRoot, 'cursor', 'pro');
+
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    const tierCheck = result.checks.find((c) => c.name === 'Tier coverage');
+    // Installed on every detected platform (just cursor) → pass, not warn.
+    assert.strictEqual(tierCheck.status, 'pass');
+  });
+
+  test('windsurf workflow OR rule file counts as installed', async () => {
+    await seedPlatform(tmpRoot, 'windsurf');
+    const rulesDir = path.join(tmpRoot, '.windsurf/rules');
+    await mkdir(rulesDir, { recursive: true });
+    await writeFile(path.join(rulesDir, 'rune-pro-context-inject-rule.md'), '# rule\n');
+
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    const tierCheck = result.checks.find((c) => c.name === 'Tier coverage');
+    assert.strictEqual(tierCheck.status, 'pass');
+  });
+});

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

@@ -4,12 +4,14 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
 import { installHooks } from '../commands/hooks/install.js';
 import { SETTINGS_REL_PATH } from '../commands/hooks/presets.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import { uninstallHooks } from '../commands/hooks/uninstall.js';
 
-const RUNE_ROOT = path.resolve(import.meta.dirname, '..', '..');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNE_ROOT = path.resolve(__dirname, '..', '..');
 
 let tmpRoot;
 

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

@@ -18,18 +18,25 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promis
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
 import { installHooks } from '../commands/hooks/install.js';
 import { SETTINGS_REL_PATH } from '../commands/hooks/presets.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import {
+  _resetFreeVersionCache,
+  assertFreeVersionCompat,
   checkManifestRequires,
+  compareSemver,
+  getFreeVersion,
   loadTierManifest,
   locateTierManifest,
+  parseSemver,
   resolveTier,
   validateManifest,
 } from '../commands/hooks/tiers.js';
 
-const RUNE_ROOT = path.resolve(import.meta.dirname, '..', '..');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNE_ROOT = path.resolve(__dirname, '..', '..');
 
 let tmpRoot;
 let tierRoot;
@@ -494,6 +501,100 @@ describe('review fixes: M3 overrides consumption', () => {
   });
 });
 
+describe('Gap 2: minFreeVersion version gate', () => {
+  test('parseSemver accepts x.y.z and ignores prerelease/build', () => {
+    assert.deepStrictEqual(parseSemver('2.12.0'), [2, 12, 0]);
+    assert.deepStrictEqual(parseSemver('2.12.0-rc.1'), [2, 12, 0]);
+    assert.deepStrictEqual(parseSemver('2.12.0+sha.abc'), [2, 12, 0]);
+    assert.strictEqual(parseSemver('not-a-version'), null);
+    assert.strictEqual(parseSemver(null), null);
+  });
+
+  test('compareSemver returns -1/0/1 ordering', () => {
+    assert.strictEqual(compareSemver('2.12.0', '2.12.0'), 0);
+    assert.strictEqual(compareSemver('2.11.9', '2.12.0'), -1);
+    assert.strictEqual(compareSemver('2.12.1', '2.12.0'), 1);
+    assert.strictEqual(compareSemver('3.0.0', '2.12.0'), 1);
+    assert.strictEqual(compareSemver('bogus', '2.12.0'), null);
+  });
+
+  test('validateManifest accepts optional minFreeVersion', () => {
+    const m = validateManifest({ ...PRO_MANIFEST_FIXTURE, minFreeVersion: '2.12.0' });
+    assert.strictEqual(m.minFreeVersion, '2.12.0');
+  });
+
+  test('validateManifest rejects non-semver minFreeVersion', () => {
+    assert.throws(
+      () => validateManifest({ ...PRO_MANIFEST_FIXTURE, minFreeVersion: 'latest' }),
+      /minFreeVersion.*must be semver/,
+    );
+  });
+
+  test('validateManifest rejects empty minFreeVersion string', () => {
+    assert.throws(() => validateManifest({ ...PRO_MANIFEST_FIXTURE, minFreeVersion: '' }), /minFreeVersion.*non-empty/);
+  });
+
+  test('assertFreeVersionCompat is a no-op when minFreeVersion unset', () => {
+    const m = validateManifest(PRO_MANIFEST_FIXTURE);
+    assert.doesNotThrow(() => assertFreeVersionCompat(m, '0.0.1'));
+  });
+
+  test('assertFreeVersionCompat passes when current >= minFreeVersion', () => {
+    const m = validateManifest({ ...PRO_MANIFEST_FIXTURE, minFreeVersion: '2.12.0' });
+    assert.doesNotThrow(() => assertFreeVersionCompat(m, '2.12.0'));
+    assert.doesNotThrow(() => assertFreeVersionCompat(m, '2.12.1'));
+    assert.doesNotThrow(() => assertFreeVersionCompat(m, '3.0.0'));
+  });
+
+  test('assertFreeVersionCompat throws helpful upgrade error when current < minFreeVersion', () => {
+    const m = validateManifest({ ...PRO_MANIFEST_FIXTURE, minFreeVersion: '2.12.0' });
+    assert.throws(
+      () => assertFreeVersionCompat(m, '2.11.0'),
+      (err) => {
+        assert.match(err.message, /requires Rune Free >= 2\.12\.0/);
+        assert.match(err.message, /installed compiler is 2\.11\.0/);
+        assert.match(err.message, /npm i -g @rune-kit\/rune@latest/);
+        assert.match(err.message, /--tier pro/);
+        return true;
+      },
+    );
+  });
+
+  test('resolveTier enforces minFreeVersion via assertFreeVersionCompat', async () => {
+    const futureManifest = { ...PRO_MANIFEST_FIXTURE, minFreeVersion: '999.0.0' };
+    await writeFile(path.join(tierRoot, 'hooks', 'manifest.json'), JSON.stringify(futureManifest, null, 2));
+    await assert.rejects(resolveTier('pro', tmpRoot), /requires Rune Free >= 999\.0\.0/);
+  });
+
+  test('getFreeVersion reads package.json semver', () => {
+    _resetFreeVersionCache();
+    const v = getFreeVersion();
+    assert.match(v, /^\d+\.\d+\.\d+/);
+  });
+});
+
+describe('Gap 3: actionable missing-manifest error', () => {
+  test('resolveTier error lists both env var and monorepo sibling path', async () => {
+    delete process.env.RUNE_PRO_ROOT;
+    await assert.rejects(resolveTier('pro', tmpRoot), (err) => {
+      assert.match(err.message, /RUNE_PRO_ROOT/);
+      assert.match(err.message, /monorepo sibling/);
+      assert.match(err.message, /Drop --tier pro/);
+      assert.match(err.message, /rune\.dev\/docs\/hooks/);
+      return true;
+    });
+  });
+
+  test('resolveTier error for unknown tier (no env var) still includes sibling + docs hint', async () => {
+    await assert.rejects(resolveTier('unknowntier', tmpRoot), (err) => {
+      assert.match(err.message, /monorepo sibling fallback/);
+      assert.match(err.message, /Drop --tier unknowntier/);
+      assert.match(err.message, /rune\.dev\/docs\/hooks/);
+      return true;
+    });
+  });
+});
+
 describe('regression: Pro+Claude parity', () => {
   test('Pro entries present BEFORE and AFTER migration produce equivalent settings.json shape', async () => {
     await mkdir(path.join(tmpRoot, '.claude'), { recursive: true });

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

@@ -3,12 +3,14 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promis
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
 import * as windsurf from '../adapters/hooks/windsurf.js';
 import { installHooks } from '../commands/hooks/install.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import { uninstallHooks } from '../commands/hooks/uninstall.js';
 
-const RUNE_ROOT = path.resolve(import.meta.dirname, '..', '..');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNE_ROOT = path.resolve(__dirname, '..', '..');
 const WF_DIR = '.windsurf/workflows';
 const RULES_DIR = '.windsurf/rules';
 

package/compiler/commands/hooks/tiers.js

@@ -16,9 +16,10 @@
  * third-party) plugs in by shipping a manifest at a known path.
  */
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 /** Known tier env vars. Adding a new tier = add its env var here. */
 export const TIER_ENV_VARS = Object.freeze({
@@ -26,6 +27,56 @@ export const TIER_ENV_VARS = Object.freeze({
   business: 'RUNE_BUSINESS_ROOT',
 });
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Read Free compiler version from the bundled package.json. Cached after first read.
+ * @returns {string} semver string, e.g. "2.12.1"
+ */
+let _freeVersionCache = null;
+export function getFreeVersion() {
+  if (_freeVersionCache) return _freeVersionCache;
+  const pkgPath = path.resolve(__dirname, '..', '..', '..', 'package.json');
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    _freeVersionCache = typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+  } catch {
+    _freeVersionCache = '0.0.0';
+  }
+  return _freeVersionCache;
+}
+
+/** For test/override scenarios — resets the cache. */
+export function _resetFreeVersionCache() {
+  _freeVersionCache = null;
+}
+
+/**
+ * Parse a semver `x.y.z` (ignores pre-release/build) into a tuple. Returns null on malformed input.
+ * @param {string} v
+ * @returns {[number,number,number]|null}
+ */
+export function parseSemver(v) {
+  if (typeof v !== 'string') return null;
+  const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * Compare two semver strings. Returns -1, 0, 1 or null if either is malformed.
+ */
+export function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] < pb[i]) return -1;
+    if (pa[i] > pb[i]) return 1;
+  }
+  return 0;
+}
+
 /** Valid event names a manifest entry may declare. */
 const VALID_EVENTS = new Set(['UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'statusLine']);
 
@@ -148,11 +199,23 @@ export function validateManifest(manifest, source = '<memory>') {
     };
   });
 
+  const minFreeVersion =
+    typeof manifest.minFreeVersion === 'string' && manifest.minFreeVersion.length > 0 ? manifest.minFreeVersion : null;
+  if (manifest.minFreeVersion !== undefined && minFreeVersion === null) {
+    throw new Error(`Manifest ${source}: 'minFreeVersion' must be a non-empty string if present`);
+  }
+  if (minFreeVersion && !parseSemver(minFreeVersion)) {
+    throw new Error(
+      `Manifest ${source}: 'minFreeVersion' must be semver x.y.z (got ${JSON.stringify(minFreeVersion)})`,
+    );
+  }
+
   return {
     name: typeof manifest.name === 'string' ? manifest.name : `Rune ${manifest.tier} Hooks`,
     description: typeof manifest.description === 'string' ? manifest.description : '',
     tier: manifest.tier,
     version: typeof manifest.version === 'string' ? manifest.version : '0.0.0',
+    minFreeVersion,
     requires: Array.isArray(manifest.requires) ? [...manifest.requires] : [],
     entries,
     overrides: manifest.overrides && typeof manifest.overrides === 'object' ? { ...manifest.overrides } : {},
@@ -160,6 +223,29 @@ export function validateManifest(manifest, source = '<memory>') {
   };
 }
 
+/**
+ * Assert the current Free compiler satisfies a manifest's `minFreeVersion`.
+ * Throws with an actionable upgrade message when the local Free is too old.
+ *
+ * @param {import('./tiers.js').TierManifest} manifest
+ * @param {string} [currentFreeVersion] — defaults to `getFreeVersion()`. Override for tests.
+ */
+export function assertFreeVersionCompat(manifest, currentFreeVersion) {
+  if (!manifest || !manifest.minFreeVersion) return;
+  const current = currentFreeVersion ?? getFreeVersion();
+  const cmp = compareSemver(current, manifest.minFreeVersion);
+  if (cmp === null) {
+    // Malformed input — surface but don't block (defensive).
+    return;
+  }
+  if (cmp < 0) {
+    throw new Error(
+      `Tier '${manifest.tier}' requires Rune Free >= ${manifest.minFreeVersion} but the installed compiler is ${current}. ` +
+        `Upgrade Free first: \`npm i -g @rune-kit/rune@latest\` (or \`npx @rune-kit/rune@latest hooks install --tier ${manifest.tier}\`).`,
+    );
+  }
+}
+
 /**
  * Check whether a manifest's `requires` list is satisfied by current env.
  * Returns { ok, missing }.
@@ -169,6 +255,48 @@ export function checkManifestRequires(manifest) {
   return { ok: missing.length === 0, missing };
 }
 
+/**
+ * Enumerate known tiers and return status for each that can be located.
+ * Tiers that can't be found (no env var, no monorepo sibling) are skipped.
+ * Invalid/corrupt manifests are reported with { found: false, error }.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<Array<{tier: string, found: boolean, manifestPath: string|null, version?: string, requires: string[], requiresOk: boolean, requiresMissing: string[], entries: number, error?: string}>>}
+ */
+export async function listDetectedTiers(projectRoot) {
+  const out = [];
+  for (const tier of Object.keys(TIER_ENV_VARS)) {
+    const manifestPath = locateTierManifest(tier, projectRoot);
+    if (!manifestPath) continue;
+    try {
+      const manifest = await loadTierManifest(manifestPath);
+      const req = checkManifestRequires(manifest);
+      out.push({
+        tier,
+        found: true,
+        manifestPath,
+        version: manifest.version,
+        requires: [...(manifest.requires || [])],
+        requiresOk: req.ok,
+        requiresMissing: req.missing,
+        entries: manifest.entries.length,
+      });
+    } catch (err) {
+      out.push({
+        tier,
+        found: false,
+        manifestPath,
+        requires: [],
+        requiresOk: false,
+        requiresMissing: [],
+        entries: 0,
+        error: err.message,
+      });
+    }
+  }
+  return out;
+}
+
 /**
  * Resolve a tier request (`--tier pro`) into a loaded, validated manifest,
  * or throw with a helpful upgrade/missing-env message.
@@ -180,16 +308,32 @@ export function checkManifestRequires(manifest) {
 export async function resolveTier(tier, projectRoot) {
   const manifestPath = locateTierManifest(tier, projectRoot);
   if (!manifestPath) {
-    const envHint = TIER_ENV_VARS[tier] ? ` Set $${TIER_ENV_VARS[tier]} to your ${tier} install dir.` : '';
-    throw new Error(
-      `Could not locate '${tier}' tier manifest.${envHint}` +
-        ` See https://rune.dev/docs/hooks#tiers for install instructions.`,
-    );
+    const envVar = TIER_ENV_VARS[tier];
+    const capitalized = tier.charAt(0).toUpperCase() + tier.slice(1);
+    const siblingPath = path.resolve(projectRoot, '..', capitalized, 'hooks', 'manifest.json');
+    const lines = [`Could not locate '${tier}' tier manifest. Rune looked in:`];
+    if (envVar) {
+      lines.push(`  1. $${envVar}/hooks/manifest.json  (env var — set this if ${capitalized} is installed elsewhere)`);
+      lines.push(`  2. ${siblingPath}  (monorepo sibling fallback)`);
+    } else {
+      lines.push(`  • ${siblingPath}  (monorepo sibling fallback)`);
+    }
+    lines.push('');
+    lines.push(`Fix one of:`);
+    if (envVar) {
+      lines.push(`  • export ${envVar}=/path/to/${capitalized}   # point at your ${tier} install`);
+    }
+    lines.push(`  • Clone ${capitalized} next to Free so the sibling path resolves`);
+    lines.push(`  • Drop --tier ${tier} to install Free-only hooks`);
+    lines.push('');
+    lines.push(`See https://rune.dev/docs/hooks#tiers for details.`);
+    throw new Error(lines.join('\n'));
   }
   const manifest = await loadTierManifest(manifestPath);
   if (manifest.tier !== tier) {
     throw new Error(`Manifest at ${manifestPath} declares tier='${manifest.tier}' but was requested as '${tier}'`);
   }
+  assertFreeVersionCompat(manifest);
   return manifest;
 }
 

package/compiler/doctor.js

@@ -8,6 +8,8 @@
 import { existsSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { detectPlatforms } from './adapters/hooks/index.js';
+import { listDetectedTiers } from './commands/hooks/tiers.js';
 import { parseOrgConfig, parsePack, parseTemplate } from './parser.js';
 
 /**
@@ -46,6 +48,9 @@ export async function runDoctor({ outputRoot, adapter, config, runeRoot }) {
   // Check 2: Output directory exists
   if (adapter.name === 'claude') {
     results.checks.push({ name: 'Output directory', status: 'skip', detail: 'Claude Code uses source directly' });
+    const tierCoverage = await checkTierCoverage({ projectRoot: outputRoot });
+    for (const check of tierCoverage.checks) results.checks.push(check);
+    for (const warn of tierCoverage.warnings) results.warnings.push(warn);
     return results;
   }
 
@@ -164,11 +169,137 @@ export async function runDoctor({ outputRoot, adapter, config, runeRoot }) {
     results.warnings.push(...orgErrors);
   }
 
+  // Check 11: Tier hook coverage across detected platforms (advisory)
+  const tierCoverage = await checkTierCoverage({ projectRoot: outputRoot });
+  for (const check of tierCoverage.checks) results.checks.push(check);
+  for (const warn of tierCoverage.warnings) results.warnings.push(warn);
+
   if (results.errors.length > 0) results.healthy = false;
 
   return results;
 }
 
+const PLATFORM_TIER_DIRS = Object.freeze({
+  cursor: '.cursor/rules',
+  windsurf: '.windsurf/workflows',
+  antigravity: '.antigravity/rules',
+});
+
+const PLATFORM_TIER_EXTS = Object.freeze({
+  cursor: '.mdc',
+  windsurf: '.md',
+  antigravity: '.md',
+});
+
+/**
+ * True if the platform's config shows tier hooks installed for `tier`.
+ * Claude: scans `.claude/settings.json` for the `${RUNE_<TIER>_ROOT}` substring
+ *         that the installer emits into every tier command string.
+ * Others: scans the platform's rules/workflow dir for a `rune-<tier>-*` file.
+ *         Windsurf additionally checks `.windsurf/rules` since a tier entry
+ *         writes both a workflow and a rule file.
+ */
+async function platformHasTier(platformId, projectRoot, tier) {
+  if (platformId === 'claude') {
+    const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+    if (!existsSync(settingsPath)) return false;
+    const raw = await readFile(settingsPath, 'utf-8');
+    return raw.includes(`\${RUNE_${tier.toUpperCase()}_ROOT}`);
+  }
+  const relDir = PLATFORM_TIER_DIRS[platformId];
+  if (!relDir) return false;
+  const ext = PLATFORM_TIER_EXTS[platformId];
+  const prefix = `rune-${tier}-`;
+
+  const scanDir = async (dir) => {
+    if (!existsSync(dir)) return false;
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.some((e) => e.isFile() && e.name.startsWith(prefix) && e.name.endsWith(ext));
+  };
+
+  if (await scanDir(path.join(projectRoot, relDir))) return true;
+  if (platformId === 'windsurf') {
+    if (await scanDir(path.join(projectRoot, '.windsurf/rules'))) return true;
+  }
+  return false;
+}
+
+/**
+ * Advisory tier-coverage check. Silent when no tiers are detected or no
+ * tier hooks are installed anywhere. Warns when:
+ *   1. A tier's hooks are installed on some detected platforms but missing
+ *      on others — suggests re-running `rune hooks install --tier ... --platform all`.
+ *   2. A tier manifest requires env vars that are unset — installed hooks
+ *      will fail at runtime, and `rune hooks install` surfaces this too.
+ *
+ * Advisory only: emits WARN, never blocks the doctor pipeline.
+ *
+ * @param {{projectRoot: string}} options
+ * @returns {Promise<{checks: object[], warnings: string[]}>}
+ */
+export async function checkTierCoverage({ projectRoot }) {
+  const result = { checks: [], warnings: [] };
+  const tiers = await listDetectedTiers(projectRoot);
+  if (tiers.length === 0) return result;
+
+  const detected = detectPlatforms(projectRoot);
+  const gaps = [];
+  let installedSomewhere = false;
+  const coverageByTier = [];
+
+  for (const tierInfo of tiers) {
+    if (!tierInfo.found) {
+      result.warnings.push(
+        `tier ${tierInfo.tier}: manifest at ${tierInfo.manifestPath} failed to load — ${tierInfo.error}`,
+      );
+      continue;
+    }
+
+    const coverage = { tier: tierInfo.tier, installedOn: [], missingOn: [] };
+    for (const id of detected) {
+      const has = await platformHasTier(id, projectRoot, tierInfo.tier);
+      if (has) coverage.installedOn.push(id);
+      else coverage.missingOn.push(id);
+    }
+    if (coverage.installedOn.length > 0) installedSomewhere = true;
+    if (coverage.installedOn.length > 0 && coverage.missingOn.length > 0) {
+      gaps.push(coverage);
+    }
+    coverageByTier.push(coverage);
+
+    if (!tierInfo.requiresOk && coverage.installedOn.length > 0) {
+      result.warnings.push(
+        `tier ${tierInfo.tier}: required env var${tierInfo.requiresMissing.length === 1 ? '' : 's'} unset (${tierInfo.requiresMissing.join(', ')}) — hooks will FAIL at runtime. Fix: export ${tierInfo.requiresMissing[0]}=/path/to/${tierInfo.tier} then re-run your shell.`,
+      );
+    }
+  }
+
+  if (!installedSomewhere) return result;
+
+  if (gaps.length === 0) {
+    result.checks.push({
+      name: 'Tier coverage',
+      status: 'pass',
+      detail: coverageByTier.map((c) => `${c.tier}:${c.installedOn.join('+') || 'none'}`).join(', '),
+    });
+    return result;
+  }
+
+  const detailParts = gaps.map((g) => `${g.tier} missing on ${g.missingOn.join(', ')}`);
+  result.checks.push({
+    name: 'Tier coverage',
+    status: 'warn',
+    detail: detailParts.join('; '),
+  });
+  for (const gap of gaps) {
+    const plural = gap.missingOn.length === 1 ? 'platform' : 'platforms';
+    result.warnings.push(
+      `tier ${gap.tier} installed on ${gap.installedOn.join(', ')} but missing on detected ${plural} ${gap.missingOn.join(', ')}. Re-run: rune hooks install --preset gentle --tier ${gap.tier} --platform all`,
+    );
+  }
+  return result;
+}
+
 /**
  * Check that all cross-references in compiled files point to existing files
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.12.0",
+  "version": "2.12.3",
   "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.",
   "type": "module",
   "bin": {

package/skills/ba/SKILL.md

@@ -3,7 +3,7 @@ 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.
 metadata:
   author: runedev
-  version: "0.6.0"
+  version: "0.7.0"
   layer: L2
   model: opus
   group: creation
@@ -87,6 +87,23 @@ Each question must be asked separately, wait for answer before next.
 Exception: if user provides a detailed spec/PRD → extract answers from it, confirm with user.
 </HARD-GATE>
 
+#### Question Discipline (MANDATORY)
+
+Every question the user answers burns attention you don't get back. Protect it.
+
+1. **Max 5 questions total across the whole BA session.** If you find yourself wanting a 6th, the answer is in the first 5 or you're stalling — re-read, don't re-ask.
+2. **Prefer yes/no or multiple-choice over open-ended.** An open-ended question is a last resort when no reasonable option set exists.
+   - BAD: "What auth strategy do you want?"
+   - GOOD: "Auth: **(a)** email+password with JWT, **(b)** OAuth (Google/GitHub), **(c)** magic link, **(d)** I'll decide — pick one."
+3. **Never ask what you can infer.** If the answer is in the repo, the user's message, or the classification from Step 1 — don't ask it.
+   - Wrong stack? → read `package.json`, don't ask.
+   - Wrong audience? → check the `README`, don't ask.
+   - Wrong framework? → check config files, don't ask.
+4. **Cache the answer.** Write each Q→A pair into the Requirements Document verbatim. If the user restarts the BA session on the same feature, reuse the cached answers — never re-ask what was already answered.
+5. **Bundle yes/no questions after Q1 if the user is concise.** A user who replies "y" / "n" / "skip" in 1-2 words tolerates a bundle. A user who replies with paragraphs wants the slow pace — keep one-at-a-time.
+
+Every Q should earn its slot: removing it must leave the Requirements Document materially worse. If it wouldn't, cut the question.
+
 #### Structured Elicitation Frameworks
 
 Choose the framework that fits the requirement type. Use it to STRUCTURE the 5 Questions above, not replace them.
@@ -449,13 +466,16 @@ Saved to `.rune/features/<feature-name>/requirements.md`
 
 ## Constraints
 
-1. MUST ask 5 probing questions before producing requirements — no assumptions
-2. MUST identify hidden requirements — the obvious ones are never the full picture
-3. MUST define out-of-scope explicitly — prevents scope creep
-4. MUST produce testable acceptance criteria — they become test cases
-5. MUST NOT write code or plan implementation — BA produces WHAT, plan produces HOW
-6. MUST ask ONE question at a time — don't overwhelm user with 5 questions at once
-7. MUST NOT skip BA for non-trivial tasks — "just build it" gets redirected to Question 1
+1. MUST ask up to 5 probing questions before producing requirements — never more, skip any you can infer from context
+2. MUST prefer yes/no or multiple-choice questions — open-ended only when no reasonable option set exists
+3. MUST NOT ask for information already present in the user's message, the repo, or classification — read/grep first, ask second
+4. MUST cache each Q→A pair in the Requirements Document and reuse on subsequent BA sessions for the same feature
+5. MUST identify hidden requirements — the obvious ones are never the full picture
+6. MUST define out-of-scope explicitly — prevents scope creep
+7. MUST produce testable acceptance criteria — they become test cases
+8. MUST NOT write code or plan implementation — BA produces WHAT, plan produces HOW
+9. MUST ask ONE question at a time by default; bundle yes/no batches only after user shows concise replies
+10. MUST NOT skip BA for non-trivial tasks — "just build it" gets redirected to Question 1
 
 ## Returns
 
@@ -476,6 +496,10 @@ Known failure modes for this skill. Check these before declaring done.
 | Answering own questions instead of asking user | HIGH | Questions require USER input — BA doesn't guess |
 | Producing implementation details (HOW) instead of requirements (WHAT) | HIGH | BA outputs requirements doc → plan outputs implementation |
 | All-at-once question dump (asking 5 questions in one message) | MEDIUM | One question at a time, wait for answer before next |
+| Asking open-ended questions when yes/no or multiple-choice would work | HIGH | Question Discipline rule 2 — option sets are faster to answer and easier to cache |
+| Asking for info already in the repo/message (stack, framework, audience) | HIGH | Question Discipline rule 3 — read `package.json`/README/config first, ask only what you genuinely can't find |
+| Exceeding 5 questions when the user seems "engaged" | MEDIUM | Question Discipline rule 1 — hard cap at 5. A 6th question is a sign of stalling, not thoroughness |
+| Re-asking on session restart when answers were cached | MEDIUM | Question Discipline rule 4 — load `.rune/features/<name>/requirements.md` and reuse cached Q→A pairs |
 | Missing hidden requirements (auth, error handling, edge cases) | HIGH | Step 3 checklist is mandatory scan |
 | Requirements doc too verbose (>500 lines) | MEDIUM | Max 200 lines — concise, actionable, testable |
 | Skipping BA for "simple" features that turn out complex | HIGH | Let cook's complexity detection trigger BA, not user judgment |

package/skills/cook/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "2.4.0"
+  version: "2.5.0"
   layer: L1
   model: sonnet
   group: orchestrator
@@ -307,9 +307,10 @@ Contract violations are NON-NEGOTIABLE. If `.rune/contract.md` exists and a plan
 2. **Feature workspace** (opt-in) — for non-trivial features (3+ phases), suggest creating `.rune/features/<feature-name>/` with `spec.md`, `plan.md`, `decisions.md`, `status.md`. Skip for simple bug fixes, fast mode.
 3. Create implementation plan: exact files to create/modify, change order, dependencies, active decision constraints
 4. If multiple valid approaches exist → invoke `rune:brainstorm` for trade-off analysis
-5. Present plan to user for approval
-6. If feature workspace was created, write approved plan to `.rune/features/<name>/plan.md`
-7. Mark Phase 2 as `completed`
+5. **Frontend detection** — if task touches `.tsx/.jsx/.vue/.svelte/.css`, component files, or mentions "UI/page/screen/design/layout/landing": invoke `rune:design` BEFORE plan approval. Pass hint `mode: "tweaks-default"` — design proposes ONE opinionated default per `.rune/design-system.md` (Step 2.7), not a 5-option menu. User replies with tweaks ("more professional", "darker") rather than picking from a list. If `.rune/design-system.md` is missing, design creates it first.
+6. Present plan to user for approval
+7. If feature workspace was created, write approved plan to `.rune/features/<name>/plan.md`
+8. Mark Phase 2 as `completed`
 
 **Gate**: User MUST approve the plan before proceeding. Do NOT skip this.
 
@@ -751,7 +752,7 @@ Mentally track tool call fingerprints. 3 identical calls → WARN. 5 identical c
 | 1 | `logic-guardian` | L2 | Conditional: when `.rune/logic-manifest.json` exists — protect complex business logic before any edits |
 | 2 | `plan` | L2 | Create implementation plan |
 | 2 | `brainstorm` | L2 | Trade-off analysis / rescue mode |
-| 2 | `design` | L2 | UI/design phase for frontend features |
+| 2 | `design` | L2 | UI/design phase for frontend features — invoke with `mode: "tweaks-default"` (one opinionated default + accept natural-language tweaks, not a 5-option menu) |
 | 2.5 | `adversary` | L2 | Red-team challenge on approved plan |
 | 3 | `test` | L2 | Write failing tests (RED phase) |
 | 4 | `fix` | L2 | Implement code changes (GREEN phase) |

package/skills/design/SKILL.md

@@ -3,7 +3,7 @@ name: design
 description: Design system reasoning. Maps product domain to style, palette, typography, and platform-specific patterns. Generates .rune/design-system.md as the shared design contract for all UI-generating skills.
 metadata:
   author: runedev
-  version: "0.4.0"
+  version: "0.5.0"
   layer: L2
   model: sonnet
   group: creation
@@ -125,6 +125,84 @@ Accept a single mood keyword (or infer from context if obvious). Map mood to con
 
 **Skip if**: User says "no preference" or "just follow domain defaults" — proceed to Step 3 with domain-only reasoning.
 
+### Step 2.7 — Tweaks, Not Menus (Default Style Pattern)
+
+Picking from a 10-option style menu is how AI UI gets generic. Instead:
+
+1. **Propose ONE opinionated default** based on domain + mood (from Step 2.5). Describe it in 2-3 lines — style, palette direction, typography pairing.
+2. **Ask for tweaks, not choices.** The question is **"Any tweaks to this, or ship it?"** — not "Which of these do you prefer?"
+3. **Accept natural-language adjustments.** Map phrases → design system edits:
+   - "more professional" → heavier type weights, reduce saturation, tighter spacing
+   - "less corporate" → looser weights, brighter accent, more whitespace
+   - "darker" → swap base for darker neutral, raise contrast on elevated surfaces
+   - "more playful" → add subtle animation, soften corners, bolder accent
+   - "more trust" → cooler palette (slate/blue), heavier headers, smaller radius
+4. **If the user asks for a menu**, provide max 3 options — but mark one as the recommended default. Never present a neutral list of 5+ equivalent styles.
+
+Why: Every menu option dilutes commitment. A single confident default gets committed, tweaked, and shipped. A menu gets deliberated, A/B'd, and abandoned. This is the **Tweaks Default** pattern from Anthropic's design system guidance — the AI commits first, humans steer second.
+
+### Step 2.9 — Universal Anti-AI Rules (apply to ALL domains)
+
+These rules apply regardless of domain, mood, or platform. Every generated design system MUST comply.
+
+**Enforcement**: `rune:review` v1.1.0+ reads `.rune/design-system.md` § Scale Minimums and flags violations of all 3 rules below as MEDIUM/HIGH findings. Design defines, review enforces — this is the contract.
+
+#### Rule 1 — Scale Minimums
+
+Below these thresholds, designs read as "AI boilerplate" no matter how good the palette is.
+
+| Element | Minimum | Ideal |
+|---------|---------|-------|
+| Hero/display text | 48px | 56-72px |
+| H1 (page title) | 32px | 36-40px |
+| Body text | 16px (never 14px for primary content) | 16-18px |
+| Secondary/meta text | 14px | 14-15px |
+| Touch targets (mobile) | 44×44px | 48×48px |
+| Touch target gap (mobile) | 8px | 12px |
+| Focus-visible ring | 2px | 3px |
+
+Write these minimums to `.rune/design-system.md` under `## Scale Minimums`. Downstream skills (`cook`, `fix`) treat violations as review findings.
+
+#### Rule 2 — Placeholder Over Bad SVG
+
+If the design calls for an icon, illustration, or graphic that the agent cannot generate at high quality, **ship a boxed placeholder, not a malformed SVG**.
+
+```html
+<!-- GOOD: placeholder -->
+<div class="placeholder" data-icon="dashboard" aria-label="Dashboard icon — design pass needed">
+  [ ICON: dashboard ]
+</div>
+
+<!-- BAD: AI-generated SVG with broken geometry -->
+<svg viewBox="0 0 24 24">
+  <path d="M12 2L2 7l10 5 10-5-10-5z M2 17l10 5 10-5 M2 12l10 5 10-5"/>
+</svg>
+```
+
+- Use **Phosphor Icons** (`@phosphor-icons/react`) or **Huge Icons** as the library default. Never generate custom SVG for standard iconography.
+- For illustrations, reference a placeholder string (e.g., `[ILLUSTRATION: empty-state-dashboard]`) that a human or asset-creator pass fills in later.
+- Malformed SVG is the #1 AI tell. A clean labeled placeholder is honest and professional.
+
+#### Rule 3 — Color Derivation via oklch(), not Manual Shading
+
+When the design needs a darker hover, lighter surface, or tinted state, **derive from the accent via oklch()** — never eyeball a hex value.
+
+```css
+/* GOOD: relative derivation */
+--accent: oklch(65% 0.2 255);
+--accent-hover:  oklch(from var(--accent) calc(l - 0.08) c h);
+--accent-pressed: oklch(from var(--accent) calc(l - 0.15) c h);
+--accent-subtle:  oklch(from var(--accent) calc(l + 0.3) calc(c * 0.4) h);
+
+/* BAD: manual hex shading — breaks hue/chroma consistency */
+--accent: #3b82f6;
+--accent-hover: #2563eb;  /* guessed darker */
+```
+
+Why: HSL shading distorts perceived brightness at different hues. oklch() keeps perceptual lightness consistent, so derived states look intentional rather than "kinda close." Write derived tokens to `.rune/design-system.md` — downstream skills reuse these, not re-derive.
+
+Bonus: use `text-wrap: pretty` on headings to prevent widow words. One line, zero ceremony.
+
 ### Step 3 — Apply Domain Reasoning Rules
 
 Map domain to design system parameters:
@@ -532,6 +610,10 @@ Trading/Fintech — Data-Dense Dark — Web
 4. MUST write `.rune/design-system.md` — ephemeral design decisions evaporate; persistence is the point
 5. MUST NOT overwrite existing design-system.md without user confirmation
 6. MUST include platform-specific overrides when platform is iOS or Android
+7. MUST propose ONE opinionated default and ask for tweaks — never present a neutral 5+ option menu (Step 2.7 Tweaks Default)
+8. MUST enforce Scale Minimums (hero ≥48px, body ≥16px, touch targets ≥44px) in every design system (Step 2.9 Rule 1)
+9. MUST use Phosphor/Huge icons or boxed placeholders — NEVER generate custom SVG for standard iconography (Step 2.9 Rule 2)
+10. MUST derive accent variants via `oklch(from var(--accent) ...)` — NEVER hand-shade hex values (Step 2.9 Rule 3)
 
 ## Mesh Gates (L1/L2 only)
 
@@ -541,6 +623,10 @@ Trading/Fintech — Data-Dense Dark — Web
 | Anti-Pattern Gate | Anti-pattern list derived from domain rules (not generic) | Domain-specific list required |
 | Persistence Gate | .rune/design-system.md written before reporting done | Write file first |
 | Platform Gate | Platform detected before generating tokens | Default to web, note assumption |
+| Tweaks-Default Gate | One opinionated default proposed before asking for tweaks | Do NOT present neutral 5-option menus |
+| Scale-Minimums Gate | Hero ≥48px, body ≥16px, touch ≥44px written into design-system.md | Emit minimums block in output |
+| SVG-Placeholder Gate | No hand-rolled SVG for standard icons — Phosphor/Huge or placeholder | Swap to icon library or `[ ICON: name ]` box |
+| oklch-Derivation Gate | All accent variants derived via `oklch(from ...)` | Rewrite manual hex shades as relative oklch |
 
 ## Returns
 
@@ -568,13 +654,20 @@ Known failure modes for this skill. Check these before declaring done.
 | Visual audit score < 18 shipped without improvement plan | MEDIUM | Step 6.5 flags weak pillars and creates backlog items |
 | iOS target generating solid-background cards | MEDIUM | Platform Gate: iOS 26 Liquid Glass deprecates this pattern |
 | Android target using hardcoded hex colors | MEDIUM | Platform Gate: MaterialTheme.colorScheme is mandatory for dynamic color |
+| Presenting a neutral 5+ option style menu (deliberation death) | HIGH | Step 2.7 Tweaks Default — propose ONE opinionated default, ask for tweaks |
+| Body text at 14px or hero at <40px (AI boilerplate scale) | HIGH | Step 2.9 Rule 1 — enforce Scale Minimums table in every design system |
+| Hand-rolled SVG for dashboard/menu/close icons (malformed geometry) | HIGH | Step 2.9 Rule 2 — Phosphor/Huge Icons or `[ ICON: name ]` placeholder, never custom |
+| Accent variants shaded by eyeball (inconsistent perceived brightness) | MEDIUM | Step 2.9 Rule 3 — `oklch(from var(--accent) calc(l - 0.1) c h)` |
+| Missing `text-wrap: pretty` on headings (widow words) | LOW | One-line CSS — add to base heading styles |
 
 ## Done When
 
 - Design reference loaded (user override or baseline)
 - Domain classified (one of the 10 categories or explicit custom reasoning)
 - Mood mapped to constraints (or explicitly skipped with "domain defaults")
-- Design system generated with: colors (primitive + semantic), typography, spacing, effects, anti-patterns
+- Opinionated default proposed (Step 2.7) — user confirmed or requested tweaks
+- Universal anti-AI rules applied (Step 2.9): Scale Minimums, Placeholder-over-bad-SVG, oklch() color derivation
+- Design system generated with: colors (primitive + semantic, oklch-derived variants), typography, spacing, effects, anti-patterns
 - Platform-specific overrides applied (if iOS/Android target)
 - UI-SPEC.md written with locked layout, hierarchy, and component decisions
 - Accessibility review completed (6 checks: contrast, focus, touch targets, labels, semantic HTML, motion)

package/skills/graft/SKILL.md

@@ -3,7 +3,7 @@ name: graft
 description: "Clone, port, or convert features from any GitHub repo into your project. Understand before copy, challenge before implement. 4 modes: port (rewrite), compare (analysis), copy (transplant), improve (copy + optimize)."
 metadata:
   author: runedev
-  version: "0.1.0"
+  version: "0.2.0"
   layer: L2
   model: sonnet
   group: creation
@@ -18,6 +18,17 @@ metadata:
 
 External code intelligence — structured workflow for learning from, adapting, and integrating features from any public repository into your project. Graft is NOT a copy-paste tool. It enforces understanding before adoption through a mandatory challenge gate that evaluates license compatibility, stack fit, scope, quality, and maintenance health before any code touches your codebase.
 
+## Core Rule: The Tree is a Menu, Not the Meal
+
+When you clone a repo you see hundreds of files. **That tree is a menu — options to order from, not a meal to eat.** Grafting the whole tree is how context windows die and foreign patterns leak into your codebase.
+
+- Read the README + the **2-5 files that implement the target feature**. Skip the rest.
+- If you cannot name the specific files you need before reading, you do not know what you want yet — go back to Step 0 and narrow scope.
+- `WebFetch` on raw GitHub URLs beats `git clone` whenever you know the exact files. Use clone only when discovery is genuinely needed.
+- A graft that reads >10 source files is almost always a scoping failure, not a thorough one.
+
+This rule applies to ALL modes. Copy mode is not an excuse to import a directory wholesale — you still select files deliberately.
+
 <HARD-GATE>
 Challenge gate (Step 4) MUST complete before adaptation planning (Step 5).
 No implementation without confronting trade-offs. This applies to ALL modes except compare.
@@ -123,14 +134,16 @@ git sparse-checkout set <target-dir>
 
 For specific files or small repos: use `WebFetch` on raw GitHub URLs instead of cloning.
 
-**Read in this order** (stop when you have enough context):
+**Read in this order** (stop when you have enough context — see Core Rule: the tree is a menu):
 1. README.md — purpose, architecture overview
-2. Target dir's files — the actual code to graft
+2. Target dir's files — the actual code to graft (aim for 2-5 files, hard-cap at 10)
 3. package.json / pyproject.toml / Cargo.toml — dependencies and stack
 4. Tests for target feature — understand expected behavior
 
 **Scope guard**: If target feature spans >15 files or >2000 LOC → WARN user: "Feature is large. Suggest narrowing to [specific module]. Continue anyway?"
 
+**Menu discipline**: Before reading file #6, pause and ask "do I actually need this, or am I eating the menu?" If the answer isn't a concrete reason tied to the target feature, stop reading and move to Step 2.
+
 ### Step 2 — Analyze Source
 
 Understand the target feature's architecture:
@@ -289,6 +302,7 @@ graft.complete:
 5. MUST respect local conventions — grafted code should look native, not foreign
 6. MUST NOT modify the source repository — read-only access only
 7. MUST NOT graft without scoping — always narrow to specific feature/module
+8. MUST treat the source file tree as a menu, not a meal — read the 2-5 files the feature actually needs, not every file you can see
 
 ## Mesh Gates
 
@@ -305,6 +319,7 @@ graft.complete:
 | Grafting GPL code into MIT project | CRITICAL | Challenge gate checks license — blocks incompatible |
 | Blindly copying code without understanding | CRITICAL | HARD-GATE: challenge before implement |
 | Context overflow from large source files | HIGH | Scope guard: >15 files or >2000 LOC triggers warning |
+| Reading the whole repo instead of the feature | HIGH | "Tree is a menu" rule — pause before file #6, justify each read |
 | Grafted code doesn't match local conventions | HIGH | Step 3 scans local patterns, Step 5 plans adaptation |
 | Stale source (abandoned repo) | MEDIUM | Maintenance dimension in challenge gate |
 | Private repo URL fails | MEDIUM | Fallback to WebFetch raw URLs or manual paste |
@@ -320,6 +335,7 @@ SELF-VALIDATION (run before emitting graft.complete):
 - [ ] License compatibility confirmed (or user override documented)
 - [ ] Temp clone directory cleaned up
 - [ ] Grafted code compiles/lints without new errors
+- [ ] Source files read count ≤10 (menu discipline) — if >10, document why in the output
 IF ANY check fails → fix before reporting done. Do NOT defer to completion-gate.
 ```
 

package/skills/onboard/scripts/onboard-invariants.js

@@ -19,12 +19,14 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { detectInvariants, renderInvariants } from './detect-invariants.js';
 import { applyInvariantsPointer } from './inject-claude-md.js';
 
 const AUTO_HEADER = '## Auto-detected (new)';
 const TEMPLATE_REL_PATH = '../references/invariants-template.md';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 /**
  * Locate the next `## `-level section boundary in `text`, ignoring any `##`
@@ -60,7 +62,7 @@ function findNextSectionOffset(text) {
 }
 
 export async function loadTemplate(templatePath) {
-  const resolved = templatePath ?? path.resolve(import.meta.dirname, TEMPLATE_REL_PATH);
+  const resolved = templatePath ?? path.resolve(__dirname, TEMPLATE_REL_PATH);
   return readFile(resolved, 'utf8');
 }
 

package/skills/preflight/SKILL.md

@@ -3,7 +3,7 @@ name: preflight
 description: Pre-commit quality gate that catches "almost right" code. Goes beyond linting — checks logic correctness, error handling, regressions, and completeness.
 metadata:
   author: runedev
-  version: "1.0.0"
+  version: "1.1.0"
   layer: L2
   model: sonnet
   group: quality
@@ -224,14 +224,20 @@ 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` files in the diff.
+
+**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."
 
 | Check | What to Scan | Severity |
 |-------|-------------|----------|
 | **Design token compliance** | Hardcoded colors (`#fff`, `rgb(`, `hsl(`) instead of CSS variables or Tailwind tokens | WARN: "Hardcoded color at {file}:{line} — use design token" |
 | **UI-SPEC drift** | If `.rune/ui-spec.md` exists, compare component decisions (card style, form layout, nav type) against spec | BLOCK: "Component at {file} uses bordered cards but UI-SPEC locks elevated cards" |
 | **Animation accessibility** | Animations/transitions without `prefers-reduced-motion` guard | WARN: "Animation at {file}:{line} missing reduced-motion check" |
-| **Touch target size** | Interactive elements with explicit small sizing (`w-5 h-5`, `p-0.5` on buttons/links) < 44×44px | WARN: "Touch target too small at {file}:{line}" |
+| **Touch target size** | Interactive elements with explicit small sizing (`w-5 h-5`, `p-0.5` on buttons/links) < 44×44px (or project override from design-system.md) | WARN: "Touch target too small at {file}:{line}" |
+| **Scale Minimum — body text** | `text-sm` / `text-xs` / explicit `font-size: 14px` on `<p>` or primary body regions (not meta/secondary) | WARN: "Body text below 16px at {file}:{line} — reads as AI boilerplate" |
+| **Scale Minimum — hero display** | `<h1>` with `text-3xl` or smaller (30px) when the heading is in a hero/landing section | WARN: "Hero heading below 48px at {file}:{line} — insufficient visual hierarchy" |
+| **Hand-rolled SVG for standard icons** | Inline `<svg viewBox=` in JSX when the surrounding comment/class names indicate standard iconography (dashboard, menu, close, chevron, arrow, search, home, user, settings, bell, trash) | WARN: "Hand-rolled SVG at {file}:{line} — use @phosphor-icons/react or huge-icons, or ship boxed placeholder" |
+| **Manual hex accent shading** | CSS/Tailwind config defining 2+ sibling `--accent-hover` / `--accent-pressed` / `--accent-active` with hex literals (no `oklch(from ...)` or design-token chain) | WARN: "Manual hex shade at {file}:{line} — derive via oklch(from var(--accent) calc(l - 0.08) c h)" |
 | **Missing states** | Components fetching data without loading/error/empty states | WARN: "Async component at {file} missing [loading|error|empty] state" |
 | **Icon accessibility** | Decorative icons without `aria-hidden="true"`, functional icons without `aria-label` | WARN: "Icon at {file}:{line} missing aria attribute" |
 | **Inline styles** | `style={{` or `style=` attribute usage instead of classes/tokens | WARN: "Inline style at {file}:{line} — use CSS class or Tailwind" |
@@ -240,6 +246,10 @@ When UI/Frontend hook is triggered, run these checks on all `.tsx`/`.jsx`/`.svel
 
 **Skip if**: Diff contains only test files, config files, or non-UI code (detected by absence of JSX/template syntax).
 
+**Exception for Scale Minimums**: Secondary/meta text (`<time>`, `<small>`, form hints, table captions) is allowed at 14px. The check only fires on primary body regions — paragraphs inside `<main>`, `<article>`, card body, marketing hero/features. Use common sense or an explicit `data-scale="meta"` attribute to opt out.
+
+**Exception for hand-rolled SVG**: Project logos, data visualizations (charts/graphs via d3/recharts/visx), and human-designed illustrations are never flagged. The check fires only when class/comment context names a standard icon.
+
 #### Pack Integration
 
 When a domain pack is installed (e.g., `@rune-pro/finance`, `@rune-pro/legal`), preflight checks the pack's **Hard-Stop Thresholds** table and applies matching rules to staged files. This means:

package/skills/review/SKILL.md

@@ -3,7 +3,7 @@ name: review
 description: Code quality review — patterns, security, performance, correctness. Finds bugs, suggests improvements, triggers fix for issues found. Escalates to opus for security-critical code.
 metadata:
   author: runedev
-  version: "1.0.0"
+  version: "1.1.0"
   layer: L2
   model: sonnet
   group: development
@@ -381,6 +381,9 @@ Apply **only** when `.tsx`, `.jsx`, `.svelte`, `.vue`, or `.html` files are in t
 
 These are the **"AI UI signature"** — patterns that make AI-generated frontends visually identifiable as non-human-designed. Flag each as MEDIUM severity.
 
+**Preamble — load design contract first:**
+If `.rune/design-system.md` exists, read it first. Pull the project's **Scale Minimums** block (if authored by `rune:design` v0.5.0+) and apply those thresholds instead of the defaults below. Missing design-system.md → use defaults and add a LOW finding: "Project has no design-system.md — run `rune design` to lock visual decisions." Never enforce stale defaults against a project that has already declared stricter/looser minimums.
+
 **AI_ANTIPATTERN — Purple/indigo default accent with no domain justification:**
 ```tsx
 // BAD: LLM default color bias — signals "AI-generated" to experienced designers
@@ -415,6 +418,55 @@ className="bg-indigo-600 text-white"  // every button/CTA is indigo
 <span className="font-mono text-2xl font-bold">${price}</span>
 ```
 
+**AI_ANTIPATTERN — Scale Minimum violations (AI boilerplate tell):**
+```tsx
+// BAD: body text at 14px (AI default) — primary content must be ≥16px
+<p className="text-sm">Welcome to the dashboard.</p>
+
+// BAD: hero/display text below 40px — reads as "section heading", not "hero"
+<h1 className="text-3xl font-bold">Ship Faster</h1>  // 30px
+
+// BAD: touch target below 44×44px on mobile
+<button className="w-8 h-8"><XIcon /></button>  // 32px — WCAG 2.5.8 failure
+
+// GOOD: hero ≥48px, body ≥16px, touch ≥44×44px
+<h1 className="text-5xl md:text-6xl font-bold">Ship Faster</h1>   // 48-60px
+<p className="text-base">Welcome to the dashboard.</p>             // 16px
+<button className="w-11 h-11"><XIcon /></button>                   // 44px
+```
+Pull project-specific overrides from `.rune/design-system.md` § Scale Minimums.
+
+**AI_ANTIPATTERN — Hand-rolled SVG for standard iconography:**
+```tsx
+// BAD: custom <svg> for dashboard/menu/close/chevron — AI geometry almost always malformed
+<svg viewBox="0 0 24 24"><path d="M3 3h18v18H3z M3 9h18 M9 3v18"/></svg>
+
+// GOOD: Phosphor Icons (preferred) or Huge Icons
+import { House, List, X } from '@phosphor-icons/react';
+<House weight="bold" size={24} />
+
+// GOOD: labeled placeholder when no icon library available yet
+<span className="icon-placeholder" aria-label="Dashboard icon — design pass needed">
+  [ ICON: dashboard ]
+</span>
+```
+Exceptions: inline SVG for project-unique logos, data visualizations (charts/graphs), or decorative illustrations generated by a human designer — these are not "standard iconography."
+
+**AI_ANTIPATTERN — Manual hex shading for accent states (oklch() violation):**
+```css
+/* BAD: hand-darkened hex — breaks perceived lightness consistency */
+--accent: #3b82f6;
+--accent-hover: #2563eb;    /* guessed darker */
+--accent-pressed: #1d4ed8;  /* guessed even darker */
+
+/* GOOD: relative oklch() derivation */
+--accent: oklch(62% 0.19 258);
+--accent-hover:   oklch(from var(--accent) calc(l - 0.08) c h);
+--accent-pressed: oklch(from var(--accent) calc(l - 0.15) c h);
+--accent-subtle:  oklch(from var(--accent) calc(l + 0.3) calc(c * 0.4) h);
+```
+Flag any CSS file defining 2+ hover/pressed/active variants with sibling hex literals. Not a finding if accent uses a design-token library (Radix Colors, Tailwind palette) that already ships perceptually-tuned scales.
+
 **AI_ANTIPATTERN — Missing UI states (only happy path rendered):**
 ```tsx
 // BAD: data rendering without empty/error/loading states