orbital-command 0.2.0 → 1.0.0

package/server/wizard/phases/welcome.ts

@@ -0,0 +1,39 @@
+/**
+ * Phase 2 welcome gate — project-scoped only.
+ *
+ * If the project is already initialized, offers re-init or config editor.
+ * If not, returns false to continue the project setup flow.
+ */
+
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import type { ProjectSetupState } from '../types.js';
+import { NOTES } from '../ui.js';
+import { runConfigEditor } from '../config-editor.js';
+
+export async function phaseWelcome(state: ProjectSetupState): Promise<boolean> {
+  if (state.isProjectInitialized) {
+    p.note(NOTES.reconfigure, pc.yellow('Already Initialized'));
+
+    const action = await p.select({
+      message: 'What would you like to do?',
+      options: [
+        { value: 'configure', label: 'Open config editor', hint: 'modify settings' },
+        { value: 'cancel', label: 'Cancel' },
+      ],
+    });
+
+    if (p.isCancel(action) || action === 'cancel') {
+      p.cancel('Cancelled.');
+      process.exit(0);
+    }
+
+    if (action === 'configure') {
+      await runConfigEditor(state.projectRoot, state.packageVersion, []);
+      process.exit(0);
+    }
+  }
+
+  // Not initialized — continue normally
+  return false;
+}

package/server/wizard/phases/workflow-setup.ts

@@ -0,0 +1,28 @@
+/**
+ * Phase 2: Workflow preset selection.
+ */
+
+import * as p from '@clack/prompts';
+import type { ProjectSetupState } from '../types.js';
+import { WORKFLOW_PRESETS } from '../types.js';
+import { NOTES } from '../ui.js';
+
+export async function phaseWorkflowSetup(state: ProjectSetupState): Promise<void> {
+  p.note(NOTES.workflow, 'Workflow Selection');
+
+  const preset = await p.select({
+    message: 'Choose a workflow preset',
+    options: WORKFLOW_PRESETS.map(p => ({
+      value: p.value,
+      label: p.label,
+      hint: p.hint,
+    })),
+  });
+
+  if (p.isCancel(preset)) {
+    p.cancel('Setup cancelled.');
+    process.exit(0);
+  }
+
+  state.workflowPreset = preset as string;
+}

package/server/wizard/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Types for the interactive CLI wizard.
+ *
+ * Two wizard flows:
+ *   Phase 1 (SetupState)        — first-time Orbital setup, ~/.orbital/ creation
+ *   Phase 2 (ProjectSetupState) — per-project scaffolding into .claude/
+ */
+
+export interface SetupState {
+  packageVersion: string;
+  isFirstTime: boolean;           // ~/.orbital/ doesn't exist yet
+  linkedProjects: string[];       // project paths added during setup
+}
+
+export interface ProjectSetupState {
+  projectRoot: string;
+  isProjectInitialized: boolean;  // .claude/orbital.config.json exists
+  packageVersion: string;
+
+  // Collected from phases
+  projectName?: string;
+  serverPort?: number;
+  clientPort?: number;
+  detectedCommands?: Record<string, string | null>;
+  selectedCommands?: Record<string, string | null>;
+  workflowPreset?: string;        // 'default' | 'minimal' | 'development' | 'gitflow'
+}
+
+export interface PresetInfo {
+  value: string;
+  label: string;
+  hint: string;
+}
+
+export const WORKFLOW_PRESETS: PresetInfo[] = [
+  {
+    value: 'default',
+    label: 'Default',
+    hint: '7 lists, trunk-based — Icebox → Planning → Backlog → Implementing → Review → Completed → Main',
+  },
+  {
+    value: 'minimal',
+    label: 'Minimal',
+    hint: '3 lists — To Do → In Progress → Done',
+  },
+  {
+    value: 'development',
+    label: 'Development',
+    hint: '5 lists, dev branch — Backlog → Implementing → Review → Completed → Dev',
+  },
+  {
+    value: 'gitflow',
+    label: 'Gitflow',
+    hint: '9 lists, multi-branch — Full pipeline with Dev, Staging, and Production',
+  },
+];

