kenaz 0.3.17 → 0.3.19

package/core/.specialist/tools/rule-engine.js

@@ -1,621 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * rule-engine.js — Self-Evolution Rule Runtime
- *
- * Loads ansuz_rules.yaml, tracks session observations for proposed rules,
- * auto-promotes proposed → active after sessions_required threshold,
- * and validates immutable rules are unchanged.
- *
- * CLI:
- *   node rule-engine.js load                                # Load and display all rules
- *   node rule-engine.js track <ruleId>                      # Increment sessions_observed for a proposed rule
- *   node rule-engine.js promote                             # Auto-promote eligible proposed rules
- *   node rule-engine.js validate                            # Validate immutable rules unchanged
- *   node rule-engine.js record-apply <ruleId> <sessionId>   # Record rule application in session
- *   node rule-engine.js record-outcome <ruleId> <sessionId> <good|bad>  # Record outcome
- *   node rule-engine.js validate-hash                       # Validate immutable rules via SHA256
- *   node rule-engine.js mark-review <ruleId>                # Mark rule for Amelia review
- *
- * Module:
- *   const engine = require('.specialist/tools/rule-engine');
- *   engine.loadRules()
- *   engine.trackSession('R-200')
- *   engine.promoteRules()
- *   engine.validateImmutable(baselineRules)
- *   engine.recordApplication('R-001', 'session-xyz')
- *   engine.recordOutcome('R-001', 'session-xyz', 'good')
- *   engine.validateImmutableHash()
- *   engine.markPendingReview('R-200')
- */
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-// ═══════════════════════════════════════
-//  YAML loading (project-standard pattern)
-// ═══════════════════════════════════════
-
-const yaml = (() => {
-  try { return require('js-yaml'); } catch {
-    const candidates = [
-      path.resolve(__dirname, '../../.vendor/js-yaml.cjs'),
-      path.resolve(__dirname, '.vendor/js-yaml.cjs'),
-    ];
-    if (process.env.KENAZ_SOURCE_DIR) {
-      candidates.unshift(path.join(process.env.KENAZ_SOURCE_DIR, '.vendor', 'js-yaml.cjs'));
-    }
-    for (const c of candidates) {
-      try { return require(c); } catch { /* continue */ }
-    }
-    throw new Error('js-yaml not found. Install it or place .vendor/js-yaml.cjs');
-  }
-})();
-
-// ═══════════════════════════════════════
-//  Path resolution
-// ═══════════════════════════════════════
-
-function findProjectRoot() {
-  let dir = __dirname;
-  while (dir !== path.dirname(dir)) {
-    const parent = path.dirname(dir);
-    if (fs.existsSync(path.join(parent, '.specialist'))) return parent;
-    dir = parent;
-  }
-  return process.cwd();
-}
-
-const BASE_DIR = findProjectRoot();
-
-function getRulesPath(projectPath) {
-  const root = projectPath || BASE_DIR;
-  // Sub-projects store rules in .kenaz/specialist/
-  const kenazPath = path.join(root, '.kenaz', 'specialist', 'ansuz_rules.yaml');
-  if (fs.existsSync(kenazPath)) return kenazPath;
-  // Core project
-  const corePath = path.join(root, '.specialist', 'Ansuz', 'ansuz_rules.yaml');
-  if (fs.existsSync(corePath)) return corePath;
-  return kenazPath; // default to .kenaz path
-}
-
-// ═══════════════════════════════════════
-//  Ephemeral stats sidecar
-//  These fields mutate every session (autoTrackSession increments
-//  sessions_observed for all rules), so tracking them inside the
-//  git-tracked ansuz_rules.yaml causes a merge conflict on every pull.
-//  They live in an ignored sibling JSON instead; the YAML keeps only
-//  rule definitions + meaningful shared state (status/version/hash).
-// ═══════════════════════════════════════
-
-const STAT_FIELDS = ['sessions_observed', 'sessions_applied', 'good_outcomes', 'bad_outcomes'];
-
-function getStatsPath(rulesPath) {
-  return rulesPath.replace(/ansuz_rules\.yaml$/, 'ansuz_rules_stats.json');
-}
-
-function loadStats(statsPath) {
-  try {
-    if (fs.existsSync(statsPath)) {
-      return JSON.parse(fs.readFileSync(statsPath, 'utf8')) || {};
-    }
-  } catch { /* corrupt sidecar → start fresh, definitions are the source of truth */ }
-  return {};
-}
-
-function saveStats(statsPath, rules) {
-  const stats = {};
-  for (const r of rules) {
-    const entry = {};
-    for (const f of STAT_FIELDS) {
-      if (r[f] !== undefined) entry[f] = r[f];
-    }
-    if (Object.keys(entry).length > 0) stats[r.id] = entry;
-  }
-  fs.writeFileSync(statsPath, JSON.stringify(stats, null, 2) + '\n', 'utf8');
-}
-
-/**
- * Serialize rules to YAML with ephemeral stat fields stripped out.
- * Deterministic given the definitions, so counter increments never churn the file.
- */
-function dumpRulesYaml(_raw) {
-  const clone = JSON.parse(JSON.stringify(_raw));
-  if (Array.isArray(clone.rules)) {
-    for (const r of clone.rules) {
-      for (const f of STAT_FIELDS) delete r[f];
-    }
-  }
-  return yaml.dump(clone, { lineWidth: -1, noRefs: true, quotingType: '"' });
-}
-
-/** Persist both the (stat-stripped) YAML definitions and the ignored stats sidecar. */
-function persist(filePath, statsPath, _raw, rules) {
-  fs.writeFileSync(filePath, dumpRulesYaml(_raw), 'utf8');
-  saveStats(statsPath, rules);
-}
-
-// ═══════════════════════════════════════
-//  Core functions
-// ═══════════════════════════════════════
-
-/**
- * Load all rules from ansuz_rules.yaml.
- * @param {string} [projectPath] - Optional project root override
- * @returns {{ version: number, rules: object[], filePath: string }}
- */
-function loadRules(projectPath) {
-  const filePath = getRulesPath(projectPath);
-  if (!fs.existsSync(filePath)) {
-    throw new Error(`ansuz_rules.yaml not found at: ${filePath}`);
-  }
-  const content = fs.readFileSync(filePath, 'utf8');
-  const data = yaml.load(content);
-  if (!data || !Array.isArray(data.rules)) {
-    throw new Error('Invalid ansuz_rules.yaml: missing rules array');
-  }
-
-  // Merge ephemeral stats from the ignored sidecar over any legacy values
-  // still present in the YAML (backward-compat: pre-migration YAMLs carry
-  // sessions_observed inline; the sidecar wins once it exists).
-  const statsPath = getStatsPath(filePath);
-  const stats = loadStats(statsPath);
-  for (const rule of data.rules) {
-    const s = stats[rule.id];
-    if (!s) continue;
-    for (const f of STAT_FIELDS) {
-      if (s[f] !== undefined) rule[f] = s[f];
-    }
-  }
-
-  return {
-    version: data.version || 1,
-    rules: data.rules,
-    filePath,
-    statsPath,
-    _raw: data,
-  };
-}
-
-/**
- * Increment sessions_observed for a proposed rule and write back.
- * @param {string} ruleId - Rule ID (e.g. 'R-200')
- * @param {string} [projectPath] - Optional project root override
- * @returns {{ ruleId: string, sessions_observed: number, sessions_required: number }}
- */
-function trackSession(ruleId, projectPath) {
-  const { rules, filePath, statsPath, _raw } = loadRules(projectPath);
-
-  const rule = rules.find(r => r.id === ruleId);
-  if (!rule) {
-    throw new Error(`Rule not found: ${ruleId}`);
-  }
-  if (rule.status !== 'proposed') {
-    throw new Error(`Rule ${ruleId} is '${rule.status}', not 'proposed'. Only proposed rules can be tracked.`);
-  }
-
-  // Increment
-  rule.sessions_observed = (rule.sessions_observed || 0) + 1;
-
-  // Write back
-  persist(filePath, statsPath, _raw, rules);
-
-  return {
-    ruleId: rule.id,
-    sessions_observed: rule.sessions_observed,
-    sessions_required: rule.sessions_required || 3,
-  };
-}
-
-/**
- * Auto-promote proposed rules where sessions_observed >= sessions_required.
- * @param {string} [projectPath] - Optional project root override
- * @returns {{ promoted: string[], unchanged: string[] }}
- */
-function promoteRules(projectPath) {
-  const { rules, filePath, statsPath, _raw } = loadRules(projectPath);
-
-  const promoted = [];
-  const unchanged = [];
-
-  for (const rule of rules) {
-    if (rule.status !== 'proposed') continue;
-
-    const observed = rule.sessions_observed || 0;
-    const required = rule.sessions_required || 3;
-
-    if (observed >= required) {
-      // Outcome gate: refuse promotion if outcome_rate < 30%
-      const applied = Array.isArray(rule.sessions_applied) ? rule.sessions_applied.length : (rule.sessions_applied || 0);
-      const good = rule.good_outcomes || 0;
-      const outcomeRate = applied > 0 ? good / applied : 1.0; // no data = benefit of doubt
-
-      if (outcomeRate < 0.3) {
-        rule.status = 'deprecated';
-        rule.deprecated_reason = `Auto-deprecated: outcome_rate ${(outcomeRate * 100).toFixed(0)}% < 30% threshold after ${observed} sessions`;
-        promoted.push(`${rule.id} (DEPRECATED — outcome_rate ${(outcomeRate * 100).toFixed(0)}%)`);
-      } else {
-        rule.status = 'active';
-        promoted.push(rule.id);
-      }
-    } else {
-      unchanged.push(rule.id);
-    }
-  }
-
-  if (promoted.length > 0) {
-    // Bump file version
-    _raw.version = (_raw.version || 1) + 1;
-    _raw.timestamp = new Date().toISOString();
-
-    persist(filePath, statsPath, _raw, rules);
-  }
-
-  return { promoted, unchanged };
-}
-
-/**
- * Validate that immutable rules have not been modified.
- * Compares current immutable rules against a baseline snapshot.
- * @param {object[]} baselineRules - Array of immutable rules from a known-good state
- * @param {string} [projectPath] - Optional project root override
- * @returns {{ valid: boolean, violations: string[] }}
- */
-function validateImmutable(baselineRules, projectPath) {
-  const { rules } = loadRules(projectPath);
-  const violations = [];
-
-  const currentImmutable = rules.filter(r => r.status === 'immutable');
-  const baselineMap = new Map(baselineRules.map(r => [r.id, r]));
-
-  for (const rule of currentImmutable) {
-    const baseline = baselineMap.get(rule.id);
-    if (!baseline) continue; // new immutable rule, no baseline to compare
-
-    if (rule.rule !== baseline.rule) {
-      violations.push(`${rule.id}: rule text changed from "${baseline.rule}" to "${rule.rule}"`);
-    }
-    if (rule.version !== baseline.version) {
-      violations.push(`${rule.id}: version changed from ${baseline.version} to ${rule.version}`);
-    }
-  }
-
-  // Check for removed immutable rules
-  for (const [id, baseline] of baselineMap) {
-    if (!currentImmutable.find(r => r.id === id)) {
-      violations.push(`${id}: immutable rule removed`);
-    }
-  }
-
-  return { valid: violations.length === 0, violations };
-}
-
-// ═══════════════════════════════════════
-//  Performance metrics & review
-// ═══════════════════════════════════════
-
-/**
- * Record that a rule was applied in a session.
- * Appends sessionId to the rule's sessions_applied array.
- * @param {string} ruleId - Rule ID (e.g. 'R-001')
- * @param {string} sessionId - Session identifier
- * @param {string} [projectPath] - Optional project root override
- * @returns {{ ruleId: string, sessions_applied: string[] }}
- */
-function recordApplication(ruleId, sessionId, projectPath) {
-  const { rules, filePath, statsPath, _raw } = loadRules(projectPath);
-
-  const rule = rules.find(r => r.id === ruleId);
-  if (!rule) {
-    throw new Error(`Rule not found: ${ruleId}`);
-  }
-
-  if (!Array.isArray(rule.sessions_applied)) {
-    rule.sessions_applied = [];
-  }
-  if (!rule.sessions_applied.includes(sessionId)) {
-    rule.sessions_applied.push(sessionId);
-  }
-
-  persist(filePath, statsPath, _raw, rules);
-
-  return { ruleId: rule.id, sessions_applied: rule.sessions_applied };
-}
-
-/**
- * Record an outcome (good/bad) for a rule in a session.
- * Increments good_outcomes or bad_outcomes counters.
- * @param {string} ruleId - Rule ID
- * @param {string} sessionId - Session identifier
- * @param {'good'|'bad'} outcome - Outcome type
- * @param {string} [projectPath] - Optional project root override
- * @returns {{ ruleId: string, good_outcomes: number, bad_outcomes: number }}
- */
-function recordOutcome(ruleId, sessionId, outcome, projectPath) {
-  if (outcome !== 'good' && outcome !== 'bad') {
-    throw new Error(`Invalid outcome: '${outcome}'. Must be 'good' or 'bad'.`);
-  }
-
-  const { rules, filePath, statsPath, _raw } = loadRules(projectPath);
-
-  const rule = rules.find(r => r.id === ruleId);
-  if (!rule) {
-    throw new Error(`Rule not found: ${ruleId}`);
-  }
-
-  // Ensure sessions_applied includes this session
-  if (!Array.isArray(rule.sessions_applied)) {
-    rule.sessions_applied = [];
-  }
-  if (!rule.sessions_applied.includes(sessionId)) {
-    rule.sessions_applied.push(sessionId);
-  }
-
-  // Increment outcome counter
-  if (outcome === 'good') {
-    rule.good_outcomes = (rule.good_outcomes || 0) + 1;
-  } else {
-    rule.bad_outcomes = (rule.bad_outcomes || 0) + 1;
-  }
-
-  persist(filePath, statsPath, _raw, rules);
-
-  return {
-    ruleId: rule.id,
-    good_outcomes: rule.good_outcomes || 0,
-    bad_outcomes: rule.bad_outcomes || 0,
-  };
-}
-
-/**
- * Compute SHA256 hash of a rule's content (rule text + version).
- * @param {object} rule - Rule object
- * @returns {string} hex hash
- */
-function computeRuleHash(rule) {
-  const content = `${rule.id}:${rule.rule}:${rule.version || 1}`;
-  return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
-}
-
-/**
- * Validate immutable rules by SHA256 hash comparison.
- * Each immutable rule should have an immutable_hash field. If missing, the hash
- * is computed and stored (first-run seeding). If present, the current hash is
- * compared against the stored hash to detect unauthorized changes.
- * @param {string} [projectPath] - Optional project root override
- * @returns {{ valid: boolean, violations: string[], seeded: string[] }}
- */
-function validateImmutableHash(projectPath) {
-  const { rules, filePath, statsPath, _raw } = loadRules(projectPath);
-  const violations = [];
-  const seeded = [];
-
-  const immutableRules = rules.filter(r => r.status === 'immutable');
-  let needsWrite = false;
-
-  for (const rule of immutableRules) {
-    const currentHash = computeRuleHash(rule);
-
-    if (!rule.immutable_hash) {
-      // First run: seed the hash
-      rule.immutable_hash = currentHash;
-      seeded.push(rule.id);
-      needsWrite = true;
-    } else if (rule.immutable_hash !== currentHash) {
-      violations.push(`${rule.id}: content drift detected (stored hash: ${rule.immutable_hash.slice(0, 12)}..., current: ${currentHash.slice(0, 12)}...)`);
-    }
-  }
-
-  if (needsWrite) {
-    persist(filePath, statsPath, _raw, rules);
-  }
-
-  return { valid: violations.length === 0, violations, seeded };
-}
-
-/**
- * Auto-increment sessions_observed for ALL non-immutable, non-deprecated rules.
- * Called at Phase 0 exit so every session counts toward observation thresholds.
- * @param {string} [projectPath] - Optional project root override
- * @returns {{ tracked: string[], skipped: string[], total: number }}
- */
-function autoTrackSession(projectPath) {
-  const { rules, filePath, statsPath, _raw } = loadRules(projectPath);
-
-  const tracked = [];
-  const skipped = [];
-
-  for (const rule of rules) {
-    if (rule.status === 'immutable' || rule.status === 'deprecated') {
-      skipped.push(rule.id);
-      continue;
-    }
-    rule.sessions_observed = (rule.sessions_observed || 0) + 1;
-    tracked.push(rule.id);
-  }
-
-  if (tracked.length > 0) {
-    persist(filePath, statsPath, _raw, rules);
-  }
-
-  return { tracked, skipped, total: tracked.length };
-}
-
-/**
- * Migrate any inline stat fields out of the YAML into the ignored sidecar.
- * Idempotent: safe to run repeatedly. On first run it strips sessions_observed
- * (etc.) from the tracked YAML and seeds ansuz_rules_stats.json.
- * @param {string} [projectPath] - Optional project root override
- * @returns {{ filePath: string, statsPath: string, ruleCount: number }}
- */
-function migrateStats(projectPath) {
-  const { rules, filePath, statsPath, _raw } = loadRules(projectPath);
-  persist(filePath, statsPath, _raw, rules);
-  return { filePath, statsPath, ruleCount: rules.length };
-}
-
-/**
- * Mark a rule as pending Amelia review.
- * Sets pending_amelia_review = true and pending_review_since timestamp.
- * @param {string} ruleId - Rule ID
- * @param {string} [projectPath] - Optional project root override
- * @returns {{ ruleId: string, pending_amelia_review: boolean, pending_review_since: string }}
- */
-function markPendingReview(ruleId, projectPath) {
-  const { rules, filePath, statsPath, _raw } = loadRules(projectPath);
-
-  const rule = rules.find(r => r.id === ruleId);
-  if (!rule) {
-    throw new Error(`Rule not found: ${ruleId}`);
-  }
-
-  rule.pending_amelia_review = true;
-  rule.pending_review_since = new Date().toISOString();
-
-  persist(filePath, statsPath, _raw, rules);
-
-  return {
-    ruleId: rule.id,
-    pending_amelia_review: rule.pending_amelia_review,
-    pending_review_since: rule.pending_review_since,
-  };
-}
-
-// ═══════════════════════════════════════
-//  Module exports
-// ═══════════════════════════════════════
-
-module.exports = {
-  loadRules,
-  trackSession,
-  autoTrackSession,
-  promoteRules,
-  validateImmutable,
-  recordApplication,
-  recordOutcome,
-  validateImmutableHash,
-  markPendingReview,
-  migrateStats,
-  computeRuleHash,
-};
-
-// ═══════════════════════════════════════
-//  CLI
-// ═══════════════════════════════════════
-
-if (require.main === module) {
-  const args = process.argv.slice(2);
-  const command = args[0];
-
-  try {
-    switch (command) {
-      case 'load': {
-        const { version, rules } = loadRules();
-        console.log(`ansuz_rules v${version}: ${rules.length} rules`);
-        const byStatus = {};
-        for (const r of rules) {
-          byStatus[r.status] = (byStatus[r.status] || 0) + 1;
-        }
-        console.log('Status breakdown:', JSON.stringify(byStatus));
-        for (const r of rules) {
-          const extra = r.status === 'proposed'
-            ? ` [${r.sessions_observed || 0}/${r.sessions_required || 3} sessions]`
-            : '';
-          console.log(`  ${r.id} [${r.status}]${extra} ${r.rule}`);
-        }
-        break;
-      }
-      case 'track': {
-        const ruleId = args[1];
-        if (!ruleId) { console.error('Usage: rule-engine.js track <ruleId>'); process.exit(1); }
-        const result = trackSession(ruleId);
-        console.log(`Tracked ${result.ruleId}: ${result.sessions_observed}/${result.sessions_required} sessions`);
-        break;
-      }
-      case 'promote': {
-        const result = promoteRules();
-        if (result.promoted.length > 0) {
-          console.log(`Promoted: ${result.promoted.join(', ')}`);
-        } else {
-          console.log('No rules ready for promotion.');
-        }
-        if (result.unchanged.length > 0) {
-          console.log(`Still pending: ${result.unchanged.join(', ')}`);
-        }
-        break;
-      }
-      case 'validate': {
-        const { rules } = loadRules();
-        const immutableBaseline = rules.filter(r => r.status === 'immutable');
-        const result = validateImmutable(immutableBaseline);
-        if (result.valid) {
-          console.log('All immutable rules intact.');
-        } else {
-          console.error('VIOLATIONS:');
-          result.violations.forEach(v => console.error(`  - ${v}`));
-          process.exit(1);
-        }
-        break;
-      }
-      case 'record-apply': {
-        const ruleId = args[1];
-        const sessionId = args[2];
-        if (!ruleId || !sessionId) { console.error('Usage: rule-engine.js record-apply <ruleId> <sessionId>'); process.exit(1); }
-        const result = recordApplication(ruleId, sessionId);
-        console.log(`Recorded application of ${result.ruleId} in session. Total sessions: ${result.sessions_applied.length}`);
-        break;
-      }
-      case 'record-outcome': {
-        const ruleId = args[1];
-        const sessionId = args[2];
-        const outcome = args[3];
-        if (!ruleId || !sessionId || !outcome) { console.error('Usage: rule-engine.js record-outcome <ruleId> <sessionId> <good|bad>'); process.exit(1); }
-        const result = recordOutcome(ruleId, sessionId, outcome);
-        console.log(`Recorded ${outcome} outcome for ${result.ruleId}. Good: ${result.good_outcomes}, Bad: ${result.bad_outcomes}`);
-        break;
-      }
-      case 'validate-hash': {
-        const result = validateImmutableHash();
-        if (result.seeded.length > 0) {
-          console.log(`Seeded hashes for: ${result.seeded.join(', ')}`);
-        }
-        if (result.valid) {
-          console.log('All immutable rule hashes valid.');
-        } else {
-          console.error('HASH VIOLATIONS:');
-          result.violations.forEach(v => console.error(`  - ${v}`));
-          process.exit(1);
-        }
-        break;
-      }
-      case 'auto-track': {
-        const result = autoTrackSession();
-        console.log(`Auto-tracked ${result.total} rules: ${result.tracked.join(', ')}`);
-        if (result.skipped.length > 0) {
-          console.log(`Skipped (immutable/deprecated): ${result.skipped.join(', ')}`);
-        }
-        break;
-      }
-      case 'mark-review': {
-        const ruleId = args[1];
-        if (!ruleId) { console.error('Usage: rule-engine.js mark-review <ruleId>'); process.exit(1); }
-        const result = markPendingReview(ruleId);
-        console.log(`Marked ${result.ruleId} for Amelia review (since ${result.pending_review_since})`);
-        break;
-      }
-      case 'migrate-stats': {
-        const result = migrateStats();
-        console.log(`Migrated stats for ${result.ruleCount} rules → ${result.statsPath}`);
-        console.log(`YAML now definition-only: ${result.filePath}`);
-        break;
-      }
-      default:
-        console.log('Usage: rule-engine.js <load|track|promote|validate|record-apply|record-outcome|validate-hash|mark-review|migrate-stats> [args]');
-        process.exit(1);
-    }
-  } catch (err) {
-    console.error(`Error: ${err.message}`);
-    process.exit(1);
-  }
-}