kodelyth-ecc 1.2.0

package/scripts/lib/skill-improvement/health.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const HEALTH_SCHEMA_VERSION = 'ecc.skill-health.v1';
+
+function roundRate(value) {
+  return Math.round(value * 1000) / 1000;
+}
+
+function rankCounts(values) {
+  return Array.from(values.entries())
+    .map(([value, count]) => ({ value, count }))
+    .sort((left, right) => right.count - left.count || left.value.localeCompare(right.value));
+}
+
+function summarizeVariantRuns(records) {
+  return records.reduce((accumulator, record) => {
+    const key = record.run && record.run.variant ? record.run.variant : 'baseline';
+    if (!accumulator[key]) {
+      accumulator[key] = { runs: 0, successes: 0, failures: 0 };
+    }
+
+    accumulator[key].runs += 1;
+    if (record.outcome && record.outcome.success) {
+      accumulator[key].successes += 1;
+    } else {
+      accumulator[key].failures += 1;
+    }
+
+    return accumulator;
+  }, {});
+}
+
+function deriveSkillStatus(skillSummary, options = {}) {
+  const minFailureCount = options.minFailureCount || 2;
+  if (skillSummary.failures >= minFailureCount) {
+    return 'failing';
+  }
+
+  if (skillSummary.failures > 0) {
+    return 'watch';
+  }
+
+  return 'healthy';
+}
+
+function buildSkillHealthReport(records, options = {}) {
+  const filterSkillId = options.skillId || null;
+  const filtered = filterSkillId
+    ? records.filter(record => record.skill && record.skill.id === filterSkillId)
+    : records.slice();
+
+  const grouped = filtered.reduce((accumulator, record) => {
+    const skillId = record.skill.id;
+    if (!accumulator.has(skillId)) {
+      accumulator.set(skillId, []);
+    }
+    accumulator.get(skillId).push(record);
+    return accumulator;
+  }, new Map());
+
+  const skills = Array.from(grouped.entries())
+    .map(([skillId, skillRecords]) => {
+      const successes = skillRecords.filter(record => record.outcome && record.outcome.success).length;
+      const failures = skillRecords.length - successes;
+      const recurringErrors = new Map();
+      const recurringTasks = new Map();
+      const recurringFeedback = new Map();
+
+      skillRecords.forEach(record => {
+        if (!record.outcome || record.outcome.success) {
+          return;
+        }
+
+        if (record.outcome.error) {
+          recurringErrors.set(record.outcome.error, (recurringErrors.get(record.outcome.error) || 0) + 1);
+        }
+        if (record.task) {
+          recurringTasks.set(record.task, (recurringTasks.get(record.task) || 0) + 1);
+        }
+        if (record.outcome.feedback) {
+          recurringFeedback.set(record.outcome.feedback, (recurringFeedback.get(record.outcome.feedback) || 0) + 1);
+        }
+      });
+
+      const summary = {
+        skill: {
+          id: skillId,
+          path: skillRecords[0].skill.path || null
+        },
+        totalRuns: skillRecords.length,
+        successes,
+        failures,
+        successRate: skillRecords.length > 0 ? roundRate(successes / skillRecords.length) : 0,
+        status: 'healthy',
+        recurringErrors: rankCounts(recurringErrors).map(entry => ({ error: entry.value, count: entry.count })),
+        recurringTasks: rankCounts(recurringTasks).map(entry => ({ task: entry.value, count: entry.count })),
+        recurringFeedback: rankCounts(recurringFeedback).map(entry => ({ feedback: entry.value, count: entry.count })),
+        variants: summarizeVariantRuns(skillRecords)
+      };
+
+      summary.status = deriveSkillStatus(summary, options);
+      return summary;
+    })
+    .sort((left, right) => right.failures - left.failures || left.skill.id.localeCompare(right.skill.id));
+
+  return {
+    schemaVersion: HEALTH_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    totalObservations: filtered.length,
+    skillCount: skills.length,
+    skills
+  };
+}
+
+module.exports = {
+  HEALTH_SCHEMA_VERSION,
+  buildSkillHealthReport
+};