package/server/wizard/ui.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared UI helpers, concept notes, and formatting for the wizard.
+ */
+
+import pc from 'picocolors';
+
+// ─── Concept Notes ──────────────────────────────────────────────
+
+export const NOTES = {
+  // Phase 1: Setup wizard (runs on install / first use)
+  setupWelcome: `Orbital Command is a mission control layer for Claude Code.
+
+It gives your projects a real-time dashboard with a Kanban board,
+${pc.cyan('scopes')} (work items), ${pc.cyan('workflow stages')}, ${pc.cyan('quality gates')},
+${pc.cyan('dispatches')} (automated Claude sessions), and a ${pc.cyan('sprint orchestrator')}.
+
+Everything is driven by config files and hooks inside your project's
+${pc.cyan('.claude/')} directory — no database or external service required.`,
+
+  setupComplete: `${pc.bold('Setup complete.')}
+
+  ${pc.cyan('orbital')}                 Add a project or launch the dashboard
+  ${pc.cyan('orbital doctor')}          Health check & version info`,
+
+  addProject: `You can add projects now or later by running ${pc.cyan('orbital')} in a project directory.
+Each project gets its own workflow, scopes, and quality gates.`,
+
+  // Phase 2: Project setup (runs per-project)
+  reconfigure: `This project is already initialized with Orbital Command.
+You can reconfigure settings or select ${pc.cyan('Reset to defaults')} from the hub menu.`,
+
+  projectConfig: `${pc.bold('Project Config')} ${pc.dim('(.claude/orbital.config.json)')}
+
+Each project gets its own config inside ${pc.cyan('.claude/')}. The project
+config controls the name shown in the dashboard, ports, build commands
+used by quality gates, and agent definitions.`,
+
+  workflow: `${pc.bold('Workflows')} ${pc.dim('(Scopes, Lists, Dispatches)')}
+
+Orbital organizes work into ${pc.cyan('scopes')} (cards) that move through
+${pc.cyan('lists')} (Kanban columns). Transitions between lists can trigger
+commands, quality gates, and Claude Code sessions (${pc.cyan('dispatches')}).
+
+Choose a preset to start — you can customize it later from the
+dashboard's workflow editor or by editing ${pc.cyan('.claude/config/workflow.json')}.`,
+
+  postInstall: (counts: { hooks: number; skills: number; agents: number }) =>
+    `${pc.bold('What was just created')}
+
+${pc.cyan('Hooks')} (${counts.hooks})     Lifecycle scripts that enforce rules on transitions
+${pc.cyan('Skills')} (${counts.skills})    Slash commands for Claude (/scope-create, /git-commit, etc.)
+${pc.cyan('Agents')} (${counts.agents})    Team specifications for code review, architecture, security
+${pc.cyan('Workflow')}      Your selected preset defining lists and transitions
+${pc.cyan('Quality Gates')}  Automated checks (lint, typecheck, tests) before transitions`,
+
+  nextSteps: `${pc.bold('Next Steps')}
+
+  1. Run ${pc.cyan('orbital')} and select ${pc.bold('Launch dashboard')}
+  2. Create a scope from the board or use ${pc.cyan('/scope-create')}
+  3. Use ${pc.cyan('/scope-implement')} to start working on a scope
+
+${pc.bold('Useful Commands')}
+
+  ${pc.cyan('orbital')}           Hub menu — launch, config, doctor, etc.
+  ${pc.cyan('orbital status')}    See template sync status
+  ${pc.cyan('orbital config')}    Modify project settings
+  ${pc.cyan('orbital update')}    Sync to latest templates`,
+};
+
+// ─── Formatting Helpers ─────────────────────────────────────────
+
+export function formatDetectedCommands(commands: Record<string, string | null>): string {
+  const entries = Object.entries(commands).filter(([, v]) => v !== null);
+  if (entries.length === 0) return pc.dim('  No commands detected');
+
+  return entries
+    .map(([key, val]) => `  ${pc.cyan(key.padEnd(12))} ${val}`)
+    .join('\n');
+}
+
+export function formatSummary(state: {
+  projectName?: string;
+  workflowPreset?: string;
+  serverPort?: number;
+  clientPort?: number;
+}): string {
+  return [
+    `  Project:    ${pc.cyan(state.projectName || 'Unknown')}`,
+    `  Workflow:   ${pc.cyan(state.workflowPreset || 'default')}`,
+    `  Ports:      ${pc.cyan(String(state.serverPort || 4444))} (server) / ${pc.cyan(String(state.clientPort || 4445))} (client)`,
+  ].join('\n');
+}

