@aikdna/studio-core 0.1.0

package/src/quality/contradiction.js

@@ -0,0 +1,172 @@
+/**
+ * Contradiction Check — Surface conflicts, gaps, and weak judgment.
+ *
+ * Detects:
+ *   - Axiom contradictions (two axioms that cannot both be true)
+ *   - Missing boundaries (axiom lacks does_not_apply_when)
+ *   - Weak self-checks (not a yes/no question, too vague)
+ *   - Over-generalized axioms (too broad to be testable)
+ *   - Straw-man misunderstandings (describes something no one believes)
+ *   - Missing counterexamples (misunderstanding lacks a real example)
+ */
+
+function detectContradictions(cards) {
+  const issues = [];
+  const axioms = cards.filter(c => c.type === 'axiom' && c.locked);
+
+  // Check for missing boundaries on locked axioms
+  for (const ax of axioms) {
+    if (!ax.fields?.does_not_apply_when || ax.fields.does_not_apply_when.length === 0) {
+      issues.push({
+        type: 'missing_boundary',
+        card_id: ax.id,
+        severity: 'blocking',
+        message: `${ax.id}: locked axiom lacks does_not_apply_when`,
+        fix: 'Define at least one situation where this axiom should NOT be applied.',
+      });
+    }
+    if (!ax.fields?.applies_when || ax.fields.applies_when.length === 0) {
+      issues.push({
+        type: 'missing_applicability',
+        card_id: ax.id,
+        severity: 'blocking',
+        message: `${ax.id}: locked axiom lacks applies_when`,
+        fix: 'Define at least one situation where this axiom applies.',
+      });
+    }
+    if (ax.fields?.full_statement && ax.fields.full_statement.length < 30) {
+      issues.push({
+        type: 'too_short',
+        card_id: ax.id,
+        severity: 'warning',
+        message: `${ax.id}: full_statement is very short — may be too vague`,
+      });
+    }
+
+    // Check for over-generalization: axioms that use absolute language without boundaries
+    const oneLiner = (ax.fields?.one_sentence || '').toLowerCase();
+    if (/\b(always|never|every|all|none|must)\b/.test(oneLiner) && (!ax.fields.does_not_apply_when || ax.fields.does_not_apply_when.length === 0)) {
+      issues.push({
+        type: 'overgeneralized',
+        card_id: ax.id,
+        severity: 'warning',
+        message: `${ax.id}: uses absolute language ("${oneLiner.match(/always|never|every|all|none|must/)[0]}") but has no does_not_apply_when`,
+        fix: 'Add does_not_apply_when to prevent this axiom from being applied universally.',
+      });
+    }
+  }
+
+  // Check misunderstandings
+  const misunderstandings = cards.filter(c => c.type === 'misunderstanding' && c.locked);
+  for (const ms of misunderstandings) {
+    const wrong = ms.fields?.wrong || '';
+    const correct = ms.fields?.correct || '';
+
+    // Check for straw-man: the "wrong" belief describes something no real person would believe
+    if (wrong.length < 15) {
+      issues.push({
+        type: 'vague_misunderstanding',
+        card_id: ms.id,
+        severity: 'warning',
+        message: `${ms.id}: wrong belief description is very short — may not describe a real mistake`,
+      });
+    }
+
+    // Check the wrong and correct are actually different (not just negation)
+    const wrongWords = new Set(wrong.toLowerCase().split(/\s+/).filter(w => w.length > 3));
+    const correctWords = correct.toLowerCase().split(/\s+/).filter(w => w.length > 3);
+    const sharedWords = correctWords.filter(w => wrongWords.has(w)).length;
+    if (correctWords.length > 0 && sharedWords / correctWords.length > 0.7) {
+      issues.push({
+        type: 'weak_distinction',
+        card_id: ms.id,
+        severity: 'warning',
+        message: `${ms.id}: wrong and correct share ${Math.round(sharedWords / correctWords.length * 100)}% of words — distinction may be too weak`,
+      });
+    }
+
+    // Key distinction check
+    if (!ms.fields?.key_distinction || ms.fields.key_distinction.length < 20) {
+      issues.push({
+        type: 'missing_distinction',
+        card_id: ms.id,
+        severity: 'blocking',
+        message: `${ms.id}: key_distinction missing or too short`,
+        fix: 'Explain the conceptual boundary between the wrong belief and the correct one.',
+      });
+    }
+  }
+
+  // Check self-checks
+  const selfChecks = cards.filter(c => c.type === 'self_check' && c.locked);
+  for (const sc of selfChecks) {
+    const question = sc.fields?.question || '';
+    if (!question.trim().endsWith('?')) {
+      issues.push({
+        type: 'not_a_question',
+        card_id: sc.id,
+        severity: 'blocking',
+        message: `${sc.id}: self_check must be phrased as a question ending with ?`,
+      });
+    }
+    if (question.length < 15) {
+      issues.push({
+        type: 'vague_check',
+        card_id: sc.id,
+        severity: 'warning',
+        message: `${sc.id}: self_check question is very short — may be too vague to verify`,
+      });
+    }
+    // Check for generic self-checks
+    const genericPatterns = ['is this good', 'is this correct', 'is this helpful', 'is this clear', 'is this response', 'is the response', 'good enough', 'is it good'];
+    if (genericPatterns.some(p => question.toLowerCase().includes(p))) {
+      issues.push({
+        type: 'generic_check',
+        card_id: sc.id,
+        severity: 'warning',
+        message: `${sc.id}: self_check is too generic — should be domain-specific`,
+        fix: 'Rephrase with domain-specific criteria, e.g. "Did the agent diagnose the type of uncertainty before suggesting action?"',
+      });
+    }
+  }
+
+  // Check boundaries
+  const boundaries = cards.filter(c => c.type === 'boundary' && c.locked);
+  for (const bd of boundaries) {
+    if (bd.fields?.out_of_scope && bd.fields.out_of_scope.length < 10) {
+      issues.push({
+        type: 'vague_boundary',
+        card_id: bd.id,
+        severity: 'warning',
+        message: `${bd.id}: out_of_scope is very short — boundary may be unclear`,
+      });
+    }
+    if (!bd.fields?.acceptable_exceptions || bd.fields.acceptable_exceptions.length === 0) {
+      issues.push({
+        type: 'no_exceptions',
+        card_id: bd.id,
+        severity: 'warning',
+        message: `${bd.id}: no acceptable_exceptions declared — every boundary has justified exceptions`,
+      });
+    }
+  }
+
+  return issues;
+}
+
+function summarizeContradictions(issues) {
+  const blocking = issues.filter(i => i.severity === 'blocking');
+  const warnings = issues.filter(i => i.severity === 'warning');
+  return {
+    total: issues.length,
+    blocking: blocking.length,
+    warnings: warnings.length,
+    clean: issues.length === 0,
+    by_type: issues.reduce((acc, i) => {
+      acc[i.type] = (acc[i.type] || 0) + 1;
+      return acc;
+    }, {}),
+  };
+}
+
+module.exports = { detectContradictions, summarizeContradictions };

