@aikdna/studio-core 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/studio-core",
-  "version": "0.1.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/compile/index.js

@@ -3,32 +3,22 @@
  *
  * Only locked cards enter compilation output.
  * Draft/Revised cards are silently excluded.
+ * Supports full 6-file output: Core / Patterns / Scenarios / Cases / Reasoning / Evolution.
  */
+const provenance = require('../provenance');
 
 function compileCore(cards) {
-  const axioms = cards.filter(c => c.type === 'axiom' && c.locked).map(c => ({
-    id: c.id,
-    ...c.fields,
-  }));
-  const ontology = cards.filter(c => c.type === 'ontology' && c.locked).map(c => ({
-    id: c.id,
-    ...c.fields,
-  }));
+  const axioms = cards.filter(c => c.type === 'axiom' && c.locked).map(c => ({ id: c.id, ...c.fields }));
+  const ontology = cards.filter(c => c.type === 'ontology' && c.locked).map(c => ({ id: c.id, ...c.fields }));
   const frameworks = [];
   const stances = [];
   const boundaries = cards.filter(c => c.type === 'boundary' && c.locked).map(c => ({
     id: c.id,
-    scope: c.fields.scope,
-    out_of_scope: c.fields.out_of_scope,
-    acceptable_exceptions: c.fields.acceptable_exceptions || [],
-  }));
-
-  const risks = cards.filter(c => c.type === 'risk' && c.locked).map(c => ({
-    id: c.id,
-    failure_mode: c.fields.failure_mode,
-    likelihood: c.fields.likelihood,
-    mitigation: c.fields.mitigation,
+    scope: c.fields?.scope || '',
+    out_of_scope: c.fields?.out_of_scope || '',
+    acceptable_exceptions: c.fields?.acceptable_exceptions || [],
   }));
+  const risks = cards.filter(c => c.type === 'risk' && c.locked).map(c => ({ id: c.id, ...c.fields }));
 
   return { axioms, ontology, frameworks, stances, boundaries, risks };
 }
