agileflow 3.3.0 → 3.4.1

package/scripts/lib/audit-registry.js

@@ -0,0 +1,304 @@
+/**
+ * audit-registry.js - Static registry mapping audit types to analyzers
+ *
+ * Centralizes the mapping of 6 audit commands to their analyzer agents,
+ * consensus coordinators, and depth configurations. Previously this info
+ * was duplicated across 6 .md command files.
+ *
+ * Usage:
+ *   const { getAuditType, getAnalyzersForAudit } = require('./audit-registry');
+ *   const security = getAuditType('security');
+ *   const focused = getAnalyzersForAudit('security', 'deep', ['injection', 'auth']);
+ */
+
+/**
+ * Complete audit type registry.
+ * Each entry defines: name, short prefix for tmux, color for tab groups,
+ * all analyzers with their subagent_type, which are quick vs deep,
+ * and the consensus coordinator.
+ */
+const AUDIT_TYPES = {
+  logic: {
+    name: 'Logic Analysis',
+    prefix: 'Logic',
+    color: '#7aa2f7', // sky
+    command: 'code/logic',
+    analyzers: {
+      edge: { subagent_type: 'logic-analyzer-edge', label: 'Edge Cases' },
+      invariant: { subagent_type: 'logic-analyzer-invariant', label: 'Invariants' },
+      flow: { subagent_type: 'logic-analyzer-flow', label: 'Control Flow' },
+      type: { subagent_type: 'logic-analyzer-type', label: 'Type Safety' },
+      race: { subagent_type: 'logic-analyzer-race', label: 'Race Conditions' },
+    },
+    consensus: { subagent_type: 'logic-consensus', label: 'Logic Consensus' },
+    quick_analyzers: ['edge', 'invariant', 'flow', 'type', 'race'],
+    deep_analyzers: ['edge', 'invariant', 'flow', 'type', 'race'],
+  },
+
+  security: {
+    name: 'Security Vulnerability',
+    prefix: 'Sec',
+    color: '#f7768e', // coral
+    command: 'code/security',
+    analyzers: {
+      injection: { subagent_type: 'security-analyzer-injection', label: 'Injection' },
+      auth: { subagent_type: 'security-analyzer-auth', label: 'Authentication' },
+      authz: { subagent_type: 'security-analyzer-authz', label: 'Authorization' },
+      secrets: { subagent_type: 'security-analyzer-secrets', label: 'Secrets' },
+      input: { subagent_type: 'security-analyzer-input', label: 'Input Validation' },
+      deps: { subagent_type: 'security-analyzer-deps', label: 'Dependencies' },
+      infra: { subagent_type: 'security-analyzer-infra', label: 'Infrastructure' },
+      api: { subagent_type: 'security-analyzer-api', label: 'API Security' },
+    },
+    consensus: { subagent_type: 'security-consensus', label: 'Security Consensus' },
+    quick_analyzers: ['injection', 'auth', 'authz', 'secrets', 'input'],
+    deep_analyzers: ['injection', 'auth', 'authz', 'secrets', 'input', 'deps', 'infra', 'api'],
+  },
+
+  performance: {
+    name: 'Performance Bottleneck',
+    prefix: 'Perf',
+    color: '#73daca', // mint
+    command: 'code/performance',
+    analyzers: {
+      queries: { subagent_type: 'perf-analyzer-queries', label: 'Queries' },
+      rendering: { subagent_type: 'perf-analyzer-rendering', label: 'Rendering' },
+      memory: { subagent_type: 'perf-analyzer-memory', label: 'Memory' },
+      bundle: { subagent_type: 'perf-analyzer-bundle', label: 'Bundle Size' },
+      compute: { subagent_type: 'perf-analyzer-compute', label: 'Compute' },
+      network: { subagent_type: 'perf-analyzer-network', label: 'Network' },
+      caching: { subagent_type: 'perf-analyzer-caching', label: 'Caching' },
+      assets: { subagent_type: 'perf-analyzer-assets', label: 'Assets' },
+    },
+    consensus: { subagent_type: 'perf-consensus', label: 'Performance Consensus' },
+    quick_analyzers: ['queries', 'rendering', 'memory', 'bundle', 'compute'],
+    deep_analyzers: [
+      'queries',
+      'rendering',
+      'memory',
+      'bundle',
+      'compute',
+      'network',
+      'caching',
+      'assets',
+    ],
+  },
+
+  test: {
+    name: 'Test Quality',
+    prefix: 'Test',
+    color: '#e0af68', // amber
+    command: 'code/test',
+    analyzers: {
+      coverage: { subagent_type: 'test-analyzer-coverage', label: 'Coverage' },
+      fragility: { subagent_type: 'test-analyzer-fragility', label: 'Fragility' },
+      mocking: { subagent_type: 'test-analyzer-mocking', label: 'Mocking' },
+      assertions: { subagent_type: 'test-analyzer-assertions', label: 'Assertions' },
+      structure: { subagent_type: 'test-analyzer-structure', label: 'Structure' },
+      integration: { subagent_type: 'test-analyzer-integration', label: 'Integration' },
+      maintenance: { subagent_type: 'test-analyzer-maintenance', label: 'Maintenance' },
+      patterns: { subagent_type: 'test-analyzer-patterns', label: 'Anti-Patterns' },
+    },
+    consensus: { subagent_type: 'test-consensus', label: 'Test Consensus' },
+    quick_analyzers: ['coverage', 'fragility', 'mocking', 'assertions', 'structure'],
+    deep_analyzers: [
+      'coverage',
+      'fragility',
+      'mocking',
+      'assertions',
+      'structure',
+      'integration',
+      'maintenance',
+      'patterns',
+    ],
+  },
+
+  completeness: {
+    name: 'Completeness',
+    prefix: 'Comp',
+    color: '#bb9af7', // violet
+    command: 'code/completeness',
+    analyzers: {
+      handlers: { subagent_type: 'completeness-analyzer-handlers', label: 'Handlers' },
+      routes: { subagent_type: 'completeness-analyzer-routes', label: 'Routes' },
+      api: { subagent_type: 'completeness-analyzer-api', label: 'API Endpoints' },
+      stubs: { subagent_type: 'completeness-analyzer-stubs', label: 'Stubs' },
+      state: { subagent_type: 'completeness-analyzer-state', label: 'State' },
+      imports: { subagent_type: 'completeness-analyzer-imports', label: 'Imports' },
+      conditional: { subagent_type: 'completeness-analyzer-conditional', label: 'Conditionals' },
+    },
+    consensus: { subagent_type: 'completeness-consensus', label: 'Completeness Consensus' },
+    quick_analyzers: ['handlers', 'routes', 'api', 'stubs', 'state'],
+    deep_analyzers: ['handlers', 'routes', 'api', 'stubs', 'state', 'imports', 'conditional'],
+  },
+
+  brainstorm: {
+    name: 'Feature Brainstorm',
+    prefix: 'Brain',
+    color: '#c0caf5', // lavender
+    command: 'ideate/features',
+    analyzers: {
+      features: { subagent_type: 'brainstorm-analyzer-features', label: 'Feature Gaps' },
+      ux: { subagent_type: 'brainstorm-analyzer-ux', label: 'UX Improvements' },
+      market: { subagent_type: 'brainstorm-analyzer-market', label: 'Market Features' },
+      growth: { subagent_type: 'brainstorm-analyzer-growth', label: 'Growth & Engagement' },
+      integration: { subagent_type: 'brainstorm-analyzer-integration', label: 'Integrations' },
+    },
+    consensus: { subagent_type: 'brainstorm-consensus', label: 'Brainstorm Consensus' },
+    quick_analyzers: ['features', 'ux', 'market'],
+    deep_analyzers: ['features', 'ux', 'market', 'growth', 'integration'],
+  },
+
+  ideate: {
+    name: 'Ideation',
+    prefix: 'Idea',
+    color: '#ff9e64', // orange
+    command: 'ideate/new',
+    analyzers: {
+      security: { subagent_type: 'agileflow-security', label: 'Security' },
+      performance: { subagent_type: 'agileflow-performance', label: 'Performance' },
+      refactor: { subagent_type: 'agileflow-refactor', label: 'Code Quality' },
+      ui: { subagent_type: 'agileflow-ui', label: 'UX/Design' },
+      testing: { subagent_type: 'agileflow-testing', label: 'Testing' },
+      api: { subagent_type: 'agileflow-api', label: 'API/Architecture' },
+      accessibility: { subagent_type: 'agileflow-accessibility', label: 'Accessibility' },
+      compliance: { subagent_type: 'agileflow-compliance', label: 'Compliance' },
+      database: { subagent_type: 'agileflow-database', label: 'Database' },
+      monitoring: { subagent_type: 'agileflow-monitoring', label: 'Monitoring' },
+      qa: { subagent_type: 'agileflow-qa', label: 'QA' },
+      analytics: { subagent_type: 'agileflow-analytics', label: 'Analytics' },
+      documentation: { subagent_type: 'agileflow-documentation', label: 'Documentation' },
+    },
+    consensus: null, // ideation does its own synthesis (no consensus coordinator)
+    quick_analyzers: ['security', 'performance', 'refactor', 'ui', 'testing', 'api'],
+    deep_analyzers: [
+      'security',
+      'performance',
+      'refactor',
+      'ui',
+      'testing',
+      'api',
+      'accessibility',
+      'compliance',
+      'database',
+      'monitoring',
+      'qa',
+      'analytics',
+      'documentation',
+    ],
+  },
+
+  legal: {
+    name: 'Legal Risk',
+    prefix: 'Legal',
+    color: '#9ece6a', // lime
+    command: 'code/legal',
+    analyzers: {
+      privacy: { subagent_type: 'legal-analyzer-privacy', label: 'Privacy' },
+      terms: { subagent_type: 'legal-analyzer-terms', label: 'Terms' },
+      a11y: { subagent_type: 'legal-analyzer-a11y', label: 'Accessibility' },
+      licensing: { subagent_type: 'legal-analyzer-licensing', label: 'Licensing' },
+      consumer: { subagent_type: 'legal-analyzer-consumer', label: 'Consumer' },
+      security: { subagent_type: 'legal-analyzer-security', label: 'Security' },
+      ai: { subagent_type: 'legal-analyzer-ai', label: 'AI Compliance' },
+      content: { subagent_type: 'legal-analyzer-content', label: 'Content' },
+      international: { subagent_type: 'legal-analyzer-international', label: 'International' },
+    },
+    consensus: { subagent_type: 'legal-consensus', label: 'Legal Consensus' },
+    quick_analyzers: ['privacy', 'terms', 'a11y', 'licensing', 'consumer'],
+    deep_analyzers: [
+      'privacy',
+      'terms',
+      'a11y',
+      'licensing',
+      'consumer',
+      'security',
+      'ai',
+      'content',
+      'international',
+    ],
+  },
+};
+
+/**
+ * Get audit type configuration.
+ *
+ * @param {string} type - Audit type key (logic, security, performance, test, completeness, legal, ideate)
+ * @returns {object|null} Audit type config or null if invalid
+ */
+function getAuditType(type) {
+  return AUDIT_TYPES[type] || null;
+}
+
+/**
+ * Get all valid audit type keys.
+ *
+ * @returns {string[]} Array of audit type keys
+ */
+function getAuditTypeKeys() {
+  return Object.keys(AUDIT_TYPES);
+}
+
+/**
+ * Get analyzers for a given audit type, depth, and focus.
+ *
+ * @param {string} type - Audit type key
+ * @param {string} [depth='quick'] - 'quick', 'deep', or 'ultradeep'
+ * @param {string[]} [focus] - Array of focus areas, or null/['all'] for all
+ * @returns {{ analyzers: Array<{ key: string, subagent_type: string, label: string }>, consensus: object }|null}
+ */
+function getAnalyzersForAudit(type, depth, focus) {
+  const audit = AUDIT_TYPES[type];
+  if (!audit) return null;
+
+  const effectiveDepth = depth === 'ultradeep' || depth === 'extreme' ? 'deep' : depth || 'quick';
+  const analyzerKeys = effectiveDepth === 'deep' ? audit.deep_analyzers : audit.quick_analyzers;
+
+  // Filter by focus if specified
+  let selectedKeys = analyzerKeys;
+  if (focus && focus.length > 0 && !focus.includes('all')) {
+    selectedKeys = analyzerKeys.filter(key => focus.includes(key));
+    // If focus specifies keys not in current depth, include them anyway
+    for (const f of focus) {
+      if (audit.analyzers[f] && !selectedKeys.includes(f)) {
+        selectedKeys.push(f);
+      }
+    }
+  }
+
+  const analyzers = selectedKeys.map(key => ({
+    key,
+    subagent_type: audit.analyzers[key].subagent_type,
+    label: audit.analyzers[key].label,
+  }));
+
+  return {
+    analyzers,
+    consensus: audit.consensus,
+  };
+}
+
+/**
+ * Get analyzer count for a given audit type at each depth.
+ *
+ * @param {string} type - Audit type key
+ * @returns {{ quick: number, deep: number, total: number }|null}
+ */
+function getAnalyzerCounts(type) {
+  const audit = AUDIT_TYPES[type];
+  if (!audit) return null;
+
+  return {
+    quick: audit.quick_analyzers.length,
+    deep: audit.deep_analyzers.length,
+    total: Object.keys(audit.analyzers).length,
+  };
+}
+
+module.exports = {
+  AUDIT_TYPES,
+  getAuditType,
+  getAuditTypeKeys,
+  getAnalyzersForAudit,
+  getAnalyzerCounts,
+};

