@aikdna/kdna-studio-core 1.3.0

package/src/quality/index.js

@@ -0,0 +1,161 @@
+/**
+ * Enhanced Quality Gates — 4-grade readiness with integrated card validation.
+ *
+ * Grades:
+ *   draft_grade       — Core+Patterns exist, ≥3 human-reviewed cards
+ *   human_controlled  — All core axioms locked with boundaries, ≥50% have Feynman
+ *   tested_grade      — ≥5 rated evals, ≥3 comparison tests
+ *   publishable_grade — ≥10 evals, all axioms have Feynman, README 4 questions, no blocking
+ *
+ * v0.3.2: integrates validateAllCards, Feynman enforcement at publishable grade.
+ */
+
+const contradiction = require('./contradiction');
+const { validateAllCards } = require('./validate-cards');
+const { validateGovernance } = require('../governance');
+const { computeI18nCoverage } = require('../i18n');
+
+function computeReadiness(project) {
+  const cards = project.cards || [];
+  const tests = project.tests || [];
+  const locked = cards.filter(c => c.locked);
+  const lockedAxioms = locked.filter(c => c.type === 'axiom');
+  const lockedSelfChecks = locked.filter(c => c.type === 'self_check');
+  const lockedMisunderstandings = locked.filter(c => c.type === 'misunderstanding');
+  const ratedTests = tests.filter(t => t.result);
+
+  const blocking = [];
+  const warnings = [];
+
+  // ── Governance check (v0.6.1) ───────────────────────────────────
+  const govResult = validateGovernance(project);
+
+  // ── I18N check (v1.2.0) ─────────────────────────────────────────
+  const isOfficial = project.name?.startsWith('@aikdna/') || project.release?.official === true;
+  const i18nCoverage = computeI18nCoverage(project);
+  if (isOfficial && i18nCoverage.level === 'L0') {
+    blocking.push('I18N: official domains require at least L1 (KDNA_CARD.json + README in locales/zh-CN/)');
+  } else if (isOfficial && i18nCoverage.level === 'L1') {
+    warnings.push('I18N: L1 achieved (card + readme). Recommended: L2 overlay for publishable grade.');
+  }
+  for (const issue of govResult.issues) {
+    (issue.severity === 'blocking' ? blocking : warnings).push(`Governance: ${issue.message}`);
+  }
+
+  // ── Card validation integration (v0.3.2) ─────────────────────────
+  const cardResults = validateAllCards(project);
+  for (const { card_id, issues } of cardResults) {
+    for (const issue of issues) {
+      if (issue.severity === 'blocking') blocking.push(`${card_id}: ${issue.message}`);
+      else warnings.push(`${card_id}: ${issue.message}`);
+    }
+  }
+
+  // ── Minimum Structure ──────────────────────────────────────────
+  if (cards.length === 0) { blocking.push('Project has no cards'); return buildResult('draft_grade', blocking, warnings, project); }
+  if (locked.length === 0) { blocking.push('No locked cards — nothing to compile'); return buildResult('draft_grade', blocking, warnings, project); }
+
+  // ── Axiom Checks ──────────────────────────────────────────────
+  for (const ax of lockedAxioms) {
+    if (!ax.fields?.one_sentence || ax.fields.one_sentence.length < 10) blocking.push(`${ax.id}: one_sentence too short`);
+    if (!ax.fields?.applies_when?.length) blocking.push(`${ax.id}: missing applies_when`);
+    if (!ax.fields?.does_not_apply_when?.length) blocking.push(`${ax.id}: missing does_not_apply_when`);
+    if (!ax.fields?.failure_risk) blocking.push(`${ax.id}: missing failure_risk`);
+    if (!ax.human_lock) blocking.push(`${ax.id}: not locked`);
+    if (!ax.feynman_restatement) warnings.push(`${ax.id}: missing Feynman restatement`);
+  }
+
+  // ── Misunderstanding Checks ────────────────────────────────────
+  for (const ms of lockedMisunderstandings) {
+    if (!ms.fields?.key_distinction || ms.fields.key_distinction.length < 20) blocking.push(`${ms.id}: key_distinction too short`);
+  }
+
+  // ── Self-check Checks ──────────────────────────────────────────
+  for (const sc of lockedSelfChecks) {
+    const q = sc.fields?.question || '';
+    if (!q.endsWith('?')) blocking.push(`${sc.id}: self_check must end with ?`);
+  }
+
+  // ── Contradiction Check ────────────────────────────────────────
+  for (const c of contradiction.detectContradictions(cards)) {
+    (c.severity === 'blocking' ? blocking : warnings).push(c.message);
+  }
+
+  // ── Determine Grade ────────────────────────────────────────────
+  const axiomsComplete = lockedAxioms.length >= 1 &&
+    lockedAxioms.every(ax => ax.fields?.applies_when?.length && ax.fields?.does_not_apply_when?.length && ax.fields?.failure_risk && ax.human_lock);
+  const feynmanRatio = lockedAxioms.length > 0 ? lockedAxioms.filter(ax => ax.feynman_restatement).length / lockedAxioms.length : 0;
+  const allFeynman = lockedAxioms.every(ax => ax.feynman_restatement) && lockedMisunderstandings.every(ms => !ms.locked || ms.feynman_restatement);
+
+  // Feynman quality threshold (v0.6.2)
+  const feynmanQuality = lockedAxioms.every(ax => {
+    if (!ax.feynman_restatement?.score) return false;
+    return ax.feynman_restatement.score.total >= 4;
+  });
+  const misunderstandingFeynmanQuality = lockedMisunderstandings.length === 0 ||
+    lockedMisunderstandings.every(ms => {
+      if (!ms.feynman_restatement?.score) return false;
+      return ms.feynman_restatement.score.total >= 3;
+    });
+  if (allFeynman && !feynmanQuality) {
+    warnings.push('Feynman: axiom restatements should score ≥4/5 for publishable grade');
+  }
+
+  // Compare test results requirements (v0.6.4)
+  const withKdnaBetter = ratedTests.filter(t => t.result === 'with_kdna_better').length;
+  const withoutKdnaBetter = ratedTests.filter(t => t.result === 'without_kdna_better').length;
+  if (ratedTests.length > 0 && withoutKdnaBetter > 0) {
+    warnings.push(`${withoutKdnaBetter} test(s) favored response WITHOUT KDNA — domain may not improve judgment`);
+  }
+  if (ratedTests.length > 0 && withKdnaBetter < 3 && ratedTests.length >= 5) {
+    warnings.push(`Only ${withKdnaBetter} tests favor KDNA — recommend ≥3 for confidence`);
+  }
+
+  let grade = 'draft_grade';
+  if (locked.length >= 3 && axiomsComplete && feynmanRatio >= 0.5) grade = 'human_controlled';
+  if (grade === 'human_controlled' && ratedTests.length >= 5 && lockedSelfChecks.length >= 3) grade = 'tested_grade';
+  if (grade === 'tested_grade' && ratedTests.length >= 10 && lockedAxioms.length >= 3 && lockedSelfChecks.length >= 5 && blocking.length === 0 && allFeynman && feynmanQuality && misunderstandingFeynmanQuality) {
+    grade = 'publishable_grade';
+  }
+
+  // Downgrade if governance issues exist
+  if (grade === 'publishable_grade' && govResult && !govResult.valid) {
+    grade = 'tested_grade';
+    warnings.push('Governance checks not passed — publishable downgraded to tested');
+  }
+
+  return buildResult(grade, blocking, warnings, project, { feynmanRatio, allFeynman, governance: govResult, i18n: i18nCoverage });
+}
+
+function buildResult(grade, blocking, warnings, project, detail = {}) {
+  const lockedCount = (project.cards || []).filter(c => c.locked).length;
+  const ratedTests = (project.tests || []).filter(t => t.result).length;
+
+  return {
+    grade,
+    publishable: grade === 'publishable_grade' && blocking.length === 0,
+    blocking,
+    warnings,
+    score: Math.max(0, 100 - blocking.length * 15 - warnings.length * 3),
+    governance: detail.governance || null,
+    i18n: detail.i18n || null,
+    stats: {
+      total_cards: (project.cards || []).length,
+      locked_cards: lockedCount,
+      locked_axioms: (project.cards || []).filter(c => c.type === 'axiom' && c.locked).length,
+      locked_self_checks: (project.cards || []).filter(c => c.type === 'self_check' && c.locked).length,
+      total_tests: (project.tests || []).length,
+      rated_tests: ratedTests,
+      feynman_ratio: detail.feynmanRatio !== undefined ? Math.round(detail.feynmanRatio * 100) + '%' : 'N/A',
+      i18n_level: detail.i18n?.level || 'L0',
+    },
+    next_step: grade === 'draft_grade' ? 'Lock at least 3 axioms with boundaries and 50% Feynman.' :
+      grade === 'human_controlled' ? 'Add 5+ rated evals and 3+ self-checks.' :
+      grade === 'tested_grade' ? 'Add 10+ evals, complete Feynman on all axioms/misunderstandings, resolve all blocking issues.' :
+      'Ready for Studio compile/export. Publish the resulting .kdna with kdna publish <file.kdna>.',
+  };
+}
+
+function getBlockingIssues(project) { return computeReadiness(project).blocking; }
+
+module.exports = { computeReadiness, getBlockingIssues };