package/scripts/lib/skill-improvement/observations.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const OBSERVATION_SCHEMA_VERSION = 'ecc.skill-observation.v1';
+
+function resolveProjectRoot(options = {}) {
+  return path.resolve(options.projectRoot || options.cwd || process.cwd());
+}
+
+function getSkillTelemetryRoot(options = {}) {
+  return path.join(resolveProjectRoot(options), '.claude', 'ecc', 'skills');
+}
+
+function getSkillObservationsPath(options = {}) {
+  return path.join(getSkillTelemetryRoot(options), 'observations.jsonl');
+}
+
+function ensureString(value, label) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+
+  return value.trim();
+}
+
+function createObservationId() {
+  return `obs-${Date.now()}-${process.pid}-${Math.random().toString(16).slice(2, 8)}`;
+}
+
+function createSkillObservation(input) {
+  const task = ensureString(input.task, 'task');
+  const skillId = ensureString(input.skill && input.skill.id, 'skill.id');
+  const skillPath = typeof input.skill.path === 'string' && input.skill.path.trim().length > 0
+    ? input.skill.path.trim()
+    : null;
+  const success = Boolean(input.success);
+  const error = input.error === null || input.error === undefined ? null : String(input.error);
+  const feedback = input.feedback === null || input.feedback === undefined ? null : String(input.feedback);
+  const variant = typeof input.variant === 'string' && input.variant.trim().length > 0
+    ? input.variant.trim()
+    : 'baseline';
+
+  return {
+    schemaVersion: OBSERVATION_SCHEMA_VERSION,
+    observationId: typeof input.observationId === 'string' && input.observationId.length > 0
+      ? input.observationId
+      : createObservationId(),
+    timestamp: typeof input.timestamp === 'string' && input.timestamp.length > 0
+      ? input.timestamp
+      : new Date().toISOString(),
+    task,
+    skill: {
+      id: skillId,
+      path: skillPath
+    },
+    outcome: {
+      success,
+      status: success ? 'success' : 'failure',
+      error,
+      feedback
+    },
+    run: {
+      variant,
+      amendmentId: input.amendmentId || null,
+      sessionId: input.sessionId || null,
+      source: input.source || 'manual'
+    }
+  };
+}
+
+function appendSkillObservation(observation, options = {}) {
+  const outputPath = getSkillObservationsPath(options);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.appendFileSync(outputPath, `${JSON.stringify(observation)}${os.EOL}`, 'utf8');
+  return outputPath;
+}
+
+function readSkillObservations(options = {}) {
+  const observationPath = path.resolve(options.observationsPath || getSkillObservationsPath(options));
+  if (!fs.existsSync(observationPath)) {
+    return [];
+  }
+
+  return fs.readFileSync(observationPath, 'utf8')
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map(line => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(record => record && record.schemaVersion === OBSERVATION_SCHEMA_VERSION);
+}
+
+module.exports = {
+  OBSERVATION_SCHEMA_VERSION,
+  appendSkillObservation,
+  createSkillObservation,
+  getSkillObservationsPath,
+  getSkillTelemetryRoot,
+  readSkillObservations,
+  resolveProjectRoot
+};

package/scripts/lib/state-store/index.js

@@ -0,0 +1,191 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const initSqlJs = require('sql.js');
+
+const { applyMigrations, getAppliedMigrations } = require('./migrations');
+const { createQueryApi } = require('./queries');
+const { assertValidEntity, validateEntity } = require('./schema');
+
+const DEFAULT_STATE_STORE_RELATIVE_PATH = path.join('.claude', 'ecc', 'state.db');
+
+function resolveStateStorePath(options = {}) {
+  if (options.dbPath) {
+    if (options.dbPath === ':memory:') {
+      return options.dbPath;
+    }
+    return path.resolve(options.dbPath);
+  }
+
+  const homeDir = options.homeDir || process.env.HOME || os.homedir();
+  return path.join(homeDir, DEFAULT_STATE_STORE_RELATIVE_PATH);
+}
+
+/**
+ * Wraps a sql.js Database with a better-sqlite3-compatible API surface so
+ * that the rest of the state-store code (migrations.js, queries.js) can
+ * operate without knowing which driver is in use.
+ *
+ * IMPORTANT: sql.js db.export() implicitly ends any active transaction, so
+ * we must defer all disk writes until after the transaction commits.
+ */
+function wrapSqlJsDatabase(rawDb, dbPath) {
+  let inTransaction = false;
+
+  function saveToDisk() {
+    if (dbPath === ':memory:' || inTransaction) {
+      return;
+    }
+    const data = rawDb.export();
+    const buffer = Buffer.from(data);
+    fs.writeFileSync(dbPath, buffer);
+  }
+
+  const db = {
+    exec(sql) {
+      rawDb.run(sql);
+      saveToDisk();
+    },
+
+    pragma(pragmaStr) {
+      try {
+        rawDb.run(`PRAGMA ${pragmaStr}`);
+      } catch (_error) {
+        // Ignore unsupported pragmas (e.g. WAL for in-memory databases).
+      }
+    },
+
+    prepare(sql) {
+      return {
+        all(...positionalArgs) {
+          const stmt = rawDb.prepare(sql);
+          if (positionalArgs.length === 1 && typeof positionalArgs[0] !== 'object') {
+            stmt.bind([positionalArgs[0]]);
+          } else if (positionalArgs.length > 1) {
+            stmt.bind(positionalArgs);
+          }
+
+          const rows = [];
+          while (stmt.step()) {
+            rows.push(stmt.getAsObject());
+          }
+          stmt.free();
+          return rows;
+        },
+
+        get(...positionalArgs) {
+          const stmt = rawDb.prepare(sql);
+          if (positionalArgs.length === 1 && typeof positionalArgs[0] !== 'object') {
+            stmt.bind([positionalArgs[0]]);
+          } else if (positionalArgs.length > 1) {
+            stmt.bind(positionalArgs);
+          }
+
+          let row = null;
+          if (stmt.step()) {
+            row = stmt.getAsObject();
+          }
+          stmt.free();
+          return row;
+        },
+
+        run(namedParams) {
+          const stmt = rawDb.prepare(sql);
+          if (namedParams && typeof namedParams === 'object' && !Array.isArray(namedParams)) {
+            const sqlJsParams = {};
+            for (const [key, value] of Object.entries(namedParams)) {
+              sqlJsParams[`@${key}`] = value === undefined ? null : value;
+            }
+            stmt.bind(sqlJsParams);
+          }
+          stmt.step();
+          stmt.free();
+          saveToDisk();
+        },
+      };
+    },
+
+    transaction(fn) {
+      return (...args) => {
+        rawDb.run('BEGIN');
+        inTransaction = true;
+        try {
+          const result = fn(...args);
+          rawDb.run('COMMIT');
+          inTransaction = false;
+          saveToDisk();
+          return result;
+        } catch (error) {
+          try {
+            rawDb.run('ROLLBACK');
+          } catch (_rollbackError) {
+            // Transaction may already be rolled back.
+          }
+          inTransaction = false;
+          throw error;
+        }
+      };
+    },
+
+    close() {
+      saveToDisk();
+      rawDb.close();
+    },
+  };
+
+  return db;
+}
+
+async function openDatabase(SQL, dbPath) {
+  if (dbPath !== ':memory:') {
+    fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  }
+
+  let rawDb;
+  if (dbPath !== ':memory:' && fs.existsSync(dbPath)) {
+    const fileBuffer = fs.readFileSync(dbPath);
+    rawDb = new SQL.Database(fileBuffer);
+  } else {
+    rawDb = new SQL.Database();
+  }
+
+  const db = wrapSqlJsDatabase(rawDb, dbPath);
+  db.pragma('foreign_keys = ON');
+  try {
+    db.pragma('journal_mode = WAL');
+  } catch (_error) {
+    // Some SQLite environments reject WAL for in-memory or readonly contexts.
+  }
+  return db;
+}
+
+async function createStateStore(options = {}) {
+  const dbPath = resolveStateStorePath(options);
+  const SQL = await initSqlJs();
+  const db = await openDatabase(SQL, dbPath);
+  const appliedMigrations = applyMigrations(db);
+  const queryApi = createQueryApi(db);
+
+  return {
+    dbPath,
+    close() {
+      db.close();
+    },
+    getAppliedMigrations() {
+      return getAppliedMigrations(db);
+    },
+    validateEntity,
+    assertValidEntity,
+    ...queryApi,
+    _database: db,
+    _migrations: appliedMigrations,
+  };
+}
+
+module.exports = {
+  DEFAULT_STATE_STORE_RELATIVE_PATH,
+  createStateStore,
+  resolveStateStorePath,
+};

package/scripts/lib/state-store/migrations.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const INITIAL_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  applied_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  adapter_id TEXT NOT NULL,
+  harness TEXT NOT NULL,
+  state TEXT NOT NULL,
+  repo_root TEXT,
+  started_at TEXT,
+  ended_at TEXT,
+  snapshot TEXT NOT NULL CHECK (json_valid(snapshot))
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_state_started_at
+  ON sessions (state, started_at DESC);
+CREATE INDEX IF NOT EXISTS idx_sessions_started_at
+  ON sessions (started_at DESC);
+
+CREATE TABLE IF NOT EXISTS skill_runs (
+  id TEXT PRIMARY KEY,
+  skill_id TEXT NOT NULL,
+  skill_version TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  task_description TEXT NOT NULL,
+  outcome TEXT NOT NULL,
+  failure_reason TEXT,
+  tokens_used INTEGER,
+  duration_ms INTEGER,
+  user_feedback TEXT,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (session_id) REFERENCES sessions (id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_skill_runs_session_id_created_at
+  ON skill_runs (session_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_skill_runs_created_at
+  ON skill_runs (created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_skill_runs_outcome_created_at
+  ON skill_runs (outcome, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS skill_versions (
+  skill_id TEXT NOT NULL,
+  version TEXT NOT NULL,
+  content_hash TEXT NOT NULL,
+  amendment_reason TEXT,
+  promoted_at TEXT,
+  rolled_back_at TEXT,
+  PRIMARY KEY (skill_id, version)
+);
+
+CREATE INDEX IF NOT EXISTS idx_skill_versions_promoted_at
+  ON skill_versions (promoted_at DESC);
+
+CREATE TABLE IF NOT EXISTS decisions (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  rationale TEXT NOT NULL,
+  alternatives TEXT NOT NULL CHECK (json_valid(alternatives)),
+  supersedes TEXT,
+  status TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (session_id) REFERENCES sessions (id) ON DELETE CASCADE,
+  FOREIGN KEY (supersedes) REFERENCES decisions (id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_decisions_session_id_created_at
+  ON decisions (session_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_decisions_status_created_at
+  ON decisions (status, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS install_state (
+  target_id TEXT NOT NULL,
+  target_root TEXT NOT NULL,
+  profile TEXT,
+  modules TEXT NOT NULL CHECK (json_valid(modules)),
+  operations TEXT NOT NULL CHECK (json_valid(operations)),
+  installed_at TEXT NOT NULL,
+  source_version TEXT,
+  PRIMARY KEY (target_id, target_root)
+);
+
+CREATE INDEX IF NOT EXISTS idx_install_state_installed_at
+  ON install_state (installed_at DESC);
+
+CREATE TABLE IF NOT EXISTS governance_events (
+  id TEXT PRIMARY KEY,
+  session_id TEXT,
+  event_type TEXT NOT NULL,
+  payload TEXT NOT NULL CHECK (json_valid(payload)),
+  resolved_at TEXT,
+  resolution TEXT,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (session_id) REFERENCES sessions (id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_governance_events_resolved_at_created_at
+  ON governance_events (resolved_at, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_governance_events_session_id_created_at
+  ON governance_events (session_id, created_at DESC);
+`;
+
+const MIGRATIONS = [
+  {
+    version: 1,
+    name: '001_initial_state_store',
+    sql: INITIAL_SCHEMA_SQL,
+  },
+];
+
+function ensureMigrationTable(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      version INTEGER PRIMARY KEY,
+      name TEXT NOT NULL,
+      applied_at TEXT NOT NULL
+    );
+  `);
+}
+
+function getAppliedMigrations(db) {
+  ensureMigrationTable(db);
+  return db
+    .prepare(`
+      SELECT version, name, applied_at
+      FROM schema_migrations
+      ORDER BY version ASC
+    `)
+    .all()
+    .map(row => ({
+      version: row.version,
+      name: row.name,
+      appliedAt: row.applied_at,
+    }));
+}
+
+function applyMigrations(db) {
+  ensureMigrationTable(db);
+
+  const appliedVersions = new Set(
+    db.prepare('SELECT version FROM schema_migrations').all().map(row => row.version)
+  );
+  const insertMigration = db.prepare(`
+    INSERT INTO schema_migrations (version, name, applied_at)
+    VALUES (@version, @name, @applied_at)
+  `);
+
+  const applyPending = db.transaction(() => {
+    for (const migration of MIGRATIONS) {
+      if (appliedVersions.has(migration.version)) {
+        continue;
+      }
+
+      db.exec(migration.sql);
+      insertMigration.run({
+        version: migration.version,
+        name: migration.name,
+        applied_at: new Date().toISOString(),
+      });
+    }
+  });
+
+  applyPending();
+  return getAppliedMigrations(db);
+}
+
+module.exports = {
+  MIGRATIONS,
+  applyMigrations,
+  getAppliedMigrations,
+};