package/shared/__fixtures__/workflow-configs.ts

@@ -0,0 +1,80 @@
+import type { WorkflowConfig } from '../workflow-config.js';
+import defaultWorkflowJson from '../default-workflow.json' with { type: 'json' };
+
+/** The full 7-list trunk-based workflow from default-workflow.json */
+export const DEFAULT_CONFIG = defaultWorkflowJson as unknown as WorkflowConfig;
+
+/** Smallest valid config: 2 lists, 1 edge, 1 entry point */
+export const MINIMAL_CONFIG: WorkflowConfig = {
+  version: 1,
+  name: 'Minimal',
+  lists: [
+    { id: 'todo', label: 'To Do', order: 0, color: '0 0% 50%', hex: '#808080', isEntryPoint: true, hasDirectory: true },
+    { id: 'done', label: 'Done', order: 1, color: '120 50% 50%', hex: '#40bf40', hasDirectory: true },
+  ],
+  edges: [
+    { from: 'todo', to: 'done', direction: 'forward', command: null, confirmLevel: 'quick', label: 'Complete', description: 'Mark as done' },
+  ],
+  terminalStatuses: ['done'],
+  allowedCommandPrefixes: ['/test-'],
+};
+
+/** Config with hooks for hook-related tests */
+export const CONFIG_WITH_HOOKS: WorkflowConfig = {
+  version: 1,
+  name: 'With Hooks',
+  lists: [
+    { id: 'backlog', label: 'Backlog', order: 0, color: '0 0% 50%', hex: '#808080', isEntryPoint: true, hasDirectory: true, supportsSprint: true },
+    { id: 'active', label: 'Active', order: 1, color: '200 80% 50%', hex: '#1a8ccc', hasDirectory: true, sessionKey: 'implementScope' },
+    { id: 'review', label: 'Review', order: 2, color: '45 90% 50%', hex: '#f0c010', hasDirectory: true, supportsBatch: true, sessionKey: 'reviewGate' },
+    { id: 'shipped', label: 'Shipped', order: 3, color: '120 70% 40%', hex: '#30a030', hasDirectory: true, gitBranch: 'main' },
+  ],
+  edges: [
+    { from: 'backlog', to: 'active', direction: 'forward', command: '/scope-implement {id}', confirmLevel: 'quick', label: 'Start', description: 'Begin work', dispatchOnly: true, autoRevert: true, hooks: ['blocker-check'], agents: ['architect'] },
+    { from: 'active', to: 'review', direction: 'forward', command: '/scope-post-review {id}', confirmLevel: 'quick', label: 'Review', description: 'Submit for review', dispatchOnly: true, hooks: ['blocker-check', 'session-enforcer'] },
+    { from: 'review', to: 'shipped', direction: 'forward', command: '/git-main', confirmLevel: 'quick', label: 'Ship', description: 'Push to main', dispatchOnly: true },
+    { from: 'active', to: 'backlog', direction: 'backward', command: null, confirmLevel: 'quick', label: 'Revert', description: 'Back to backlog', humanOnly: true },
+    { from: 'review', to: 'active', direction: 'backward', command: null, confirmLevel: 'quick', label: 'Rework', description: 'Back to active' },
+  ],
+  hooks: [
+    { id: 'blocker-check', label: 'Blocker Check', timing: 'before', type: 'shell', target: '.claude/hooks/blocker-check.sh', blocking: false, category: 'gate', description: 'Checks for blockers' },
+    { id: 'session-enforcer', label: 'Session Auth', timing: 'before', type: 'shell', target: '.claude/hooks/session-enforcer.sh', blocking: true, category: 'guard', description: 'Enforces session auth' },
+    { id: 'scope-transition', label: 'File Mover', timing: 'before', type: 'shell', target: '.claude/hooks/scope-transition.sh', blocking: false, category: 'lifecycle' },
+    { id: 'dashboard-sync', label: 'Dashboard Sync', timing: 'after', type: 'shell', target: '.claude/hooks/dashboard-sync.sh', blocking: false, category: 'observer' },
+  ],
+  groups: [
+    { id: 'planning', label: 'Planning', order: 0 },
+    { id: 'development', label: 'Development', order: 1 },
+  ],
+  eventInference: [
+    { eventType: 'SCOPE_STATUS_CHANGED', targetStatus: '', dataField: 'to', forwardOnly: true },
+    { eventType: 'AGENT_STARTED', targetStatus: 'active', forwardOnly: true },
+    { eventType: 'AGENT_COMPLETED', targetStatus: '', conditions: { outcome: ['success', 'failure'], dispatchResolution: true }, forwardOnly: false },
+  ],
+  terminalStatuses: ['shipped'],
+  allowedCommandPrefixes: ['/scope-', '/git-'],
+};
+
+/** Named invalid configs for constructor error tests */
+export const INVALID_CONFIGS = {
+  noLists: { version: 1 as const, name: 'No Lists', lists: [], edges: [{ from: 'a', to: 'b', direction: 'forward' as const, command: null, confirmLevel: 'quick' as const, label: 'X', description: 'X' }] } as WorkflowConfig,
+  noEdges: { version: 1 as const, name: 'No Edges', lists: [{ id: 'a', label: 'A', order: 0, color: '0 0% 0%', hex: '#000', isEntryPoint: true, hasDirectory: true }], edges: [] } as WorkflowConfig,
+  twoEntryPoints: {
+    version: 1 as const,
+    name: 'Two Entry Points',
+    lists: [
+      { id: 'a', label: 'A', order: 0, color: '0 0% 0%', hex: '#000', isEntryPoint: true, hasDirectory: true },
+      { id: 'b', label: 'B', order: 1, color: '0 0% 0%', hex: '#000', isEntryPoint: true, hasDirectory: true },
+    ],
+    edges: [{ from: 'a', to: 'b', direction: 'forward' as const, command: null, confirmLevel: 'quick' as const, label: 'X', description: 'X' }],
+  } as WorkflowConfig,
+  zeroEntryPoints: {
+    version: 1 as const,
+    name: 'Zero Entry Points',
+    lists: [
+      { id: 'a', label: 'A', order: 0, color: '0 0% 0%', hex: '#000', hasDirectory: true },
+      { id: 'b', label: 'B', order: 1, color: '0 0% 0%', hex: '#000', hasDirectory: true },
+    ],
+    edges: [{ from: 'a', to: 'b', direction: 'forward' as const, command: null, confirmLevel: 'quick' as const, label: 'X', description: 'X' }],
+  } as WorkflowConfig,
+};