package/src/quality/validate-cards.js

@@ -0,0 +1,164 @@
+/**
+ * Card Validator — Anti-vagueness, anti-SOP, anti-slogan, anti-straw-man checks.
+ *
+ * Ensures every card meets minimum quality before it can be locked.
+ * These checks mirror the kdna-cli publish --check rules.
+ */
+
+const ANTI_PATTERNS = {
+  axiom: {
+    slogans: ['is key', 'is important', 'matters', 'is critical', 'is essential', 'should be', 'must be'],
+    sops: ['first, you should', 'follow these steps', 'always remember to', 'the process is'],
+  },
+  misunderstanding: {
+    straw_men: ['some people say', 'many believe', 'it is commonly thought'],
+  },
+  self_check: {
+    generics: ['is this good', 'is this correct', 'is this helpful', 'is this clear', 'does this work', 'is it right'],
+  },
+};
+
+function validateCard(card) {
+  const issues = [];
+
+  switch (card.type) {
+    case 'axiom':
+      validateAxiom(card, issues);
+      break;
+    case 'misunderstanding':
+      validateMisunderstanding(card, issues);
+      break;
+    case 'self_check':
+      validateSelfCheck(card, issues);
+      break;
+    case 'ontology':
+      validateOntology(card, issues);
+      break;
+    case 'boundary':
+      validateBoundary(card, issues);
+      break;
+  }
+
+  return issues;
+}
+
+function validateAxiom(card, issues) {
+  const oneLiner = (card.fields?.one_sentence || '').toLowerCase();
+  const full = (card.fields?.full_statement || '').toLowerCase();
+
+  // Anti-slogan: reject axioms that are just motivational slogans
+  for (const slogan of ANTI_PATTERNS.axiom.slogans) {
+    if (oneLiner.includes(slogan) && oneLiner.length < 40) {
+      issues.push({
+        type: 'slogan',
+        severity: 'warning',
+        message: `${card.id}: one_sentence may be a slogan — "${oneLiner.slice(0, 60)}"`,
+        fix: 'Axioms must be specific, testable judgment principles. Replace vague slogans with concrete decision rules.',
+      });
+      break;
+    }
+  }
+
+  // Anti-SOP: axioms should not encode step-by-step procedures
+  for (const sop of ANTI_PATTERNS.axiom.sops) {
+    if (oneLiner.includes(sop) || full.includes(sop)) {
+      issues.push({
+        type: 'sop',
+        severity: 'warning',
+        message: `${card.id}: axiom reads like a procedure, not a judgment principle`,
+        fix: 'Axioms encode how to judge, not what steps to follow. Rephrase as a decision principle.',
+      });
+      break;
+    }
+  }
+
+  // Anti-vagueness: one_sentence must be specific enough
+  if (oneLiner.length < 15) {
+    issues.push({ type: 'too_short', severity: 'blocking', message: `${card.id}: one_sentence too short (${oneLiner.length} chars)`, fix: 'Make it a complete, specific judgment statement.' });
+  }
+
+  // Check for dictionary-definition style (axiom should not start with "X is")
+  if (/^\w+\s+is\s/.test(oneLiner) && oneLiner.length < 50) {
+    issues.push({ type: 'definition_like', severity: 'warning', message: `${card.id}: one_sentence reads like a definition, not a judgment — rephrase as a principle` });
+  }
+}
+
+function validateMisunderstanding(card, issues) {
+  const wrong = (card.fields?.wrong || '').toLowerCase();
+  const correct = (card.fields?.correct || '').toLowerCase();
+  const distinction = card.fields?.key_distinction || '';
+
+  // Anti-straw-man: the wrong belief should be something real people believe
+  if (wrong.length < 15) {
+    issues.push({ type: 'vague_wrong', severity: 'warning', message: `${card.id}: wrong belief too short — may describe a straw man no one believes` });
+  }
+  for (const straw of ANTI_PATTERNS.misunderstanding.straw_men) {
+    if (wrong.includes(straw)) {
+      issues.push({ type: 'straw_man', severity: 'warning', message: `${card.id}: wrong belief uses straw-man phrasing — describe what people actually get wrong` });
+      break;
+    }
+  }
+
+  if (!distinction || distinction.length < 20) {
+    issues.push({ type: 'missing_distinction', severity: 'blocking', message: `${card.id}: key_distinction missing or too short (${distinction.length} chars)` });
+  }
+}
+
+function validateSelfCheck(card, issues) {
+  const question = card.fields?.question || '';
+
+  const isQuestion = question.endsWith('?') || question.endsWith('？') || /[吗是否]$/.test(question);
+  if (!isQuestion) {
+    issues.push({ type: 'not_question', severity: 'blocking', message: `${card.id}: must be a yes/no answerable question` });
+  }
+
+  if (question.length < 15) {
+    issues.push({ type: 'vague', severity: 'warning', message: `${card.id}: question too short — make it domain-specific` });
+  }
+
+  for (const gen of ANTI_PATTERNS.self_check.generics) {
+    if (question.toLowerCase().includes(gen)) {
+      issues.push({ type: 'generic', severity: 'warning', message: `${card.id}: question is generic — should reference domain-specific criteria` });
+      break;
+    }
+  }
+}
+
+function validateOntology(card, issues) {
+  const essence = card.fields?.essence || '';
+  const boundary = card.fields?.boundary || '';
+  const trigger = card.fields?.trigger_signal || '';
+
+  if (essence.length < 15) {
+    issues.push({ type: 'vague_essence', severity: 'warning', message: `${card.id}: essence too short — explain operational meaning` });
+  }
+  if (boundary.length < 10) {
+    issues.push({ type: 'missing_boundary', severity: 'warning', message: `${card.id}: boundary missing — what is this concept NOT?` });
+  }
+  if (trigger.length < 10) {
+    issues.push({ type: 'missing_trigger', severity: 'warning', message: `${card.id}: trigger_signal missing — how does the agent detect this concept?` });
+  }
+}
+
+function validateBoundary(card, issues) {
+  const scope = card.fields?.scope || '';
+  const outOfScope = card.fields?.out_of_scope || '';
+
+  if (scope.length < 10) {
+    issues.push({ type: 'vague_scope', severity: 'warning', message: `${card.id}: scope too short` });
+  }
+  if (outOfScope.length < 10) {
+    issues.push({ type: 'vague_out_of_scope', severity: 'blocking', message: `${card.id}: out_of_scope missing or too short` });
+  }
+}
+
+function validateAllCards(project) {
+  const allIssues = [];
+  for (const card of (project.cards || [])) {
+    const cardIssues = validateCard(card);
+    allIssues.push({ card_id: card.id, issues: cardIssues });
+  }
+  return allIssues;
+}
+
+module.exports = { validateCard, validateAllCards, ANTI_PATTERNS };

