9thlevelsoftware/legion/intent-router

/**
 * Parse intent flags from command arguments
 * @param {string[]} args - Command arguments (e.g., ['--just-harden', '--skip-frontend'])
 * @returns {Object} Normalized intent configuration
 * 
 * Returns:
 * {
 *   rawFlags: ['--just-harden', '--skip-frontend'],
 *   intents: ['harden'],
 *   filters: {
 *     skipFrontend: true,
 *     skipBackend: false
 *   },
 *   primaryIntent: 'harden',
 *   hasConflicts: false
 * }
 */

function parseIntentFlags(args) {
  const result = {
    rawFlags: [],
    intents: [],
    filters: {
      skipFrontend: false,
      skipBackend: false
    },
    primaryIntent: null,
    hasConflicts: false
  };
  const seenFlags = new Set();
  
  for (const arg of args) {
    const flag = arg.toLowerCase().split('=')[0];
    
    if (seenFlags.has(flag)) continue;
    seenFlags.add(flag);
    
    switch (flag) {
      case '--just-harden':
        result.rawFlags.push(flag);
        result.intents.push('harden');
        result.primaryIntent = 'harden';
        break;
      case '--just-document':
        result.rawFlags.push(flag);
        result.intents.push('document');
        result.primaryIntent = 'document';
        break;
      case '--just-security':
        result.rawFlags.push(flag);
        result.intents.push('security-only');
        result.primaryIntent = 'security-only';
        break;
      case '--skip-frontend':
        result.rawFlags.push(flag);
        result.filters.skipFrontend = true;
        break;
      case '--skip-backend':
        result.rawFlags.push(flag);
        result.filters.skipBackend = true;
        break;
      default:
        if (flag.startsWith('--just-') || flag.startsWith('--skip-')) {
          console.warn(`Unknown intent flag: ${arg}`);
        }
    }
  }
  
  // Detect conflicts
  if (result.intents.length > 1) {
    result.hasConflicts = true;
  }
  
  return result;
}

/**
 * Validate intent flags against combination rules
 * @param {Object} intents - Output from parseIntentFlags()
 * @param {string} command - Command context ('build', 'review', 'plan', etc.)
 * @returns {Object} Validation result with errors and suggestions
 * 
 * Returns:
 * {
 *   valid: false,
 *   errors: ['Cannot use --just-harden and --just-document together'],
 *   suggestions: ['Use --just-harden alone for security audit']
 * }
 */

function validateFlagCombination(intents, command) {
  const errors = [];
  const suggestions = [];
  
  // Load validation rules from intent-teams.yaml
  const rules = loadValidationRules();
  
  // Check mutual exclusion
  for (const rule of rules.mutual_exclusion) {
    const hasAllFlags = rule.flags.every(flag => 
      intents.intents.includes(flag) || 
      (flag === 'skip-frontend' && intents.filters.skipFrontend) ||
      (flag === 'skip-backend' && intents.filters.skipBackend)
    );
    
    if (hasAllFlags) {
      errors.push(rule.error);
      if (rule.flags.length === 2) {
        suggestions.push(`Use only --${rule.flags[0].replace('_', '-')} for this operation`);
      }
    }
  }
  
  // Check command context
  for (const rule of rules.requires_command) {
    if (intents.intents.includes(rule.flag)) {
      if (!rule.commands.includes(command)) {
        errors.push(`${rule.error} (used with ${command})`);
        if (rule.commands.length === 1) {
          suggestions.push(`Use /legion:${rule.commands[0]} instead`);
        }
      }
    }
  }
  
  // Check skip-frontend + skip-backend = nothing to build
  if (intents.filters.skipFrontend && intents.filters.skipBackend) {
    errors.push('Cannot skip both frontend and backend — nothing to build.');
    suggestions.push('Remove one skip flag to proceed');
  }
  
  // Check document + skip-frontend redundancy
  if (intents.intents.includes('document') && intents.filters.skipFrontend) {
    errors.push('--just-document already excludes implementation; --skip-frontend is redundant.');
    suggestions.push('Use --just-document alone');
  }
  
  return {
    valid: errors.length === 0,
    errors,
    suggestions
  };
}

❌ Intent Validation Failed
 
Errors:
1. Cannot use --just-harden and --just-document together. Choose one intent.
2. --just-harden is only valid for /legion:build (used with review)
 
Suggestions:
- Use only --just-harden for this operation
- Use /legion:build instead