@@ -36,52 +26,98 @@ function compileCore(cards) {
 function compilePatterns(cards) {
   const misunderstandings = cards.filter(c => c.type === 'misunderstanding' && c.locked).map(c => ({
     id: c.id,
-    wrong: c.fields.wrong,
-    correct: c.fields.correct,
-    key_distinction: c.fields.key_distinction,
-    failure_risk: c.fields.failure_risk,
-  }));
-  const selfChecks = cards.filter(c => c.type === 'self_check' && c.locked).map(c => c.fields.question);
-  const bannedTerms = [];
-  const aesthetics = cards.filter(c => c.type === 'aesthetic' && c.locked).map(c => ({
-    id: c.id,
-    preference: c.fields.preference,
-    rationale: c.fields.rationale,
+    wrong: c.fields?.wrong || '',
+    correct: c.fields?.correct || '',
+    key_distinction: c.fields?.key_distinction || '',
+    failure_risk: c.fields?.failure_risk || null,
+    applies_when: c.fields?.applies_when || [],
+    does_not_apply_when: c.fields?.does_not_apply_when || [],
   }));
+  const selfCheckQuestions = cards.filter(c => c.type === 'self_check' && c.locked).map(c => c.fields?.question || '');
+  const aesthetics = cards.filter(c => c.type === 'aesthetic' && c.locked).map(c => ({ id: c.id, ...c.fields }));
 
   const terminology = {
     standard_terms: [],
-    banned_terms: bannedTerms,
+    banned_terms: [],
   };
 
-  return { terminology, misunderstandings, self_check: selfChecks, aesthetics };
+  return { terminology, misunderstandings, self_check: selfCheckQuestions, aesthetics };
 }
 
 function compileScenarios(cards) {
-  return cards.filter(c => c.type === 'scenario' && c.locked).map(c => ({
-    id: c.id,
-    ...c.fields,
-  }));
+  const locked = cards.filter(c => c.type === 'scenario' && c.locked);
+  if (locked.length === 0) return [];
+  return locked.map(c => ({ id: c.id, ...c.fields }));
 }
 
 function compileCases(cards) {
-  return cards.filter(c => c.type === 'case' && c.locked).map(c => ({
-    id: c.id,
-    ...c.fields,
+  const locked = cards.filter(c => c.type === 'case' && c.locked);
+  if (locked.length === 0) return [];
+  return locked.map(c => ({ id: c.id, ...c.fields }));
+}
+
+function compileReasoning(cards) {
+  // Reasoning chains from axiom implications
+  const lockedAxioms = cards.filter(c => c.type === 'axiom' && c.locked);
+  if (lockedAxioms.length === 0) return [];
+  return lockedAxioms.map(ax => ({
+    id: `chain_${ax.id}`,
+    from: ax.fields?.one_sentence || '',
+    logic: [ax.fields?.full_statement || ''],
+    so_what: ax.fields?.why || 'Agent judgment changes when this axiom is loaded.',
   }));
 }
 
+function compileEvolution(cards) {
+  const lockedCards = cards.filter(c => c.locked);
+  if (lockedCards.length === 0) return { stages: [], capability_layers: [], measurements: [] };
+
+  // Build evolution from audit logs
+  const stages = [];
+  const seenAxioms = new Set();
+  for (const card of lockedCards) {
+    if (seenAxioms.has(card.id)) continue;
+    seenAxioms.add(card.id);
+    for (const entry of (card.audit_log || [])) {
+      if (entry.event === 'locked' || entry.event === 'published') {
+        stages.push({
+          card_id: card.id,
+          event: entry.event,
+          at: entry.at,
+          by: entry.by,
+        });
+      }
+    }
+  }
+
+  return {
+    stages: stages.sort((a, b) => a.at.localeCompare(b.at)),
+    capability_layers: [
+      { layer: 1, name: 'Foundation', description: 'Core axioms and patterns established.' },
+    ],
+    measurements: [
+      { metric: 'locked_axioms', value: lockedCards.filter(c => c.type === 'axiom').length },
+      { metric: 'locked_misunderstandings', value: lockedCards.filter(c => c.type === 'misunderstanding').length },
+      { metric: 'self_checks', value: lockedCards.filter(c => c.type === 'self_check').length },
+    ],
+  };
+}
+
 function compileManifest(project) {
-  const lockedCount = project.cards.filter(c => c.locked).length;
+  const lockedCount = (project.cards || []).filter(c => c.locked).length;
+  const cards = project.cards || [];
+  const hasScenarios = cards.some(c => c.type === 'scenario' && c.locked);
+  const hasCases = cards.some(c => c.type === 'case' && c.locked);
+  const fileCount = 2 + (hasScenarios ? 1 : 0) + (hasCases ? 1 : 0) + 2; // Core+Patterns+Reasoning+Evolution (+ Scenarios + Cases)
   return {
     kdna_spec: '1.0-rc',
     name: project.name,
-    version: project.release?.version || '0.1.0',
+    version: (project.release && project.release.version) || '0.1.0',
     status: 'experimental',
-    access: project.release?.access || 'open',
-    author: project.author,
-    description: project.release?.description || project.name,
-    file_count: 2, // Core + Patterns minimum
+    access: (project.release && project.release.access) || 'open',
+    author: project.author || { name: '', id: '' },
+    description: project.name,
+    file_count: 2,
     created: project.created,
     updated: project.updated,
   };
@@ -93,26 +129,129 @@ function compileDomain(project) {
   const patterns = compilePatterns(cards);
   const scenarios = compileScenarios(cards);
   const cases = compileCases(cards);
+  const reasoning = compileReasoning(cards);
+  const evolution = compileEvolution(cards);
   const manifest = compileManifest(project);
 
   const files = {};
   files['KDNA_Core.json'] = JSON.stringify(core, null, 2);
   files['KDNA_Patterns.json'] = JSON.stringify(patterns, null, 2);
-  if (scenarios.length > 0) files['KDNA_Scenarios.json'] = JSON.stringify(scenarios, null, 2);
-  if (cases.length > 0) files['KDNA_Cases.json'] = JSON.stringify(cases, null, 2);
+  if (scenarios.length > 0) files['KDNA_Scenarios.json'] = JSON.stringify({ scenes: scenarios }, null, 2);
+  if (cases.length > 0) files['KDNA_Cases.json'] = JSON.stringify({ cases }, null, 2);
+  if (reasoning.length > 0) files['KDNA_Reasoning.json'] = JSON.stringify({ chains: reasoning }, null, 2);
+  if (evolution.stages && evolution.stages.length > 0) files['KDNA_Evolution.json'] = JSON.stringify(evolution, null, 2);
   files['kdna.json'] = JSON.stringify(manifest, null, 2);
 
-  const excludedCount = (project.cards || []).filter(c => !c.locked && !['deprecated'].includes(c.status)).length;
+  const excludedCount = cards.filter(c => !c.locked && !['deprecated'].includes(c.status)).length;
 
   return {
     files,
     stats: {
-      total_cards: (project.cards || []).length,
-      locked_cards: (project.cards || []).filter(c => c.locked).length,
+      total_cards: cards.length,
+      locked_cards: cards.filter(c => c.locked).length,
       excluded_cards: excludedCount,
-      deprecated_cards: (project.cards || []).filter(c => c.status === 'deprecated').length,
+      deprecated_cards: cards.filter(c => c.status === 'deprecated').length,
+      files_output: Object.keys(files).length,
     },
   };
 }
 
-module.exports = { compileDomain, compileCore, compilePatterns, compileScenarios, compileCases, compileManifest };
+function generateReadme(project, options = {}) {
+  const cards = project.cards || [];
+  const locked = cards.filter(c => c.locked);
+  const lockedAxioms = locked.filter(c => c.type === 'axiom');
+  const lockedMisunderstandings = locked.filter(c => c.type === 'misunderstanding');
+  const lockedSelfChecks = locked.filter(c => c.type === 'self_check');
+  const lockedBoundaries = locked.filter(c => c.type === 'boundary');
+  const tests = project.tests || [];
+
+  const lines = [];
+  lines.push(`# ${project.name}`);
+  lines.push('');
+  if (options.description) {
+    lines.push(options.description);
+    lines.push('');
+  }
+
+  // Four Questions
+  lines.push('## Where it comes from');
+  lines.push('');
+  lines.push(options.origin || `Domain expertise encoded into ${locked.length} judgment cards through structured interview and human lock.`);
+  lines.push('');
+
+  lines.push('## Where it applies');
+  lines.push('');
+  const appliesWhen = [...new Set(lockedAxioms.flatMap(ax => ax.fields?.applies_when || []))];
+  if (appliesWhen.length > 0) {
+    appliesWhen.forEach(w => lines.push(`- ${w}`));
+  } else {
+    lines.push('- As declared in each axiom\'s applies_when field.');
+  }
+  lines.push('');
+
+  lines.push('## How it is verified');
+  lines.push('');
+  lines.push(`- ${tests.length} eval cases (${tests.filter(t => t.result).length} rated)`);
+  lines.push(`- ${lockedAxioms.length} locked axioms with applies_when / does_not_apply_when / failure_risk`);
+  lines.push(`- ${lockedSelfChecks.length} self-check questions`);
+  lines.push(`- ${lockedMisunderstandings.length} misunderstanding patterns`);
+  lines.push('');
+
+  lines.push('## When it does NOT apply');
+  lines.push('');
+  const notApply = [...new Set(lockedAxioms.flatMap(ax => ax.fields?.does_not_apply_when || []))];
+  if (notApply.length > 0) {
+    notApply.forEach(w => lines.push(`- ${w}`));
+  }
+  const outOfScope = lockedBoundaries.flatMap(b => [b.fields?.out_of_scope || '']).filter(Boolean);
+  for (const oos of outOfScope) {
+    if (!notApply.includes(oos)) lines.push(`- ${oos}`);
+  }
+  lines.push('');
+
+  // Top Axioms
+  if (lockedAxioms.length > 0) {
+    lines.push('## Top Axioms');
+    lines.push('');
+    lockedAxioms.forEach(ax => {
+      lines.push(`- **${ax.fields?.one_sentence || ax.id}**`);
+      if (ax.fields?.failure_risk) lines.push(`  - Failure risk: ${ax.fields.failure_risk}`);
+    });
+    lines.push('');
+  }
+
+  // Top Misunderstandings
+  if (lockedMisunderstandings.length > 0) {
+    lines.push('## Top Misunderstandings');
+    lines.push('');
+    lockedMisunderstandings.forEach(ms => {
+      lines.push(`- WRONG: ${ms.fields?.wrong}`);
+      lines.push(`  CORRECT: ${ms.fields?.correct}`);
+    });
+    lines.push('');
+  }
+
+  // Self-checks
+  if (lockedSelfChecks.length > 0) {
+    lines.push('## Eval Score');
+    lines.push('');
+    lines.push(`- quality_badge: ${tests.filter(t => t.result === 'with_kdna_better').length >= 5 ? 'tested' : 'untested'}`);
+    lines.push(`- eval cases: ${tests.length}`);
+    lines.push('');
+  }
+
+  // Files
+  lines.push('## Files');
+  lines.push('');
+  const fileCount = 2
+    + (cards.filter(c => c.type === 'scenario' && c.locked).length > 0 ? 1 : 0)
+    + (cards.filter(c => c.type === 'case' && c.locked).length > 0 ? 1 : 0)
+    + (lockedAxioms.length > 0 ? 1 : 0)
+    + (cards.filter(c => c.status === 'locked' || c.status === 'tested').length > 0 ? 1 : 0);
+  lines.push(`${fileCount} KDNA JSON files + evals/ + demo/`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+module.exports = { compileDomain, compileCore, compilePatterns, compileScenarios, compileCases, compileReasoning, compileEvolution, compileManifest, generateReadme };

package/src/index.js

@@ -28,6 +28,8 @@ const testlab = require('./testlab');
 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,
@@ -41,4 +43,6 @@ module.exports = {
   versioning,
   feynman,
   contradiction,
+  validateCards,
+  delta,
 };

package/src/quality/index.js

@@ -1,65 +1,175 @@
 /**
- * Quality gates and readiness scoring.
+ * Enhanced Quality Gates — 4-grade readiness scoring with detailed rules.
  *
- * 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
+ * Grades:
+ *   draft_grade       — Core+Patterns exist, ≥3 human-reviewed cards
+ *   human_controlled  — All core axioms locked, each with applies_when/does_not_apply_when/failure_risk
+ *   tested_grade      — ≥5 eval cases, ≥3 comparison tests
+ *   publishable_grade — ≥10 evals, README complete, known limitations, kdna verify passes
  */
+const contradiction = require('./contradiction');
+
 function computeReadiness(project) {
   const cards = project.cards || [];
-  const locked = cards.filter(c => c.locked);
   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 ratedTests = tests.filter(t => t.result);
 
   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');
+  // ── Minimum Structure ──────────────────────────────────────────
+  if (project.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);
+  }
 
-  // Check boundary completeness
+  // ── Axiom Checks ──────────────────────────────────────────────
   for (const ax of lockedAxioms) {
-    if (!ax.fields?.does_not_apply_when?.length) {
+    if (!ax.fields?.one_sentence || ax.fields.one_sentence.length < 10) {
+      blocking.push(`${ax.id}: one_sentence too short or missing`);
+    }
+    if (!ax.fields?.full_statement || ax.fields.full_statement.length < 30) {
+      warnings.push(`${ax.id}: full_statement too short — may be vague`);
+    }
+    if (!ax.fields?.why || ax.fields.why.length < 10) {
+      warnings.push(`${ax.id}: missing "why" — explains what the agent gets wrong without this`);
+    }
+    if (!ax.fields?.applies_when || ax.fields.applies_when.length === 0) {
+      blocking.push(`${ax.id}: missing applies_when`);
+    }
+    if (!ax.fields?.does_not_apply_when || ax.fields.does_not_apply_when.length === 0) {
       blocking.push(`${ax.id}: missing does_not_apply_when`);
     }
     if (!ax.fields?.failure_risk) {
-      warnings.push(`${ax.id}: missing failure_risk`);
+      blocking.push(`${ax.id}: missing failure_risk`);
     }
     if (!ax.human_lock) {
-      blocking.push(`${ax.id}: missing human_lock`);
+      blocking.push(`${ax.id}: not locked — must be locked before compile`);
     }
     if (!ax.feynman_restatement) {
       warnings.push(`${ax.id}: missing Feynman restatement`);
     }
   }
 
-  // Check self-checks
-  const lockedSelfChecks = locked.filter(c => c.type === 'self_check');
+  // ── Self-check Checks ──────────────────────────────────────────
   for (const sc of lockedSelfChecks) {
-    if (sc.fields?.question && !sc.fields.question.trim().endsWith('?')) {
-      blocking.push(`${sc.id}: self_check question must end with ?`);
+    const q = sc.fields?.question || '';
+    if (!q.endsWith('?')) {
+      blocking.push(`${sc.id}: self_check must be a question ending with ?`);
+    }
+    if (q.length < 15) {
+      warnings.push(`${sc.id}: self_check question too short — may be too vague`);
+    }
+    if (/\b(is this good|is this correct|is this helpful|is this clear|good enough)\b/i.test(q)) {
+      warnings.push(`${sc.id}: self_check is generic — should be domain-specific`);
+    }
+  }
+
+  // ── Misunderstanding Checks ────────────────────────────────────
+  const lockedMisunderstandings = locked.filter(c => c.type === 'misunderstanding');
+  for (const ms of lockedMisunderstandings) {
+    if (!ms.fields?.key_distinction || ms.fields.key_distinction.length < 20) {
+      blocking.push(`${ms.id}: key_distinction missing or too short`);
+    }
+    if (!ms.fields?.wrong || ms.fields.wrong.length < 10) {
+      warnings.push(`${ms.id}: wrong belief very short — may be a straw man`);
     }
+    if (!ms.fields?.correct || ms.fields.correct.length < 10) {
+      warnings.push(`${ms.id}: correct belief very short`);
+    }
+  }
+
+  // ── Boundary Checks ────────────────────────────────────────────
+  const lockedBoundaries = locked.filter(c => c.type === 'boundary');
+  for (const bd of lockedBoundaries) {
+    if (bd.fields?.acceptable_exceptions && bd.fields.acceptable_exceptions.length === 0) {
+      warnings.push(`${bd.id}: no acceptable_exceptions — every boundary has justified exceptions`);
+    }
+  }
+
+  // ── Contradiction Check ────────────────────────────────────────
+  const contradictions = contradiction.detectContradictions(cards);
+  for (const c of contradictions) {
+    if (c.severity === 'blocking') blocking.push(c.message);
+    else warnings.push(c.message);
+  }
+
+  // ── Test Count Checks ──────────────────────────────────────────
+  if (ratedTests.length === 0 && locked.length >= 3) {
+    warnings.push('No rated tests — domain may not actually change agent behavior');
   }
+  if (ratedTests.length < 3 && ratedTests.length > 0) {
+    warnings.push(`Only ${ratedTests.length} rated tests — recommend at least 3 for confidence`);
+  }
+
+  // ── 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 boundariesComplete = lockedBoundaries.length === 0 ||
+    lockedBoundaries.every(b => b.fields?.scope && b.fields?.out_of_scope);
 
-  // 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';
+  if (locked.length >= 3 && axiomsComplete) {
+    grade = 'human_controlled';
+  }
+  if (grade === 'human_controlled' && ratedTests.length >= 5 && lockedSelfChecks.length >= 3 && boundariesComplete) {
+    grade = 'tested_grade';
+  }
+  if (grade === 'tested_grade' &&
+      ratedTests.length >= 10 &&
+      lockedAxioms.length >= 3 &&
+      lockedSelfChecks.length >= 5 &&
+      blocking.length === 0) {
+    grade = 'publishable_grade';
+  }
+
+  return buildResult(grade, blocking, warnings, project);
+}
+
+function buildResult(grade, blocking, warnings, project) {
+  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 * 5),
+    score: Math.max(0, 100 - blocking.length * 15 - warnings.length * 3),
+    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,
+    },
+    next_step: grade === 'draft_grade'
+      ? 'Lock at least 3 axioms with applies_when, does_not_apply_when, and failure_risk.'
+      : grade === 'human_controlled'
+        ? 'Add 5+ eval cases and run kdna compare to reach tested grade.'
+        : grade === 'tested_grade'
+          ? 'Add 10+ evals, 3+ axioms, 5+ self-checks, and pass kdna verify --judgment to reach publishable.'
+          : 'Ready to publish. Run kdna pack and kdna publish.',
   };
 }
 
-module.exports = { computeReadiness };
+function getBlockingIssues(project) {
+  const result = computeReadiness(project);
+  return result.blocking;
+}
+
+module.exports = { computeReadiness, getBlockingIssues };