@soleri/core 9.14.4 → 9.16.7

package/src/runtime/admin-setup-ops.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createAdminSetupOps } from './admin-setup-ops.js';
+import { createAdminSetupOps, syncHooksToClaudeSettings } from './admin-setup-ops.js';
 import type { AgentRuntime } from './types.js';
 import type { OpDefinition } from '../facades/types.js';
 
@@ -46,6 +46,11 @@ vi.mock('./claude-md-helpers.js', () => ({
   injectEngineRulesBlock: vi.fn((content: string) => content),
 }));
 
+vi.mock('../paths.js', () => ({
+  agentPlansPath: vi.fn(() => '/mock-home/.soleri/test-agent/plans.json'),
+  agentVaultPath: vi.fn(() => '/mock-home/.soleri/test-agent/vault.db'),
+}));
+
 vi.mock('../skills/sync-skills.js', () => ({
   discoverSkills: vi.fn(() => [{ name: 'skill-1', path: '/mock/skills/skill-1' }]),
   syncSkillsToClaudeCode: vi.fn(() => ({
@@ -101,18 +106,6 @@ describe('createAdminSetupOps', () => {
     ops = createAdminSetupOps(runtime);
   });
 
-  it('returns 4 ops', () => {
-    expect(ops).toHaveLength(4);
-  });
-
-  it('all ops have required fields', () => {
-    for (const op of ops) {
-      expect(op.name).toBeTruthy();
-      expect(op.handler).toBeDefined();
-      expect(['read', 'write', 'admin']).toContain(op.auth);
-    }
-  });
-
   describe('admin_inject_claude_md', () => {
     it('returns error when CLAUDE.md not found and createIfMissing is false', async () => {
       const result = (await findOp(ops, 'admin_inject_claude_md').handler({
@@ -290,6 +283,190 @@ describe('createAdminSetupOps', () => {
     });
   });
 
+  describe('syncHooksToClaudeSettings', () => {
+    it('installs SessionStart, PreCompact, and Stop hooks on fresh settings', () => {
+      const result = syncHooksToClaudeSettings('test-agent');
+      const written = mockFs['/mock-home/.claude/settings.json'];
+      expect(written).toBeDefined();
+      const settings = JSON.parse(written);
+      expect(settings.hooks.SessionStart).toHaveLength(2);
+      expect(settings.hooks.PreCompact).toHaveLength(1);
+      expect(settings.hooks.Stop).toHaveLength(1);
+      expect(result.installed).toContain('SessionStart');
+      expect(result.installed).toContain('PreCompact');
+      expect(result.installed).toContain('Stop');
+      expect(result.updated).toHaveLength(0);
+      expect(result.skipped).toHaveLength(0);
+      expect(result.error).toBeUndefined();
+    });
+
+    it('includes the {agentId}-mode skill hook in SessionStart', () => {
+      syncHooksToClaudeSettings('test-agent');
+      const settings = JSON.parse(mockFs['/mock-home/.claude/settings.json']);
+      const commands = settings.hooks.SessionStart.flatMap((g: { hooks: { command?: string }[] }) =>
+        g.hooks.map((h) => h.command),
+      );
+      expect(commands.some((c: string) => c.includes('test-agent-mode skill'))).toBe(true);
+    });
+
+    it('includes the admin_health hook in SessionStart', () => {
+      syncHooksToClaudeSettings('test-agent');
+      const settings = JSON.parse(mockFs['/mock-home/.claude/settings.json']);
+      const commands = settings.hooks.SessionStart.flatMap((g: { hooks: { command?: string }[] }) =>
+        g.hooks.map((h) => h.command),
+      );
+      expect(commands.some((c: string) => c.includes('admin_health'))).toBe(true);
+    });
+
+    it('is idempotent — running twice produces the same output', () => {
+      syncHooksToClaudeSettings('test-agent');
+      const after1 = mockFs['/mock-home/.claude/settings.json'];
+      const result2 = syncHooksToClaudeSettings('test-agent');
+      const after2 = mockFs['/mock-home/.claude/settings.json'];
+      expect(after1).toBe(after2);
+      expect(result2.skipped).toContain('SessionStart');
+      expect(result2.installed).toHaveLength(0);
+      expect(result2.updated).toHaveLength(0);
+    });
+
+    it('preserves non-agent hooks already in settings', () => {
+      mockFs['/mock-home/.claude/settings.json'] = JSON.stringify({
+        hooks: {
+          SessionStart: [{ hooks: [{ type: 'command', command: 'echo existing' }] }],
+        },
+      });
+      syncHooksToClaudeSettings('test-agent');
+      const settings = JSON.parse(mockFs['/mock-home/.claude/settings.json']);
+      const commands = settings.hooks.SessionStart.flatMap((g: { hooks: { command?: string }[] }) =>
+        g.hooks.map((h) => h.command),
+      );
+      expect(commands).toContain('echo existing');
+      expect(commands.some((c: string) => c.includes('admin_health'))).toBe(true);
+    });
+
+    it('updates stale agent hooks to match current defaults', () => {
+      // A stale hook contains the agent marker but outdated content
+      mockFs['/mock-home/.claude/settings.json'] = JSON.stringify({
+        hooks: {
+          SessionStart: [
+            {
+              hooks: [
+                {
+                  type: 'command',
+                  command: `root=$(git rev-parse --show-toplevel 2>/dev/null || echo "."); if grep -q '"test-agent"' "$root/.mcp.json" 2>/dev/null; then echo 'Call mcp__test-agent__test-agent_admin op:OLD_STALE_OP'; fi`,
+                  timeout: 5000,
+                },
+              ],
+            },
+          ],
+        },
+      });
+      const result = syncHooksToClaudeSettings('test-agent');
+      const settings = JSON.parse(mockFs['/mock-home/.claude/settings.json']);
+      const commands = settings.hooks.SessionStart.flatMap((g: { hooks: { command?: string }[] }) =>
+        g.hooks.map((h) => h.command),
+      );
+      expect(commands.some((c: string) => c.includes('OLD_STALE_OP'))).toBe(false);
+      expect(commands.some((c: string) => c.includes('admin_health'))).toBe(true);
+      expect(result.updated).toContain('SessionStart');
+      expect(result.error).toBeUndefined();
+    });
+
+    it('returns error field when write fails', async () => {
+      const { writeFileSync } = await import('node:fs');
+      vi.mocked(writeFileSync).mockImplementationOnce(() => {
+        throw new Error('EACCES: permission denied');
+      });
+      const result = syncHooksToClaudeSettings('test-agent');
+      expect(result.error).toMatch(/EACCES/);
+      expect(result.installed).toHaveLength(0);
+      expect(result.updated).toHaveLength(0);
+      expect(result.skipped).toHaveLength(0);
+    });
+  });
+
+  describe('multi-agent hook coexistence', () => {
+    type HookGroup = { hooks: { command?: string }[] };
+
+    function getSessionStartCommands(): string[] {
+      const settings = JSON.parse(mockFs['/mock-home/.claude/settings.json']);
+      return (settings.hooks.SessionStart as HookGroup[]).flatMap((g) =>
+        g.hooks.map((h) => h.command ?? ''),
+      );
+    }
+
+    function getAgentCommands(agentId: string): string[] {
+      const settings = JSON.parse(mockFs['/mock-home/.claude/settings.json']);
+      return (settings.hooks.SessionStart as HookGroup[])
+        .flatMap((g) => g.hooks)
+        .map((h) => h.command ?? '')
+        .filter((c) => c.includes(agentId));
+    }
+
+    it('install A then B — both sets present, no overlap', () => {
+      syncHooksToClaudeSettings('agent-a');
+      syncHooksToClaudeSettings('agent-b');
+
+      const commands = getSessionStartCommands();
+
+      // Both agents must have hooks present
+      expect(commands.some((c) => c.includes('agent-a'))).toBe(true);
+      expect(commands.some((c) => c.includes('agent-b'))).toBe(true);
+
+      // agent-a commands must not mention agent-b and vice versa
+      const aCommands = getAgentCommands('agent-a');
+      const bCommands = getAgentCommands('agent-b');
+
+      expect(aCommands.every((c) => !c.includes('agent-b'))).toBe(true);
+      expect(bCommands.every((c) => !c.includes('agent-a'))).toBe(true);
+    });
+
+    it('re-install A after B — B hooks untouched', () => {
+      syncHooksToClaudeSettings('agent-a');
+      syncHooksToClaudeSettings('agent-b');
+
+      const beforeB = getAgentCommands('agent-b');
+
+      syncHooksToClaudeSettings('agent-a'); // re-run A (e.g. after update)
+
+      const afterB = getAgentCommands('agent-b');
+
+      expect(afterB).toEqual(beforeB);
+    });
+
+    it('no duplicates after running both twice', () => {
+      syncHooksToClaudeSettings('agent-a');
+      syncHooksToClaudeSettings('agent-b');
+
+      const settings1 = JSON.parse(mockFs['/mock-home/.claude/settings.json']);
+      const groupCountAfterTwo = (settings1.hooks.SessionStart as HookGroup[]).length;
+
+      syncHooksToClaudeSettings('agent-a');
+      syncHooksToClaudeSettings('agent-b');
+
+      const settings2 = JSON.parse(mockFs['/mock-home/.claude/settings.json']);
+      const groupCountAfterFour = (settings2.hooks.SessionStart as HookGroup[]).length;
+
+      expect(groupCountAfterFour).toBe(groupCountAfterTwo);
+    });
+
+    it('manually added non-agent hook survives all agent installs', () => {
+      // Pre-populate settings with a non-agent hook in SessionStart
+      mockFs['/mock-home/.claude/settings.json'] = JSON.stringify({
+        hooks: {
+          SessionStart: [{ hooks: [{ type: 'command', command: 'echo custom-non-agent-hook' }] }],
+        },
+      });
+
+      syncHooksToClaudeSettings('agent-a');
+      syncHooksToClaudeSettings('agent-b');
+      syncHooksToClaudeSettings('agent-a');
+
+      const commands = getSessionStartCommands();
+      expect(commands).toContain('echo custom-non-agent-hook');
+    });
+  });
+
   describe('admin_check_persistence', () => {
     it('returns NO_STORAGE_DIRECTORY when nothing exists', async () => {
       const result = (await findOp(ops, 'admin_check_persistence').handler({})) as Record<
@@ -330,5 +507,44 @@ describe('createAdminSetupOps', () => {
       expect(activePlans[0].status).toBe('executing');
       expect(result.recommendation).toContain('need attention');
     });
+
+    it('uses configured or resolved .soleri plan paths and understands planner stores', async () => {
+      runtime = {
+        ...createMockRuntime(),
+        config: {
+          agentId: 'test-agent',
+          dataDir: '/mock/agent-data',
+          agentDir: '/mock/agent-dir',
+        },
+      } as unknown as AgentRuntime;
+      ops = createAdminSetupOps(runtime);
+
+      mockDirs.add('/mock-home/.soleri/test-agent');
+      mockFs['/mock-home/.soleri/test-agent/vault.db'] = 'binary';
+      mockFs['/mock-home/.soleri/test-agent/plans.json'] = JSON.stringify({
+        version: '1.0',
+        plans: [
+          { id: 'plan-1', status: 'executing' },
+          { id: 'plan-2', status: 'completed' },
+        ],
+      });
+
+      const result = (await findOp(ops, 'admin_check_persistence').handler({})) as Record<
+        string,
+        unknown
+      >;
+
+      expect((result.storageDirectory as Record<string, unknown>).path).toBe(
+        '/mock-home/.soleri/test-agent',
+      );
+      expect(
+        ((result.files as Record<string, unknown>).plans as Record<string, unknown>).path,
+      ).toBe('/mock-home/.soleri/test-agent/plans.json');
+      expect(
+        ((result.files as Record<string, unknown>).plans as Record<string, unknown>).items,
+      ).toBe(2);
+      expect(result.status).toBe('PERSISTENCE_ACTIVE');
+      expect(result.activePlans).toEqual([{ id: 'plan-1', status: 'executing' }]);
+    });
   });
 });

package/src/runtime/admin-setup-ops.ts

@@ -27,6 +27,10 @@ import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
+import {
+  agentPlansPath as getAgentPlansPath,
+  agentVaultPath as getAgentVaultPath,
+} from '../paths.js';
 import {
   hasSections,
   removeSections,
@@ -74,19 +78,63 @@ function getFileInfo(path: string): { exists: boolean; size: number; items: numb
   try {
     const stat = statSync(path);
     const content = JSON.parse(readFileSync(path, 'utf-8'));
-    const items = content.items
-      ? Object.keys(content.items).length
-      : content.contexts
-        ? content.contexts.length
-        : Array.isArray(content)
-          ? content.length
-          : 0;
+    const items = countPersistedItems(content);
     return { exists: true, size: stat.size, items };
   } catch {
     return { exists: true, size: 0, items: -1 };
   }
 }
 
+function countPersistedItems(content: unknown): number {
+  if (Array.isArray(content)) return content.length;
+  if (!content || typeof content !== 'object') return 0;
+
+  const data = content as Record<string, unknown>;
+  if (Array.isArray(data.plans)) return data.plans.length;
+  if (data.items && typeof data.items === 'object') return Object.keys(data.items).length;
+  if (Array.isArray(data.contexts)) return data.contexts.length;
+  return 0;
+}
+
+function extractActivePlans(content: unknown): Array<{ id: string; status: string }> {
+  if (!content || typeof content !== 'object') return [];
+
+  const plans = Array.isArray((content as Record<string, unknown>).plans)
+    ? ((content as Record<string, unknown>).plans as unknown[])
+    : null;
+  if (plans) {
+    return plans.flatMap((plan) => {
+      if (!plan || typeof plan !== 'object') return [];
+      const p = plan as Record<string, unknown>;
+      const id = typeof p.id === 'string' ? p.id : null;
+      const lifecycle =
+        typeof p.lifecycleStatus === 'string'
+          ? p.lifecycleStatus
+          : typeof p.status === 'string'
+            ? p.status
+            : null;
+      if (!id || (lifecycle !== 'executing' && lifecycle !== 'reconciling')) return [];
+      return [{ id, status: lifecycle }];
+    });
+  }
+
+  const items = (content as Record<string, unknown>).items;
+  if (!items || typeof items !== 'object') return [];
+
+  return Object.entries(items).flatMap(([id, plan]) => {
+    if (!plan || typeof plan !== 'object') return [];
+    const p = plan as Record<string, unknown>;
+    const lifecycle =
+      typeof p.lifecycleStatus === 'string'
+        ? p.lifecycleStatus
+        : typeof p.status === 'string'
+          ? p.status
+          : null;
+    if (lifecycle !== 'executing' && lifecycle !== 'reconciling') return [];
+    return [{ id, status: lifecycle }];
+  });
+}
+
 /** Discover hookify rule files in a directory */
 function discoverHookifyFiles(dir: string): Array<{ name: string; path: string }> {
   if (!existsSync(dir)) return [];
@@ -97,6 +145,37 @@ function discoverHookifyFiles(dir: string): Array<{ name: string; path: string }
 
 // discoverSkills imported from '../skills/sync-skills.js'
 
+// ─── Deep Equality Helper ─────────────────────────────────────────────
+
+/** Recursively compare two values by structure, independent of key insertion order. */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== 'object') return false;
+
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+
+  const objA = a as Record<string, unknown>;
+  const objB = b as Record<string, unknown>;
+  const keysA = Object.keys(objA);
+  const keysB = Object.keys(objB);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (!Object.prototype.hasOwnProperty.call(objB, key)) return false;
+    if (!deepEqual(objA[key], objB[key])) return false;
+  }
+  return true;
+}
+
 // ─── Settings.json Hook Merging ───────────────────────────────────────
 
 interface SettingsHook {
@@ -119,7 +198,7 @@ interface SettingsHookGroup {
 function buildConditionalHookCommand(agentId: string, instruction: string): string {
   // Escape single quotes in instruction for safe shell embedding
   const escaped = instruction.replace(/'/g, "'\\''");
-  return `root=$(git rev-parse --show-toplevel 2>/dev/null || echo "."); if grep -q '"${agentId}"' "$root/.mcp.json" 2>/dev/null; then echo '${escaped}'; fi`;
+  return `root=$(git rev-parse --show-toplevel 2>/dev/null || echo "."); if grep -qF '"${agentId}"' "$root/.mcp.json" 2>/dev/null; then echo '${escaped}'; fi`;
 }
 
 /** Default lifecycle hooks for any Soleri agent */
@@ -141,6 +220,16 @@ function getDefaultLifecycleHooks(agentId: string): Record<string, SettingsHookG
           },
         ],
       },
+      {
+        matcher: '',
+        hooks: [
+          {
+            type: 'command',
+            command: `echo 'SESSION_START: Invoke the ${agentId}-mode skill now to load full routing context and command reference.'`,
+            timeout: 5,
+          },
+        ],
+      },
     ],
     PreCompact: [
       {
@@ -178,8 +267,11 @@ function getDefaultLifecycleHooks(agentId: string): Record<string, SettingsHookG
 /** Check if a hook group belongs to this agent by inspecting prompts for the marker */
 function isAgentHookGroup(group: SettingsHookGroup, agentId: string): boolean {
   const marker = `mcp__${agentId}__${agentId}_`;
+  const skillMarker = `${agentId}-mode skill`;
   return group.hooks.some(
-    (h) => (h.prompt && h.prompt.includes(marker)) || (h.command && h.command.includes(marker)),
+    (h) =>
+      (h.prompt && (h.prompt.includes(marker) || h.prompt.includes(skillMarker))) ||
+      (h.command && (h.command.includes(marker) || h.command.includes(skillMarker))),
   );
 }
 
@@ -206,29 +298,55 @@ function mergeSettingsHooks(
       continue;
     }
 
-    // Check if agent group already exists
-    const existingIdx = merged[event].findIndex((g) => isAgentHookGroup(g, agentId));
+    // Remove all existing agent-owned groups, keep non-agent hooks
+    const nonAgentGroups = merged[event].filter((g) => !isAgentHookGroup(g, agentId));
+    const existingAgentGroups = merged[event].filter((g) => isAgentHookGroup(g, agentId));
 
-    if (existingIdx === -1) {
-      // Append agent hooks (don't touch non-agent hooks)
-      merged[event].push(...groups);
+    if (deepEqual(existingAgentGroups, groups)) {
+      skipped.push(event);
+    } else if (existingAgentGroups.length === 0) {
+      merged[event] = [...nonAgentGroups, ...groups];
       installed.push(event);
     } else {
-      // Check if template matches
-      const existing = JSON.stringify(merged[event][existingIdx]);
-      const template = JSON.stringify(groups[0]);
-      if (existing === template) {
-        skipped.push(event);
-      } else {
-        merged[event][existingIdx] = groups[0];
-        updated.push(event);
-      }
+      // Replace all agent groups with current defaults
+      merged[event] = [...nonAgentGroups, ...groups];
+      updated.push(event);
     }
   }
 
   return { hooks: merged, installed, updated, skipped };
 }
 
+/**
+ * Auto-sync lifecycle hooks into ~/.claude/settings.json at engine startup.
+ * Idempotent — skips hooks already present, updates stale ones.
+ * Returns a summary of what was installed, updated, or skipped.
+ */
+export function syncHooksToClaudeSettings(agentId: string): {
+  installed: string[];
+  updated: string[];
+  skipped: string[];
+  error?: string;
+} {
+  try {
+    const settings = readSettingsJson();
+    const currentHooks = (settings.hooks ?? {}) as Record<string, SettingsHookGroup[]>;
+    const { hooks, installed, updated, skipped } = mergeSettingsHooks(currentHooks, agentId);
+    if (installed.length > 0 || updated.length > 0) {
+      writeSettingsJson({ ...settings, hooks });
+    }
+    return { installed, updated, skipped };
+  } catch (err) {
+    // Non-fatal — hooks will be installed on next run or via admin_setup_global
+    return {
+      installed: [],
+      updated: [],
+      skipped: [],
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
 // ─── Op Definitions ───────────────────────────────────────────────────
 
 /**
@@ -621,15 +739,15 @@ export function createAdminSetupOps(runtime: AgentRuntime): OpDefinition[] {
       auth: 'read',
       handler: async () => {
         const { agentId, plansPath, vaultPath } = config;
-        const storageDir = join(homedir(), `.${agentId}`);
+        const plansFile = plansPath ?? getAgentPlansPath(agentId);
+        const vaultFile = vaultPath ?? getAgentVaultPath(agentId);
+        const storageDir = dirname(plansFile);
         const storageDirExists = existsSync(storageDir);
 
         // Check plan storage
-        const plansFile = plansPath ?? join(storageDir, 'plans.json');
         const plansInfo = getFileInfo(plansFile);
 
         // Check vault
-        const vaultFile = vaultPath ?? join(storageDir, 'vault.db');
         const vaultExists = existsSync(vaultFile);
         let vaultSize = 0;
         if (vaultExists) {
@@ -655,16 +773,7 @@ export function createAdminSetupOps(runtime: AgentRuntime): OpDefinition[] {
         if (plansInfo.exists) {
           try {
             const plansData = JSON.parse(readFileSync(plansFile, 'utf-8'));
-            const items = plansData.items ?? plansData;
-            if (typeof items === 'object' && items !== null) {
-              for (const [id, plan] of Object.entries(items)) {
-                const p = plan as Record<string, unknown>;
-                const lifecycle = (p.lifecycleStatus ?? p.status) as string | undefined;
-                if (lifecycle === 'executing' || lifecycle === 'reconciling') {
-                  activePlans.push({ id, status: lifecycle });
-                }
-              }
-            }
+            activePlans.push(...extractActivePlans(plansData));
           } catch {
             // Parse error — not critical
           }

package/src/runtime/archive-ops.test.ts

@@ -83,34 +83,6 @@ describe('createArchiveOps', () => {
     ops = createArchiveOps(runtime);
   });
 
-  it('returns 12 ops', () => {
-    expect(ops).toHaveLength(12);
-  });
-
-  it('all ops have required fields', () => {
-    for (const op of ops) {
-      expect(op.name).toBeTruthy();
-      expect(op.handler).toBeDefined();
-      expect(['read', 'write', 'admin']).toContain(op.auth);
-    }
-  });
-
-  it('contains expected op names', () => {
-    const names = ops.map((o) => o.name);
-    expect(names).toContain('vault_archive');
-    expect(names).toContain('vault_restore');
-    expect(names).toContain('vault_optimize');
-    expect(names).toContain('vault_backup');
-    expect(names).toContain('vault_age_report');
-    expect(names).toContain('vault_set_temporal');
-    expect(names).toContain('vault_find_expiring');
-    expect(names).toContain('vault_find_expired');
-    expect(names).toContain('knowledge_audit');
-    expect(names).toContain('knowledge_health');
-    expect(names).toContain('knowledge_merge');
-    expect(names).toContain('knowledge_reorganize');
-  });
-
   describe('vault_archive', () => {
     it('archives old entries', async () => {
       await findOp(ops, 'vault_archive').handler({

package/src/runtime/branching-ops.test.ts

@@ -35,23 +35,6 @@ describe('branching-ops', () => {
     ops = captureOps(createBranchingOps(runtime));
   });
 
-  it('registers all 5 branching ops', () => {
-    expect(ops.size).toBe(5);
-    expect(ops.has('vault_branch')).toBe(true);
-    expect(ops.has('vault_branch_add')).toBe(true);
-    expect(ops.has('vault_branch_list')).toBe(true);
-    expect(ops.has('vault_merge_branch')).toBe(true);
-    expect(ops.has('vault_delete_branch')).toBe(true);
-  });
-
-  it('has correct auth levels', () => {
-    expect(ops.get('vault_branch')!.auth).toBe('write');
-    expect(ops.get('vault_branch_add')!.auth).toBe('write');
-    expect(ops.get('vault_branch_list')!.auth).toBe('read');
-    expect(ops.get('vault_merge_branch')!.auth).toBe('admin');
-    expect(ops.get('vault_delete_branch')!.auth).toBe('admin');
-  });
-
   describe('vault_branch', () => {
     it('creates a branch', async () => {
       const result = await executeOp(ops, 'vault_branch', { name: 'experiment' });

package/src/runtime/capture-ops.test.ts

@@ -83,18 +83,6 @@ describe('createCaptureOps', () => {
     ops = createCaptureOps(runtime);
   });
 
-  it('returns 4 ops', () => {
-    expect(ops).toHaveLength(4);
-  });
-
-  it('all ops have required fields', () => {
-    for (const op of ops) {
-      expect(op.name).toBeTruthy();
-      expect(op.handler).toBeDefined();
-      expect(['read', 'write']).toContain(op.auth);
-    }
-  });
-
   describe('capture_knowledge', () => {
     it('captures a single entry with governance approval', async () => {
       const result = (await findOp(ops, 'capture_knowledge').handler({
@@ -191,7 +179,7 @@ describe('createCaptureOps', () => {
         entries: [{ type: 'pattern', domain: 'a', title: 'A', description: 'a', tags: [] }],
       })) as Record<string, unknown>;
       expect(result.autoLinkedCount).toBe(1);
-      expect(result.suggestedLinks).toBeDefined();
+      expect((result.suggestedLinks as unknown[]).length).toBe(1); // one suggestion returned by mock
     });
 
     it('maps extended types correctly', async () => {
@@ -252,7 +240,8 @@ describe('createCaptureOps', () => {
         description: 'A quick capture',
       })) as Record<string, unknown>;
       expect(result.captured).toBe(true);
-      expect(result.id).toBeDefined();
+      expect(typeof result.id).toBe('string');
+      expect((result.id as string).startsWith('testing-')).toBe(true); // id is generated as <domain>-<timestamp>-<random>
       expect((result.governance as Record<string, unknown>).action).toBe('capture');
     });
 
@@ -380,6 +369,43 @@ describe('createCaptureOps', () => {
       // Capture should still succeed despite sync error
       expect(result.captured).toBe(true);
     });
+
+    it('adds planningNote when type is anti-pattern', async () => {
+      const result = (await findOp(ops, 'capture_quick').handler({
+        type: 'anti-pattern',
+        domain: 'testing',
+        title: 'No content body',
+        description: 'captured without context/example/why',
+      })) as Record<string, unknown>;
+      expect(result.captured).toBe(true);
+      expect(typeof result.planningNote).toBe('string');
+      expect(result.planningNote as string).toContain('capture_knowledge');
+    });
+
+    it('adds planningNote when tags include planning-gate', async () => {
+      const result = (await findOp(ops, 'capture_quick').handler({
+        type: 'rule',
+        domain: 'testing',
+        title: 'Gated rule',
+        description: 'should warn',
+        tags: ['planning-gate'],
+      })) as Record<string, unknown>;
+      expect(result.captured).toBe(true);
+      expect(typeof result.planningNote).toBe('string');
+      expect(result.planningNote as string).toContain('capture_knowledge');
+    });
+
+    it('does not add planningNote for non-planning types without planning tags', async () => {
+      const result = (await findOp(ops, 'capture_quick').handler({
+        type: 'reference',
+        domain: 'docs',
+        title: 'A plain reference',
+        description: 'no planning intent',
+        tags: ['docs'],
+      })) as Record<string, unknown>;
+      expect(result.captured).toBe(true);
+      expect(result.planningNote).toBeUndefined();
+    });
   });
 
   describe('search_intelligent', () => {
@@ -387,8 +413,7 @@ describe('createCaptureOps', () => {
       const result = (await findOp(ops, 'search_intelligent').handler({
         query: 'auth patterns',
       })) as Array<Record<string, unknown>>;
-      expect(Array.isArray(result)).toBe(true);
-      expect(result.length).toBeGreaterThan(0);
+      expect(result).toHaveLength(1); // brain.intelligentSearch mock returns exactly 1 result
       expect(result[0].source).toBe('vault');
     });