orbital-command 0.2.0 → 0.3.0

package/shared/onboarding-tour.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest';
+import { TOUR_STEPS } from '../src/components/onboarding/tour-steps';
+
+describe('onboarding tour steps', () => {
+  it('should have at least one step', () => {
+    expect(TOUR_STEPS.length).toBeGreaterThan(0);
+  });
+
+  it('should have unique step IDs', () => {
+    const ids = TOUR_STEPS.map(s => s.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('should have unique targets', () => {
+    const targets = TOUR_STEPS.map(s => s.target);
+    expect(new Set(targets).size).toBe(targets.length);
+  });
+
+  it('should have title and description for every step', () => {
+    for (const step of TOUR_STEPS) {
+      expect(step.title).toBeTruthy();
+      expect(step.description).toBeTruthy();
+    }
+  });
+
+  it('should have valid placement values', () => {
+    const validPlacements = new Set(['top', 'bottom', 'left', 'right']);
+    for (const step of TOUR_STEPS) {
+      if (step.placement) {
+        expect(validPlacements.has(step.placement)).toBe(true);
+      }
+    }
+  });
+
+  it('should mark dynamic content steps as optional', () => {
+    const dynamicTargets = ['kanban-column', 'scope-card'];
+    for (const step of TOUR_STEPS) {
+      if (dynamicTargets.includes(step.target)) {
+        expect(step.optional).toBe(true);
+      }
+    }
+  });
+
+  it('should cover all expected pages', () => {
+    const pages = new Set(TOUR_STEPS.filter(s => s.page).map(s => s.page));
+    expect(pages.has('/')).toBe(true);
+    expect(pages.has('/primitives')).toBe(true);
+    expect(pages.has('/guards')).toBe(true);
+    expect(pages.has('/repo')).toBe(true);
+    expect(pages.has('/sessions')).toBe(true);
+    expect(pages.has('/workflow')).toBe(true);
+  });
+
+  describe('step sequencing', () => {
+    it('first step should target the Kanban nav', () => {
+      expect(TOUR_STEPS[0].target).toBe('nav-kanban');
+      expect(TOUR_STEPS[0].page).toBe('/');
+    });
+
+    it('last step should target Settings', () => {
+      const last = TOUR_STEPS[TOUR_STEPS.length - 1];
+      expect(last.target).toBe('nav-settings');
+    });
+
+    it('should complete a full traversal of all steps', () => {
+      let index = 0;
+      const visited: string[] = [];
+      while (index < TOUR_STEPS.length) {
+        visited.push(TOUR_STEPS[index].id);
+        index++;
+      }
+      expect(visited.length).toBe(TOUR_STEPS.length);
+      expect(visited[0]).toBe('welcome');
+      expect(visited[visited.length - 1]).toBe('nav-settings');
+    });
+  });
+
+  describe('completion tracking', () => {
+    it('default state should be pending', () => {
+      const DEFAULT_STATE = 'pending';
+      expect(DEFAULT_STATE).toBe('pending');
+    });
+
+    it('completed state should be the string completed', () => {
+      const state: string = 'completed';
+      expect(state).toBe('completed');
+    });
+
+    it('dismissed state should be the string dismissed', () => {
+      const state: string = 'dismissed';
+      expect(state).toBe('dismissed');
+    });
+  });
+});

package/shared/project-colors.ts

@@ -0,0 +1,24 @@
+/** Predefined project color palette (HSL strings). Used for auto-assigning
+ *  project badge colors when projects are registered with Orbital Command. */
+export const PROJECT_COLORS = [
+  '0 90% 62%',      // red
+  '20 95% 60%',     // vermilion
+  '40 95% 56%',     // orange
+  '58 90% 52%',     // amber
+  '76 85% 50%',     // chartreuse
+  '100 80% 48%',    // lime
+  '130 80% 48%',    // green
+  '158 85% 46%',    // emerald
+  '178 90% 46%',    // teal
+  '194 95% 52%',    // cyan
+  '212 90% 60%',    // sky
+  '232 88% 64%',    // blue
+  '254 85% 66%',    // indigo
+  '272 85% 64%',    // purple
+  '292 82% 62%',    // violet
+  '312 85% 58%',    // magenta
+  '330 88% 58%',    // hot pink
+  '348 92% 60%',    // rose
+  '150 82% 52%',    // mint
+  '56 95% 62%',     // gold
+] as const;

package/shared/workflow-config.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isWorkflowConfig, isWorkflowList, isWorkflowEdge, getHookEnforcement,
+  type WorkflowHook,
+} from './workflow-config.js';
+import { MINIMAL_CONFIG, DEFAULT_CONFIG } from './__fixtures__/workflow-configs.js';
+
+describe('isWorkflowConfig()', () => {
+  it('returns true for valid minimal config', () => {
+    expect(isWorkflowConfig(MINIMAL_CONFIG)).toBe(true);
+  });
+
+  it('returns true for full default config', () => {
+    expect(isWorkflowConfig(DEFAULT_CONFIG)).toBe(true);
+  });
+
+  it('returns false for null', () => {
+    expect(isWorkflowConfig(null)).toBe(false);
+  });
+
+  it('returns false for undefined', () => {
+    expect(isWorkflowConfig(undefined)).toBe(false);
+  });
+
+  it('returns false for non-object', () => {
+    expect(isWorkflowConfig('string')).toBe(false);
+    expect(isWorkflowConfig(42)).toBe(false);
+  });
+
+  it('returns false when version != 1', () => {
+    expect(isWorkflowConfig({ ...MINIMAL_CONFIG, version: 2 })).toBe(false);
+  });
+
+  it('returns false when lists is not an array', () => {
+    expect(isWorkflowConfig({ ...MINIMAL_CONFIG, lists: 'not-array' })).toBe(false);
+  });
+
+  it('returns false when name is not a string', () => {
+    expect(isWorkflowConfig({ ...MINIMAL_CONFIG, name: 123 })).toBe(false);
+  });
+
+  it('returns false when branchingMode is invalid', () => {
+    expect(isWorkflowConfig({ ...MINIMAL_CONFIG, branchingMode: 'invalid' })).toBe(false);
+  });
+
+  it('returns true when branchingMode is trunk or worktree', () => {
+    expect(isWorkflowConfig({ ...MINIMAL_CONFIG, branchingMode: 'trunk' })).toBe(true);
+    expect(isWorkflowConfig({ ...MINIMAL_CONFIG, branchingMode: 'worktree' })).toBe(true);
+  });
+});
+
+describe('isWorkflowList()', () => {
+  const validList = MINIMAL_CONFIG.lists[0];
+
+  it('returns true for valid list', () => {
+    expect(isWorkflowList(validList)).toBe(true);
+  });
+
+  it('returns false for non-object', () => {
+    expect(isWorkflowList(null)).toBe(false);
+    expect(isWorkflowList('string')).toBe(false);
+  });
+
+  it('returns false when missing required fields', () => {
+    expect(isWorkflowList({ id: 'a', label: 'A' })).toBe(false); // missing order, color, hex, hasDirectory
+  });
+
+  it('returns true with optional fields present', () => {
+    expect(isWorkflowList({ ...validList, gitBranch: 'main', sessionKey: 'test' })).toBe(true);
+  });
+});
+
+describe('isWorkflowEdge()', () => {
+  const validEdge = MINIMAL_CONFIG.edges[0];
+
+  it('returns true for valid edge', () => {
+    expect(isWorkflowEdge(validEdge)).toBe(true);
+  });
+
+  it('returns false for non-object', () => {
+    expect(isWorkflowEdge(null)).toBe(false);
+    expect(isWorkflowEdge(42)).toBe(false);
+  });
+
+  it('returns false when missing required string fields', () => {
+    expect(isWorkflowEdge({ from: 'a', to: 'b' })).toBe(false); // missing direction, label, description
+  });
+});
+
+describe('getHookEnforcement()', () => {
+  const makeHook = (category: string): WorkflowHook => ({
+    id: 'test', label: 'Test', timing: 'before', type: 'shell',
+    target: 'test.sh', category: category as WorkflowHook['category'],
+  });
+
+  it('guard -> blocker', () => {
+    expect(getHookEnforcement(makeHook('guard'))).toBe('blocker');
+  });
+
+  it('gate -> advisor', () => {
+    expect(getHookEnforcement(makeHook('gate'))).toBe('advisor');
+  });
+
+  it('lifecycle -> operator', () => {
+    expect(getHookEnforcement(makeHook('lifecycle'))).toBe('operator');
+  });
+
+  it('observer -> silent', () => {
+    expect(getHookEnforcement(makeHook('observer'))).toBe('silent');
+  });
+});

package/shared/workflow-config.ts

@@ -59,6 +59,9 @@ export interface WorkflowConfig {
   commitBranchPatterns?: string;
 }
 
+/** Semantic phase for All Projects normalization */
+export type Phase = 'queued' | 'active' | 'review' | 'shipped';
+
 export interface WorkflowList {
   id: string;
   label: string;
@@ -73,6 +76,8 @@ export interface WorkflowList {
   gitBranch?: string;
   sessionKey?: string;
   activeHooks?: string[];
+  /** Semantic phase for All Projects normalization. Inferred from group/sessionKey if omitted. */
+  phase?: Phase;
 }
 
 export interface WorkflowEdge {
@@ -87,6 +92,8 @@ export interface WorkflowEdge {
   skipServerTransition?: boolean;
   dispatchOnly?: boolean;
   humanOnly?: boolean;
+  /** When true, revert scope status to `from` if the dispatch session is abandoned */
+  autoRevert?: boolean;
   hooks?: string[];
   agents?: string[];
 }

package/shared/workflow-engine.test.ts

@@ -0,0 +1,388 @@
+import { describe, it, expect } from 'vitest';
+import { WorkflowEngine } from './workflow-engine.js';
+import { MINIMAL_CONFIG, CONFIG_WITH_HOOKS, DEFAULT_CONFIG, INVALID_CONFIGS } from './__fixtures__/workflow-configs.js';
+
+// ─── Constructor ──────────────────────────────────────────────
+
+describe('WorkflowEngine', () => {
+  describe('constructor', () => {
+    it('creates engine from minimal config', () => {
+      const engine = new WorkflowEngine(MINIMAL_CONFIG);
+      expect(engine.getConfig().name).toBe('Minimal');
+    });
+
+    it('throws on empty lists', () => {
+      expect(() => new WorkflowEngine(INVALID_CONFIGS.noLists)).toThrow('at least 1 list');
+    });
+
+    it('throws on empty edges', () => {
+      expect(() => new WorkflowEngine(INVALID_CONFIGS.noEdges)).toThrow('at least 1 edge');
+    });
+
+    it('throws on two entry points', () => {
+      expect(() => new WorkflowEngine(INVALID_CONFIGS.twoEntryPoints)).toThrow('exactly 1 entry point, found 2');
+    });
+
+    it('throws on zero entry points', () => {
+      expect(() => new WorkflowEngine(INVALID_CONFIGS.zeroEntryPoints)).toThrow('exactly 1 entry point, found 0');
+    });
+  });
+
+  // ─── reload() ─────────────────────────────────────────────────
+
+  describe('reload()', () => {
+    it('replaces config and rebuilds indexes', () => {
+      const engine = new WorkflowEngine(MINIMAL_CONFIG);
+      expect(engine.getLists()).toHaveLength(2);
+
+      engine.reload(CONFIG_WITH_HOOKS);
+      expect(engine.getLists()).toHaveLength(4);
+      expect(engine.getConfig().name).toBe('With Hooks');
+    });
+
+    it('throws on invalid config during reload', () => {
+      const engine = new WorkflowEngine(MINIMAL_CONFIG);
+      expect(() => engine.reload(INVALID_CONFIGS.noLists)).toThrow();
+    });
+  });
+
+  // ─── List Queries ─────────────────────────────────────────────
+
+  describe('list queries', () => {
+    const engine = new WorkflowEngine(DEFAULT_CONFIG);
+
+    it('getLists() returns sorted by order', () => {
+      const lists = engine.getLists();
+      for (let i = 1; i < lists.length; i++) {
+        expect(lists[i].order).toBeGreaterThanOrEqual(lists[i - 1].order);
+      }
+    });
+
+    it('getList() returns correct list or undefined', () => {
+      expect(engine.getList('icebox')?.label).toBe('Icebox');
+      expect(engine.getList('nonexistent')).toBeUndefined();
+    });
+
+    it('getEntryPoint() returns the entry point', () => {
+      const entry = engine.getEntryPoint();
+      expect(entry.isEntryPoint).toBe(true);
+      expect(entry.id).toBe('icebox');
+    });
+
+    it('getBatchLists() filters by supportsBatch', () => {
+      const batch = engine.getBatchLists();
+      expect(batch.length).toBeGreaterThan(0);
+      expect(batch.every(l => l.supportsBatch)).toBe(true);
+    });
+
+    it('getSprintLists() filters by supportsSprint', () => {
+      const sprint = engine.getSprintLists();
+      expect(sprint.length).toBeGreaterThan(0);
+      expect(sprint.every(l => l.supportsSprint)).toBe(true);
+    });
+
+    it('getBoardColumns() returns id, label, color tuples sorted by order', () => {
+      const cols = engine.getBoardColumns();
+      expect(cols[0]).toEqual({ id: 'icebox', label: 'Icebox', color: expect.any(String) });
+      for (let i = 1; i < cols.length; i++) {
+        const prevOrder = engine.getList(cols[i - 1].id)!.order;
+        const currOrder = engine.getList(cols[i].id)!.order;
+        expect(currOrder).toBeGreaterThanOrEqual(prevOrder);
+      }
+    });
+  });
+
+  // ─── Edge Queries ─────────────────────────────────────────────
+
+  describe('edge queries', () => {
+    const engine = new WorkflowEngine(DEFAULT_CONFIG);
+
+    it('findEdge() returns edge or undefined', () => {
+      const edge = engine.findEdge('icebox', 'planning');
+      expect(edge).toBeDefined();
+      expect(edge!.direction).toBe('forward');
+      expect(engine.findEdge('icebox', 'main')).toBeUndefined();
+    });
+
+    it('isValidTransition() returns boolean', () => {
+      expect(engine.isValidTransition('icebox', 'planning')).toBe(true);
+      expect(engine.isValidTransition('icebox', 'main')).toBe(false);
+    });
+
+    it('getValidTargets() returns target IDs', () => {
+      const targets = engine.getValidTargets('icebox');
+      expect(targets).toContain('planning');
+    });
+
+    it('getValidTargets() returns empty for unknown status', () => {
+      expect(engine.getValidTargets('nonexistent')).toEqual([]);
+    });
+
+    it('getAllEdges() returns all edges', () => {
+      expect(engine.getAllEdges().length).toBe(DEFAULT_CONFIG.edges.length);
+    });
+
+    it('getEdgesByDirection() filters correctly', () => {
+      const forward = engine.getEdgesByDirection('forward');
+      expect(forward.every(e => e.direction === 'forward')).toBe(true);
+
+      const backward = engine.getEdgesByDirection('backward');
+      expect(backward.every(e => e.direction === 'backward')).toBe(true);
+      expect(backward.length).toBeGreaterThan(0);
+    });
+  });
+
+  // ─── validateTransition() ─────────────────────────────────────
+
+  describe('validateTransition()', () => {
+    const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+
+    it('rejects invalid target status', () => {
+      const result = engine.validateTransition('backlog', 'nonexistent', 'patch');
+      expect(result).toEqual({ ok: false, error: expect.stringContaining('Invalid status'), code: 'INVALID_STATUS' });
+    });
+
+    it('bulk-sync always succeeds', () => {
+      expect(engine.validateTransition('shipped', 'backlog', 'bulk-sync')).toEqual({ ok: true });
+    });
+
+    it('rollback always succeeds', () => {
+      expect(engine.validateTransition('shipped', 'backlog', 'rollback')).toEqual({ ok: true });
+    });
+
+    it('same status is always ok', () => {
+      expect(engine.validateTransition('backlog', 'backlog', 'patch')).toEqual({ ok: true });
+    });
+
+    it('rejects non-existent edge', () => {
+      const result = engine.validateTransition('backlog', 'shipped', 'patch');
+      expect(result).toEqual({ ok: false, error: expect.stringContaining('not allowed'), code: 'INVALID_TRANSITION' });
+    });
+
+    it('rejects patch context on dispatchOnly edge', () => {
+      const result = engine.validateTransition('backlog', 'active', 'patch');
+      expect(result).toEqual({ ok: false, error: expect.stringContaining('requires dispatch'), code: 'DISPATCH_REQUIRED' });
+    });
+
+    it('allows dispatch context on dispatchOnly edge', () => {
+      expect(engine.validateTransition('backlog', 'active', 'dispatch')).toEqual({ ok: true });
+    });
+  });
+
+  // ─── Status Helpers ───────────────────────────────────────────
+
+  describe('status helpers', () => {
+    const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+
+    it('isValidStatus() returns true for known, false for unknown', () => {
+      expect(engine.isValidStatus('backlog')).toBe(true);
+      expect(engine.isValidStatus('nonexistent')).toBe(false);
+    });
+
+    it('isTerminalStatus() returns true for terminal statuses', () => {
+      expect(engine.isTerminalStatus('shipped')).toBe(true);
+      expect(engine.isTerminalStatus('backlog')).toBe(false);
+    });
+
+    it('getStatusOrder() returns numeric order or -1', () => {
+      expect(engine.getStatusOrder('backlog')).toBe(0);
+      expect(engine.getStatusOrder('active')).toBe(1);
+      expect(engine.getStatusOrder('unknown')).toBe(-1);
+    });
+
+    it('isForwardMovement() compares orders', () => {
+      expect(engine.isForwardMovement('backlog', 'active')).toBe(true);
+      expect(engine.isForwardMovement('active', 'backlog')).toBe(false);
+      expect(engine.isForwardMovement('active', 'active')).toBe(false);
+    });
+  });
+
+  // ─── Commands ─────────────────────────────────────────────────
+
+  describe('commands', () => {
+    const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+
+    it('buildCommand() replaces {id} with scope ID', () => {
+      const edge = engine.findEdge('backlog', 'active')!;
+      expect(engine.buildCommand(edge, 42)).toBe('/scope-implement 42');
+    });
+
+    it('buildCommand() returns null when edge has no command', () => {
+      const edge = engine.findEdge('active', 'backlog')!;
+      expect(engine.buildCommand(edge, 1)).toBeNull();
+    });
+
+    it('isAllowedCommand() checks prefix list', () => {
+      expect(engine.isAllowedCommand('/scope-implement 42')).toBe(true);
+      expect(engine.isAllowedCommand('/git-main')).toBe(true);
+      expect(engine.isAllowedCommand('/unknown-command')).toBe(false);
+    });
+  });
+
+  // ─── Batch / Sprint ───────────────────────────────────────────
+
+  describe('batch/sprint', () => {
+    const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+
+    it('getBatchTargetStatus() finds first forward dispatchOnly edge target', () => {
+      expect(engine.getBatchTargetStatus('backlog')).toBe('active');
+    });
+
+    it('getBatchTargetStatus() returns undefined for no match', () => {
+      expect(engine.getBatchTargetStatus('shipped')).toBeUndefined();
+    });
+
+    it('getBatchCommand() strips {id} placeholder', () => {
+      expect(engine.getBatchCommand('backlog')).toBe('/scope-implement');
+    });
+
+    it('getBatchCommand() returns undefined for no match', () => {
+      expect(engine.getBatchCommand('shipped')).toBeUndefined();
+    });
+  });
+
+  // ─── inferStatus() ────────────────────────────────────────────
+
+  describe('inferStatus()', () => {
+    const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+
+    it('returns null when no rules match event type', () => {
+      expect(engine.inferStatus('UNKNOWN_EVENT', 'backlog', {})).toBeNull();
+    });
+
+    it('matches AGENT_STARTED to active status', () => {
+      expect(engine.inferStatus('AGENT_STARTED', 'backlog', {})).toBe('active');
+    });
+
+    it('forwardOnly guard prevents backward movement', () => {
+      // active (order 1) → active (order 1) — not forward, returns null
+      expect(engine.inferStatus('AGENT_STARTED', 'active', {})).toBeNull();
+    });
+
+    it('handles SCOPE_STATUS_CHANGED with dataField resolution', () => {
+      const result = engine.inferStatus('SCOPE_STATUS_CHANGED', 'backlog', { to: 'active' });
+      expect(result).toBe('active');
+    });
+
+    it('SCOPE_STATUS_CHANGED with dataField returns null for empty value', () => {
+      expect(engine.inferStatus('SCOPE_STATUS_CHANGED', 'backlog', { to: '' })).toBeNull();
+    });
+
+    it('handles dispatchResolution conditions', () => {
+      const result = engine.inferStatus('AGENT_COMPLETED', 'active', { outcome: 'success' });
+      expect(result).toEqual({ dispatchResolution: true, resolution: 'completed' });
+    });
+
+    it('handles dispatchResolution with failure outcome', () => {
+      const result = engine.inferStatus('AGENT_COMPLETED', 'active', { outcome: 'failure' });
+      expect(result).toEqual({ dispatchResolution: true, resolution: 'failed' });
+    });
+  });
+
+  // ─── Generation ───────────────────────────────────────────────
+
+  describe('generation', () => {
+    const engine = new WorkflowEngine(MINIMAL_CONFIG);
+
+    it('generateCSSVariables() produces correct format', () => {
+      const css = engine.generateCSSVariables();
+      expect(css).toContain('--status-todo:');
+      expect(css).toContain('--status-done:');
+    });
+
+    it('generateShellManifest() produces valid bash structure', () => {
+      const manifest = engine.generateShellManifest();
+      expect(manifest).toContain('#!/bin/bash');
+      expect(manifest).toContain('WORKFLOW_STATUSES="todo done"');
+      expect(manifest).toContain('WORKFLOW_ENTRY_STATUS="todo"');
+      expect(manifest).toContain('WORKFLOW_TERMINAL_STATUSES="done"');
+      expect(manifest).toContain('WORKFLOW_EDGES=(');
+      expect(manifest).toContain('is_valid_status()');
+    });
+  });
+
+  // ─── Git / Lifecycle ──────────────────────────────────────────
+
+  describe('git/lifecycle', () => {
+    const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+
+    it('getListByGitBranch() finds the right list', () => {
+      expect(engine.getListByGitBranch('main')?.id).toBe('shipped');
+    });
+
+    it('getListByGitBranch() returns undefined for unknown branch', () => {
+      expect(engine.getListByGitBranch('feature/foo')).toBeUndefined();
+    });
+
+    it('getGitBranch() returns branch or undefined', () => {
+      expect(engine.getGitBranch('shipped')).toBe('main');
+      expect(engine.getGitBranch('backlog')).toBeUndefined();
+    });
+
+    it('getSessionKey() returns session key or undefined', () => {
+      expect(engine.getSessionKey('active')).toBe('implementScope');
+      expect(engine.getSessionKey('backlog')).toBeUndefined();
+    });
+
+    it('getActiveHooksForList() returns empty for list without activeHooks', () => {
+      expect(engine.getActiveHooksForList('backlog')).toEqual([]);
+    });
+
+    it('getAgentsForEdge() returns agents array', () => {
+      expect(engine.getAgentsForEdge('backlog', 'active')).toEqual(['architect']);
+    });
+
+    it('getAgentsForEdge() returns empty for edge without agents', () => {
+      expect(engine.getAgentsForEdge('active', 'backlog')).toEqual([]);
+    });
+  });
+
+  // ─── Hooks ────────────────────────────────────────────────────
+
+  describe('hooks', () => {
+    const engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+
+    it('getHooksForEdge() resolves hook IDs to hook objects', () => {
+      const hooks = engine.getHooksForEdge('backlog', 'active');
+      expect(hooks).toHaveLength(1);
+      expect(hooks[0].id).toBe('blocker-check');
+    });
+
+    it('getHooksForEdge() returns empty for edge without hooks', () => {
+      const engine2 = new WorkflowEngine(MINIMAL_CONFIG);
+      expect(engine2.getHooksForEdge('todo', 'done')).toEqual([]);
+    });
+
+    it('getAllHooks() returns all hooks', () => {
+      expect(engine.getAllHooks()).toHaveLength(4);
+    });
+
+    it('getHookEnforcement() maps category correctly', () => {
+      const guard = engine.getAllHooks().find(h => h.category === 'guard')!;
+      expect(engine.getHookEnforcement(guard)).toBe('blocker');
+
+      const gate = engine.getAllHooks().find(h => h.category === 'gate')!;
+      expect(engine.getHookEnforcement(gate)).toBe('advisor');
+    });
+
+    it('getHooksByCategory() filters by category', () => {
+      const guards = engine.getHooksByCategory('guard');
+      expect(guards.every(h => h.category === 'guard')).toBe(true);
+      expect(guards.length).toBe(1);
+    });
+  });
+
+  // ─── Config Access ────────────────────────────────────────────
+
+  describe('config access', () => {
+    it('getBranchingMode() returns trunk by default', () => {
+      const engine = new WorkflowEngine(MINIMAL_CONFIG);
+      expect(engine.getBranchingMode()).toBe('trunk');
+    });
+
+    it('getBranchingMode() returns configured value', () => {
+      const engine = new WorkflowEngine(DEFAULT_CONFIG);
+      expect(engine.getBranchingMode()).toBe('trunk');
+    });
+  });
+});