@aikdna/studio-core 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/studio-core",
-  "version": "0.6.0",
+  "version": "0.7.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

@@ -172,6 +172,14 @@ function compileDomain(project) {
   if (evolution) files['KDNA_Evolution.json'] = JSON.stringify(evolution, null, 2);
   files['kdna.json'] = JSON.stringify(compileManifest(project, files), null, 2);
 
+  // ── KDNA Card (governance metadata) ─────────────────────────────
+  if (project.governance) {
+    const { generateKdnaCard } = require('../governance');
+    const prov = require('../provenance').buildProvenance(project, files);
+    const kdnaCard = generateKdnaCard(project, {}, prov);
+    files['KDNA_CARD.json'] = JSON.stringify(kdnaCard, null, 2);
+  }
+
   const excludedCount = cards.filter(c => !c.locked && !['deprecated'].includes(c.status)).length;
 
   return {

package/src/governance/index.js

@@ -0,0 +1,139 @@
+/**
+ * Governance risk assessment — classify domain risk level and validate governance metadata.
+ *
+ * Risk levels:
+ *   R0 — Low: inconvenience, not harm
+ *   R1 — Medium: suboptimal outcomes
+ *   R2 — High: significant harm possible
+ *   R3 — Restricted: serious harm, not for public registry
+ */
+
+const HIGH_RISK_KEYWORDS = {
+  medical: ['diagnosis', 'treatment', 'symptom', 'patient', 'clinical', 'therapy', 'medication', 'disease', 'prescription', 'surgery', 'medical'],
+  legal: ['lawsuit', 'liability', 'plaintiff', 'defendant', 'jurisdiction', 'statute', 'legal advice', 'attorney', 'court', 'litigation'],
+  financial: ['investment', 'portfolio', 'stock', 'bond', 'retirement', 'insurance', 'mortgage', 'loan', 'tax advice', 'credit score', 'financial advice'],
+  safety: ['weapon', 'surveillance', 'monitoring', 'tracking', 'child safety', 'emergency response', 'public safety', 'self-harm', 'suicide'],
+  decision: ['hiring', 'firing', 'termination', 'employment decision', 'performance review'],
+};
+
+function computeRiskLevel(project) {
+  const cards = project.cards || [];
+  const allText = cards.map(c => {
+    const fields = c.fields || {};
+    return [fields.one_sentence, fields.full_statement, fields.wrong, fields.correct, fields.question,
+      fields.essence, fields.scope, fields.out_of_scope,
+      ...(fields.applies_when || []), ...(fields.does_not_apply_when || [])]
+      .filter(Boolean).join(' ').toLowerCase();
+  }).join(' ');
+
+  // Check declared risk level first
+  const declared = (project.governance && project.governance.risk_level) || null;
+  if (declared === 'R3') return 'R3';
+
+  // Check for high-risk keywords
+  let detectedCategory = null;
+  for (const [category, keywords] of Object.entries(HIGH_RISK_KEYWORDS)) {
+    for (const kw of keywords) {
+      if (allText.includes(kw)) { detectedCategory = category; break; }
+    }
+    if (detectedCategory) break;
+  }
+
+  // If no high-risk keywords found and R0-R2 declared, trust the declaration
+  if (!detectedCategory && declared) return declared;
+
+  // Default risk levels
+  if (['medical', 'safety'].includes(detectedCategory)) return 'R3';
+  if (['legal', 'financial'].includes(detectedCategory)) return 'R2';
+  if (detectedCategory === 'decision') return 'R1';
+
+  return declared || 'R1'; // Default: medium risk
+}
+
+function requiresExpertReview(riskLevel) {
+  return riskLevel === 'R2' || riskLevel === 'R3';
+}
+
+function validateGovernance(project) {
+  const issues = [];
+  const gov = project.governance || {};
+
+  // Required fields
+  if (!gov.risk_level) {
+    issues.push({ type: 'missing_risk_level', severity: 'blocking', message: 'Governance: risk_level must be declared (R0/R1/R2/R3)' });
+  }
+  if (!gov.intended_use || !gov.intended_use.length) {
+    issues.push({ type: 'missing_intended_use', severity: 'blocking', message: 'Governance: intended_use must be declared' });
+  }
+  if (!gov.out_of_scope || !gov.out_of_scope.length) {
+    issues.push({ type: 'missing_out_of_scope', severity: 'blocking', message: 'Governance: out_of_scope must be declared' });
+  }
+  if (!gov.known_limitations || !gov.known_limitations.length) {
+    issues.push({ type: 'missing_limitations', severity: 'blocking', message: 'Governance: known_limitations must be declared' });
+  }
+
+  // Risk level specific checks
+  const riskLevel = gov.risk_level || computeRiskLevel(project);
+  if (requiresExpertReview(riskLevel)) {
+    if (!gov.reviewed_by) {
+      issues.push({ type: 'requires_expert_review', severity: 'blocking', message: `Governance: risk_level ${riskLevel} requires expert_review. reviewed_by must be set.` });
+    }
+    if (!gov.risk_warnings || !gov.risk_warnings.length) {
+      issues.push({ type: 'missing_risk_warnings', severity: 'blocking', message: `Governance: risk_level ${riskLevel} requires risk_warnings.` });
+    }
+  }
+
+  // Check for high-risk keywords in content that might not match declared level
+  const detectedLevel = computeRiskLevel(project);
+  if (gov.risk_level && ['R0', 'R1'].includes(gov.risk_level) && ['R2', 'R3'].includes(detectedLevel)) {
+    issues.push({
+      type: 'risk_mismatch',
+      severity: 'blocking',
+      message: `Governance: declared risk_level ${gov.risk_level} but content analysis suggests ${detectedLevel}. Review required.`,
+    });
+  }
+
+  // Author responsibility required for R1+
+  if (['R1', 'R2', 'R3'].includes(riskLevel) && !gov.author_statement) {
+    issues.push({ type: 'missing_author_statement', severity: 'blocking', message: `Governance: risk_level ${riskLevel} requires author_statement.` });
+  }
+
+  return {
+    valid: issues.filter(i => i.severity === 'blocking').length === 0,
+    issues,
+    risk_level: riskLevel,
+    requires_expert_review: requiresExpertReview(riskLevel),
+  };
+}
+
+function generateKdnaCard(project, compiledStats, provenance) {
+  const gov = project.governance || {};
+  const cards = project.cards || [];
+  const lockedCards = cards.filter(c => c.locked);
+
+  return {
+    name: project.name,
+    version: (project.release && project.release.version) || '0.1.0',
+    risk_level: gov.risk_level || computeRiskLevel(project),
+    intended_use: gov.intended_use || [],
+    out_of_scope: gov.out_of_scope || [],
+    known_limitations: gov.known_limitations || [],
+    author_responsibility: gov.author_statement || '',
+    risk_warnings: gov.risk_warnings || [],
+    human_lock_summary: {
+      locked_cards: lockedCards.length,
+      locked_axioms: lockedCards.filter(c => c.type === 'axiom').length,
+      locked_misunderstandings: lockedCards.filter(c => c.type === 'misunderstanding').length,
+      locked_self_checks: lockedCards.filter(c => c.type === 'self_check').length,
+      feynman_restatements: lockedCards.filter(c => c.feynman_restatement).length,
+      locked_by: (project.author && project.author.id) || 'unknown',
+    },
+    quality_badge: (compiledStats && compiledStats.locked_cards > 0) ? 'tested' : 'untested',
+    review_status: gov.review_status || 'community',
+    requires_expert_review: requiresExpertReview(gov.risk_level || 'R1'),
+    provenance: provenance || {},
+    license: (project.release && project.release.license) || 'CC-BY-4.0',
+  };
+}
+
+module.exports = { computeRiskLevel, requiresExpertReview, validateGovernance, generateKdnaCard, HIGH_RISK_KEYWORDS };

package/src/index.js

@@ -20,6 +20,7 @@
 const cards = require('./cards');
 const compile = require('./compile');
 const evidence = require('./evidence');
+const governance = require('./governance');
 const packaging = require('./packaging');
 const pipeline = require('./pipeline');
 const project = require('./project');
@@ -40,6 +41,7 @@ module.exports = {
   quality,
   provenance,
   pipeline,
+  governance,
 
   // Experimental
   evidence,

package/src/quality/index.js

@@ -12,6 +12,7 @@
 
 const contradiction = require('./contradiction');
 const { validateAllCards } = require('./validate-cards');
+const { validateGovernance } = require('../governance');
 
 function computeReadiness(project) {
   const cards = project.cards || [];
@@ -25,6 +26,12 @@ function computeReadiness(project) {
   const blocking = [];
   const warnings = [];
 
+  // ── Governance check (v0.6.1) ───────────────────────────────────
+  const govResult = validateGovernance(project);
+  for (const issue of govResult.issues) {
+    (issue.severity === 'blocking' ? blocking : warnings).push(`Governance: ${issue.message}`);
+  }
+
   // ── Card validation integration (v0.3.2) ─────────────────────────
   const cardResults = validateAllCards(project);
   for (const { card_id, issues } of cardResults) {
@@ -70,14 +77,44 @@ function computeReadiness(project) {
   const feynmanRatio = lockedAxioms.length > 0 ? lockedAxioms.filter(ax => ax.feynman_restatement).length / lockedAxioms.length : 0;
   const allFeynman = lockedAxioms.every(ax => ax.feynman_restatement) && lockedMisunderstandings.every(ms => !ms.locked || ms.feynman_restatement);
 
+  // Feynman quality threshold (v0.6.2)
+  const feynmanQuality = lockedAxioms.every(ax => {
+    if (!ax.feynman_restatement?.score) return false;
+    return ax.feynman_restatement.score.total >= 4;
+  });
+  const misunderstandingFeynmanQuality = lockedMisunderstandings.length === 0 ||
+    lockedMisunderstandings.every(ms => {
+      if (!ms.feynman_restatement?.score) return false;
+      return ms.feynman_restatement.score.total >= 3;
+    });
+  if (allFeynman && !feynmanQuality) {
+    warnings.push('Feynman: axiom restatements should score ≥4/5 for publishable grade');
+  }
+
+  // Compare test results requirements (v0.6.4)
+  const withKdnaBetter = ratedTests.filter(t => t.result === 'with_kdna_better').length;
+  const withoutKdnaBetter = ratedTests.filter(t => t.result === 'without_kdna_better').length;
+  if (ratedTests.length > 0 && withoutKdnaBetter > 0) {
+    warnings.push(`${withoutKdnaBetter} test(s) favored response WITHOUT KDNA — domain may not improve judgment`);
+  }
+  if (ratedTests.length > 0 && withKdnaBetter < 3 && ratedTests.length >= 5) {
+    warnings.push(`Only ${withKdnaBetter} tests favor KDNA — recommend ≥3 for confidence`);
+  }
+
   let grade = 'draft_grade';
   if (locked.length >= 3 && axiomsComplete && feynmanRatio >= 0.5) grade = 'human_controlled';
   if (grade === 'human_controlled' && ratedTests.length >= 5 && lockedSelfChecks.length >= 3) grade = 'tested_grade';
-  if (grade === 'tested_grade' && ratedTests.length >= 10 && lockedAxioms.length >= 3 && lockedSelfChecks.length >= 5 && blocking.length === 0 && allFeynman) {
+  if (grade === 'tested_grade' && ratedTests.length >= 10 && lockedAxioms.length >= 3 && lockedSelfChecks.length >= 5 && blocking.length === 0 && allFeynman && feynmanQuality && misunderstandingFeynmanQuality) {
     grade = 'publishable_grade';
   }
 
-  return buildResult(grade, blocking, warnings, project, { feynmanRatio, allFeynman });
+  // Downgrade if governance issues exist
+  if (grade === 'publishable_grade' && govResult && !govResult.valid) {
+    grade = 'tested_grade';
+    warnings.push('Governance checks not passed — publishable downgraded to tested');
+  }
+
+  return buildResult(grade, blocking, warnings, project, { feynmanRatio, allFeynman, governance: govResult });
 }
 
 function buildResult(grade, blocking, warnings, project, detail = {}) {
@@ -90,6 +127,7 @@ function buildResult(grade, blocking, warnings, project, detail = {}) {
     blocking,
     warnings,
     score: Math.max(0, 100 - blocking.length * 15 - warnings.length * 3),
+    governance: detail.governance || null,
     stats: {
       total_cards: (project.cards || []).length,
       locked_cards: lockedCount,

package/src/testlab/index.js

@@ -42,6 +42,22 @@ function linkTestToCards(testCase, cardIds) {
   return testCase;
 }
 
+function applyTestResultsToCards(project, testCase) {
+  if (!testCase.result) return project;
+  const cards = project.cards || [];
+  for (const cardId of (testCase.linked_cards || [])) {
+    const card = cards.find(c => c.id === cardId);
+    if (!card) continue;
+    if (card.status === 'locked' && testCase.result === 'with_kdna_better') {
+      const { transitionCard } = require('../cards');
+      try {
+        transitionCard(card, 'tested', { by: testCase.rated_by || 'testlab', reason: `test ${testCase.id}: ${testCase.result}` });
+      } catch { /* card may have been already tested */ }
+    }
+  }
+  return project;
+}
+
 function generateTestSummary(project) {
   const tests = project.tests || [];
   const total = tests.length;

package/src/versioning/index.js

@@ -129,14 +129,19 @@ function bumpVersion(currentVersion, bumpType) {
 }
 
 function markBreakingChange(diff) {
+  const recommended = recommendVersionBump(diff);
   const removedAxioms = diff.removed.filter(c => c.type === 'axiom');
   const scopeWidening = diff.changed.filter(c => c.changes && 'applies_when' in c.changes &&
     (c.changes.applies_when.after || []).length > (c.changes.applies_when.before || []).length);
+  const coreMeaningChanges = diff.changed.filter(c => c.changes &&
+    ('one_sentence' in c.changes || 'full_statement' in c.changes));
+
   return {
-    breaking: removedAxioms.length > 0,
+    breaking: recommended === 'major',
     reason: removedAxioms.length > 0 ? `${removedAxioms.length} axiom(s) removed — breaking change` :
+      coreMeaningChanges.length > 0 ? `${coreMeaningChanges.length} core meaning change(s) — breaking change` :
       scopeWidening.length > 0 ? `${scopeWidening.length} scope widening(s) — may affect existing behavior` : null,
-    recommended_bump: recommendVersionBump(diff),
+    recommended_bump: recommended,
   };
 }