package/src/quality/index.js

@@ -0,0 +1,65 @@
+/**
+ * Quality gates and readiness scoring.
+ *
+ * Four quality grades:
+ *   draft_grade          — structure exists, at least 3 human-reviewed cards
+ *   human_controlled     — all core axioms locked, each with applies_when/does_not_apply_when/failure_risk
+ *   tested_grade         — at least 5 eval cases, at least 3 comparison tests
+ *   publishable_grade    — at least 10 evals, README complete, kdna verify --judgment passes
+ */
+function computeReadiness(project) {
+  const cards = project.cards || [];
+  const locked = cards.filter(c => c.locked);
+  const tests = project.tests || [];
+
+  const blocking = [];
+  const warnings = [];
+
+  // Check minimum locked axioms
+  const lockedAxioms = locked.filter(c => c.type === 'axiom');
+  if (lockedAxioms.length < 1) blocking.push('At least 1 locked axiom required');
+  if (lockedAxioms.length < 3) warnings.push('Recommend at least 3 locked axioms');
+
+  // Check boundary completeness
+  for (const ax of lockedAxioms) {
+    if (!ax.fields?.does_not_apply_when?.length) {
+      blocking.push(`${ax.id}: missing does_not_apply_when`);
+    }
+    if (!ax.fields?.failure_risk) {
+      warnings.push(`${ax.id}: missing failure_risk`);
+    }
+    if (!ax.human_lock) {
+      blocking.push(`${ax.id}: missing human_lock`);
+    }
+    if (!ax.feynman_restatement) {
+      warnings.push(`${ax.id}: missing Feynman restatement`);
+    }
+  }
+
+  // Check self-checks
+  const lockedSelfChecks = locked.filter(c => c.type === 'self_check');
+  for (const sc of lockedSelfChecks) {
+    if (sc.fields?.question && !sc.fields.question.trim().endsWith('?')) {
+      blocking.push(`${sc.id}: self_check question must end with ?`);
+    }
+  }
+
+  // Determine grade
+  let grade = 'draft_grade';
+  const axiomsComplete = lockedAxioms.every(ax =>
+    ax.fields?.applies_when?.length && ax.fields?.does_not_apply_when?.length && ax.human_lock
+  );
+  if (axiomsComplete && locked.length >= 3) grade = 'human_controlled';
+  if (axiomsComplete && tests.length >= 5) grade = 'tested_grade';
+  if (axiomsComplete && tests.length >= 10 && lockedSelfChecks.length >= 3) grade = 'publishable_grade';
+
+  return {
+    grade,
+    publishable: grade === 'publishable_grade' && blocking.length === 0,
+    blocking,
+    warnings,
+    score: Math.max(0, 100 - blocking.length * 15 - warnings.length * 5),
+  };
+}
+
+module.exports = { computeReadiness };

