@aikdna/studio-core 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/studio-core",
-  "version": "0.1.0",
+  "version": "0.2.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,7 @@ const testlab = require('./testlab');
 const versioning = require('./versioning');
 const feynman = require('./cards/feynman');
 const contradiction = require('./quality/contradiction');
+const validateCards = require('./quality/validate-cards');
 
 module.exports = {
   cards,
@@ -41,4 +42,5 @@ module.exports = {
   versioning,
   feynman,
   contradiction,
+  validateCards,
 };

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 };

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/tests/milestone2.test.js

@@ -0,0 +1,285 @@
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { createProject } = require('../src/project');
+const { createCard, lockCard, transitionCard, createFeynmanRestatement, attachRestatementToLock } = require('../src/cards');
+const { computeReadiness } = require('../src/quality');
+const { detectContradictions } = require('../src/quality/contradiction');
+const { validateCard, validateAllCards } = require('../src/quality/validate-cards');
+const { compileDomain, generateReadme } = require('../src/compile');
+const { createTestCase, recordHumanRating } = require('../src/testlab');
+const { buildProvenance } = require('../src/provenance');
+
+function makeLockedCard(type, fields = {}, id = null) {
+  const card = createCard(type, fields, id);
+  transitionCard(card, 'revised', { by: 'tester' });
+  lockCard(card, {
+    by: 'tester',
+    statement: 'I confirm this judgment.',
+    checked: { applies_when: true, does_not_apply_when: true, failure_risk: true },
+  });
+  return card;
+}
+
+// ─── Quality Gates (4-grade scoring) ─────────────────────────────────
+
+describe('Quality Gates', () => {
+  test('draft_grade: empty project', () => {
+    const r = computeReadiness({ cards: [], tests: [] });
+    assert.equal(r.grade, 'draft_grade');
+    assert.equal(r.publishable, false);
+    assert.ok(r.blocking.length > 0);
+  });
+
+  test('draft_grade: no locked cards → nothing to compile', () => {
+    const project = createProject('test');
+    project.cards = [createCard('axiom', { one_sentence: 'Draft.' })];
+    const r = computeReadiness(project);
+    assert.equal(r.grade, 'draft_grade');
+    assert.ok(r.blocking.some(b => b.includes('nothing to compile') || b.includes('No locked cards')));
+  });
+
+  test('human_controlled: 3+ locked axioms with boundaries ', () => {
+    const project = createProject('test');
+    for (let i = 0; i < 3; i++) {
+      const ax = makeLockedCard('axiom', {
+        one_sentence: `Axiom ${i}: a specific testable judgment principle.`,
+        full_statement: `Full statement for axiom ${i} explaining what the agent should do differently.`,
+        why: 'Without this, agents would get this specific thing wrong.',
+        applies_when: [`situation ${i}a`, `situation ${i}b`],
+        does_not_apply_when: [`not when ${i}`],
+        failure_risk: `Risk ${i}: misapplying this could cause X.`,
+      });
+      attachRestatementToLock(ax, createFeynmanRestatement(ax, `Simple explanation for axiom ${i}: when you see this situation, do this instead of that, but only if the conditions are right.`));
+      project.cards.push(ax);
+    }
+    const r = computeReadiness(project);
+    assert.equal(r.grade, 'human_controlled');
+    assert.equal(r.stats.locked_axioms, 3);
+    assert.ok(r.score >= 70);
+  });
+
+  test('tested_grade: 5+ rated tests + 3+ self-checks', () => {
+    const project = createProject('test');
+    for (let i = 0; i < 3; i++) {
+      const ax = makeLockedCard('axiom', {
+        one_sentence: `Test axiom ${i}.`,
+        full_statement: `Full statement ${i} with enough detail for the agent.`,
+        why: 'Because.',
+        applies_when: ['when x'],
+        does_not_apply_when: ['when y'],
+        failure_risk: 'risk',
+      });
+      project.cards.push(ax);
+    }
+    for (let i = 0; i < 3; i++) {
+      const sc = makeLockedCard('self_check', { question: `Does the response satisfy condition ${i}?` });
+      project.cards.push(sc);
+    }
+    for (let i = 0; i < 6; i++) {
+      const tc = createTestCase(`input ${i}`);
+      recordHumanRating(tc, i < 4 ? 'with_kdna_better' : 'no_difference', 'tester');
+      project.tests.push(tc);
+    }
+    const r = computeReadiness(project);
+    assert.equal(r.grade, 'tested_grade');
+    assert.equal(r.stats.rated_tests, 6);
+  });
+
+  test('publishable_grade: 10+ eval cases, 3+ axioms, 5+ self-checks', () => {
+    const project = createProject('test');
+    for (let i = 0; i < 4; i++) {
+      project.cards.push(makeLockedCard('axiom', {
+        one_sentence: `Pub axiom ${i} with judgment.`,
+        full_statement: `Full statement ${i} with enough detail for the agent to act on.`,
+        why: 'Without this, agents default to wrong behavior.',
+        applies_when: ['when x'],
+        does_not_apply_when: ['when y'],
+        failure_risk: 'risk of misapplication',
+      }));
+    }
+    for (let i = 0; i < 5; i++) {
+      project.cards.push(makeLockedCard('self_check', { question: `Does the output pass criterion ${i}?` }));
+    }
+    for (let i = 0; i < 12; i++) {
+      const tc = createTestCase(`eval case ${i}`);
+      recordHumanRating(tc, 'with_kdna_better', 'tester');
+      project.tests.push(tc);
+    }
+    const r = computeReadiness(project);
+    assert.equal(r.grade, 'publishable_grade');
+    assert.equal(r.publishable, true);
+    assert.equal(r.blocking.length, 0);
+    assert.ok(r.score >= 75);
+  });
+});
+
+// ─── Anti-Vagueness Validation ──────────────────────────────────────
+
+describe('Card Validation', () => {
+  test('flags slogan-like axiom', () => {
+    const card = createCard('axiom', { one_sentence: 'Trust is important for teams.', full_statement: 'Trust matters.' });
+    const issues = validateCard(card);
+    assert.ok(issues.some(i => i.type === 'slogan' || i.type === 'too_short'));
+  });
+
+  test('flags SOP-like axiom', () => {
+    const card = createCard('axiom', {
+      one_sentence: 'First, you should always remember to follow these steps.',
+      full_statement: 'The process is to first identify the problem.',
+    });
+    const issues = validateCard(card);
+    assert.ok(issues.some(i => i.type === 'sop'));
+  });
+
+  test('flags straw-man misunderstanding', () => {
+    const card = createCard('misunderstanding', {
+      wrong: 'Some people say it is commonly thought that quality matters.',
+      correct: 'Actually it does matter.',
+      key_distinction: 'Quality is about getting things right the first time.',
+    });
+    const issues = validateCard(card);
+    assert.ok(issues.some(i => i.type === 'straw_man'));
+  });
+
+  test('flags generic self_check', () => {
+    const card = createCard('self_check', { question: 'Is this good?' });
+    const issues = validateCard(card);
+    assert.ok(issues.some(i => i.type === 'generic' || i.type === 'vague'));
+  });
+
+  test('validateAllCards aggregates per-card', () => {
+    const project = createProject('test');
+    project.cards = [
+      createCard('axiom', { one_sentence: 'Trust is key.', full_statement: 'Trust matters in everything.' }),
+      createCard('self_check', { question: 'Is it helpful?' }),
+    ];
+    const results = validateAllCards(project);
+    assert.equal(results.length, 2);
+    for (const r of results) {
+      assert.ok(r.card_id);
+      assert.ok(r.issues.length > 0);
+    }
+  });
+});
+
+// ─── Full 6-File Compile ────────────────────────────────────────────
+
+describe('Full Compile', () => {
+  test('produces Core + Patterns minimum', () => {
+    const project = createProject('test');
+    project.cards = [
+      makeLockedCard('axiom', { one_sentence: 'Test.', full_statement: 'Test full.', why: 'Because.', applies_when: ['x'], does_not_apply_when: ['y'], failure_risk: 'risk' }),
+    ];
+    const result = compileDomain(project);
+    assert.ok('KDNA_Core.json' in result.files);
+    assert.ok('KDNA_Patterns.json' in result.files);
+    assert.ok('kdna.json' in result.files);
+    assert.ok(result.stats.files_output >= 4); // Core + Patterns + Reasoning + Evolution minimum
+  });
+
+  test('excludes draft cards from output', () => {
+    const project = createProject('test');
+    project.cards = [
+      makeLockedCard('axiom', { one_sentence: 'Locked.', full_statement: 'FS.', why: 'B.', applies_when: ['x'], does_not_apply_when: ['y'], failure_risk: 'r' }),
+      createCard('axiom', { one_sentence: 'Draft.' }),
+    ];
+    const result = compileDomain(project);
+    assert.equal(result.stats.locked_cards, 1);
+    assert.equal(result.stats.excluded_cards, 1);
+    const core = JSON.parse(result.files['KDNA_Core.json']);
+    assert.equal(core.axioms.length, 1);
+  });
+
+  test('produces Scenarios when scenario cards locked', () => {
+    const project = createProject('test');
+    project.cards = [
+      makeLockedCard('scenario', { id: 'scene_01', name: 'User reports bug', trigger_signal: 'bug report', sub_scenarios: [] }, 'sc_001'),
+    ];
+    const result = compileDomain(project);
+    assert.ok('KDNA_Scenarios.json' in result.files);
+  });
+
+  test('produces Reasoning from axiom implications', () => {
+    const project = createProject('test');
+    project.cards = [
+      makeLockedCard('axiom', { one_sentence: 'Price objections are certainty deficits.', full_statement: 'When a buyer says too expensive, first diagnose which type of uncertainty is blocking them.', why: 'Without this axiom, agents default to offering discounts instead of diagnosing.', applies_when: ['price objection'], does_not_apply_when: ['explicit discount request'], failure_risk: 'Agent may seem evasive.' }),
+    ];
+    const result = compileDomain(project);
+    assert.ok('KDNA_Reasoning.json' in result.files);
+    const reasoning = JSON.parse(result.files['KDNA_Reasoning.json']);
+    assert.ok(reasoning.chains.length > 0);
+    assert.equal(reasoning.chains[0].so_what, 'Without this axiom, agents default to offering discounts instead of diagnosing.');
+  });
+
+  test('produces Evolution from audit logs', () => {
+    const project = createProject('test');
+    const card = makeLockedCard('axiom', { one_sentence: 'Evolution test.', full_statement: 'FS.', why: 'B.', applies_when: ['x'], does_not_apply_when: ['y'], failure_risk: 'r' });
+    project.cards = [card];
+    const result = compileDomain(project);
+    const evo = JSON.parse(result.files['KDNA_Evolution.json']);
+    assert.ok(evo.stages.length > 0);
+    assert.equal(evo.measurements[0].metric, 'locked_axioms');
+    assert.equal(evo.measurements[0].value, 1);
+  });
+});
+
+// ─── README Generation ──────────────────────────────────────────────
+
+describe('README Generation', () => {
+  test('generates README with 4 questions', () => {
+    const project = createProject('leadership_decisions', 'domain', { author: { name: 'Expert' } });
+    project.cards = [
+      makeLockedCard('axiom', {
+        one_sentence: 'Execution failure is decision failure in disguise.',
+        full_statement: 'When a team fails to execute, first check whether a real decision was ever made.',
+        why: 'Without this axiom, managers address symptoms while missing the root cause.',
+        applies_when: ['Team reports being stuck'],
+        does_not_apply_when: ['Clear decision exists'],
+        failure_risk: 'May cause over-scrutiny of decision quality when issue is resources.',
+      }),
+      makeLockedCard('misunderstanding', {
+        wrong: 'If the team is not executing, they lack motivation.',
+        correct: 'If the team is not executing, first check whether a decision with owner+deadline+criteria was made.',
+        key_distinction: 'Motivation gaps produce gradual decline. Decision voids produce sudden stalls.',
+      }),
+      makeLockedCard('self_check', { question: 'Did I verify that a concrete decision exists before diagnosing the team?' }),
+    ];
+    project.tests = [];
+    for (let i = 0; i < 6; i++) {
+      const tc = createTestCase(`test ${i}`);
+      recordHumanRating(tc, 'with_kdna_better', 'expert');
+      project.tests.push(tc);
+    }
+
+    const readme = generateReadme(project, {
+      description: 'Leadership decision-making judgment — diagnose whether execution failures are really decision voids.',
+      origin: '15 years of leadership coaching across 200+ teams.',
+    });
+
+    assert.ok(readme.includes('# leadership_decisions'));
+    assert.ok(readme.includes('## Where it comes from'));
+    assert.ok(readme.includes('## Where it applies'));
+    assert.ok(readme.includes('## How it is verified'));
+    assert.ok(readme.includes('## When it does NOT apply'));
+    assert.ok(readme.includes('15 years'));
+    assert.ok(readme.includes('quality_badge: tested'));
+  });
+});
+
+// ─── Provenance with Compile ────────────────────────────────────────
+
+describe('Provenance Integration', () => {
+  test('buildProvenance captures compile metadata', () => {
+    const project = createProject('test', 'domain', { author: { name: 'Author', id: 'auth_001' } });
+    project.cards = [
+      makeLockedCard('axiom', { one_sentence: 'T.', full_statement: 'FS.', why: 'B.', applies_when: ['x'], does_not_apply_when: ['y'], failure_risk: 'r' }),
+    ];
+    const compiled = compileDomain(project);
+    const prov = buildProvenance(project, compiled.files);
+    assert.equal(prov.author_id, 'auth_001');
+    assert.equal(prov.locked_card_count, 1);
+    assert.ok(prov.build_id.startsWith('build_'));
+    assert.ok(prov.content_fingerprint.startsWith('sha256:'));
+  });
+});