package/shared/api-types.ts

@@ -18,3 +18,109 @@ export interface AgentConfig {
   emoji: string;
   color: string;
 }
+
+// ─── Dispatch Flags (CLI flags passed to `claude`) ──────────
+
+export interface DispatchFlags {
+  permissionMode: 'bypass' | 'default' | 'plan' | 'acceptEdits';
+  verbose: boolean;
+  allowedTools: string[];
+  disallowedTools: string[];
+  appendSystemPrompt: string;
+  outputFormat: '' | 'text' | 'json' | 'stream-json';
+  noMarkdown: boolean;
+  printMode: boolean;
+}
+
+export const DEFAULT_DISPATCH_FLAGS: DispatchFlags = {
+  permissionMode: 'bypass',
+  verbose: true,
+  allowedTools: [],
+  disallowedTools: [],
+  appendSystemPrompt: '',
+  outputFormat: '',
+  noMarkdown: false,
+  printMode: false,
+};
+
+// ─── Dispatch Config (Orbital operational settings) ─────────
+
+export interface DispatchConfig {
+  staleTimeoutMinutes: number;
+  maxBatchSize: number;
+  maxConcurrent: number;
+  envVars: Record<string, string>;
+}
+
+export const DEFAULT_DISPATCH_CONFIG: DispatchConfig = {
+  staleTimeoutMinutes: 10,
+  maxBatchSize: 20,
+  maxConcurrent: 0,
+  envVars: {},
+};
+
+// ─── Validation ─────────────────────────────────────────────
+
+export const VALID_PERMISSION_MODES = ['bypass', 'default', 'plan', 'acceptEdits'] as const;
+export const VALID_OUTPUT_FORMATS = ['', 'text', 'json', 'stream-json'];
+export const VALID_TERMINAL_ADAPTERS = ['auto', 'iterm2', 'subprocess', 'none'];
+
+const SAFE_TOOL_NAME = /^[a-zA-Z0-9_:.-]+$/;
+const SAFE_ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export function validateToolName(name: string): boolean {
+  return SAFE_TOOL_NAME.test(name);
+}
+
+export function validateEnvKey(key: string): boolean {
+  return SAFE_ENV_KEY.test(key);
+}
+
+export function validateDispatchFlags(flags: Partial<DispatchFlags>): string | null {
+  if (flags.permissionMode !== undefined && !VALID_PERMISSION_MODES.includes(flags.permissionMode as typeof VALID_PERMISSION_MODES[number])) {
+    return `Invalid permissionMode: ${flags.permissionMode}`;
+  }
+  if (flags.outputFormat !== undefined && !VALID_OUTPUT_FORMATS.includes(flags.outputFormat as string)) {
+    return `Invalid outputFormat: ${flags.outputFormat}`;
+  }
+  if (flags.allowedTools !== undefined) {
+    if (!Array.isArray(flags.allowedTools)) return 'allowedTools must be an array';
+    for (const t of flags.allowedTools) {
+      if (typeof t !== 'string' || !validateToolName(t)) return `Invalid tool name: ${t}`;
+    }
+  }
+  if (flags.disallowedTools !== undefined) {
+    if (!Array.isArray(flags.disallowedTools)) return 'disallowedTools must be an array';
+    for (const t of flags.disallowedTools) {
+      if (typeof t !== 'string' || !validateToolName(t)) return `Invalid tool name: ${t}`;
+    }
+  }
+  if (flags.appendSystemPrompt !== undefined && typeof flags.appendSystemPrompt !== 'string') {
+    return 'appendSystemPrompt must be a string';
+  }
+  return null;
+}
+
+export function validateDispatchConfig(config: Partial<DispatchConfig> & { terminalAdapter?: string }): string | null {
+  if (config.terminalAdapter !== undefined && !VALID_TERMINAL_ADAPTERS.includes(config.terminalAdapter)) {
+    return `Invalid terminalAdapter: ${config.terminalAdapter}`;
+  }
+  if (config.staleTimeoutMinutes !== undefined && (typeof config.staleTimeoutMinutes !== 'number' || config.staleTimeoutMinutes < 1)) {
+    return 'staleTimeoutMinutes must be a positive number';
+  }
+  if (config.maxBatchSize !== undefined && (typeof config.maxBatchSize !== 'number' || config.maxBatchSize < 1)) {
+    return 'maxBatchSize must be a positive number';
+  }
+  if (config.maxConcurrent !== undefined && (typeof config.maxConcurrent !== 'number' || config.maxConcurrent < 0)) {
+    return 'maxConcurrent must be a non-negative number';
+  }
+  if (config.envVars !== undefined) {
+    if (typeof config.envVars !== 'object' || config.envVars === null || Array.isArray(config.envVars)) {
+      return 'envVars must be an object';
+    }
+    for (const key of Object.keys(config.envVars)) {
+      if (!validateEnvKey(key)) return `Invalid env var key: ${key}`;
+    }
+  }
+  return null;
+}

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[];
 }