@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/session-manager.cjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+/**
+ * Session Manager — Core session state persistence module
+ *
+ * Manages session lifecycle: create, load, update, end, list
+ * Sessions stored in .planning/sessions/session-{timestamp}.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safePlanningWriteSync } = require('./planning-write.cjs');
+const { defaultLogger: logger } = require('./logger.cjs');
+
+class SessionManager {
+  /**
+   * Create a SessionManager instance
+   * @param {string} sessionsDir - Directory for session files (default: .planning/sessions)
+   */
+  constructor(sessionsDir = '.planning/sessions') {
+    this.sessionsDir = sessionsDir;
+    this._ensureDir();
+  }
+
+  /**
+   * Ensure sessions directory exists
+   * @private
+   */
+  _ensureDir() {
+    if (!fs.existsSync(this.sessionsDir)) {
+      fs.mkdirSync(this.sessionsDir, { recursive: true });
+      logger.info('Sessions directory created', { dir: this.sessionsDir });
+    }
+  }
+
+  /**
+   * Generate session ID from timestamp
+   * Format: session-YYYYMMDD-HHMMSS
+   * @private
+   * @returns {string} Session ID
+   */
+  _generateSessionId() {
+    const now = new Date();
+    const timestamp = now.toISOString()
+      .replace(/[:.]/g, '-')
+      .replace('T', '-')
+      .slice(0, -5); // Remove milliseconds and Z
+    return `session-${timestamp}`;
+  }
+
+  /**
+   * Deep merge source into target
+   * @private
+   * @param {Object} target - Target object
+   * @param {Object} source - Source object
+   * @returns {Object} Merged object
+   */
+  _deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+      if (source.hasOwnProperty(key)) {
+        if (source[key] instanceof Object && key !== null) {
+          result[key] = this._deepMerge(result[key] || {}, source[key]);
+        } else {
+          result[key] = source[key];
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Create a new session
+   * @param {Object} options - Session options
+   * @param {string} [options.model] - Model identifier
+   * @param {number} [options.phase] - Phase number
+   * @param {number} [options.plan] - Plan number
+   * @param {string} [options.objective] - Session objective
+   * @returns {string} Session ID
+   */
+  createSession(options = {}) {
+    const sessionId = this._generateSessionId();
+    const sessionPath = path.join(this.sessionsDir, `${sessionId}.json`);
+
+    const session = {
+      metadata: {
+        session_id: sessionId,
+        session_version: '1.0',
+        started_at: new Date().toISOString(),
+        ended_at: null,
+        model: options.model || null,
+        phase: options.phase || null,
+        plan: options.plan || null,
+        status: 'active',
+        session_chain: [],
+        token_usage: {
+          input: 0,
+          output: 0,
+          total: 0
+        }
+      },
+      context: {
+        transcript: '',
+        tasks: [],
+        decisions: [],
+        file_changes: [],
+        open_questions: [],
+        blockers: []
+      },
+      state: {
+        current_phase: options.phase || null,
+        current_plan: options.plan || null,
+        incomplete_tasks: [],
+        last_action: null,
+        next_recommended_action: options.objective || null
+      }
+    };
+
+    try {
+      safePlanningWriteSync(sessionPath, JSON.stringify(session, null, 2));
+      logger.info('Session created', { sessionId, sessionPath });
+      return sessionId;
+    } catch (err) {
+      logger.error('Failed to create session', { sessionId, error: err.message });
+      throw err;
+    }
+  }
+
+  /**
+   * Load a session by ID
+   * @param {string} sessionId - Session ID
+   * @returns {Object|null} Session object or null if not found
+   */
+  loadSession(sessionId) {
+    const sessionPath = path.join(this.sessionsDir, `${sessionId}.json`);
+
+    if (!fs.existsSync(sessionPath)) {
+      logger.error('Session not found', { sessionId, sessionPath });
+      return null;
+    }
+
+    try {
+      const content = fs.readFileSync(sessionPath, 'utf-8');
+      const session = JSON.parse(content);
+      logger.info('Session loaded', { sessionId });
+      return session;
+    } catch (err) {
+      logger.error('Failed to load session', { sessionId, error: err.message });
+      return null;
+    }
+  }
+
+  /**
+   * Get the most recent session
+   * @returns {Object|null} Last session or null if none exist
+   */
+  getLastSession() {
+    const sessionFiles = this._getSessionFiles();
+
+    if (sessionFiles.length === 0) {
+      logger.info('No sessions found');
+      return null;
+    }
+
+    // Files are sorted, newest first
+    const lastFile = sessionFiles[0];
+    const sessionId = lastFile.replace('.json', '');
+    return this.loadSession(sessionId);
+  }
+
+  /**
+   * Update a session with new data
+   * @param {string} sessionId - Session ID
+   * @param {Object} updates - Updates to merge into session
+   * @returns {boolean} True on success, false if session not found
+   */
+  updateSession(sessionId, updates) {
+    const session = this.loadSession(sessionId);
+    if (!session) {
+      return false;
+    }
+
+    const updatedSession = this._deepMerge(session, updates);
+    const sessionPath = path.join(this.sessionsDir, `${sessionId}.json`);
+
+    try {
+      safePlanningWriteSync(sessionPath, JSON.stringify(updatedSession, null, 2));
+      logger.info('Session updated', { sessionId });
+      return true;
+    } catch (err) {
+      logger.error('Failed to update session', { sessionId, error: err.message });
+      return false;
+    }
+  }
+
+  /**
+   * End a session
+   * @param {string} sessionId - Session ID
+   * @param {Object} finalState - Final state information
+   * @param {string} [finalState.status] - Final status (default: 'completed')
+   * @param {Array} [finalState.incomplete_tasks] - Incomplete tasks
+   * @param {string} [finalState.next_recommended_action] - Next recommended action
+   * @returns {boolean} True on success, false if session not found
+   */
+  endSession(sessionId, finalState = {}) {
+    const session = this.loadSession(sessionId);
+    if (!session) {
+      return false;
+    }
+
+    const updates = {
+      metadata: {
+        ended_at: new Date().toISOString(),
+        status: finalState.status || 'completed'
+      },
+      state: {}
+    };
+
+    if (finalState.incomplete_tasks) {
+      updates.state.incomplete_tasks = finalState.incomplete_tasks;
+    }
+
+    if (finalState.next_recommended_action) {
+      updates.state.next_recommended_action = finalState.next_recommended_action;
+    }
+
+    return this.updateSession(sessionId, updates);
+  }
+
+  /**
+   * List all sessions
+   * @returns {Array} Array of session metadata sorted by date (newest first)
+   */
+  listSessions() {
+    const sessionFiles = this._getSessionFiles();
+    const sessions = [];
+
+    for (const file of sessionFiles) {
+      const sessionId = file.replace('.json', '');
+      const session = this.loadSession(sessionId);
+      if (session) {
+        sessions.push({
+          session_id: session.metadata.session_id,
+          started_at: session.metadata.started_at,
+          ended_at: session.metadata.ended_at,
+          model: session.metadata.model,
+          phase: session.metadata.phase,
+          plan: session.metadata.plan,
+          status: session.metadata.status
+        });
+      }
+    }
+
+    return sessions;
+  }
+
+  /**
+   * Get session files sorted by name (newest first)
+   * @private
+   * @returns {Array} Array of filenames
+   */
+  _getSessionFiles() {
+    if (!fs.existsSync(this.sessionsDir)) {
+      return [];
+    }
+
+    try {
+      const files = fs.readdirSync(this.sessionsDir)
+        .filter(file => /^session-.*\.json$/.test(file))
+        .sort()
+        .reverse();
+      return files;
+    } catch (err) {
+      logger.error('Failed to read sessions directory', { error: err.message });
+      return [];
+    }
+  }
+}
+
+module.exports = SessionManager;

package/bin/lib/skill-context.cjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+/**
+ * Skill Context — Context schema validation for skill matcher
+ *
+ * Validates and normalizes matcher context:
+ * - stack: object with language, framework, version
+ * - scope: enum [new-feature, bugfix, refactor, migration, maintenance]
+ * - projectType: string (optional)
+ * - mode: enum [greenfield, existing, rapid-mvp, scale-up, maintenance]
+ * - constraints: object with deadline, teamSize, compliance, legacySystems
+ * - taskDescription: string (for keyword matching)
+ * - codebaseFiles: array of strings (for file pattern matching)
+ * - executedCommands: array of strings (for command matching)
+ *
+ * Usage:
+ *   const { validateContext, CONTEXT_SCHEMA } = require('./skill-context.cjs');
+ *   const { valid, errors, normalizedContext } = validateContext(context);
+ */
+
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+/**
+ * Context schema definition
+ */
+const CONTEXT_SCHEMA = {
+  stack: {
+    type: 'object',
+    optional: true,
+    properties: {
+      language: { type: 'string', optional: false },
+      framework: { type: 'string', optional: true },
+      version: { type: 'string', optional: true }
+    }
+  },
+  scope: {
+    type: 'enum',
+    values: ['new-feature', 'bugfix', 'refactor', 'migration', 'maintenance'],
+    optional: true
+  },
+  projectType: {
+    type: 'string',
+    optional: true
+  },
+  mode: {
+    type: 'enum',
+    values: ['greenfield', 'existing', 'rapid-mvp', 'scale-up', 'maintenance'],
+    optional: true,
+    normalize: (value) => {
+      const mappings = {
+        'mvp': 'rapid-mvp',
+        'green-field': 'greenfield',
+        'brownfield': 'existing',
+        'scale': 'scale-up',
+        'maint': 'maintenance'
+      };
+      return mappings[value] || value;
+    }
+  },
+  constraints: {
+    type: 'object',
+    optional: true,
+    properties: {
+      deadline: { type: 'string', optional: true },
+      teamSize: { type: 'number', optional: true },
+      compliance: { type: 'array', optional: true },
+      legacySystems: { type: 'array', optional: true }
+    }
+  },
+  taskDescription: { type: 'string', optional: true },
+  codebaseFiles: { type: 'array', optional: true },
+  executedCommands: { type: 'array', optional: true }
+};
+
+/**
+ * Validate and normalize context object
+ * @param {Object} context - Context object to validate
+ * @returns {Object} Validation result: { valid, errors, normalizedContext }
+ */
+function validateContext(context) {
+  const errors = [];
+  const normalized = { ...context };
+
+  if (!context || typeof context !== 'object') {
+    return {
+      valid: false,
+      errors: ['Context must be an object'],
+      normalizedContext: null
+    };
+  }
+
+  // Validate and normalize mode
+  if (context.mode) {
+    const modeSchema = CONTEXT_SCHEMA.mode;
+    if (!modeSchema.values.includes(context.mode)) {
+      const normalizedMode = modeSchema.normalize?.(context.mode);
+      if (normalizedMode && modeSchema.values.includes(normalizedMode)) {
+        normalized.mode = normalizedMode;
+      } else {
+        errors.push(`Invalid mode: ${context.mode}. Valid: ${modeSchema.values.join(', ')}`);
+      }
+    }
+  }
+
+  // Validate scope
+  if (context.scope) {
+    const scopeSchema = CONTEXT_SCHEMA.scope;
+    if (!scopeSchema.values.includes(context.scope)) {
+      errors.push(`Invalid scope: ${context.scope}. Valid: ${scopeSchema.values.join(', ')}`);
+    }
+  }
+
+  // Validate stack structure
+  if (context.stack) {
+    if (!context.stack.language && !context.stack.framework) {
+      errors.push('Stack must have at least language or framework');
+    }
+  }
+
+  // Validate constraints structure
+  if (context.constraints) {
+    if (context.constraints.teamSize && typeof context.constraints.teamSize !== 'number') {
+      errors.push('teamSize must be a number');
+    }
+    if (context.constraints.compliance && !Array.isArray(context.constraints.compliance)) {
+      errors.push('compliance must be an array');
+    }
+  }
+
+  if (errors.length > 0) {
+    logger.warn('Context validation failed', {
+      errorCount: errors.length,
+      errors
+    });
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    normalizedContext: errors.length === 0 ? normalized : null
+  };
+}
+
+module.exports = {
+  validateContext,
+  CONTEXT_SCHEMA
+};

package/bin/lib/skill-matcher.cjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+
+/**
+ * Skill Matcher — Rule-based skill matching algorithm
+ *
+ * Matches context to skills using 5-rule matching:
+ * - Rule 1: Stack skills (mandatory, priority 100)
+ * - Rule 2: Domain skills (if project type detected, priority 90)
+ * - Rule 3: Mode skills (ceremony level, priority 85)
+ * - Rule 4: Constraint-based skills (deadline, team, compliance, priority 80)
+ * - Rule 5: Universal skills (always activate, priority 50)
+ *
+ * Enforces 3-7 skill limit per task (EDGE-05 compliance)
+ *
+ * Usage:
+ *   const { SkillMatcher, SKILL_LIMITS } = require('./skill-matcher.cjs');
+ *   const matcher = new SkillMatcher(registry);
+ *   const result = matcher.match(context);
+ */
+
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+/**
+ * Skill activation limits (EDGE-05 compliance)
+ */
+const SKILL_LIMITS = {
+  MIN_ACTIVE: 3,
+  MAX_ACTIVE: 7,
+  CRITICAL_TASK_MAX: 5,  // For security-sensitive tasks
+  MVP_MODE_MAX: 4,       // Rapid MVP mode reduces complexity
+};
+
+/**
+ * Skill Matcher class for matching context to skills
+ */
+class SkillMatcher {
+  /**
+   * Create a SkillMatcher instance
+   * @param {Object} registry - SkillRegistry instance
+   * @param {Object} options - Matcher options
+   */
+  constructor(registry, options = {}) {
+    this.registry = registry;
+    this.logger = options.logger || logger;
+    this.rules = this.loadMatchingRules();
+  }
+
+  /**
+   * Match context to skills
+   * @param {Object} context - Matching context
+   * @returns {Object} Match result: { activatedSkills, rationale, conflicts, metadata }
+   */
+  match(context) {
+    const candidates = [];
+
+    // Rule 1: Stack skills (mandatory)
+    if (context.stack?.framework || context.stack?.language) {
+      const stackSkills = this.findByStack(context.stack);
+      stackSkills.forEach(skill => {
+        candidates.push({ skill, priority: 100, rule: 'stack' });
+      });
+    }
+
+    // Rule 2: Domain skills (if project type detected)
+    if (context.projectType) {
+      const domainSkills = this.findByDomain(context.projectType);
+      domainSkills.forEach(skill => {
+        candidates.push({ skill, priority: 90, rule: 'domain' });
+      });
+    }
+
+    // Rule 3: Mode skills (ceremony level)
+    if (context.mode) {
+      const modeSkills = this.findByMode(context.mode);
+      modeSkills.forEach(skill => {
+        candidates.push({ skill, priority: 85, rule: 'mode' });
+      });
+    }
+
+    // Rule 4: Constraint-based skills
+    const constraintSkills = this.findByConstraints(context.constraints);
+    constraintSkills.forEach(skill => {
+      candidates.push({ skill, priority: 80, rule: 'constraint' });
+    });
+
+    // Rule 5: Universal skills (always activate)
+    const universalSkills = this.registry.findByTag('universal');
+    universalSkills.forEach(skill => {
+      candidates.push({ skill, priority: 50, rule: 'universal' });
+    });
+
+    // Sort by priority and apply limits
+    const sorted = candidates.sort((a, b) => b.priority - a.priority);
+    const limited = this.enforceSkillLimits(sorted, context);
+    const activatedSkills = limited.map(c => c.skill);
+
+    return {
+      activatedSkills,
+      rationale: this.generateRationale(activatedSkills, context),
+      conflicts: [], // Reserved for Phase 36 SKILL-07
+      metadata: {
+        totalCandidates: candidates.length,
+        rulesApplied: [...new Set(candidates.map(c => c.rule))],
+        limitEnforced: candidates.length > limited.length
+      }
+    };
+  }
+
+  /**
+   * Enforce skill activation limits
+   * @param {Object[]} candidates - Sorted candidate skills
+   * @param {Object} context - Matching context
+   * @returns {Object[]} Limited candidate array
+   * @private
+   */
+  enforceSkillLimits(candidates, context) {
+    const maxSkills = context.mode === 'rapid-mvp'
+      ? SKILL_LIMITS.MVP_MODE_MAX
+      : SKILL_LIMITS.MAX_ACTIVE;
+
+    if (candidates.length > maxSkills) {
+      this.logger.warn('Skill limit exceeded', {
+        candidateCount: candidates.length,
+        maxSkills,
+        mode: context.mode,
+        skills: candidates.slice(0, maxSkills).map(c => c.skill.name)
+      });
+    }
+
+    return candidates.slice(0, maxSkills);
+  }
+
+  /**
+   * Generate rationale for skill activation
+   * @param {Object[]} skills - Activated skills
+   * @param {Object} context - Matching context
+   * @returns {string} Rationale string
+   * @private
+   */
+  generateRationale(skills, context) {
+    const categories = {};
+    skills.forEach(skill => {
+      const cat = skill.category || 'other';
+      if (!categories[cat]) categories[cat] = [];
+      categories[cat].push(skill.name);
+    });
+
+    const parts = [];
+    if (categories.stack) parts.push(`stack: ${categories.stack.join(', ')}`);
+    if (categories.domain) parts.push(`domain: ${categories.domain.join(', ')}`);
+    if (categories.mode) parts.push(`mode: ${categories.mode.join(', ')}`);
+    if (categories.constraint) parts.push(`constraint: ${categories.constraint.join(', ')}`);
+    if (categories.universal) parts.push(`universal: ${categories.universal.join(', ')}`);
+
+    return `Activated ${skills.length} skills based on ${context.mode || 'default'} mode: ${parts.join('; ')}`;
+  }
+
+  /**
+   * Find skills by stack
+   * @param {Object|string} stack - Stack identifier
+   * @returns {Object[]} Matching skills
+   */
+  findByStack(stack) {
+    return this.registry.findByStack(stack);
+  }
+
+  /**
+   * Find skills by domain/project type
+   * @param {string} projectType - Project type
+   * @returns {Object[]} Matching skills
+   */
+  findByDomain(projectType) {
+    return this.registry.findByTag(projectType);
+  }
+
+  /**
+   * Find skills by mode
+   * @param {string} mode - Mode identifier
+   * @returns {Object[]} Matching skills
+   */
+  findByMode(mode) {
+    return this.registry.findByTag(mode);
+  }
+
+  /**
+   * Find skills by constraints
+   * @param {Object} constraints - Constraint object
+   * @returns {Object[]} Matching skills
+   * @private
+   */
+  findByConstraints(constraints) {
+    const skills = [];
+    if (!constraints) return skills;
+
+    // Deadline-based skills
+    if (constraints.deadline === '2-weeks' || constraints.deadline === '1-week') {
+      const rapid = this.registry.get('rapid_delivery_skill_v1');
+      if (rapid) skills.push(rapid);
+    }
+
+    // Compliance-based skills
+    if (constraints.compliance?.includes('hipaa')) {
+      const hipaa = this.registry.get('hipaa_compliance_skill_v1');
+      if (hipaa) skills.push(hipaa);
+    }
+
+    // Team size skills
+    if (constraints.teamSize === 1) {
+      const solo = this.registry.get('solo_developer_skill_v1');
+      if (solo) skills.push(solo);
+    }
+
+    return skills;
+  }
+
+  /**
+   * Load matching rules configuration
+   * @returns {Object} Rules configuration
+   * @private
+   */
+  loadMatchingRules() {
+    return {
+      stack: { priority: 100, required: true },
+      domain: { priority: 90, required: false },
+      mode: { priority: 85, required: false },
+      constraint: { priority: 80, required: false },
+      universal: { priority: 50, required: true }
+    };
+  }
+}
+
+module.exports = {
+  SkillMatcher,
+  SKILL_LIMITS
+};