package/src/testlab/index.js

@@ -0,0 +1,100 @@
+/**
+ * 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_${Date.now().toString(36)}`,
+    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 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,
+};

package/src/versioning/index.js

@@ -0,0 +1 @@
+module.exports = {};

package/tests/core.test.js

@@ -0,0 +1,132 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { createProject, validateProject } = require('../src/project');
+const { createCard, lockCard, getLockedCards, transitionCard } = require('../src/cards');
+const { compileDomain } = require('../src/compile');
+const { computeReadiness } = require('../src/quality');
+const { buildProvenance } = require('../src/provenance');
+
+// ─── Project ──────────────────────────────────────────────────────────
+
+test('createProject returns valid project', () => {
+  const p = createProject('test_domain');
+  assert.equal(p.name, 'test_domain');
+  assert.equal(p.type, 'domain');
+  assert.equal(p.status, 'drafting');
+  assert.ok(p.project_id);
+  assert.ok(Array.isArray(p.cards));
+});
+
+test('validateProject catches missing name', () => {
+  const r = validateProject({ type: 'domain', cards: [] });
+  assert.equal(r.valid, false);
+  assert.ok(r.issues.length > 0);
+});
+
+// ─── Cards State Machine ──────────────────────────────────────────────
+
+test('createCard returns draft card', () => {
+  const card = createCard('axiom', { one_sentence: 'Test axiom' });
+  assert.equal(card.status, 'draft');
+  assert.equal(card.locked, false);
+  assert.equal(card.type, 'axiom');
+});
+
+test('transitionCard: draft → revised', () => {
+  const card = createCard('axiom', {});
+  transitionCard(card, 'revised', { by: 'test_user' });
+  assert.equal(card.status, 'revised');
+});
+
+test('transitionCard blocks draft → locked', () => {
+  const card = createCard('axiom', {});
+  assert.throws(() => transitionCard(card, 'locked'), /Invalid transition/);
+});
+
+test('lockCard sets human_lock and transitions to locked', () => {
+  const card = createCard('axiom', { one_sentence: 'Test' });
+  transitionCard(card, 'revised', { by: 'test_user' });
+  lockCard(card, {
+    by: 'test_user',
+    statement: 'I confirm this judgment.',
+    checked: { applies_when: true, does_not_apply_when: true, failure_risk: true },
+  });
+  assert.equal(card.status, 'locked');
+  assert.equal(card.locked, true);
+  assert.ok(card.human_lock);
+  assert.equal(card.human_lock.by, 'test_user');
+});
+
+test('lockCard rejects missing checked fields', () => {
+  const card = createCard('axiom', {});
+  transitionCard(card, 'revised', { by: 'test_user' });
+  assert.throws(() => lockCard(card, { by: 'u', statement: 'ok', checked: {} }), /applies_when/);
+});
+
+test('getLockedCards filters correctly', () => {
+  const project = { cards: [] };
+  const c1 = createCard('axiom', {});
+  transitionCard(c1, 'revised', { by: 'u' });
+  lockCard(c1, { by: 'u', statement: 'ok', checked: { applies_when: true, does_not_apply_when: true, failure_risk: true } });
+  project.cards.push(c1);
+  project.cards.push(createCard('misunderstanding', {})); // draft
+  assert.equal(getLockedCards(project).length, 1);
+});
+
+// ─── Compile ──────────────────────────────────────────────────────────
+
+test('compileDomain only includes locked cards', () => {
+  const project = createProject('test');
+  const card = createCard('axiom', {
+    one_sentence: 'Test axiom.',
+    full_statement: 'Full statement.',
+    why: 'Because.',
+    applies_when: ['when testing'],
+    does_not_apply_when: ['when not testing'],
+    failure_risk: 'Test may fail.',
+  });
+  transitionCard(card, 'revised', { by: 'u' });
+  lockCard(card, { by: 'u', statement: 'ok', checked: { applies_when: true, does_not_apply_when: true, failure_risk: true } });
+  project.cards = [card, createCard('axiom', { one_sentence: 'Draft axiom' })];
+
+  const result = compileDomain(project);
+  assert.ok('KDNA_Core.json' in result.files);
+  assert.equal(result.stats.locked_cards, 1);
+  assert.equal(result.stats.excluded_cards, 1);
+});
+
+// ─── Quality ──────────────────────────────────────────────────────────
+
+test('computeReadiness empty project → draft_grade', () => {
+  const r = computeReadiness({ cards: [], tests: [] });
+  assert.equal(r.grade, 'draft_grade');
+  assert.equal(r.publishable, false);
+});
+
+test('computeReadiness locked cards → human_controlled', () => {
+  const project = createProject('test');
+  const card = createCard('axiom', {
+    one_sentence: 'Test.',
+    applies_when: ['when test'],
+    does_not_apply_when: ['when not test'],
+    failure_risk: 'risk',
+  });
+  transitionCard(card, 'revised', { by: 'u' });
+  lockCard(card, { by: 'u', statement: 'ok', checked: { applies_when: true, does_not_apply_when: true, failure_risk: true } });
+  project.cards = [card];
+  const r = computeReadiness(project);
+  assert.equal(r.grade, 'draft_grade'); // still need 3 locked cards for human_controlled
+  assert.ok(r.warnings.length > 0);
+});
+
+// ─── Provenance ───────────────────────────────────────────────────────
+
+test('buildProvenance returns metadata', () => {
+  const project = createProject('test', 'domain', { author: { name: 'Tester', id: 'tester' } });
+  project.cards = [];
+  const prov = buildProvenance(project, {});
+  assert.equal(prov.studio_core, 'knowledge-dna/kdna-studio');
+  assert.ok(prov.build_id);
+  assert.ok(prov.content_fingerprint);
+});