package/src/testlab/delta.js

@@ -0,0 +1,193 @@
+/**
+ * Judgment Delta — Structured comparison of agent response with vs without KDNA.
+ *
+ * Parses kdna compare output (text or JSON) into structured axes:
+ *   1. CLASSIFICATION — how the task was classified
+ *   2. DIAGNOSIS — root cause identified
+ *   3. ACTIONS — what the response suggests
+ *   4. BOUNDARY — scope awareness
+ *   5. TERMINOLOGY — domain-specific terms used
+ *
+ * Also supports scoring along the D1-D7 dimensions defined in the
+ * KDNA Compare Report specification.
+ */
+
+function parseCompareOutput(diffText) {
+  const axes = {};
+  const matches = diffText.matchAll(/^(\d)\.\s*(\w+(?:\s+\w+)*):\s*(.+)$/gim);
+  for (const m of matches) {
+    const name = m[2].toLowerCase().replace(/\s+/g, '_');
+    const value = m[3].trim();
+    if (value.toUpperCase() !== 'SAME') {
+      axes[name] = value;
+    }
+  }
+
+  // Legacy format: "<axis>: <value>"
+  if (Object.keys(axes).length === 0) {
+    const legacyMatch = diffText.matchAll(/^(\w+):\s*(.+)$/gim);
+    for (const m of legacyMatch) {
+      const name = m[1].toLowerCase();
+      const value = m[2].trim();
+      if (name === 'verdict') continue;
+      if (value.toUpperCase() !== 'SAME') {
+        axes[name] = value;
+      }
+    }
+  }
+
+  const verdictMatch = diffText.match(/VERDICT:\s*(.+)/i);
+  const verdict = verdictMatch ? verdictMatch[1].trim().toLowerCase() : 'trajectory_unchanged';
+
+  return { axes, verdict };
+}
+
+function scoreDelta(axes) {
+  let score = 5;
+  const changed = [];
+  for (const [axis, value] of Object.entries(axes)) {
+    changed.push({ axis, value: value.slice(0, 100) });
+    score = Math.min(10, score + 1);
+  }
+  return { score: Math.min(10, score), changed };
+}
+
+function createJudgmentDelta(domain, input, responseA, responseB, diffText, options = {}) {
+  const { axes, verdict } = parseCompareOutput(diffText);
+  const domainScore = scoreDelta(axes);
+  const triggeredAxioms = options.triggeredAxioms || [];
+  const avoidedMisunderstandings = options.avoidedMisunderstandings || [];
+  const selfChecksPassed = options.selfChecksPassed || null;
+
+  return {
+    meta: {
+      domain,
+      input: input.slice(0, 200),
+      model: options.model || 'unknown',
+      timestamp: new Date().toISOString(),
+    },
+    classification: {
+      without_kdna: axes.classification || 'generic',
+      with_kdna: axes.classification ? 'domain_specific' : 'unchanged',
+      changed: !!axes.classification,
+    },
+    axes,
+    verdict,
+    score: domainScore.score,
+    changed_dimensions: domainScore.changed,
+    triggered_axioms: triggeredAxioms,
+    avoided_misunderstandings: avoidedMisunderstandings,
+    self_checks_passed: selfChecksPassed,
+    scoring: buildScoring(axes, domainScore, selfChecksPassed),
+    summary: buildSummary(domain, domainScore, verdict),
+  };
+}
+
+function buildScoring(axes, domainScore, selfChecksPassed) {
+  return {
+    D1_diagnostic_depth: axes.diagnosis ? 8 : 5,
+    D2_terminology_precision: axes.terminology ? 8 : 5,
+    D3_misunderstanding_detection: 5,
+    D4_axiom_alignment: domainScore.score,
+    D5_self_check_pass_rate: selfChecksPassed !== null
+      ? `${selfChecksPassed}%`
+      : 'N/A',
+    D6_boundary_respect: axes.boundary_awareness || axes.boundary ? 'Pass' : 'N/A',
+    D7_risk_avoidance: 'N/A',
+  };
+}
+
+function buildSummary(domain, domainScore, verdict) {
+  const changed = domainScore.changed.map(c => `**${c.axis}**`).join(', ');
+  if (changed.length === 0) {
+    return `Loading \`${domain}\` did not significantly alter the judgment trajectory for this input.`;
+  }
+  if (verdict.includes('changed')) {
+    return `Loading \`${domain}\` changed the agent's response across ${domainScore.changed.length} dimensions: ${changed}. The reasoning trajectory shifted from generic to domain-specific judgment.`;
+  }
+  return `Loading \`${domain}\` produced changes in ${domainScore.changed.length} dimensions: ${changed}.`;
+}
+
+function compareDeltas(delta1, delta2) {
+  const diffs = [];
+  for (const axis of ['classification', 'diagnosis', 'actions', 'boundary_awareness', 'terminology']) {
+    const v1 = delta1.axes[axis] || 'SAME';
+    const v2 = delta2.axes[axis] || 'SAME';
+    if (v1 !== v2) {
+      diffs.push({ axis, before: v1, after: v2 });
+    }
+  }
+  return {
+    score_change: delta2.score - delta1.score,
+    verdict_before: delta1.verdict,
+    verdict_after: delta2.verdict,
+    axis_diffs: diffs,
+    improved: delta2.score > delta1.score,
+  };
+}
+
+function formatDeltaMarkdown(delta) {
+  const lines = [];
+  lines.push('# KDNA Judgment Comparison Report'); lines.push('');
+  lines.push(`**Domain:** ${delta.meta.domain}`);
+  lines.push(`**Model:** ${delta.meta.model}`);
+  lines.push(`**Date:** ${delta.meta.timestamp}`); lines.push('');
+  lines.push('## Judgment Diff'); lines.push('');
+  lines.push('| Dimension | Change |'); lines.push('|-----------|--------|');
+  for (const d of delta.changed_dimensions) lines.push(`| ${d.axis} | **Changed**: ${d.value} |`);
+  if (!delta.changed_dimensions.length) lines.push('| (none) | No significant change |');
+  lines.push('');
+  lines.push('## Scoring'); lines.push('');
+  for (const [dim, value] of Object.entries(delta.scoring)) lines.push(`- **${dim}:** ${value}`);
+  lines.push('');
+  lines.push(`**Verdict:** ${delta.verdict.replace(/_/g, ' ')}`); lines.push('');
+  lines.push(delta.summary);
+  return lines.join('\n');
+}
+
+// ─── JSON report parsing (v0.3.3) ─────────────────────────────────────
+
+function parseCompareReportJson(report) {
+  if (!report || !report.diff) return { axes: {}, verdict: 'trajectory_unchanged' };
+
+  const axes = {};
+  // Extract axes from structured report format
+  if (report.diff.axes) {
+    for (const [axis, value] of Object.entries(report.diff.axes)) {
+      if (value && String(value).toUpperCase() !== 'SAME') axes[axis] = String(value);
+    }
+    return { axes, verdict: report.diff.verdict || 'trajectory_unchanged' };
+  }
+
+  // Legacy: raw baseline/kdna comparison
+  if (report.without_kdna && report.with_kdna) {
+    if (report.without_kdna.classification !== report.with_kdna.classification)
+      axes.classification = 'changed';
+    return { axes, verdict: Object.keys(axes).length > 0 ? 'trajectory_changed' : 'trajectory_unchanged' };
+  }
+
+  return { axes: {}, verdict: 'trajectory_unchanged' };
+}
+
+function createJudgmentDeltaFromReport(domain, input, report, options = {}) {
+  const { axes, verdict } = parseCompareReportJson(report);
+  const domainScore = scoreDelta(axes);
+
+  return {
+    meta: { domain, input: (input || '').slice(0, 200), model: report.meta?.model || options.model || 'unknown',
+      timestamp: new Date().toISOString() },
+    classification: { without_kdna: axes.classification || 'generic',
+      with_kdna: axes.classification ? 'domain_specific' : 'unchanged', changed: !!axes.classification },
+    axes, verdict,
+    score: domainScore.score,
+    changed_dimensions: domainScore.changed,
+    triggered_axioms: options.triggeredAxioms || [],
+    avoided_misunderstandings: options.avoidedMisunderstandings || [],
+    self_checks_passed: options.selfChecksPassed || null,
+    scoring: buildScoring(axes, domainScore, options.selfChecksPassed),
+    summary: buildSummary(domain, domainScore, verdict),
+  };
+}
+
+module.exports = { parseCompareOutput, parseCompareReportJson, scoreDelta,
+  createJudgmentDelta, createJudgmentDeltaFromReport, compareDeltas, formatDeltaMarkdown };

