@aikdna/studio-core 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/studio-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "KDNA Studio Core — pure logic library for authoring, validating, and compiling KDNA domain judgment packages.",
   "type": "commonjs",
   "main": "src/index.js",

package/src/index.js

@@ -29,6 +29,7 @@ const versioning = require('./versioning');
 const feynman = require('./cards/feynman');
 const contradiction = require('./quality/contradiction');
 const validateCards = require('./quality/validate-cards');
+const delta = require('./testlab/delta');
 
 module.exports = {
   cards,
@@ -43,4 +44,5 @@ module.exports = {
   feynman,
   contradiction,
   validateCards,
+  delta,
 };

package/src/testlab/delta.js

@@ -0,0 +1,160 @@
+/**
+ * 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 === 0) {
+    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');
+}
+
+module.exports = { parseCompareOutput, scoreDelta, createJudgmentDelta, compareDeltas, formatDeltaMarkdown };

package/src/versioning/index.js

@@ -1 +1,181 @@
-module.exports = {};
+/**
+ * Versioning — Judgment-aware version management.
+ *
+ * KDNA versioning tracks judgment changes, not just text diffs.
+ * A version bump is based on:
+ *   - PATCH: wording fixes, clarifications (no judgment change)
+ *   - MINOR: new axioms, misunderstandings, self-checks added
+ *   - MAJOR: axioms removed, domain scope changed, access mode changed
+ *
+ * Provides:
+ *   - Judgment diff between two project snapshots
+ *   - Changelog generation from audit logs
+ *   - Version bump recommendation
+ *   - Semantic version tracking
+ */
+
+function diffProjects(oldProject, newProject) {
+  const oldCards = oldProject.cards || [];
+  const newCards = newProject.cards || [];
+
+  const oldById = new Map(oldCards.map(c => [c.id, c]));
+  const newById = new Map(newCards.map(c => [c.id, c]));
+
+  const added = [];
+  const removed = [];
+  const changed = [];
+  const unchanged = [];
+
+  for (const [id, newCard] of newById) {
+    if (!oldById.has(id)) {
+      added.push({ id, type: newCard.type, one_sentence: newCard.fields?.one_sentence || newCard.fields?.question || '' });
+    } else {
+      const oldCard = oldById.get(id);
+      if (JSON.stringify(oldCard.fields) !== JSON.stringify(newCard.fields)) {
+        const fieldChanges = diffFields(oldCard.fields || {}, newCard.fields || {});
+        changed.push({ id, type: newCard.type, changes: fieldChanges });
+      } else if (oldCard.status !== newCard.status) {
+        changed.push({ id, type: newCard.type, status_change: { from: oldCard.status, to: newCard.status } });
+      } else {
+        unchanged.push(id);
+      }
+    }
+  }
+
+  for (const [id, oldCard] of oldById) {
+    if (!newById.has(id)) {
+      removed.push({ id, type: oldCard.type, one_sentence: oldCard.fields?.one_sentence || oldCard.fields?.question || '' });
+    }
+  }
+
+  return {
+    added,
+    removed,
+    changed,
+    unchanged: unchanged.length,
+    summary: {
+      added_count: added.length,
+      removed_count: removed.length,
+      changed_count: changed.length,
+      unchanged_count: unchanged.length,
+    },
+  };
+}
+
+function diffFields(oldFields, newFields) {
+  const changes = {};
+  for (const key of new Set([...Object.keys(oldFields), ...Object.keys(newFields)])) {
+    const oldVal = JSON.stringify(oldFields[key] || null);
+    const newVal = JSON.stringify(newFields[key] || null);
+    if (oldVal !== newVal) {
+      changes[key] = { before: oldFields[key] || null, after: newFields[key] || null };
+    }
+  }
+  return changes;
+}
+
+function recommendVersionBump(diff) {
+  const { added, removed, changed } = diff;
+
+  // MAJOR: axioms removed or domain structure changed
+  const axiomsRemoved = removed.filter(c => c.type === 'axiom').length;
+  const misunderstandingsRemoved = removed.filter(c => c.type === 'misunderstanding').length;
+  if (axiomsRemoved > 0 || misunderstandingsRemoved > 0) return 'major';
+
+  // MINOR: new axioms, misunderstandings, or field changes on existing cards
+  const axiomsAdded = added.filter(c => c.type === 'axiom').length;
+  const misunderstandingsAdded = added.filter(c => c.type === 'misunderstanding').length;
+  if (axiomsAdded > 0 || misunderstandingsAdded > 0 || changed.length > 0) return 'minor';
+
+  // PATCH: wording-only changes (status changes, new self-checks, new boundaries)
+  if (added.length > 0 || changed.length > 0) return 'patch';
+
+  return 'none';
+}
+
+function generateChangelog(diff, oldVersion, newVersion, options = {}) {
+  const lines = [];
+  lines.push(`# ${options.domain || 'domain'} v${newVersion}`);
+  lines.push('');
+  lines.push(`**Previous:** v${oldVersion}`);
+  lines.push(`**Bump:** ${recommendVersionBump(diff).toUpperCase()}`);
+  lines.push('');
+
+  if (diff.summary.added_count > 0) {
+    lines.push('## Added');
+    lines.push('');
+    for (const card of diff.added) {
+      lines.push(`- **${card.type}** \`${card.id}\`: ${card.one_sentence}`);
+    }
+    lines.push('');
+  }
+
+  if (diff.summary.removed_count > 0) {
+    lines.push('## Removed');
+    lines.push('');
+    for (const card of diff.removed) {
+      lines.push(`- **${card.type}** \`${card.id}\`: ${card.one_sentence}`);
+    }
+    lines.push('');
+  }
+
+  if (diff.summary.changed_count > 0) {
+    lines.push('## Changed');
+    lines.push('');
+    for (const card of diff.changed) {
+      lines.push(`- **${card.type}** \`${card.id}\``);
+      if (card.status_change) {
+        lines.push(`  - Status: ${card.status_change.from} → ${card.status_change.to}`);
+      }
+      if (card.changes && Object.keys(card.changes).length > 0) {
+        for (const [field, change] of Object.entries(card.changes)) {
+          const before = typeof change.before === 'string' ? change.before.slice(0, 80) : JSON.stringify(change.before).slice(0, 80);
+          const after = typeof change.after === 'string' ? change.after.slice(0, 80) : JSON.stringify(change.after).slice(0, 80);
+          lines.push(`  - ${field}: "${before}" → "${after}"`);
+        }
+      }
+    }
+    lines.push('');
+  }
+
+  if (diff.summary.added_count === 0 && diff.summary.removed_count === 0 && diff.summary.changed_count === 0) {
+    lines.push('No judgment changes detected.');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function bumpVersion(currentVersion, bumpType) {
+  const parts = currentVersion.split('.').map(Number);
+  switch (bumpType) {
+    case 'major': return `${parts[0] + 1}.0.0`;
+    case 'minor': return `${parts[0]}.${parts[1] + 1}.0`;
+    case 'patch': return `${parts[0]}.${parts[1]}.${parts[2] + 1}`;
+    default: return currentVersion;
+  }
+}
+
+function markBreakingChange(diff) {
+  const axiomsRemoved = diff.removed.filter(c => c.type === 'axiom').length;
+  const scopeChanges = diff.changed.filter(c =>
+    c.changes && ('applies_when' in c.changes || 'does_not_apply_when' in c.changes)
+  ).length;
+  return {
+    breaking: axiomsRemoved > 0,
+    reason: axiomsRemoved > 0
+      ? `${axiomsRemoved} axiom(s) removed — breaking change`
+      : scopeChanges > 0
+        ? `${scopeChanges} scope change(s) — may affect existing agent behavior`
+        : null,
+    recommended_bump: recommendVersionBump(diff),
+  };
+}
+
+module.exports = {
+  diffProjects,
+  recommendVersionBump,
+  generateChangelog,
+  bumpVersion,
+  markBreakingChange,
+};

package/tests/milestone3.test.js

@@ -0,0 +1,156 @@
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { createProject } = require('../src/project');
+const { createCard, lockCard, transitionCard } = require('../src/cards');
+const { parseCompareOutput, createJudgmentDelta, compareDeltas, formatDeltaMarkdown, scoreDelta } = require('../src/testlab/delta');
+const { diffProjects, recommendVersionBump, generateChangelog, bumpVersion, markBreakingChange } = require('../src/versioning');
+
+function makeLockedCard(type, fields, id) {
+  const card = createCard(type, fields, id);
+  transitionCard(card, 'revised', { by: 'tester' });
+  lockCard(card, { by: 'tester', statement: 'ok', checked: { applies_when: true, does_not_apply_when: true, failure_risk: true } });
+  return card;
+}
+
+// ─── Judgment Delta ──────────────────────────────────────────────────
+
+describe('Judgment Delta', () => {
+  const DIFF_TEXT = `1. CLASSIFICATION: language_polishing → structural_diagnosis
+2. DIAGNOSIS: The root cause was identified as a missing argument rather than poor wording.
+3. ACTIONS: Suggested deletion more than rewriting — structural fix, not surface polish.
+4. BOUNDARY AWARENESS: SAME
+5. TERMINOLOGY: Used domain-specific terms like judgment_pressure and cognitive_hook.
+VERDICT: trajectory_changed`;
+
+  test('parseCompareOutput extracts axes', () => {
+    const result = parseCompareOutput(DIFF_TEXT);
+    assert.equal(result.verdict, 'trajectory_changed');
+    assert.ok(result.axes.classification);
+    assert.ok(result.axes.diagnosis);
+    assert.ok(result.axes.actions);
+    assert.ok(!result.axes.boundary_awareness); // SAME → omitted
+  });
+
+  test('scoreDelta counts changed axes', () => {
+    const axes = { classification: 'changed', diagnosis: 'changed', terminology: 'changed' };
+    const result = scoreDelta(axes);
+    assert.equal(result.score, 8); // 5 + 3
+    assert.equal(result.changed.length, 3);
+  });
+
+  test('createJudgmentDelta builds full report', () => {
+    const delta = createJudgmentDelta('@aikdna/writing', 'Help me improve this post',
+      'Generic response...', 'Domain-specific response...', DIFF_TEXT,
+      { model: 'claude-sonnet-4-5', triggeredAxioms: ['ax_001'], selfChecksPassed: 5 }
+    );
+    assert.equal(delta.meta.domain, '@aikdna/writing');
+    assert.equal(delta.verdict, 'trajectory_changed');
+    assert.ok(delta.score >= 8);
+    assert.ok(delta.summary.includes('dimensions'));
+    assert.ok(delta.scoring.D1_diagnostic_depth >= 5);
+  });
+
+  test('createJudgmentDelta handles no-change verdict', () => {
+    const noChangeText = '1. CLASSIFICATION: SAME\n2. DIAGNOSIS: SAME\nVERDICT: trajectory_unchanged';
+    const delta = createJudgmentDelta('test', 'input', 'a', 'b', noChangeText);
+    assert.equal(delta.verdict, 'trajectory_unchanged');
+    assert.equal(delta.score, 5);
+    assert.ok(delta.summary.includes('did not significantly alter'));
+  });
+
+  test('compareDeltas shows improvement', () => {
+    const d1 = createJudgmentDelta('test', 'input', 'a', 'b', DIFF_TEXT);
+    const betterText = DIFF_TEXT.replace('SAME', 'Improved boundary awareness with explicit scope limits');
+    const d2 = createJudgmentDelta('test', 'input', 'a', 'b', betterText);
+    const cmp = compareDeltas(d1, d2);
+    assert.ok(cmp.improved);
+  });
+
+  test('formatDeltaMarkdown produces readable report', () => {
+    const delta = createJudgmentDelta('@aikdna/writing', 'test input', 'a', 'b', DIFF_TEXT);
+    const md = formatDeltaMarkdown(delta);
+    assert.ok(md.includes('# KDNA Judgment Comparison Report'));
+    assert.ok(md.includes('## Judgment Diff'));
+    assert.ok(md.includes('## Scoring'));
+    assert.ok(md.includes('Verdict'));
+  });
+
+  test('parseCompareOutput handles legacy format', () => {
+    const legacyText = 'classification: changed\nterminology: domain_specific\nVERDICT: trajectory_changed';
+    const result = parseCompareOutput(legacyText);
+    assert.equal(result.verdict, 'trajectory_changed');
+    assert.ok(result.axes.classification);
+  });
+});
+
+// ─── Versioning ──────────────────────────────────────────────────────
+
+describe('Versioning', () => {
+  test('diffProjects detects added cards', () => {
+    const oldProject = createProject('test');
+    const newProject = createProject('test');
+    newProject.cards = [makeLockedCard('axiom', { one_sentence: 'New axiom.' }, 'ax_001')];
+    const diff = diffProjects(oldProject, newProject);
+    assert.equal(diff.added.length, 1);
+    assert.equal(diff.removed.length, 0);
+  });
+
+  test('diffProjects detects removed cards', () => {
+    const oldProject = createProject('test');
+    oldProject.cards = [makeLockedCard('axiom', { one_sentence: 'Old.' }, 'ax_001')];
+    const newProject = createProject('test');
+    const diff = diffProjects(oldProject, newProject);
+    assert.equal(diff.removed.length, 1);
+  });
+
+  test('diffProjects detects changed fields', () => {
+    const oldProject = createProject('test');
+    oldProject.cards = [makeLockedCard('axiom', { one_sentence: 'Old text.', full_statement: 'Old full.' }, 'ax_001')];
+    const newProject = createProject('test');
+    newProject.cards = [makeLockedCard('axiom', { one_sentence: 'New text.', full_statement: 'New full.' }, 'ax_001')];
+    const diff = diffProjects(oldProject, newProject);
+    assert.equal(diff.changed.length, 1);
+    assert.ok(diff.changed[0].changes.one_sentence);
+  });
+
+  test('recommendVersionBump: MAJOR for removed axiom', () => {
+    const diff = { added: [], removed: [{ type: 'axiom' }], changed: [], summary: { added_count: 0, removed_count: 1, changed_count: 0 } };
+    assert.equal(recommendVersionBump(diff), 'major');
+  });
+
+  test('recommendVersionBump: MINOR for added axiom', () => {
+    const diff = { added: [{ type: 'axiom' }], removed: [], changed: [], summary: { added_count: 1, removed_count: 0, changed_count: 0 } };
+    assert.equal(recommendVersionBump(diff), 'minor');
+  });
+
+  test('recommendVersionBump: PATCH for field changes', () => {
+    const diff = { added: [], removed: [], changed: [{}], summary: { added_count: 0, removed_count: 0, changed_count: 1 } };
+    assert.equal(recommendVersionBump(diff), 'minor');
+  });
+
+  test('bumpVersion increments correctly', () => {
+    assert.equal(bumpVersion('0.1.0', 'patch'), '0.1.1');
+    assert.equal(bumpVersion('0.1.0', 'minor'), '0.2.0');
+    assert.equal(bumpVersion('0.1.0', 'major'), '1.0.0');
+    assert.equal(bumpVersion('2.3.5', 'none'), '2.3.5');
+  });
+
+  test('generateChangelog produces markdown', () => {
+    const oldProject = createProject('test');
+    const newProject = createProject('test');
+    newProject.cards = [makeLockedCard('axiom', { one_sentence: 'New axiom for agent judgment.' }, 'ax_001')];
+    const diff = diffProjects(oldProject, newProject);
+    const changelog = generateChangelog(diff, '0.1.0', '0.2.0', { domain: 'test' });
+    assert.ok(changelog.includes('# test v0.2.0'));
+    assert.ok(changelog.includes('MINOR'));
+    assert.ok(changelog.includes('ax_001'));
+  });
+
+  test('markBreakingChange detects axiom removal', () => {
+    const diff = { added: [], removed: [{ type: 'axiom' }], changed: [], summary: { added_count: 0, removed_count: 1, changed_count: 0 } };
+    const result = markBreakingChange(diff);
+    assert.equal(result.breaking, true);
+    assert.ok(result.reason.includes('breaking change'));
+  });
+});