@vellumai/assistant 0.3.19 → 0.3.21

package/src/__tests__/assistant-feature-flag-guard.test.ts

@@ -0,0 +1,206 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, test } from 'bun:test';
+
+/**
+ * Guard tests for assistant feature flags.
+ *
+ * 1. Key format validation: ensure production code uses the canonical
+ *    `feature_flags.<flagId>.enabled` format, not the legacy
+ *    `skills.<id>.enabled` format.
+ *
+ * 2. Declaration coverage: ensure all assistant-scope flag keys in the
+ *    unified registry conform to the canonical format.
+ *
+ * See AGENTS.md "Assistant Feature Flags" for the full convention.
+ */
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Resolve repo root (tests run from assistant/) */
+function getRepoRoot(): string {
+  return join(process.cwd(), '..');
+}
+
+function getRegistryPath(): string {
+  return join(getRepoRoot(), 'meta', 'feature-flags', 'feature-flag-registry.json');
+}
+
+interface RegistryFlag {
+  id: string;
+  scope: string;
+  key: string;
+  label: string;
+  description: string;
+  defaultEnabled: boolean;
+}
+
+interface Registry {
+  version: number;
+  flags: RegistryFlag[];
+}
+
+function loadRegistry(): Registry {
+  const raw = readFileSync(getRegistryPath(), 'utf-8');
+  return JSON.parse(raw);
+}
+
+const CANONICAL_KEY_RE = /^feature_flags\.[a-z0-9][a-z0-9._-]*\.enabled$/;
+
+/**
+ * Files allowed to contain the legacy `skills.<id>.enabled` key format.
+ * Keep this list minimal — only files that genuinely need to reference
+ * the legacy format for backward compatibility.
+ */
+const LEGACY_KEY_ALLOWLIST = new Set([
+  // macOS client: fallback reads from legacy config section
+  'clients/macos/vellum-assistant/Features/Settings/SettingsAccountTab.swift',
+]);
+
+function isTestFile(filePath: string): boolean {
+  return (
+    filePath.includes('/__tests__/') ||
+    filePath.includes('/Tests/') ||
+    filePath.endsWith('.test.ts') ||
+    filePath.endsWith('.test.js') ||
+    filePath.endsWith('.spec.ts') ||
+    filePath.endsWith('.spec.js') ||
+    filePath.endsWith('Tests.swift')
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Test: key format validation
+// ---------------------------------------------------------------------------
+
+describe('assistant feature flag guard', () => {
+  test('no production files use legacy skills.<id>.enabled key format outside allowlist', () => {
+    // Search for the legacy key pattern in string literals across the codebase.
+    // The pattern matches quoted strings like 'skills.browser.enabled',
+    // "skills.browser.enabled", or `skills.browser.enabled`.
+    const pattern = `['"\`]skills\\.[a-z][a-z0-9._-]*\\.enabled['"\`]`;
+
+    let grepOutput = '';
+    try {
+      // Use execFileSync to avoid shell interpretation — the pattern contains
+      // backtick characters that would trigger command substitution in /bin/sh
+      // if passed through execSync's shell.
+      grepOutput = execFileSync(
+        'git',
+        ['grep', '-lE', pattern, '--', '*.ts', '*.tsx', '*.js', '*.jsx', '*.swift'],
+        { encoding: 'utf-8', cwd: getRepoRoot() },
+      ).trim();
+    } catch (err) {
+      // Exit code 1 means no matches — happy path
+      if ((err as { status?: number }).status === 1) {
+        return;
+      }
+      throw err;
+    }
+
+    const files = grepOutput.split('\n').filter((f) => f.length > 0);
+    const violations = files.filter((f) => {
+      if (isTestFile(f)) return false;
+      if (LEGACY_KEY_ALLOWLIST.has(f)) return false;
+      return true;
+    });
+
+    if (violations.length > 0) {
+      const message = [
+        'Found production files using the legacy `skills.<id>.enabled` key format.',
+        'New code must use the canonical format: `feature_flags.<id>.enabled`.',
+        'See AGENTS.md "Assistant Feature Flags" for the convention.',
+        '',
+        'Violations:',
+        ...violations.map((f) => `  - ${f}`),
+        '',
+        'To fix: replace `skills.<id>.enabled` with `feature_flags.<id>.enabled`.',
+        'If backward-compat access is genuinely needed, add to LEGACY_KEY_ALLOWLIST in assistant-feature-flag-guard.test.ts.',
+      ].join('\n');
+
+      expect(violations, message).toEqual([]);
+    }
+  });
+
+  // ---------------------------------------------------------------------------
+  // Test: unified registry key format (assistant-scope only)
+  // ---------------------------------------------------------------------------
+
+  test('all assistant-scope keys in the unified registry use the canonical feature_flags.<id>.enabled format', () => {
+    const registry = loadRegistry();
+    const assistantFlags = registry.flags.filter((f) => f.scope === 'assistant');
+    const keys = assistantFlags.map((f) => f.key);
+
+    const violations = keys.filter((key) => !CANONICAL_KEY_RE.test(key));
+
+    if (violations.length > 0) {
+      const message = [
+        'Found assistant-scope keys in the unified registry that do not match the canonical format.',
+        'Expected format: feature_flags.<flagId>.enabled',
+        '',
+        'Violations:',
+        ...violations.map((k) => `  - ${k}`),
+      ].join('\n');
+
+      expect(violations, message).toEqual([]);
+    }
+  });
+
+  // ---------------------------------------------------------------------------
+  // Test: registry entries have required fields
+  // ---------------------------------------------------------------------------
+
+  // ---------------------------------------------------------------------------
+  // Test: bundled registry copy stays in sync with canonical meta/ copy
+  // ---------------------------------------------------------------------------
+
+  test('bundled assistant/src/config/feature-flag-registry.json matches canonical meta/ copy', () => {
+    const canonicalPath = getRegistryPath();
+    const bundledPath = join(process.cwd(), 'src', 'config', 'feature-flag-registry.json');
+
+    const canonical = JSON.parse(readFileSync(canonicalPath, 'utf-8'));
+    const bundled = JSON.parse(readFileSync(bundledPath, 'utf-8'));
+
+    expect(bundled).toEqual(canonical);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Test: registry entries have required fields
+  // ---------------------------------------------------------------------------
+
+  test('all assistant-scope entries in the unified registry have required fields', () => {
+    const registry = loadRegistry();
+    const assistantFlags = registry.flags.filter((f) => f.scope === 'assistant');
+    const violations: string[] = [];
+
+    for (const flag of assistantFlags) {
+      if (typeof flag.defaultEnabled !== 'boolean') {
+        violations.push(`${flag.key}: missing or non-boolean 'defaultEnabled'`);
+      }
+      if (typeof flag.description !== 'string' || flag.description.length === 0) {
+        violations.push(`${flag.key}: missing or empty 'description'`);
+      }
+      if (typeof flag.label !== 'string' || flag.label.length === 0) {
+        violations.push(`${flag.key}: missing or empty 'label'`);
+      }
+      if (typeof flag.id !== 'string' || flag.id.length === 0) {
+        violations.push(`${flag.key}: missing or empty 'id'`);
+      }
+    }
+
+    if (violations.length > 0) {
+      const message = [
+        'Found entries in the unified registry with missing or invalid required fields.',
+        '',
+        'Violations:',
+        ...violations.map((v) => `  - ${v}`),
+      ].join('\n');
+
+      expect(violations, message).toEqual([]);
+    }
+  });
+});

package/src/__tests__/assistant-feature-flag-guardrails.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Guard tests for assistant feature flag conventions:
+ *
+ * 1. Key format: all feature flag keys used in production code must follow the
+ *    canonical `feature_flags.<flag_id>.enabled` format. Any remaining
+ *    `skills.<id>.enabled` usage outside of migration/backward-compat code is
+ *    flagged — including template literal forms like `skills.${skillId}.enabled`.
+ *
+ * 2. Declaration coverage: all literal keys passed to
+ *    `isAssistantFeatureFlagEnabled('<key>', ...)` in production code must be
+ *    declared in the unified registry. This keeps flag usage declarative while
+ *    allowing skills to exist without corresponding feature flags.
+ */
+
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, test } from 'bun:test';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Resolve the repo root from the assistant/ package directory. */
+function getRepoRoot(): string {
+  return join(process.cwd(), '..');
+}
+
+interface RegistryFlag {
+  id: string;
+  scope: string;
+  key: string;
+  label: string;
+  description: string;
+  defaultEnabled: boolean;
+}
+
+interface Registry {
+  version: number;
+  flags: RegistryFlag[];
+}
+
+function loadRegistry(): Registry {
+  const registryPath = join(getRepoRoot(), 'meta', 'feature-flags', 'feature-flag-registry.json');
+  return JSON.parse(readFileSync(registryPath, 'utf-8'));
+}
+
+/**
+ * Files allowed to contain `skills.<id>.enabled` string literals because they
+ * are part of the backward-compat / migration layer or are test files
+ * exercising legacy paths.
+ */
+const LEGACY_KEY_ALLOWLIST = new Set([
+  // Legacy wrapper (deprecated, kept for migration)
+  'assistant/src/config/skill-state.ts',
+  // Type definitions documenting the legacy format
+  'assistant/src/config/types.ts',
+  // macOS client: fallback reads from legacy config section
+  'clients/macos/vellum-assistant/Features/Settings/SettingsAccountTab.swift',
+]);
+
+function isTestFile(filePath: string): boolean {
+  return (
+    filePath.includes('/__tests__/') ||
+    filePath.endsWith('.test.ts') ||
+    filePath.endsWith('.test.js') ||
+    filePath.endsWith('.spec.ts') ||
+    filePath.endsWith('.spec.js')
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Guard 1: Key format — no stale `skills.<id>.enabled` in production code
+// ---------------------------------------------------------------------------
+
+describe('assistant feature flag key format guard', () => {
+  test('no production TypeScript files use skills.<id>.enabled outside allowlist', () => {
+    const repoRoot = getRepoRoot();
+
+    // Search for string literals and template literals containing
+    // `skills.<id>.enabled` or `skills.${...}.enabled` in .ts files
+    // under assistant/src/ and gateway/src/ (excluding test files and
+    // allowlisted paths). The pattern catches both literal keys
+    // (e.g., `skills.foo.enabled`) and template literal forms
+    // (e.g., `skills.${skillId}.enabled`).
+    let grepOutput = '';
+    try {
+      grepOutput = execSync(
+        `git grep -lE "skills\\.[a-z0-9_-]+\\.enabled|skills\\.\\$\\{" -- 'assistant/src/**/*.ts' 'gateway/src/**/*.ts'`,
+        { encoding: 'utf-8', cwd: repoRoot },
+      ).trim();
+    } catch (err) {
+      // Exit code 1 means no matches — happy path
+      if ((err as { status?: number }).status === 1) {
+        return;
+      }
+      throw err;
+    }
+
+    const files = grepOutput.split('\n').filter((f) => f.length > 0);
+    const violations = files.filter((f) => {
+      if (isTestFile(f)) return false;
+      if (LEGACY_KEY_ALLOWLIST.has(f)) return false;
+      return true;
+    });
+
+    if (violations.length > 0) {
+      const message = [
+        'Found production TypeScript files using legacy `skills.<id>.enabled` key format.',
+        'Use the canonical `feature_flags.<id>.enabled` format instead.',
+        'Call `isAssistantFeatureFlagEnabled(`feature_flags.${skillId}.enabled`, config)` to check skill flags.',
+        '',
+        'Violations:',
+        ...violations.map((f) => `  - ${f}`),
+        '',
+        'If this is a legitimate backward-compat path, add it to LEGACY_KEY_ALLOWLIST in',
+        'assistant-feature-flag-guardrails.test.ts.',
+      ].join('\n');
+
+      expect(violations, message).toEqual([]);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Guard 2: Declaration coverage for literal key usage
+// ---------------------------------------------------------------------------
+
+describe('assistant feature flag declaration coverage guard', () => {
+  test('all literal flag keys in isAssistantFeatureFlagEnabled calls are declared in the unified registry', () => {
+    const repoRoot = getRepoRoot();
+
+    // Load the unified registry and extract assistant-scope keys
+    const registry = loadRegistry();
+    const declaredKeys = new Set(
+      registry.flags
+        .filter((f) => f.scope === 'assistant')
+        .map((f) => f.key),
+    );
+
+    // Extract full keys from isAssistantFeatureFlagEnabled('<key>', ...) calls
+    // in non-test production files. We read each matching file and apply a
+    // multiline regex so that calls split across lines are still caught:
+    //
+    //   isAssistantFeatureFlagEnabled(
+    //     'feature_flags.foo.enabled',
+    //     config,
+    //   )
+    //
+    const usedKeys = new Set<string>();
+    let matchingFiles = '';
+    try {
+      matchingFiles = execSync(
+        `git grep -l "isAssistantFeatureFlagEnabled" -- 'assistant/src/**/*.ts' ':!assistant/src/__tests__/**'`,
+        { encoding: 'utf-8', cwd: repoRoot },
+      ).trim();
+    } catch (err) {
+      if ((err as { status?: number }).status !== 1) throw err;
+    }
+
+    if (matchingFiles) {
+      // Multiline regex: match the function name, optional whitespace/newlines,
+      // opening paren, optional whitespace/newlines, then a quoted string key.
+      const multilinePattern = /isAssistantFeatureFlagEnabled\(\s*['"]([^'"]+)['"]/g;
+      for (const relPath of matchingFiles.split('\n')) {
+        if (!relPath) continue;
+        const absPath = join(repoRoot, relPath);
+        const content = readFileSync(absPath, 'utf-8');
+        for (const match of content.matchAll(multilinePattern)) {
+          usedKeys.add(match[1]);
+        }
+      }
+    }
+
+    // Check that all used keys are declared in the registry
+    const undeclared: string[] = [];
+    for (const key of usedKeys) {
+      if (!declaredKeys.has(key)) {
+        undeclared.push(key);
+      }
+    }
+
+    if (undeclared.length > 0) {
+      const message = [
+        'Found feature flag keys used in production code that are NOT declared in the unified registry.',
+        `Registry: meta/feature-flags/feature-flag-registry.json`,
+        '',
+        'Undeclared keys:',
+        ...undeclared.map((k) => `  - ${k}`),
+        '',
+        'To fix: add the missing key(s) to the unified registry with scope "assistant".',
+      ].join('\n');
+
+      expect(undeclared, message).toEqual([]);
+    }
+  });
+});

package/src/__tests__/assistant-feature-flags-integration.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Integration tests for assistant feature flag enforcement at system prompt,
+ * skill_load, and session-skill-tools projection layers.
+ *
+ * Covers:
+ *   - Flag OFF blocks all exposure paths
+ *   - Missing persisted value falls back to code default
+ *   - New assistantFeatureFlagValues is the sole override mechanism
+ *   - Undeclared keys default to enabled
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+// ---------------------------------------------------------------------------
+// Test-scoped temp directory and config state
+// ---------------------------------------------------------------------------
+
+const TEST_DIR = join(tmpdir(), `vellum-asst-flags-test-${crypto.randomUUID()}`);
+
+let currentConfig: Record<string, unknown> = {
+  sandbox: { enabled: false, backend: 'native' },
+};
+
+const DECLARED_FLAG_KEY = 'feature_flags.hatch-new-assistant.enabled';
+const DECLARED_SKILL_ID = 'hatch-new-assistant';
+
+mock.module('../util/platform.js', () => ({
+  getRootDir: () => TEST_DIR,
+  getDataDir: () => TEST_DIR,
+  getWorkspaceDir: () => TEST_DIR,
+  getWorkspaceConfigPath: () => join(TEST_DIR, 'config.json'),
+  getWorkspaceSkillsDir: () => join(TEST_DIR, 'skills'),
+  getWorkspaceHooksDir: () => join(TEST_DIR, 'hooks'),
+  getWorkspacePromptPath: (file: string) => join(TEST_DIR, file),
+  ensureDataDir: () => {},
+  getSocketPath: () => join(TEST_DIR, 'vellum.sock'),
+  getPidPath: () => join(TEST_DIR, 'vellum.pid'),
+  getDbPath: () => join(TEST_DIR, 'data', 'assistant.db'),
+  getLogPath: () => join(TEST_DIR, 'logs', 'vellum.log'),
+  getHistoryPath: () => join(TEST_DIR, 'history'),
+  getHooksDir: () => join(TEST_DIR, 'hooks'),
+  getIpcBlobDir: () => join(TEST_DIR, 'ipc-blobs'),
+  getSandboxRootDir: () => join(TEST_DIR, 'sandbox'),
+  getSandboxWorkingDir: () => TEST_DIR,
+  getInterfacesDir: () => join(TEST_DIR, 'interfaces'),
+  isMacOS: () => false,
+  isLinux: () => false,
+  isWindows: () => false,
+  getPlatformName: () => 'linux',
+  getClipboardCommand: () => null,
+  removeSocketFile: () => {},
+  migratePath: () => {},
+  migrateToWorkspaceLayout: () => {},
+  migrateToDataLayout: () => {},
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+  isDebug: () => false,
+  truncateForLog: (v: string) => v,
+}));
+
+mock.module('../config/loader.js', () => ({
+  getConfig: () => currentConfig,
+}));
+
+mock.module('../config/user-reference.js', () => ({
+  resolveUserReference: () => 'TestUser',
+}));
+
+mock.module('../security/parental-control-store.js', () => ({
+  getParentalControlSettings: () => ({ enabled: false, contentRestrictions: [], blockedToolCategories: [] }),
+}));
+
+mock.module('../tools/credentials/metadata-store.js', () => ({
+  listCredentialMetadata: () => [],
+}));
+
+const { buildSystemPrompt } = await import('../config/system-prompt.js');
+const { isAssistantFeatureFlagEnabled } = await import('../config/assistant-feature-flags.js');
+const { isSkillFeatureEnabled } = await import('../config/skill-state.js');
+
+// ---------------------------------------------------------------------------
+// Setup / Teardown
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+  currentConfig = {
+    sandbox: { enabled: false, backend: 'native' },
+  };
+});
+
+afterEach(() => {
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createSkillOnDisk(id: string, name: string, description: string): void {
+  const skillsDir = join(TEST_DIR, 'skills');
+  mkdirSync(join(skillsDir, id), { recursive: true });
+  writeFileSync(
+    join(skillsDir, id, 'SKILL.md'),
+    `---\nname: "${name}"\ndescription: "${description}"\n---\n\nInstructions for ${id}.\n`,
+  );
+  const indexPath = join(skillsDir, 'SKILLS.md');
+  const existing = existsSync(indexPath) ? readFileSync(indexPath, 'utf-8') : '';
+  writeFileSync(indexPath, existing + `- ${id}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// System prompt — assistant feature flag filtering
+// ---------------------------------------------------------------------------
+
+describe('buildSystemPrompt assistant feature flag filtering', () => {
+  test('flag OFF skill does not appear in <available_skills> section', () => {
+    createSkillOnDisk(DECLARED_SKILL_ID, 'Hatch New Assistant', 'Toggle hatch new assistant behavior');
+    createSkillOnDisk('twitter', 'Twitter', 'Post to X/Twitter');
+
+    currentConfig = {
+      sandbox: { enabled: false, backend: 'native' },
+      assistantFeatureFlagValues: { [DECLARED_FLAG_KEY]: false },
+    };
+
+    const result = buildSystemPrompt();
+
+    expect(result).toContain('id="twitter"');
+    expect(result).not.toContain(`id="${DECLARED_SKILL_ID}"`);
+  });
+
+  test('all skills visible when no flag overrides set', () => {
+    createSkillOnDisk(DECLARED_SKILL_ID, 'Hatch New Assistant', 'Toggle hatch new assistant behavior');
+    createSkillOnDisk('twitter', 'Twitter', 'Post to X/Twitter');
+
+    currentConfig = {
+      sandbox: { enabled: false, backend: 'native' },
+    };
+
+    const result = buildSystemPrompt();
+
+    expect(result).toContain(`id="${DECLARED_SKILL_ID}"`);
+    expect(result).toContain('id="twitter"');
+  });
+
+  test('flagged-off skills hidden when all flags are OFF', () => {
+    createSkillOnDisk(DECLARED_SKILL_ID, 'Hatch New Assistant', 'Toggle hatch new assistant behavior');
+    createSkillOnDisk('twitter', 'Twitter', 'Post to X/Twitter');
+
+    currentConfig = {
+      sandbox: { enabled: false, backend: 'native' },
+      assistantFeatureFlagValues: {
+        [DECLARED_FLAG_KEY]: false,
+        'feature_flags.twitter.enabled': false,
+      },
+    };
+
+    const result = buildSystemPrompt();
+
+    expect(result).not.toContain(`id="${DECLARED_SKILL_ID}"`);
+    expect(result).not.toContain('id="twitter"');
+  });
+
+  test('assistantFeatureFlagValues overrides control visibility', () => {
+    createSkillOnDisk(DECLARED_SKILL_ID, 'Hatch New Assistant', 'Toggle hatch new assistant behavior');
+
+    currentConfig = {
+      sandbox: { enabled: false, backend: 'native' },
+      assistantFeatureFlagValues: { [DECLARED_FLAG_KEY]: true },
+    };
+
+    const result = buildSystemPrompt();
+
+    expect(result).toContain(`id="${DECLARED_SKILL_ID}"`);
+  });
+
+  test('persisted overrides for undeclared flags are respected', () => {
+    createSkillOnDisk('browser', 'Browser', 'Web browsing automation');
+
+    currentConfig = {
+      sandbox: { enabled: false, backend: 'native' },
+      assistantFeatureFlagValues: { 'feature_flags.browser.enabled': false },
+    };
+
+    const result = buildSystemPrompt();
+
+    // Even though 'browser' is not in the defaults registry, the user
+    // explicitly disabled it — that override must be honored.
+    expect(result).not.toContain('id="browser"');
+  });
+
+  test('undeclared flags with no persisted override default to enabled', () => {
+    createSkillOnDisk('browser', 'Browser', 'Web browsing automation');
+
+    currentConfig = {
+      sandbox: { enabled: false, backend: 'native' },
+    };
+
+    const result = buildSystemPrompt();
+
+    expect(result).toContain('id="browser"');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Resolver unit tests (within integration context)
+// ---------------------------------------------------------------------------
+
+describe('isAssistantFeatureFlagEnabled', () => {
+  test('reads from assistantFeatureFlagValues', () => {
+    const config = {
+      assistantFeatureFlagValues: { [DECLARED_FLAG_KEY]: true },
+    } as any;
+
+    expect(isAssistantFeatureFlagEnabled(DECLARED_FLAG_KEY, config)).toBe(true);
+  });
+
+  test('explicit false override in assistantFeatureFlagValues', () => {
+    const config = {
+      assistantFeatureFlagValues: { [DECLARED_FLAG_KEY]: false },
+    } as any;
+
+    expect(isAssistantFeatureFlagEnabled(DECLARED_FLAG_KEY, config)).toBe(false);
+  });
+
+  test('missing persisted value falls back to defaults registry defaultEnabled', () => {
+    // No explicit config at all — should fall back to defaults registry
+    // which has defaultEnabled: true for hatch-new-assistant
+    const config = {} as any;
+
+    expect(isAssistantFeatureFlagEnabled(DECLARED_FLAG_KEY, config)).toBe(true);
+  });
+
+  test('unknown flag defaults to true when no persisted override', () => {
+    const config = {} as any;
+
+    expect(isAssistantFeatureFlagEnabled('feature_flags.unknown-skill.enabled', config)).toBe(true);
+  });
+
+  test('undeclared flag respects persisted canonical override', () => {
+    const config = {
+      assistantFeatureFlagValues: { 'feature_flags.browser.enabled': false },
+    } as any;
+
+    expect(isAssistantFeatureFlagEnabled('feature_flags.browser.enabled', config)).toBe(false);
+  });
+});
+
+describe('legacy isSkillFeatureEnabled backward compat', () => {
+  test('delegates to the canonical resolver', () => {
+    const config = {
+      assistantFeatureFlagValues: { [DECLARED_FLAG_KEY]: false },
+    } as any;
+
+    expect(isSkillFeatureEnabled(DECLARED_SKILL_ID, config)).toBe(false);
+  });
+
+  test('enabled when no override set', () => {
+    const config = {} as any;
+
+    expect(isSkillFeatureEnabled(DECLARED_SKILL_ID, config)).toBe(true);
+  });
+});