package/src/testlab/index.js

@@ -0,0 +1,116 @@
+/**
+ * Test Lab — Validate that a KDNA domain actually changes agent judgment.
+ *
+ * Core operations:
+ *   - Create test cases (input → expected_without_kdna → expected_with_kdna)
+ *   - Run comparison through kdna-cli compare
+ *   - Record human rating
+ *   - Attach tests to cards
+ *   - Export evals for KDNA domain
+ */
+
+function createTestCase(input, options = {}) {
+  return {
+    id: `test_${require('crypto').randomUUID()}`,
+    input,
+    expected_without_kdna: options.expectedWithout || '',
+    expected_with_kdna: options.expectedWith || '',
+    domain: options.domain || null,
+    result: null, // 'with_kdna_better' | 'no_difference' | 'without_kdna_better'
+    human_rating: null,
+    rated_by: null,
+    rated_at: null,
+    notes: '',
+    linked_cards: [],
+    created_at: new Date().toISOString(),
+  };
+}
+
+function recordHumanRating(testCase, result, ratedBy, notes = '') {
+  const validResults = ['with_kdna_better', 'no_difference', 'without_kdna_better'];
+  if (!validResults.includes(result)) throw new Error(`Invalid result: ${result}. Must be one of: ${validResults.join(', ')}`);
+  testCase.result = result;
+  testCase.human_rating = result;
+  testCase.rated_by = ratedBy;
+  testCase.rated_at = new Date().toISOString();
+  testCase.notes = notes;
+  return testCase;
+}
+
+function linkTestToCards(testCase, cardIds) {
+  testCase.linked_cards = [...new Set([...testCase.linked_cards, ...cardIds])];
+  return testCase;
+}
+
+function applyTestResultsToCards(project, testCase) {
+  if (!testCase.result) return project;
+  const cards = project.cards || [];
+  for (const cardId of (testCase.linked_cards || [])) {
+    const card = cards.find(c => c.id === cardId);
+    if (!card) continue;
+    if (card.status === 'locked' && testCase.result === 'with_kdna_better') {
+      const { transitionCard } = require('../cards');
+      try {
+        transitionCard(card, 'tested', { by: testCase.rated_by || 'testlab', reason: `test ${testCase.id}: ${testCase.result}` });
+      } catch { /* card may have been already tested */ }
+    }
+  }
+  return project;
+}
+
+function generateTestSummary(project) {
+  const tests = project.tests || [];
+  const total = tests.length;
+  const rated = tests.filter(t => t.result).length;
+  const withKdnaBetter = tests.filter(t => t.result === 'with_kdna_better').length;
+  const noDiff = tests.filter(t => t.result === 'no_difference').length;
+  const withoutBetter = tests.filter(t => t.result === 'without_kdna_better').length;
+
+  return {
+    total,
+    rated,
+    unrated: total - rated,
+    with_kdna_better: withKdnaBetter,
+    with_kdna_better_pct: total > 0 ? Math.round((withKdnaBetter / rated) * 100) : 0,
+    no_difference: noDiff,
+    without_kdna_better: withoutBetter,
+    passing: withKdnaBetter >= Math.ceil(rated * 0.6), // at least 60% of rated tests should favor KDNA
+  };
+}
+
+function exportEvals(project) {
+  const tests = (project.tests || []).filter(t => t.result);
+  return tests.map(t => ({
+    id: t.id,
+    input: t.input,
+    expected_without_kdna: t.expected_without_kdna || null,
+    expected_with_kdna: t.expected_with_kdna || null,
+    result: t.result,
+    linked_cards: t.linked_cards,
+    rated_by: t.rated_by,
+    rated_at: t.rated_at,
+    notes: t.notes,
+  }));
+}
+
+function compareAdapter(domainName, input, options = {}) {
+  // Returns the CLI command and args for kdna compare
+  const args = ['compare', domainName, '--input', input];
+  if (options.reportMd) args.push('--report-md');
+  if (options.reportJson) args.push('--report-json');
+  if (options.output) args.push('--output', options.output);
+  return {
+    command: 'kdna',
+    args,
+    description: 'Runs kdna compare to test judgment impact',
+  };
+}
+
+module.exports = {
+  createTestCase,
+  recordHumanRating,
+  linkTestToCards,
+  generateTestSummary,
+  exportEvals,
+  compareAdapter,
+};