aw-ecc 1.4.21

package/scripts/ci/catalog.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * Verify repo catalog counts against README.md and AGENTS.md.
+ *
+ * Usage:
+ *   node scripts/ci/catalog.js
+ *   node scripts/ci/catalog.js --json
+ *   node scripts/ci/catalog.js --md
+ *   node scripts/ci/catalog.js --text
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '../..');
+const README_PATH = path.join(ROOT, 'README.md');
+const AGENTS_PATH = path.join(ROOT, 'AGENTS.md');
+
+const OUTPUT_MODE = process.argv.includes('--md')
+  ? 'md'
+  : process.argv.includes('--text')
+    ? 'text'
+    : 'json';
+
+function normalizePathSegments(relativePath) {
+  return relativePath.split(path.sep).join('/');
+}
+
+function listMatchingFiles(relativeDir, matcher) {
+  const directory = path.join(ROOT, relativeDir);
+  if (!fs.existsSync(directory)) {
+    return [];
+  }
+
+  return fs.readdirSync(directory, { withFileTypes: true })
+    .filter(entry => matcher(entry))
+    .map(entry => normalizePathSegments(path.join(relativeDir, entry.name)))
+    .sort();
+}
+
+function buildCatalog() {
+  const agents = listMatchingFiles('agents', entry => entry.isFile() && entry.name.endsWith('.md'));
+  const commands = listMatchingFiles('commands', entry => entry.isFile() && entry.name.endsWith('.md'));
+  const skills = listMatchingFiles('skills', entry => entry.isDirectory() && fs.existsSync(path.join(ROOT, 'skills', entry.name, 'SKILL.md')))
+    .map(skillDir => `${skillDir}/SKILL.md`);
+
+  return {
+    agents: { count: agents.length, files: agents, glob: 'agents/*.md' },
+    commands: { count: commands.length, files: commands, glob: 'commands/*.md' },
+    skills: { count: skills.length, files: skills, glob: 'skills/*/SKILL.md' }
+  };
+}
+
+function readFileOrThrow(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    throw new Error(`Failed to read ${path.basename(filePath)}: ${error.message}`);
+  }
+}
+
+function parseReadmeExpectations(readmeContent) {
+  const expectations = [];
+
+  const quickStartMatch = readmeContent.match(/access to\s+(\d+)\s+agents,\s+(\d+)\s+skills,\s+and\s+(\d+)\s+commands/i);
+  if (!quickStartMatch) {
+    throw new Error('README.md is missing the quick-start catalog summary');
+  }
+
+  expectations.push(
+    { category: 'agents', mode: 'exact', expected: Number(quickStartMatch[1]), source: 'README.md quick-start summary' },
+    { category: 'skills', mode: 'exact', expected: Number(quickStartMatch[2]), source: 'README.md quick-start summary' },
+    { category: 'commands', mode: 'exact', expected: Number(quickStartMatch[3]), source: 'README.md quick-start summary' }
+  );
+
+  const tablePatterns = [
+    { category: 'agents', regex: /\|\s*(?:\*\*)?Agents(?:\*\*)?\s*\|\s*✅\s*(\d+)\s+agents\s*\|/i, source: 'README.md comparison table' },
+    { category: 'commands', regex: /\|\s*(?:\*\*)?Commands(?:\*\*)?\s*\|\s*✅\s*(\d+)\s+commands\s*\|/i, source: 'README.md comparison table' },
+    { category: 'skills', regex: /\|\s*(?:\*\*)?Skills(?:\*\*)?\s*\|\s*✅\s*(\d+)\s+skills\s*\|/i, source: 'README.md comparison table' }
+  ];
+
+  for (const pattern of tablePatterns) {
+    const match = readmeContent.match(pattern.regex);
+    if (!match) {
+      throw new Error(`${pattern.source} is missing the ${pattern.category} row`);
+    }
+
+    expectations.push({
+      category: pattern.category,
+      mode: 'exact',
+      expected: Number(match[1]),
+      source: `${pattern.source} (${pattern.category})`
+    });
+  }
+
+  return expectations;
+}
+
+function parseAgentsDocExpectations(agentsContent) {
+  const summaryMatch = agentsContent.match(/providing\s+(\d+)\s+specialized agents,\s+(\d+)(\+)?\s+skills,\s+(\d+)\s+commands/i);
+  if (!summaryMatch) {
+    throw new Error('AGENTS.md is missing the catalog summary line');
+  }
+
+  const expectations = [
+    { category: 'agents', mode: 'exact', expected: Number(summaryMatch[1]), source: 'AGENTS.md summary' },
+    {
+      category: 'skills',
+      mode: summaryMatch[3] ? 'minimum' : 'exact',
+      expected: Number(summaryMatch[2]),
+      source: 'AGENTS.md summary'
+    },
+    { category: 'commands', mode: 'exact', expected: Number(summaryMatch[4]), source: 'AGENTS.md summary' }
+  ];
+
+  const structurePatterns = [
+    {
+      category: 'agents',
+      mode: 'exact',
+      regex: /^\s*agents\/\s*[—–-]\s*(\d+)\s+specialized subagents\s*$/im,
+      source: 'AGENTS.md project structure'
+    },
+    {
+      category: 'skills',
+      mode: 'minimum',
+      regex: /^\s*skills\/\s*[—–-]\s*(\d+)(\+)?\s+workflow skills and domain knowledge\s*$/im,
+      source: 'AGENTS.md project structure'
+    },
+    {
+      category: 'commands',
+      mode: 'exact',
+      regex: /^\s*commands\/\s*[—–-]\s*(\d+)\s+slash commands\s*$/im,
+      source: 'AGENTS.md project structure'
+    }
+  ];
+
+  for (const pattern of structurePatterns) {
+    const match = agentsContent.match(pattern.regex);
+    if (!match) {
+      throw new Error(`${pattern.source} is missing the ${pattern.category} entry`);
+    }
+
+    expectations.push({
+      category: pattern.category,
+      mode: pattern.mode === 'minimum' && match[2] ? 'minimum' : pattern.mode,
+      expected: Number(match[1]),
+      source: `${pattern.source} (${pattern.category})`
+    });
+  }
+
+  return expectations;
+}
+
+function evaluateExpectations(catalog, expectations) {
+  return expectations.map(expectation => {
+    const actual = catalog[expectation.category].count;
+    const ok = expectation.mode === 'minimum'
+      ? actual >= expectation.expected
+      : actual === expectation.expected;
+
+    return {
+      ...expectation,
+      actual,
+      ok
+    };
+  });
+}
+
+function formatExpectation(expectation) {
+  const comparator = expectation.mode === 'minimum' ? '>=' : '=';
+  return `${expectation.source}: ${expectation.category} documented ${comparator} ${expectation.expected}, actual ${expectation.actual}`;
+}
+
+function renderText(result) {
+  console.log('Catalog counts:');
+  console.log(`- agents: ${result.catalog.agents.count}`);
+  console.log(`- commands: ${result.catalog.commands.count}`);
+  console.log(`- skills: ${result.catalog.skills.count}`);
+  console.log('');
+
+  const mismatches = result.checks.filter(check => !check.ok);
+  if (mismatches.length === 0) {
+    console.log('Documentation counts match the repository catalog.');
+    return;
+  }
+
+  console.error('Documentation count mismatches found:');
+  for (const mismatch of mismatches) {
+    console.error(`- ${formatExpectation(mismatch)}`);
+  }
+}
+
+function renderMarkdown(result) {
+  const mismatches = result.checks.filter(check => !check.ok);
+  console.log('# ECC Catalog Verification\n');
+  console.log('| Category | Count | Pattern |');
+  console.log('| --- | ---: | --- |');
+  console.log(`| Agents | ${result.catalog.agents.count} | \`${result.catalog.agents.glob}\` |`);
+  console.log(`| Commands | ${result.catalog.commands.count} | \`${result.catalog.commands.glob}\` |`);
+  console.log(`| Skills | ${result.catalog.skills.count} | \`${result.catalog.skills.glob}\` |`);
+  console.log('');
+
+  if (mismatches.length === 0) {
+    console.log('Documentation counts match the repository catalog.');
+    return;
+  }
+
+  console.log('## Mismatches\n');
+  for (const mismatch of mismatches) {
+    console.log(`- ${formatExpectation(mismatch)}`);
+  }
+}
+
+function main() {
+  const catalog = buildCatalog();
+  const readmeContent = readFileOrThrow(README_PATH);
+  const agentsContent = readFileOrThrow(AGENTS_PATH);
+  const expectations = [
+    ...parseReadmeExpectations(readmeContent),
+    ...parseAgentsDocExpectations(agentsContent)
+  ];
+  const checks = evaluateExpectations(catalog, expectations);
+  const result = { catalog, checks };
+
+  if (OUTPUT_MODE === 'json') {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (OUTPUT_MODE === 'md') {
+    renderMarkdown(result);
+  } else {
+    renderText(result);
+  }
+
+  if (checks.some(check => !check.ok)) {
+    process.exit(1);
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`ERROR: ${error.message}`);
+  process.exit(1);
+}

package/scripts/ci/validate-agents.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * Validate agent markdown files have required frontmatter
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENTS_DIR = path.join(__dirname, '../../agents');
+const REQUIRED_FIELDS = ['model', 'tools'];
+const VALID_MODELS = ['haiku', 'sonnet', 'opus'];
+
+function extractFrontmatter(content) {
+  // Strip BOM if present (UTF-8 BOM: \uFEFF)
+  const cleanContent = content.replace(/^\uFEFF/, '');
+  // Support both LF and CRLF line endings
+  const match = cleanContent.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+
+  const frontmatter = {};
+  const lines = match[1].split(/\r?\n/);
+  for (const line of lines) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx > 0) {
+      const key = line.slice(0, colonIdx).trim();
+      const value = line.slice(colonIdx + 1).trim();
+      frontmatter[key] = value;
+    }
+  }
+  return frontmatter;
+}
+
+function validateAgents() {
+  if (!fs.existsSync(AGENTS_DIR)) {
+    console.log('No agents directory found, skipping validation');
+    process.exit(0);
+  }
+
+  const files = fs.readdirSync(AGENTS_DIR).filter(f => f.endsWith('.md'));
+  let hasErrors = false;
+
+  for (const file of files) {
+    const filePath = path.join(AGENTS_DIR, file);
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf-8');
+    } catch (err) {
+      console.error(`ERROR: ${file} - ${err.message}`);
+      hasErrors = true;
+      continue;
+    }
+    const frontmatter = extractFrontmatter(content);
+
+    if (!frontmatter) {
+      console.error(`ERROR: ${file} - Missing frontmatter`);
+      hasErrors = true;
+      continue;
+    }
+
+    for (const field of REQUIRED_FIELDS) {
+      if (!frontmatter[field] || (typeof frontmatter[field] === 'string' && !frontmatter[field].trim())) {
+        console.error(`ERROR: ${file} - Missing required field: ${field}`);
+        hasErrors = true;
+      }
+    }
+
+    // Validate model is a known value
+    if (frontmatter.model && !VALID_MODELS.includes(frontmatter.model)) {
+      console.error(`ERROR: ${file} - Invalid model '${frontmatter.model}'. Must be one of: ${VALID_MODELS.join(', ')}`);
+      hasErrors = true;
+    }
+  }
+
+  if (hasErrors) {
+    process.exit(1);
+  }
+
+  console.log(`Validated ${files.length} agent files`);
+}
+
+validateAgents();

