@adia-ai/adia-ui-factory 0.2.2 → 0.2.3

package/skills/adia-ui-kit/scripts/run-skill-evals.mjs

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+/**
+ * run-skill-evals.mjs (bundled — adia-ui-kit v2.30.0+)
+ *
+ * Portable eval runner for adia-ui-kit. Runs three bundled corpora
+ * against the kit:
+ *
+ *   1. evals/routing-corpus.json
+ *      Routing-accuracy corpus (10 trigger phrases + 5 adversarial).
+ *      Scores kit's description + trigger frontmatter via TF-IDF token
+ *      overlap. Trigger phrases SHOULD activate kit; adversarial
+ *      phrases should NOT.
+ *
+ *   2. evals/evals.json
+ *      Behavioral-eval corpus (instruction-following + composition
+ *      checks). Manually reviewable for now; the runner reports
+ *      counts + structure only.
+ *
+ *   3. evals/adversarial-content-trust.json
+ *      Content-trust adversarial corpus (5 injection cases). Manually
+ *      reviewable — the runner reports case count + structure only;
+ *      actual PASS/FAIL requires presenting each case to a fresh
+ *      agent session and observing behavior. See REFACTOR-SPEC §10
+ *      OQ2 — promotion to a CI gate happens after 3 months of stable
+ *      PASS rates.
+ *
+ * Cross-skill mode (substrate-only)
+ *   When invoked from inside the chat-ui substrate (detected by
+ *   presence of `scripts/skills/run-skill-evals.mjs`), this runner
+ *   delegates the routing eval to the substrate's cross-skill version
+ *   for higher fidelity (compares kit against all 5 senior skills).
+ *
+ * Standalone mode (consumer-repo default)
+ *   When invoked from a consumer repo (no substrate runner detected),
+ *   this runner scores kit alone — does the phrase activate kit at
+ *   all (score ≥ MIN_SCORE_THRESHOLD)?
+ *
+ * Usage:
+ *   # From the kit itself:
+ *   node scripts/run-skill-evals.mjs
+ *
+ *   # From a consumer repo (skill installed as a dep):
+ *   cd <consumer-repo>
+ *   node ./node_modules/adia-ui-kit/scripts/run-skill-evals.mjs --kit-dir=./node_modules/adia-ui-kit
+ *
+ *   # JSON output:
+ *   node run-skill-evals.mjs --json
+ *
+ *   # Strict mode — exit 1 if routing F1 < 0.85:
+ *   node run-skill-evals.mjs --strict
+ *
+ * Per REFACTOR-SPEC P3.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import * as childProcess from 'node:child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const SCRIPT_DIR = path.dirname(__filename);
+// Default kit-dir is the parent of scripts/ (i.e. SKILL.md's dir).
+// Override with --kit-dir=<path> when running from outside the kit.
+const KIT_FLAG = process.argv.find(a => a.startsWith('--kit-dir='));
+const KIT_DIR = KIT_FLAG
+  ? path.resolve(KIT_FLAG.slice('--kit-dir='.length))
+  : path.dirname(SCRIPT_DIR);
+
+const JSON_MODE = process.argv.includes('--json');
+const STRICT_MODE = process.argv.includes('--strict');
+const STRICT_F1_FLOOR = 0.85;
+
+const MIN_SCORE_THRESHOLD = 2.0; // matches substrate runner
+const MIN_MATCH_COUNT = 2;
+
+// ─────────────────────────────────────────────────────────────────
+// Token overlap scorer (compatible with substrate runner)
+// ─────────────────────────────────────────────────────────────────
+
+const STOPWORDS = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'but', 'by', 'do', 'for',
+  'from', 'has', 'have', 'i', 'if', 'in', 'is', 'it', 'just', 'me', 'my',
+  'no', 'not', 'of', 'on', 'or', 'our', 's', 't', 'that', 'the', 'this',
+  'to', 'too', 'us', 'use', 'we', 'what', 'with', 'you', 'your', 'how',
+  'why', 'when', 'where', 'which', 'who', 'will', 'would', 'could', 'should',
+  'can', 'may', 'might', 'shall', 'must', 'about', 'into', 'over', 'than',
+  'up', 'down', 'out', 'off',
+]);
+
+function tokenize(text) {
+  return new Set(
+    text
+      .toLowerCase()
+      .replace(/[^a-z0-9-/]+/g, ' ')
+      .split(/\s+/)
+      .filter(t => t.length >= 2 && !STOPWORDS.has(t))
+  );
+}
+
+function loadKitFrontmatter(kitDir) {
+  const skillPath = path.join(kitDir, 'SKILL.md');
+  if (!fs.existsSync(skillPath)) {
+    throw new Error(`SKILL.md not found at ${skillPath}. Use --kit-dir=<path> to point at the kit's root.`);
+  }
+  const raw = fs.readFileSync(skillPath, 'utf8');
+  const fmMatch = raw.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) {
+    throw new Error(`No YAML frontmatter found in ${skillPath}.`);
+  }
+  const fm = fmMatch[1];
+  // Extract description (single-line or > folded) + trigger block.
+  // We're not running a full YAML parser — keep it minimal.
+  const descMatch = fm.match(/^description:\s*(?:>-?\s*\n((?:  [^\n]*\n?)+)|([^\n]+))/m);
+  const trigMatch = fm.match(/^trigger:\s*(?:>-?\s*\n((?:  [^\n]*\n?)+)|([^\n]+))/m);
+  const description = (descMatch?.[1] || descMatch?.[2] || '').trim();
+  const trigger = (trigMatch?.[1] || trigMatch?.[2] || '').trim();
+  return { description, trigger, combined: `${description} ${trigger}` };
+}
+
+function scorePhrase(phrase, kitTokens, kitTextTokens) {
+  const phraseTokens = [...tokenize(phrase)];
+  let score = 0;
+  let matchCount = 0;
+  const matchedTokens = [];
+  for (const t of phraseTokens) {
+    if (kitTokens.has(t)) {
+      // Simple IDF approximation — uncommon tokens score higher.
+      // In standalone mode we don't have a corpus-wide IDF, so use 1.0
+      // for any matched token. The substrate runner does real TF-IDF.
+      score += 1.0;
+      matchCount += 1;
+      matchedTokens.push(t);
+    }
+  }
+  const activates = score >= MIN_SCORE_THRESHOLD && matchCount >= MIN_MATCH_COUNT;
+  return { score, matchCount, matchedTokens, activates };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Eval 1 — routing corpus
+// ─────────────────────────────────────────────────────────────────
+
+function runRoutingEval(kitDir) {
+  const corpusPath = path.join(kitDir, 'evals/routing-corpus.json');
+  if (!fs.existsSync(corpusPath)) {
+    return { error: `routing-corpus.json not found at ${corpusPath}`, skipped: true };
+  }
+  const corpus = JSON.parse(fs.readFileSync(corpusPath, 'utf8'));
+  const { combined } = loadKitFrontmatter(kitDir);
+  const kitTokens = tokenize(combined);
+
+  const results = corpus.phrases.map(p => {
+    const { score, matchCount, matchedTokens, activates } = scorePhrase(p.phrase, kitTokens);
+    const expected = p.should_route_to_kit;
+    const pass = activates === expected;
+    return { ...p, score, matchCount, matchedTokens, activates, pass };
+  });
+
+  const tp = results.filter(r => r.should_route_to_kit && r.activates).length;
+  const fp = results.filter(r => !r.should_route_to_kit && r.activates).length;
+  const fn = results.filter(r => r.should_route_to_kit && !r.activates).length;
+  const tn = results.filter(r => !r.should_route_to_kit && !r.activates).length;
+
+  const precision = tp + fp === 0 ? 0 : tp / (tp + fp);
+  const recall = tp + fn === 0 ? 0 : tp / (tp + fn);
+  const f1 = precision + recall === 0 ? 0 : (2 * precision * recall) / (precision + recall);
+
+  return { results, tp, fp, fn, tn, precision, recall, f1, total: results.length };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Eval 2 — behavioral corpus (structural-only report)
+// ─────────────────────────────────────────────────────────────────
+
+function runBehavioralEval(kitDir) {
+  const corpusPath = path.join(kitDir, 'evals/evals.json');
+  if (!fs.existsSync(corpusPath)) {
+    return { error: `evals.json not found at ${corpusPath}`, skipped: true };
+  }
+  const corpus = JSON.parse(fs.readFileSync(corpusPath, 'utf8'));
+  // evals.json shape varies; report what we find.
+  const cases = corpus.cases || corpus.tests || corpus.examples || corpus.evals || [];
+  return {
+    case_count: Array.isArray(cases) ? cases.length : 0,
+    note: 'Behavioral evals are structurally counted only — actual PASS/FAIL requires running each case against a fresh agent session.',
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Eval 3 — adversarial content-trust (structural-only report)
+// ─────────────────────────────────────────────────────────────────
+
+function runAdversarialEval(kitDir) {
+  const corpusPath = path.join(kitDir, 'evals/adversarial-content-trust.json');
+  if (!fs.existsSync(corpusPath)) {
+    return { error: `adversarial-content-trust.json not found at ${corpusPath}`, skipped: true };
+  }
+  const corpus = JSON.parse(fs.readFileSync(corpusPath, 'utf8'));
+  const cases = corpus.cases || [];
+  const severities = cases.reduce((acc, c) => {
+    acc[c.severity || 'unknown'] = (acc[c.severity || 'unknown'] || 0) + 1;
+    return acc;
+  }, {});
+  return {
+    case_count: cases.length,
+    severities,
+    note: 'Adversarial content-trust evals are structurally counted only — actual PASS/FAIL requires presenting each case to a fresh agent session and observing behavior. See REFACTOR-SPEC §10 OQ2.',
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Eval 4 — §Teach routing (mechanical, scored against teach-route.mjs)
+// ─────────────────────────────────────────────────────────────────
+
+function runTeachRoutingEval(kitDir) {
+  const corpusPath = path.join(kitDir, 'evals/teach-routing-cases.json');
+  const scriptPath = path.join(kitDir, 'scripts/teach-route.mjs');
+  if (!fs.existsSync(corpusPath)) {
+    return { error: `teach-routing-cases.json not found at ${corpusPath}`, skipped: true };
+  }
+  if (!fs.existsSync(scriptPath)) {
+    return { error: `teach-route.mjs not found at ${scriptPath}`, skipped: true };
+  }
+  // Run teach-route in --eval mode and parse the Pass: X/Y summary line.
+  try {
+    const { execSync } = childProcess;
+    const out = execSync(`node "${scriptPath}" --eval="${corpusPath}"`, { encoding: 'utf8' });
+    const m = out.match(/Pass:\s*(\d+)\/(\d+)/);
+    if (m) {
+      const passed = parseInt(m[1], 10);
+      const total = parseInt(m[2], 10);
+      return { passed, total, pass_rate: total === 0 ? 0 : passed / total };
+    }
+    return { error: 'Could not parse teach-route eval output', raw: out.slice(0, 200) };
+  } catch (err) {
+    return { error: `teach-route eval failed: ${err.message}` };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Substrate cross-skill mode
+// ─────────────────────────────────────────────────────────────────
+
+function detectSubstrate(cwd) {
+  // We're in the substrate if scripts/skills/run-skill-evals.mjs exists
+  // at cwd (or any ancestor).
+  let dir = cwd;
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'scripts/skills/run-skill-evals.mjs'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────────
+
+function main() {
+  const substrate = detectSubstrate(process.cwd());
+  const mode = substrate ? 'substrate (kit-only standalone scoring)' : 'standalone';
+
+  const routing = runRoutingEval(KIT_DIR);
+  const behavioral = runBehavioralEval(KIT_DIR);
+  const adversarial = runAdversarialEval(KIT_DIR);
+  const teachRouting = runTeachRoutingEval(KIT_DIR);
+
+  const summary = {
+    runner_version: '1.1.0',
+    runner_mode: mode,
+    kit_dir: KIT_DIR,
+    substrate_detected: substrate ? path.relative(process.cwd(), substrate) || '.' : null,
+    routing,
+    behavioral,
+    adversarial,
+    teach_routing: teachRouting,
+  };
+
+  if (JSON_MODE) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    printHumanReport(summary);
+  }
+
+  if (STRICT_MODE && routing.f1 < STRICT_F1_FLOOR) {
+    console.error(`\n✗ STRICT mode: routing F1 ${routing.f1.toFixed(2)} < ${STRICT_F1_FLOOR}`);
+    process.exit(1);
+  }
+  if (STRICT_MODE && teachRouting && !teachRouting.skipped && !teachRouting.error && teachRouting.pass_rate < 1.0) {
+    console.error(`\n✗ STRICT mode: teach-routing pass rate ${(teachRouting.pass_rate * 100).toFixed(1)}% < 100%`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+function printHumanReport(summary) {
+  console.log(`\n══ adia-ui-kit bundled eval runner ══`);
+  console.log(`Mode: ${summary.runner_mode}`);
+  console.log(`Kit dir: ${summary.kit_dir}`);
+  if (summary.substrate_detected) console.log(`Substrate detected at: ${summary.substrate_detected}`);
+  console.log();
+
+  console.log(`─── Routing corpus (10 trigger + 5 adversarial) ───`);
+  if (summary.routing.error) {
+    console.log(`  ✗ ${summary.routing.error}`);
+  } else {
+    for (const r of summary.routing.results) {
+      const mark = r.pass ? '✓' : '✗';
+      const expected = r.should_route_to_kit ? 'should activate' : 'should NOT activate';
+      const got = r.activates ? 'activated' : 'did not activate';
+      console.log(`  ${mark} [${r.id}] "${r.phrase}"`);
+      console.log(`      expected ${expected}; ${got} (score=${r.score.toFixed(1)} matches=${r.matchCount} [${r.matchedTokens.slice(0, 5).join(', ')}${r.matchedTokens.length > 5 ? '...' : ''}])`);
+    }
+    console.log();
+    console.log(`  TP=${summary.routing.tp} FP=${summary.routing.fp} FN=${summary.routing.fn} TN=${summary.routing.tn}`);
+    console.log(`  Precision: ${(summary.routing.precision * 100).toFixed(1)}%`);
+    console.log(`  Recall:    ${(summary.routing.recall * 100).toFixed(1)}%`);
+    console.log(`  F1:        ${(summary.routing.f1 * 100).toFixed(1)}%`);
+  }
+  console.log();
+
+  console.log(`─── Behavioral evals ───`);
+  if (summary.behavioral.error) {
+    console.log(`  ✗ ${summary.behavioral.error}`);
+  } else {
+    console.log(`  Cases: ${summary.behavioral.case_count}`);
+    console.log(`  ${summary.behavioral.note}`);
+  }
+  console.log();
+
+  console.log(`─── Adversarial content-trust evals ───`);
+  if (summary.adversarial.error) {
+    console.log(`  ✗ ${summary.adversarial.error}`);
+  } else {
+    console.log(`  Cases: ${summary.adversarial.case_count}`);
+    const sev = summary.adversarial.severities;
+    console.log(`  Severities: ${Object.entries(sev).map(([k, v]) => `${k}=${v}`).join(', ')}`);
+    console.log(`  ${summary.adversarial.note}`);
+  }
+  console.log();
+
+  console.log(`─── §Teach routing evals (mechanical, scored against teach-route.mjs) ───`);
+  const tr = summary.teach_routing;
+  if (!tr) {
+    console.log(`  (skipped — runner version mismatch)`);
+  } else if (tr.skipped || tr.error) {
+    console.log(`  ✗ ${tr.error || 'skipped'}`);
+  } else {
+    const pct = (tr.pass_rate * 100).toFixed(1);
+    const icon = tr.pass_rate >= 1.0 ? '✓' : tr.pass_rate >= 0.8 ? '⚠' : '✗';
+    console.log(`  ${icon} Pass: ${tr.passed}/${tr.total} (${pct}%)`);
+  }
+}
+
+main();

package/skills/adia-ui-kit/scripts/validate-session-log.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/**
+ * validate-session-log.mjs (adia-ui-kit v3.1.0+)
+ *
+ * Lints a JSONL session log against the schema documented in
+ * `references/session-log-schema.md`.
+ *
+ * Per REFACTOR-SPEC P5(a).
+ *
+ * Usage:
+ *   node validate-session-log.mjs <path-to-log.jsonl>
+ *   node validate-session-log.mjs <path-to-log.jsonl> --strict
+ *   node validate-session-log.mjs <path-to-log.jsonl> --json
+ *
+ * Default mode: prints per-line findings + final summary; exits 0 if no
+ * findings, 1 if any findings.
+ *
+ * Strict mode: fails on any warning OR error (default fails only on
+ * errors — warnings are missing-recommended-field hints).
+ *
+ * JSON mode: prints `{ summary, findings }` JSON for programmatic use.
+ */
+
+import fs from 'node:fs';
+import process from 'node:process';
+
+const SCHEMA_VERSION = '1';
+
+const REQUIRED_FIELDS = ['schema_version', 'session_id', 'timestamp', 'skill', 'skill_version', 'event_type', 'payload'];
+
+const KNOWN_EVENT_TYPES = new Set([
+  'skill_loaded',
+  'mode_entered',
+  'decision_made',
+  'component_named',
+  'verify_target_run',
+  'correction_applied',
+  'teach_landing',
+  'session_closed',
+]);
+
+// Per-event-type required payload fields
+const PAYLOAD_REQUIREMENTS = {
+  skill_loaded: ['trigger'],
+  mode_entered: ['mode_id', 'mode_name'],
+  decision_made: ['decision', 'required_signal', 'possible_actions', 'chosen_action'],
+  component_named: ['tag'],
+  verify_target_run: ['verify_target', 'exit_code'],
+  correction_applied: ['feedback_ticket', 'skill_section'],
+  teach_landing: ['input_payload', 'branch', 'landing_target', 'confidence'],
+  session_closed: ['outcome'],
+};
+
+const KNOWN_BRANCHES = new Set(['A', 'B', 'C', 'D', 'E', 'F', 'G', 'NONE']);
+const KNOWN_CONFIDENCES = new Set(['high', 'medium', 'low', 'none']);
+const KNOWN_OUTCOMES = new Set(['completed', 'interrupted', 'error']);
+
+function validateLine(obj, lineNum) {
+  const findings = [];
+  const error = (msg) => findings.push({ line: lineNum, severity: 'error', msg });
+  const warn = (msg) => findings.push({ line: lineNum, severity: 'warning', msg });
+
+  // Required top-level fields
+  for (const field of REQUIRED_FIELDS) {
+    if (!(field in obj)) {
+      error(`Missing required field: ${field}`);
+    }
+  }
+
+  // Schema version
+  if (obj.schema_version && obj.schema_version !== SCHEMA_VERSION) {
+    warn(`schema_version="${obj.schema_version}" — validator only knows v${SCHEMA_VERSION}`);
+  }
+
+  // Timestamp validation (ISO 8601, UTC)
+  if (obj.timestamp) {
+    if (typeof obj.timestamp !== 'string') {
+      error(`timestamp must be a string, got ${typeof obj.timestamp}`);
+    } else if (!obj.timestamp.endsWith('Z')) {
+      error(`timestamp must be UTC (end with Z): "${obj.timestamp}"`);
+    } else {
+      const d = new Date(obj.timestamp);
+      if (Number.isNaN(d.getTime())) {
+        error(`timestamp is not valid ISO 8601: "${obj.timestamp}"`);
+      }
+    }
+  }
+
+  // session_id sanity
+  if (obj.session_id && (typeof obj.session_id !== 'string' || obj.session_id.length < 4)) {
+    error(`session_id must be a non-trivial string`);
+  }
+
+  // event_type validity
+  if (obj.event_type) {
+    if (!KNOWN_EVENT_TYPES.has(obj.event_type)) {
+      error(`Unknown event_type "${obj.event_type}". Known: ${[...KNOWN_EVENT_TYPES].join(', ')}`);
+    }
+  }
+
+  // Payload requirements per event_type
+  if (obj.event_type && obj.payload && PAYLOAD_REQUIREMENTS[obj.event_type]) {
+    const required = PAYLOAD_REQUIREMENTS[obj.event_type];
+    for (const field of required) {
+      if (!(field in obj.payload)) {
+        error(`event_type=${obj.event_type} missing required payload field: ${field}`);
+      }
+    }
+  }
+
+  // Event-specific value validation
+  if (obj.event_type === 'teach_landing' && obj.payload) {
+    if (obj.payload.branch && !KNOWN_BRANCHES.has(obj.payload.branch)) {
+      error(`teach_landing.branch="${obj.payload.branch}" — must be one of A-G or NONE`);
+    }
+    if (obj.payload.confidence && !KNOWN_CONFIDENCES.has(obj.payload.confidence)) {
+      error(`teach_landing.confidence="${obj.payload.confidence}" — must be high/medium/low/none`);
+    }
+  }
+
+  if (obj.event_type === 'session_closed' && obj.payload) {
+    if (obj.payload.outcome && !KNOWN_OUTCOMES.has(obj.payload.outcome)) {
+      error(`session_closed.outcome="${obj.payload.outcome}" — must be completed/interrupted/error`);
+    }
+    if (obj.payload.summary && obj.payload.summary.length > 500) {
+      warn(`session_closed.summary > 500 chars (${obj.payload.summary.length}) — consider trimming`);
+    }
+  }
+
+  if (obj.event_type === 'decision_made' && obj.payload) {
+    if (obj.payload.possible_actions && !Array.isArray(obj.payload.possible_actions)) {
+      error(`decision_made.possible_actions must be an array`);
+    }
+    if (obj.payload.possible_actions && Array.isArray(obj.payload.possible_actions)
+        && obj.payload.possible_actions.length < 2) {
+      warn(`decision_made.possible_actions has < 2 entries — a "decision" with only one option isn't really a decision`);
+    }
+    if (obj.payload.possible_actions && obj.payload.chosen_action
+        && Array.isArray(obj.payload.possible_actions)
+        && !obj.payload.possible_actions.includes(obj.payload.chosen_action)) {
+      error(`decision_made.chosen_action "${obj.payload.chosen_action}" is not in possible_actions`);
+    }
+  }
+
+  return findings;
+}
+
+function validateFile(path) {
+  if (!fs.existsSync(path)) {
+    return { error: `File not found: ${path}`, findings: [], lineCount: 0 };
+  }
+  const content = fs.readFileSync(path, 'utf8');
+  const lines = content.split('\n').filter(l => l.trim().length > 0);
+  const allFindings = [];
+  let parsedCount = 0;
+  const eventTypeCounts = {};
+  let sessionIds = new Set();
+
+  lines.forEach((line, idx) => {
+    const lineNum = idx + 1;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch (err) {
+      allFindings.push({ line: lineNum, severity: 'error', msg: `Invalid JSON: ${err.message}` });
+      return;
+    }
+    parsedCount += 1;
+    if (obj.event_type) {
+      eventTypeCounts[obj.event_type] = (eventTypeCounts[obj.event_type] || 0) + 1;
+    }
+    if (obj.session_id) {
+      sessionIds.add(obj.session_id);
+    }
+    const findings = validateLine(obj, lineNum);
+    allFindings.push(...findings);
+  });
+
+  const errors = allFindings.filter(f => f.severity === 'error').length;
+  const warnings = allFindings.filter(f => f.severity === 'warning').length;
+
+  return {
+    path,
+    lineCount: lines.length,
+    parsedCount,
+    errors,
+    warnings,
+    sessions: sessionIds.size,
+    event_type_counts: eventTypeCounts,
+    findings: allFindings,
+  };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const strict = args.includes('--strict');
+  const path = args.find(a => !a.startsWith('--'));
+
+  if (!path) {
+    console.error('Usage: validate-session-log.mjs <path-to-log.jsonl> [--strict] [--json]');
+    process.exit(2);
+  }
+
+  const result = validateFile(path);
+
+  if (result.error) {
+    console.error(`✗ ${result.error}`);
+    process.exit(1);
+  }
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`\n══ validate-session-log — ${result.path} ══`);
+    console.log(`  Lines:    ${result.lineCount}`);
+    console.log(`  Parsed:   ${result.parsedCount}`);
+    console.log(`  Sessions: ${result.sessions}`);
+    console.log(`  Event types:`);
+    for (const [et, count] of Object.entries(result.event_type_counts)) {
+      console.log(`    ${et}: ${count}`);
+    }
+    console.log(`  Errors:   ${result.errors}`);
+    console.log(`  Warnings: ${result.warnings}`);
+
+    if (result.findings.length > 0) {
+      console.log(`\nFindings:`);
+      for (const f of result.findings) {
+        const icon = f.severity === 'error' ? '✗' : '⚠';
+        console.log(`  ${icon} line ${f.line}: [${f.severity}] ${f.msg}`);
+      }
+    } else {
+      console.log(`\n✓ No findings.`);
+    }
+  }
+
+  if (result.errors > 0) process.exit(1);
+  if (strict && result.warnings > 0) process.exit(1);
+  process.exit(0);
+}
+
+main();