/**
 * Load and cache intent-teams.yaml configuration
 * @returns {Object} Parsed configuration with intents and validation rules
 */
function loadIntentTeams() {
  // Preconditions (verified in order):
  // 1. Read .planning/config/intent-teams.yaml explicitly via fs.readFileSync.
  // 2. ENOENT → graceful degradation (empty config, routing disabled). Intent routing is optional.
  // 3. Other read error (EACCES, EISDIR, permission) → emit <escalation severity="blocker" type="infrastructure"> and degrade.
  // 4. YAML parse failure → emit <escalation severity="warning" type="infrastructure"> and degrade.
  // 5. Schema validation failure → log warning; do NOT block (partial config is acceptable).
  const configPath = '.planning/config/intent-teams.yaml';
  const emptyConfig = {
    intents: {},
    nl_patterns: {},
    command_routes: {},
    context_rules: {}
  };
  let content;
  try {
    content = fs.readFileSync(configPath, 'utf8');
  } catch (err) {
    if (err.code === 'ENOENT') {
      // Graceful degradation: no intent config → return empty structure
      console.warn(`intent-router: ${configPath} not found. Intent routing disabled.`);
      return emptyConfig;
    }
    // Unexpected I/O error — log and degrade
    console.warn(`intent-router: failed to read ${configPath}: ${err.message}. Intent routing disabled.`);
    return emptyConfig;
  }
  let parsed;
  try {
    parsed = parseYaml(content);
  } catch (err) {
    console.warn(`intent-router: failed to parse ${configPath}: ${err.message}. Intent routing disabled.`);
    return emptyConfig;
  }
  // Schema validation (if schema file present)
  const schemaPath = '.planning/config/intent-teams.schema.json';
  try {
    if (fs.existsSync(schemaPath)) {
      const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
      const validation = validateAgainstSchema(parsed, schema);
      if (!validation.valid) {
        console.warn(`intent-router: ${configPath} failed schema validation: ${validation.errors.join('; ')}. Using subset that passed.`);
        // Return what we have, preserving top-level keys; downstream code must handle gaps.
      }
    }
  } catch (err) {
    console.warn(`intent-router: schema validation error: ${err.message}. Continuing with unvalidated config.`);
  }
  // Ensure top-level keys exist even if YAML omitted them
  return {
    intents: parsed.intents || {},
    nl_patterns: parsed.nl_patterns || {},
    command_routes: parsed.command_routes || {},
    context_rules: parsed.context_rules || {}
  };
}

/**
 * Resolve team template for an intent
 * @param {string} intentName - Intent name (e.g., 'harden', 'document')
 * @returns {Object} Team configuration
 * 
 * Returns:
 * {
 *   intent: 'harden',
 *   description: 'Security audit with Testing + Security divisions',
 *   mode: 'ad_hoc',
 *   agents: {
 *     primary: ['testing-qa-verification-specialist', 'engineering-security-engineer'],
 *     secondary: ['testing-api-tester', 'testing-qa-verification-specialist']
 *   },
 *   domains: ['security', 'owasp', 'stride', 'vulnerability-assessment']
 * }
 */
function resolveTeamTemplate(intentName) {
  const config = loadIntentTeams();
  const intent = config.intents[intentName];
  
  if (!intent) {
    throw new Error(`Unknown intent: ${intentName}`);
  }
  
  return {
    intent: intentName,
    description: intent.description,
    mode: intent.mode,
    agents: intent.agents || { primary: [], secondary: [] },
    domains: intent.domains || [],
    filters: intent.filter || null
  };
}

/**
 * Get filter predicates for filter_plans or filter_review mode
 * @param {string} intentName - Intent name
 * @returns {Object} Filter configuration
 * 
 * Returns:
 * {
 *   includeTaskTypes: ['security-audit', 'vulnerability-scan'],
 *   excludeTaskTypes: ['feature-implementation'],
 *   excludeAgents: ['engineering-frontend-developer'],
 *   excludeFilePatterns: ['*.tsx', 'src/frontend/**']
 * }
 */
function resolveFilterCriteria(intentName) {
  const config = loadIntentTeams();
  const intent = config.intents[intentName];
  
  if (!intent || !intent.filter) {
    return null;
  }
  
  return {
    includeTaskTypes: intent.filter.include_task_types || [],
    excludeTaskTypes: intent.filter.exclude_task_types || [],
    excludeAgents: intent.filter.exclude_agents || [],
    excludeFilePatterns: intent.filter.exclude_file_patterns || []
  };
}