package/scripts/ci/validate-commands.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * Validate command markdown files are non-empty, readable,
+ * and have valid cross-references to other commands, agents, and skills.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_DIR = path.join(__dirname, '../..');
+const COMMANDS_DIR = path.join(ROOT_DIR, 'commands');
+const AGENTS_DIR = path.join(ROOT_DIR, 'agents');
+const SKILLS_DIR = path.join(ROOT_DIR, 'skills');
+
+function validateCommands() {
+  if (!fs.existsSync(COMMANDS_DIR)) {
+    console.log('No commands directory found, skipping validation');
+    process.exit(0);
+  }
+
+  const files = fs.readdirSync(COMMANDS_DIR).filter(f => f.endsWith('.md'));
+  let hasErrors = false;
+  let warnCount = 0;
+
+  // Build set of valid command names (without .md extension)
+  const validCommands = new Set(files.map(f => f.replace(/\.md$/, '')));
+
+  // Build set of valid agent names (without .md extension)
+  const validAgents = new Set();
+  if (fs.existsSync(AGENTS_DIR)) {
+    for (const f of fs.readdirSync(AGENTS_DIR)) {
+      if (f.endsWith('.md')) {
+        validAgents.add(f.replace(/\.md$/, ''));
+      }
+    }
+  }
+
+  // Build set of valid skill directory names
+  const validSkills = new Set();
+  if (fs.existsSync(SKILLS_DIR)) {
+    for (const f of fs.readdirSync(SKILLS_DIR)) {
+      const skillPath = path.join(SKILLS_DIR, f);
+      try {
+        if (fs.statSync(skillPath).isDirectory()) {
+          validSkills.add(f);
+        }
+      } catch {
+        // skip unreadable entries
+      }
+    }
+  }
+
+  for (const file of files) {
+    const filePath = path.join(COMMANDS_DIR, file);
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf-8');
+    } catch (err) {
+      console.error(`ERROR: ${file} - ${err.message}`);
+      hasErrors = true;
+      continue;
+    }
+
+    // Validate the file is non-empty readable markdown
+    if (content.trim().length === 0) {
+      console.error(`ERROR: ${file} - Empty command file`);
+      hasErrors = true;
+      continue;
+    }
+
+    // Strip fenced code blocks before checking cross-references.
+    // Examples/templates inside ``` blocks are not real references.
+    const contentNoCodeBlocks = content.replace(/```[\s\S]*?```/g, '');
+
+    // Check cross-references to other commands (e.g., `/build-fix`)
+    // Skip lines that describe hypothetical output (e.g., "→ Creates: `/new-table`")
+    // Process line-by-line so ALL command refs per line are captured
+    // (previous anchored regex /^.*`\/...`.*$/gm only matched the last ref per line)
+    for (const line of contentNoCodeBlocks.split('\n')) {
+      if (/creates:|would create:/i.test(line)) continue;
+      const lineRefs = line.matchAll(/`\/([a-z][-a-z0-9]*)`/g);
+      for (const match of lineRefs) {
+        const refName = match[1];
+        if (!validCommands.has(refName)) {
+          console.error(`ERROR: ${file} - references non-existent command /${refName}`);
+          hasErrors = true;
+        }
+      }
+    }
+
+    // Check agent references (e.g., "agents/planner.md" or "`planner` agent")
+    const agentPathRefs = contentNoCodeBlocks.matchAll(/agents\/([a-z][-a-z0-9]*)\.md/g);
+    for (const match of agentPathRefs) {
+      const refName = match[1];
+      if (!validAgents.has(refName)) {
+        console.error(`ERROR: ${file} - references non-existent agent agents/${refName}.md`);
+        hasErrors = true;
+      }
+    }
+
+    // Check skill directory references (e.g., "skills/tdd-workflow/")
+    // learned and imported are reserved roots (~/.claude/skills/); no local dir expected
+    const reservedSkillRoots = new Set(['learned', 'imported']);
+    const skillRefs = contentNoCodeBlocks.matchAll(/skills\/([a-z][-a-z0-9]*)\//g);
+    for (const match of skillRefs) {
+      const refName = match[1];
+      if (reservedSkillRoots.has(refName) || validSkills.has(refName)) continue;
+      console.warn(`WARN: ${file} - references skill directory skills/${refName}/ (not found locally)`);
+      warnCount++;
+    }
+
+    // Check agent name references in workflow diagrams (e.g., "planner -> tdd-guide")
+    const workflowLines = contentNoCodeBlocks.matchAll(/^([a-z][-a-z0-9]*(?:\s*->\s*[a-z][-a-z0-9]*)+)$/gm);
+    for (const match of workflowLines) {
+      const agents = match[1].split(/\s*->\s*/);
+      for (const agent of agents) {
+        if (!validAgents.has(agent)) {
+          console.error(`ERROR: ${file} - workflow references non-existent agent "${agent}"`);
+          hasErrors = true;
+        }
+      }
+    }
+  }
+
+  if (hasErrors) {
+    process.exit(1);
+  }
+
+  let msg = `Validated ${files.length} command files`;
+  if (warnCount > 0) {
+    msg += ` (${warnCount} warnings)`;
+  }
+  console.log(msg);
+}
+
+validateCommands();

