@aikdna/studio-core 0.1.0 → 0.3.0

package/src/quality/validate-cards.js

@@ -0,0 +1,163 @@
+/**
+ * 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 || '';
+
+  if (!question.endsWith('?')) {
+    issues.push({ type: 'not_question', severity: 'blocking', message: `${card.id}: must be a question ending with ?` });
+  }
+
+  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,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,
+};