package/scripts/lib/configure-features.js

@@ -393,6 +393,25 @@ function enableFeature(feature, options = {}, version) {
   if (feature === 'agentteams') {
     settings.env = settings.env || {};
     settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
+
+    // Register PostToolUse hooks for native team observability
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+    const observerCmd = 'node $CLAUDE_PROJECT_DIR/.agileflow/scripts/native-team-observer.js';
+    for (const matcher of ['TeamCreate', 'SendMessage', 'ListTeams']) {
+      const exists = settings.hooks.PostToolUse.some(
+        h =>
+          h.matcher === matcher &&
+          h.hooks?.some(hk => hk.command && hk.command.includes('native-team-observer'))
+      );
+      if (!exists) {
+        settings.hooks.PostToolUse.push({
+          matcher,
+          hooks: [{ type: 'command', command: observerCmd, timeout: 5000 }],
+        });
+      }
+    }
+
     writeJSON('.claude/settings.json', settings);
     updateMetadata(
       {
@@ -408,6 +427,7 @@ function enableFeature(feature, options = {}, version) {
     );
     success('Native Agent Teams enabled');
     info('Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in .claude/settings.json');
+    info('Registered PostToolUse hooks for native team observability');
     info('Claude Code will use native TeamCreate/SendMessage tools');
     info('Fallback: subagent mode (Task/TaskOutput) when native is unavailable');
     return true;
@@ -954,6 +974,20 @@ function disableFeature(feature, version) {
         delete settings.env;
       }
     }
+
+    // Remove PostToolUse hooks for native team observer
+    if (settings.hooks?.PostToolUse) {
+      settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(
+        h => !h.hooks?.some(hk => hk.command && hk.command.includes('native-team-observer'))
+      );
+      if (settings.hooks.PostToolUse.length === 0) {
+        delete settings.hooks.PostToolUse;
+      }
+      if (Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+      }
+    }
+
     writeJSON('.claude/settings.json', settings);
     updateMetadata(
       {
@@ -969,6 +1003,7 @@ function disableFeature(feature, version) {
     );
     success('Native Agent Teams disabled');
     info('Removed CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS from .claude/settings.json');
+    info('Removed PostToolUse hooks for native team observer');
     info('AgileFlow will use subagent mode (Task/TaskOutput) for multi-agent orchestration');
     return true;
   }

package/scripts/lib/feature-catalog.js

@@ -116,7 +116,7 @@ const FEATURE_CATALOG = [
     feature: 'discovery',
     name: 'Discovery',
     description: 'Brainstorm, research, and synthesize findings into a Product Brief',
-    how_to_use: '/agileflow:discovery:new "<topic>"',
+    how_to_use: '/agileflow:ideate:discover "<topic>"',
     category: 'workflow',
     detector: null,
     auto_mode: null,
@@ -168,7 +168,7 @@ const FEATURE_CATALOG = [
     feature: 'logic-audit',
     name: 'Logic Audit',
     description: 'Multi-agent analysis for edge cases, race conditions, type bugs, and dead code',
-    how_to_use: '/agileflow:audit:logic',
+    how_to_use: '/agileflow:code:logic',
     category: 'analysis',
     detector: null,
     auto_mode: null,
@@ -179,7 +179,7 @@ const FEATURE_CATALOG = [
     name: 'Completeness Audit',
     description:
       'Multi-agent analysis for forgotten features, dead handlers, stub code, and incomplete implementations',
-    how_to_use: '/agileflow:audit:completeness',
+    how_to_use: '/agileflow:code:completeness',
     category: 'analysis',
     detector: null,
     auto_mode: null,

package/scripts/lib/gate-enforcer.js

@@ -0,0 +1,295 @@
+/**
+ * gate-enforcer.js - Workflow Gate Enforcement for Babysit Strict Mode
+ *
+ * Filters AskUserQuestion options based on workflow gate status.
+ * When STRICT=true in babysit, certain options are removed or blocked
+ * based on whether gates have been satisfied (tests passed, review done, etc.).
+ *
+ * Gates:
+ * - tests_passed: Must run and pass tests before commit
+ * - review_done: Must run code review for 5+ source files before commit
+ * - logic_audit_done: Must run logic audit before commit (advisory in non-strict)
+ *
+ * Usage:
+ *   const { filterOptions, getGateStatus, updateGate } = require('./gate-enforcer');
+ *   const filtered = filterOptions(options, gateState, { strict: true });
+ */
+
+'use strict';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Gate types that can block workflow progression
+ */
+const GATES = {
+  TESTS_PASSED: 'tests_passed',
+  REVIEW_DONE: 'review_done',
+  LOGIC_AUDIT_DONE: 'logic_audit_done',
+};
+
+/**
+ * Actions that require specific gates to be satisfied
+ */
+const GATE_REQUIREMENTS = {
+  commit: {
+    strict: [GATES.TESTS_PASSED],
+    strict_5plus: [GATES.TESTS_PASSED, GATES.REVIEW_DONE],
+  },
+  next_story: {
+    strict: [GATES.TESTS_PASSED],
+  },
+};
+
+/**
+ * Patterns that identify commit-related options
+ */
+const COMMIT_PATTERNS = [/^commit/i, /^git commit/i, /commit.*changes/i, /commit:?\s/i];
+
+/**
+ * Patterns that identify "skip" options
+ */
+const SKIP_PATTERNS = [/skip.*test/i, /skip.*review/i, /skip.*audit/i, /skip.*verif/i];
+
+/**
+ * Patterns that identify "next story" options
+ */
+const NEXT_STORY_PATTERNS = [/continue to/i, /next story/i, /move to.*US-/i];
+
+// ============================================================================
+// Gate State Management
+// ============================================================================
+
+/**
+ * Create initial gate state for a workflow session
+ * @param {Object} options
+ * @param {number} options.filesChanged - Number of source files modified
+ * @param {boolean} options.strict - Whether strict mode is enabled
+ * @returns {Object} Initial gate state
+ */
+function createGateState(options = {}) {
+  const { filesChanged = 0, strict = false } = options;
+
+  return {
+    strict,
+    files_changed: filesChanged,
+    gates: {
+      [GATES.TESTS_PASSED]: false,
+      [GATES.REVIEW_DONE]: false,
+      [GATES.LOGIC_AUDIT_DONE]: false,
+    },
+    history: [],
+    created_at: new Date().toISOString(),
+  };
+}
+
+/**
+ * Update a gate's status
+ * @param {Object} gateState - Current gate state
+ * @param {string} gate - Gate name from GATES
+ * @param {boolean} passed - Whether the gate passed
+ * @param {Object} metadata - Additional info (e.g., test count, review findings)
+ * @returns {Object} Updated gate state
+ */
+function updateGate(gateState, gate, passed, metadata = {}) {
+  if (!Object.values(GATES).includes(gate)) {
+    throw new Error(`Unknown gate: ${gate}. Valid: ${Object.values(GATES).join(', ')}`);
+  }
+
+  const updated = {
+    ...gateState,
+    gates: {
+      ...gateState.gates,
+      [gate]: passed,
+    },
+    history: [
+      ...gateState.history,
+      {
+        gate,
+        passed,
+        at: new Date().toISOString(),
+        ...metadata,
+      },
+    ],
+  };
+
+  return updated;
+}
+
+/**
+ * Check if all required gates for an action are satisfied
+ * @param {Object} gateState - Current gate state
+ * @param {string} action - Action to check ('commit', 'next_story')
+ * @returns {{ allowed: boolean, missing: string[] }}
+ */
+function checkGates(gateState, action) {
+  if (!gateState.strict) {
+    return { allowed: true, missing: [] };
+  }
+
+  let requirements;
+  if (action === 'commit' && gateState.files_changed >= 5) {
+    requirements = GATE_REQUIREMENTS.commit.strict_5plus || [];
+  } else {
+    requirements = (GATE_REQUIREMENTS[action] && GATE_REQUIREMENTS[action].strict) || [];
+  }
+
+  const missing = requirements.filter(gate => !gateState.gates[gate]);
+
+  return {
+    allowed: missing.length === 0,
+    missing,
+  };
+}
+
+// ============================================================================
+// Option Filtering
+// ============================================================================
+
+/**
+ * Check if an option label matches any pattern in a list
+ * @param {string} label - Option label text
+ * @param {RegExp[]} patterns - Patterns to match against
+ * @returns {boolean}
+ */
+function matchesPattern(label, patterns) {
+  if (typeof label !== 'string') return false;
+  return patterns.some(p => p.test(label));
+}
+
+/**
+ * Filter AskUserQuestion options based on gate state
+ *
+ * In strict mode:
+ * - Remove "commit" options if tests haven't passed
+ * - Remove "commit" options if review not done (5+ files)
+ * - Remove "skip tests/review/audit" options
+ * - Add gate status hints to option descriptions
+ *
+ * In non-strict mode:
+ * - Options are returned unchanged (soft guidance only)
+ *
+ * @param {Object[]} options - AskUserQuestion options array
+ * @param {Object} gateState - Current gate state
+ * @returns {Object[]} Filtered options
+ */
+function filterOptions(options, gateState) {
+  if (!Array.isArray(options)) return [];
+  if (!gateState || !gateState.strict) {
+    return options;
+  }
+
+  return options
+    .filter(opt => {
+      const label = opt.label || '';
+
+      // In strict mode, remove skip options entirely
+      if (matchesPattern(label, SKIP_PATTERNS)) {
+        return false;
+      }
+
+      // Check commit gates
+      if (matchesPattern(label, COMMIT_PATTERNS)) {
+        const { allowed } = checkGates(gateState, 'commit');
+        if (!allowed) {
+          return false;
+        }
+      }
+
+      // Check next story gates
+      if (matchesPattern(label, NEXT_STORY_PATTERNS)) {
+        const { allowed } = checkGates(gateState, 'next_story');
+        if (!allowed) {
+          return false;
+        }
+      }
+
+      return true;
+    })
+    .map(opt => {
+      // Add gate status hints to descriptions
+      const label = opt.label || '';
+
+      if (matchesPattern(label, COMMIT_PATTERNS) && gateState.strict) {
+        const checks = [];
+        if (gateState.gates[GATES.TESTS_PASSED]) checks.push('tests passed');
+        if (gateState.gates[GATES.REVIEW_DONE]) checks.push('review done');
+        if (gateState.gates[GATES.LOGIC_AUDIT_DONE]) checks.push('audit done');
+
+        if (checks.length > 0) {
+          return {
+            ...opt,
+            description: `${opt.description || ''} [Gates: ${checks.join(', ')}]`.trim(),
+          };
+        }
+      }
+
+      return opt;
+    });
+}
+
+/**
+ * Get a human-readable gate status summary
+ * @param {Object} gateState - Current gate state
+ * @returns {string} Status summary
+ */
+function getGateStatusSummary(gateState) {
+  if (!gateState || !gateState.strict) {
+    return 'Strict mode: OFF (soft guidance)';
+  }
+
+  const lines = [`Strict mode: ON | ${gateState.files_changed} files changed`];
+
+  for (const [gate, passed] of Object.entries(gateState.gates)) {
+    const icon = passed ? '✅' : '⬜';
+    const name = gate.replace(/_/g, ' ');
+    lines.push(`  ${icon} ${name}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Get blocking message for a failed gate check
+ * @param {string[]} missingGates - List of unsatisfied gates
+ * @returns {string} Human-readable blocking message
+ */
+function getBlockingMessage(missingGates) {
+  const messages = {
+    [GATES.TESTS_PASSED]: 'Run tests first (tests must pass before committing)',
+    [GATES.REVIEW_DONE]: 'Run code review first (required for 5+ modified files)',
+    [GATES.LOGIC_AUDIT_DONE]: 'Run logic audit first',
+  };
+
+  return missingGates.map(gate => `🚫 ${messages[gate] || gate}`).join('\n');
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+module.exports = {
+  // Constants
+  GATES,
+  GATE_REQUIREMENTS,
+
+  // State management
+  createGateState,
+  updateGate,
+  checkGates,
+
+  // Option filtering
+  filterOptions,
+  matchesPattern,
+
+  // Reporting
+  getGateStatusSummary,
+  getBlockingMessage,
+
+  // Patterns (for testing)
+  COMMIT_PATTERNS,
+  SKIP_PATTERNS,
+  NEXT_STORY_PATTERNS,
+};