package/scripts/ci/validate-hooks.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * Validate hooks.json schema and hook entry rules.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+const Ajv = require('ajv');
+
+const HOOKS_FILE = path.join(__dirname, '../../hooks/hooks.json');
+const HOOKS_SCHEMA_PATH = path.join(__dirname, '../../schemas/hooks.schema.json');
+const VALID_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PermissionRequest',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'Notification',
+  'SubagentStart',
+  'Stop',
+  'SubagentStop',
+  'PreCompact',
+  'InstructionsLoaded',
+  'TeammateIdle',
+  'TaskCompleted',
+  'ConfigChange',
+  'WorktreeCreate',
+  'WorktreeRemove',
+  'SessionEnd',
+];
+const VALID_HOOK_TYPES = ['command', 'http', 'prompt', 'agent'];
+const EVENTS_WITHOUT_MATCHER = new Set(['UserPromptSubmit', 'Notification', 'Stop', 'SubagentStop']);
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isNonEmptyStringArray(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(item => isNonEmptyString(item));
+}
+
+/**
+ * Validate a single hook entry has required fields and valid inline JS
+ * @param {object} hook - Hook object with type and command fields
+ * @param {string} label - Label for error messages (e.g., "PreToolUse[0].hooks[1]")
+ * @returns {boolean} true if errors were found
+ */
+function validateHookEntry(hook, label) {
+  let hasErrors = false;
+
+  if (!hook.type || typeof hook.type !== 'string') {
+    console.error(`ERROR: ${label} missing or invalid 'type' field`);
+    hasErrors = true;
+  } else if (!VALID_HOOK_TYPES.includes(hook.type)) {
+    console.error(`ERROR: ${label} has unsupported hook type '${hook.type}'`);
+    hasErrors = true;
+  }
+
+  if ('timeout' in hook && (typeof hook.timeout !== 'number' || hook.timeout < 0)) {
+    console.error(`ERROR: ${label} 'timeout' must be a non-negative number`);
+    hasErrors = true;
+  }
+
+  if (hook.type === 'command') {
+    if ('async' in hook && typeof hook.async !== 'boolean') {
+      console.error(`ERROR: ${label} 'async' must be a boolean`);
+      hasErrors = true;
+    }
+
+    if (!isNonEmptyString(hook.command) && !isNonEmptyStringArray(hook.command)) {
+      console.error(`ERROR: ${label} missing or invalid 'command' field`);
+      hasErrors = true;
+    } else if (typeof hook.command === 'string') {
+      const nodeEMatch = hook.command.match(/^node -e "(.*)"$/s);
+      if (nodeEMatch) {
+        try {
+          new vm.Script(nodeEMatch[1].replace(/\\\\/g, '\\').replace(/\\"/g, '"').replace(/\\n/g, '\n').replace(/\\t/g, '\t'));
+        } catch (syntaxErr) {
+          console.error(`ERROR: ${label} has invalid inline JS: ${syntaxErr.message}`);
+          hasErrors = true;
+        }
+      }
+    }
+
+    return hasErrors;
+  }
+
+  if ('async' in hook) {
+    console.error(`ERROR: ${label} 'async' is only supported for command hooks`);
+    hasErrors = true;
+  }
+
+  if (hook.type === 'http') {
+    if (!isNonEmptyString(hook.url)) {
+      console.error(`ERROR: ${label} missing or invalid 'url' field`);
+      hasErrors = true;
+    }
+
+    if ('headers' in hook && (typeof hook.headers !== 'object' || hook.headers === null || Array.isArray(hook.headers) || !Object.values(hook.headers).every(value => typeof value === 'string'))) {
+      console.error(`ERROR: ${label} 'headers' must be an object with string values`);
+      hasErrors = true;
+    }
+
+    if ('allowedEnvVars' in hook && (!Array.isArray(hook.allowedEnvVars) || !hook.allowedEnvVars.every(value => isNonEmptyString(value)))) {
+      console.error(`ERROR: ${label} 'allowedEnvVars' must be an array of strings`);
+      hasErrors = true;
+    }
+
+    return hasErrors;
+  }
+
+  if (!isNonEmptyString(hook.prompt)) {
+    console.error(`ERROR: ${label} missing or invalid 'prompt' field`);
+    hasErrors = true;
+  }
+
+  if ('model' in hook && !isNonEmptyString(hook.model)) {
+    console.error(`ERROR: ${label} 'model' must be a non-empty string`);
+    hasErrors = true;
+  }
+
+  return hasErrors;
+}
+
+function validateHooks() {
+  if (!fs.existsSync(HOOKS_FILE)) {
+    console.log('No hooks.json found, skipping validation');
+    process.exit(0);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(HOOKS_FILE, 'utf-8'));
+  } catch (e) {
+    console.error(`ERROR: Invalid JSON in hooks.json: ${e.message}`);
+    process.exit(1);
+  }
+
+  // Validate against JSON schema
+  if (fs.existsSync(HOOKS_SCHEMA_PATH)) {
+    const schema = JSON.parse(fs.readFileSync(HOOKS_SCHEMA_PATH, 'utf-8'));
+    const ajv = new Ajv({ allErrors: true });
+    const validate = ajv.compile(schema);
+    const valid = validate(data);
+    if (!valid) {
+      for (const err of validate.errors) {
+        console.error(`ERROR: hooks.json schema: ${err.instancePath || '/'} ${err.message}`);
+      }
+      process.exit(1);
+    }
+  }
+
+  // Support both object format { hooks: {...} } and array format
+  const hooks = data.hooks || data;
+  let hasErrors = false;
+  let totalMatchers = 0;
+
+  if (typeof hooks === 'object' && !Array.isArray(hooks)) {
+    // Object format: { EventType: [matchers] }
+    for (const [eventType, matchers] of Object.entries(hooks)) {
+      if (!VALID_EVENTS.includes(eventType)) {
+        console.error(`ERROR: Invalid event type: ${eventType}`);
+        hasErrors = true;
+        continue;
+      }
+
+      if (!Array.isArray(matchers)) {
+        console.error(`ERROR: ${eventType} must be an array`);
+        hasErrors = true;
+        continue;
+      }
+
+      for (let i = 0; i < matchers.length; i++) {
+        const matcher = matchers[i];
+        if (typeof matcher !== 'object' || matcher === null) {
+          console.error(`ERROR: ${eventType}[${i}] is not an object`);
+          hasErrors = true;
+          continue;
+        }
+        if (!('matcher' in matcher) && !EVENTS_WITHOUT_MATCHER.has(eventType)) {
+          console.error(`ERROR: ${eventType}[${i}] missing 'matcher' field`);
+          hasErrors = true;
+        } else if ('matcher' in matcher && typeof matcher.matcher !== 'string' && (typeof matcher.matcher !== 'object' || matcher.matcher === null)) {
+          console.error(`ERROR: ${eventType}[${i}] has invalid 'matcher' field`);
+          hasErrors = true;
+        }
+        if (!matcher.hooks || !Array.isArray(matcher.hooks)) {
+          console.error(`ERROR: ${eventType}[${i}] missing 'hooks' array`);
+          hasErrors = true;
+        } else {
+          // Validate each hook entry
+          for (let j = 0; j < matcher.hooks.length; j++) {
+            if (validateHookEntry(matcher.hooks[j], `${eventType}[${i}].hooks[${j}]`)) {
+              hasErrors = true;
+            }
+          }
+        }
+        totalMatchers++;
+      }
+    }
+  } else if (Array.isArray(hooks)) {
+    // Array format (legacy)
+    for (let i = 0; i < hooks.length; i++) {
+      const hook = hooks[i];
+      if (!('matcher' in hook)) {
+        console.error(`ERROR: Hook ${i} missing 'matcher' field`);
+        hasErrors = true;
+      } else if (typeof hook.matcher !== 'string' && (typeof hook.matcher !== 'object' || hook.matcher === null)) {
+        console.error(`ERROR: Hook ${i} has invalid 'matcher' field`);
+        hasErrors = true;
+      }
+      if (!hook.hooks || !Array.isArray(hook.hooks)) {
+        console.error(`ERROR: Hook ${i} missing 'hooks' array`);
+        hasErrors = true;
+      } else {
+        // Validate each hook entry
+        for (let j = 0; j < hook.hooks.length; j++) {
+          if (validateHookEntry(hook.hooks[j], `Hook ${i}.hooks[${j}]`)) {
+            hasErrors = true;
+          }
+        }
+      }
+      totalMatchers++;
+    }
+  } else {
+    console.error('ERROR: hooks.json must be an object or array');
+    process.exit(1);
+  }
+
+  if (hasErrors) {
+    process.exit(1);
+  }
+
+  console.log(`Validated ${totalMatchers} hook matchers`);
+}
+
+validateHooks();