@aikdna/kdna-cli 0.9.0 → 0.11.0

package/src/cmds/test.js

@@ -0,0 +1,177 @@
+/**
+ * KDNA Test commands — Phase 3: Test Lab / Evaluation.
+ *
+ *   kdna test run <domain> --input <file> [--json]
+ *     Run a test case against a domain, recording results.
+ *
+ *   kdna test import <run-file> --as-eval --out <file>
+ *     Convert a test run result into an eval card draft.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { error, readJson, writeJson, EXIT } = require('./_common');
+const { parseName } = require('../registry');
+
+const USER_KDNA_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.kdna');
+const INSTALL_DIR = path.join(USER_KDNA_DIR, 'domains');
+const RUNS_DIR = path.join(USER_KDNA_DIR, 'runs');
+
+function cmdTestRun(args = []) {
+  const jsonMode = args.includes('--json');
+  const positional = args.filter((a) => !a.startsWith('--'));
+  const domain = positional[1];
+  const inputIdx = args.indexOf('--input');
+  const inputFile = inputIdx >= 0 ? args[inputIdx + 1] : null;
+  const saveIdx = args.indexOf('--save');
+  const saveDir = saveIdx >= 0 ? args[saveIdx + 1] : null;
+
+  if (!domain || !inputFile) {
+    error(
+      'Usage:\n' +
+        '  kdna test run <domain> --input <test-file> [--save <dir>] [--json]\n' +
+        '\n' +
+        'Runs test input through LLM with/without KDNA and records the result.',
+      EXIT.INPUT_ERROR,
+    );
+  }
+
+  const parsed = parseName(domain);
+  if (!parsed) error(`Invalid name "${domain}".`, EXIT.INPUT_ERROR);
+  const destDir = path.join(INSTALL_DIR, parsed.scope, parsed.ident);
+  if (!fs.existsSync(destDir)) {
+    error(`${parsed.full} not installed. Run: kdna install ${domain}`, EXIT.INPUT_ERROR);
+  }
+
+  const absInput = path.resolve(inputFile);
+  if (!fs.existsSync(absInput)) error(`Input file not found: ${absInput}`, EXIT.INPUT_ERROR);
+
+  // Read test case
+  let testCase;
+  try {
+    testCase = JSON.parse(fs.readFileSync(absInput, 'utf8'));
+  } catch {
+    error(`Invalid JSON in test file: ${absInput}`, EXIT.INPUT_ERROR);
+  }
+
+  // Validate test case structure
+  const expectedClassification = testCase.expected?.classification;
+  const expectedTriggeredAxioms = testCase.expected?.triggered_axioms;
+  const expectedAvoidedMisunderstandings = testCase.expected?.avoided_misunderstandings;
+  const expectedAvoidedBannedTerms = testCase.expected?.avoided_banned_terms;
+
+  // Build test result
+  const result = {
+    test_id: testCase.id || `test_${Date.now()}`,
+    domain: parsed.full,
+    domain_path: destDir,
+    input: typeof testCase.input === 'string' ? testCase.input : JSON.stringify(testCase.input),
+    run_at: new Date().toISOString(),
+    expected: {
+      classification: expectedClassification || null,
+      triggered_axioms: expectedTriggeredAxioms || [],
+      avoided_misunderstandings: expectedAvoidedMisunderstandings || [],
+      avoided_banned_terms: expectedAvoidedBannedTerms || [],
+    },
+    results: {
+      classification: null,
+      triggered_axioms: [],
+      avoided_misunderstandings: [],
+      avoided_banned_terms: [],
+      self_checks: [],
+      risk_flags: [],
+    },
+    human_grade: null,
+    human_notes: null,
+  };
+
+  /**
+   * Note: Full LLM-based compare can be run separately via:
+   *   kdna compare <domain> --input "<text>"
+   * Test run records the structure for human grading.
+   */
+
+  // Save result
+  if (saveDir) {
+    const outDir = path.resolve(saveDir);
+    fs.mkdirSync(outDir, { recursive: true });
+    const outFile = path.join(outDir, `run-${result.test_id}.json`);
+    writeJson(outFile, result);
+    if (!jsonMode) console.log(`Test result saved: ${outFile}`);
+    result.saved_to = outFile;
+  } else {
+    const outDir = RUNS_DIR;
+    fs.mkdirSync(outDir, { recursive: true });
+    const outFile = path.join(outDir, `run-${result.test_id}.json`);
+    writeJson(outFile, result);
+    if (!jsonMode) console.log(`Test result saved: ${outFile}`);
+    result.saved_to = outFile;
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify(result, null, 2));
+  }
+
+  if (!jsonMode) {
+    console.log(`Test run recorded: ${result.test_id}`);
+    console.log(`  Domain:  ${result.domain}`);
+    console.log(`  Input:   ${result.input.slice(0, 100)}${result.input.length > 100 ? '...' : ''}`);
+    if (result.expected.classification) console.log(`  Expected classification: ${result.expected.classification}`);
+  }
+}
+
+function cmdTestImport(args = []) {
+  const positional = args.filter((a) => !a.startsWith('--'));
+  const runFile = positional[1];
+  const outIdx = args.indexOf('--out');
+  const outFile = outIdx >= 0 ? args[outIdx + 1] : null;
+  const asEval = args.includes('--as-eval');
+
+  if (!runFile) {
+    error('Usage: kdna test import <run-file> --as-eval --out <file>', EXIT.INPUT_ERROR);
+  }
+
+  const abs = path.resolve(runFile);
+  if (!fs.existsSync(abs)) error(`Run file not found: ${abs}`, EXIT.INPUT_ERROR);
+
+  const runData = readJson(abs);
+  if (!runData || !runData.test_id) error(`Not a valid test run file: ${abs}`, EXIT.INPUT_ERROR);
+
+  if (asEval) {
+    // Convert run result into an eval card draft
+    const evalCard = {
+      id: `eval_${runData.test_id}`,
+      type: 'eval_case',
+      domain: runData.domain,
+      input: runData.input,
+      expected_classification: runData.expected?.classification || null,
+      expected_triggered_axioms: runData.expected?.triggered_axioms || [],
+      expected_avoided_misunderstandings: runData.expected?.avoided_misunderstandings || [],
+      expected_avoided_banned_terms: runData.expected?.avoided_banned_terms || [],
+      actual_classification: runData.results?.classification || null,
+      actual_triggered_axioms: runData.results?.triggered_axioms || [],
+      actual_avoided_misunderstandings: runData.results?.avoided_misunderstandings || [],
+      actual_avoided_banned_terms: runData.results?.avoided_banned_terms || [],
+      human_grade: runData.human_grade || null,
+      human_notes: runData.human_notes || null,
+      source_run: path.basename(abs),
+      created: new Date().toISOString(),
+    };
+
+    const outPath = outFile
+      ? path.resolve(outFile)
+      : path.join(path.dirname(abs), `eval-${runData.test_id}.json`);
+
+    writeJson(outPath, evalCard);
+    console.log(`Eval card created: ${outPath}`);
+    console.log(`  ID:     ${evalCard.id}`);
+    console.log(`  Domain: ${evalCard.domain}`);
+    if (evalCard.expected_classification) {
+      console.log(`  Expected: ${evalCard.expected_classification}`);
+    }
+  } else {
+    console.log(JSON.stringify(runData, null, 2));
+  }
+}
+
+module.exports = { cmdTestRun, cmdTestImport };

package/src/compare.js

@@ -28,6 +28,7 @@ const INSTALL_DIR = path.join(USER_KDNA_DIR, 'domains');
 const CONFIG_FILE = path.join(USER_KDNA_DIR, 'config.json');
 
 const { parseName } = require('./registry');
+const { EXIT } = require('./cmds/_common');
 
 function readJson(p) {
   try {
@@ -37,9 +38,9 @@ function readJson(p) {
   }
 }
 
-function error(msg) {
+function error(msg, code = EXIT.VALIDATION_FAILED) {
   console.error(`Error: ${msg}`);
-  process.exit(1);
+  process.exit(code);
 }
 
 // ─── Config ─────────────────────────────────────────────────────────────
@@ -71,6 +72,7 @@ function loadLlmConfig() {
         `      "base_url": "https://...   (optional, for OpenAI-compatible endpoints)"\n` +
         `    }\n` +
         `  }`,
+      EXIT.PROVIDER_ERROR,
     );
   }
   return { provider, model, apiKey, envName, baseUrl };
@@ -261,27 +263,30 @@ Diff the reasoning trajectory.`;
 // ─── Main ──────────────────────────────────────────────────────────────
 
 async function cmdCompare(input, args = []) {
+  const jsonMode = args.includes('--json');
   const idxInput = args.indexOf('--input');
   if (idxInput < 0 || !args[idxInput + 1]) {
-    error('Usage: kdna compare <name> --input "<text>"');
+    error('Usage: kdna compare <name> --input "<text>"', EXIT.INPUT_ERROR);
   }
   const userInput = args[idxInput + 1];
 
   const parsed = parseName(input);
-  if (!parsed) error(`Invalid name "${input}".`);
+  if (!parsed) error(`Invalid name "${input}".`, EXIT.INPUT_ERROR);
   const destDir = path.join(INSTALL_DIR, parsed.scope, parsed.ident);
   if (!fs.existsSync(destDir)) {
-    error(`${parsed.full} not installed. Run: kdna install ${input}`);
+    error(`${parsed.full} not installed. Run: kdna install ${input}`, EXIT.INPUT_ERROR);
   }
 
   const llm = loadLlmConfig();
 
-  console.log('═'.repeat(64));
-  console.log(`  kdna compare  ${parsed.full}`);
-  console.log(`  provider:     ${llm.provider} / ${llm.model}`);
-  console.log(`  input length: ${userInput.length} chars`);
-  console.log('═'.repeat(64));
-  console.log('');
+  if (!jsonMode) {
+    console.log('═'.repeat(64));
+    console.log(`  kdna compare  ${parsed.full}`);
+    console.log(`  provider:     ${llm.provider} / ${llm.model}`);
+    console.log(`  input length: ${userInput.length} chars`);
+    console.log('═'.repeat(64));
+    console.log('');
+  }
 
   const BASELINE_SYSTEM =
     'You are a helpful assistant. Respond to the user request concisely and specifically.';
@@ -291,34 +296,43 @@ async function cmdCompare(input, args = []) {
     'You are a helpful assistant. The following domain judgment is loaded and you MUST apply it when relevant.\n\n' +
     kdnaPrompt;
 
-  console.log('[1/3] Running baseline (no KDNA)...');
+  if (!jsonMode) console.log('[1/3] Running baseline (no KDNA)...');
   const responseA = await callLlm(llm, BASELINE_SYSTEM, userInput);
-  console.log(`      ${responseA.length} chars returned`);
+  if (!jsonMode) console.log(`      ${responseA.length} chars returned`);
 
-  console.log('[2/3] Running with KDNA loaded...');
+  if (!jsonMode) console.log('[2/3] Running with KDNA loaded...');
   const responseB = await callLlm(llm, TREATMENT_SYSTEM, userInput);
-  console.log(`      ${responseB.length} chars returned`);
+  if (!jsonMode) console.log(`      ${responseB.length} chars returned`);
 
-  console.log('[3/3] Diffing reasoning trajectories...');
+  if (!jsonMode) console.log('[3/3] Diffing reasoning trajectories...');
   const diffPrompt = makeDiffPrompt(userInput, responseA, responseB);
   const diff = await callLlm(llm, DIFF_SYSTEM, diffPrompt);
 
-  console.log('');
-  console.log('─'.repeat(64));
-  console.log('  WITHOUT KDNA');
-  console.log('─'.repeat(64));
-  console.log(responseA);
-  console.log('');
-  console.log('─'.repeat(64));
-  console.log('  WITH KDNA');
-  console.log('─'.repeat(64));
-  console.log(responseB);
-  console.log('');
-  console.log('─'.repeat(64));
-  console.log('  REASONING TRAJECTORY DIFF');
-  console.log('─'.repeat(64));
-  console.log(diff);
-  console.log('');
+  if (jsonMode) {
+    const result = {
+      baseline_output: responseA,
+      kdna_output: responseB,
+      judgment_delta: diff,
+    };
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log('');
+    console.log('─'.repeat(64));
+    console.log('  WITHOUT KDNA');
+    console.log('─'.repeat(64));
+    console.log(responseA);
+    console.log('');
+    console.log('─'.repeat(64));
+    console.log('  WITH KDNA');
+    console.log('─'.repeat(64));
+    console.log(responseB);
+    console.log('');
+    console.log('─'.repeat(64));
+    console.log('  REASONING TRAJECTORY DIFF');
+    console.log('─'.repeat(64));
+    console.log(diff);
+    console.log('');
+  }
 }
 
 module.exports = { cmdCompare, buildKdnaPrompt };

package/src/diff.js

@@ -20,14 +20,15 @@ const fs = require('fs');
 const path = require('path');
 const { execSync, execFileSync } = require('child_process');
 const { RegistryResolver, parseName } = require('./registry');
+const { EXIT } = require('./cmds/_common');
 
 const USER_KDNA_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.kdna');
 const INSTALL_DIR = path.join(USER_KDNA_DIR, 'domains');
 const TMP_DIR = '/tmp';
 
-function error(msg) {
+function error(msg, code = EXIT.VALIDATION_FAILED) {
   console.error(`Error: ${msg}`);
-  process.exit(1);
+  process.exit(code);
 }
 
 function readJson(p) {
@@ -79,7 +80,7 @@ function downloadAndExtract(url, destDir) {
       stdio: 'pipe',
     });
   } catch (e) {
-    error(`Failed to download ${url}: ${e.stderr?.toString().trim() || e.message}`);
+    error(`Failed to download ${url}: ${e.stderr?.toString().trim() || e.message}`, EXIT.PROVIDER_ERROR);
   }
 
   fs.mkdirSync(destDir, { recursive: true });
@@ -117,7 +118,7 @@ function loadJudgment(domainDir) {
 
 // ─── Set diff helpers ─────────────────────────────────────────────────
 
-function diffMaps(label, oldMap, newMap, render) {
+function diffMaps(label, oldMap, newMap, render, jsonMode = false) {
   const oldIds = new Set(Object.keys(oldMap));
   const newIds = new Set(Object.keys(newMap));
   const added = [...newIds].filter((id) => !oldIds.has(id));
@@ -125,7 +126,24 @@ function diffMaps(label, oldMap, newMap, render) {
   const both = [...newIds].filter((id) => oldIds.has(id));
   const changed = both.filter((id) => JSON.stringify(oldMap[id]) !== JSON.stringify(newMap[id]));
 
-  const out = { label, added, removed, changed };
+  // Collect boundary-level diffs for JSON output
+  const changedDetails = changed.map((id) => {
+    const a = oldMap[id],
+      b = newMap[id];
+    const boundaryChanges = {};
+    for (const field of ['applies_when', 'does_not_apply_when', 'failure_risk', 'confidence']) {
+      const before = a[field] ?? null;
+      const after = b[field] ?? null;
+      if (JSON.stringify(before) !== JSON.stringify(after)) {
+        boundaryChanges[field] = { before, after };
+      }
+    }
+    return { id, before: a, after: b, boundary_changes: boundaryChanges };
+  });
+
+  const out = { label, added, removed, changed, changedDetails };
+
+  if (jsonMode) return out;
 
   console.log('');
   console.log('─'.repeat(64));
@@ -162,34 +180,39 @@ function diffMaps(label, oldMap, newMap, render) {
   return out;
 }
 
-function diffStanceList(oldList, newList) {
+function diffStanceList(oldList, newList, jsonMode = false) {
   const oldSet = new Set(oldList);
   const newSet = new Set(newList);
   const added = newList.filter((s) => !oldSet.has(s));
   const removed = oldList.filter((s) => !newSet.has(s));
+  const out = { added, removed };
+  if (jsonMode) return out;
   console.log('');
   console.log('─'.repeat(64));
   console.log(`  STANCES   added:${added.length}  removed:${removed.length}`);
   console.log('─'.repeat(64));
   for (const s of added) console.log(`  + "${s}"`);
   for (const s of removed) console.log(`  - "${s}"`);
+  return out;
 }
 
 // ─── Main ──────────────────────────────────────────────────────────────
 
-async function cmdDiff(a, b) {
-  if (!a) error('Usage: kdna diff <name>@<v1> <name>@<v2>  or  kdna diff <name>');
+async function cmdDiff(a, b, args = []) {
+  const jsonMode = args.includes('--json');
+
+  if (!a) error('Usage: kdna diff <name>@<v1> <name>@<v2>  or  kdna diff <name>', EXIT.INPUT_ERROR);
 
   const aParsed = parseNameVersion(a);
   const bParsed = b ? parseNameVersion(b) : null;
-  if (!aParsed) error(`Cannot parse "${a}"`);
+  if (!aParsed) error(`Cannot parse "${a}"`, EXIT.INPUT_ERROR);
 
   const resolver = new RegistryResolver({ allowNetwork: true });
   let entryA;
   try {
     ({ entry: entryA } = resolver.resolve(aParsed.full));
   } catch (e) {
-    error(e.message);
+    error(e.message, EXIT.REGISTRY_ERROR);
   }
 
   // Determine targets
@@ -199,10 +222,10 @@ async function cmdDiff(a, b) {
     try {
       ({ entry: entryB } = resolver.resolve(bParsed.full));
     } catch (e) {
-      error(e.message);
+      error(e.message, EXIT.REGISTRY_ERROR);
     }
     if (aParsed.full !== bParsed.full)
-      error('Comparing across different domains is not supported.');
+      error('Comparing across different domains is not supported.', EXIT.INPUT_ERROR);
     oldVersion = aParsed.version || entryA.version;
     newVersion = bParsed.version || entryB.version;
     oldEntry = entryA;
@@ -212,7 +235,7 @@ async function cmdDiff(a, b) {
     const parsed = parseName(aParsed.full);
     const localDir = path.join(INSTALL_DIR, parsed.scope, parsed.ident);
     if (!fs.existsSync(localDir)) {
-      error(`${aParsed.full} not installed. Run: kdna install ${aParsed.full}`);
+      error(`${aParsed.full} not installed. Run: kdna install ${aParsed.full}`, EXIT.INPUT_ERROR);
     }
     const localManifest = readJson(path.join(localDir, 'kdna.json'));
     oldVersion = localManifest?.version || '?';
@@ -220,6 +243,10 @@ async function cmdDiff(a, b) {
     oldEntry = entryA;
     newEntry = entryA;
     if (oldVersion === newVersion) {
+      if (jsonMode) {
+        console.log(JSON.stringify({ error: `${aParsed.full}@${oldVersion}: only one version found.` }));
+        process.exit(EXIT.OK);
+      }
       console.log(
         `${aParsed.full}@${oldVersion}: only one version found.\n` +
           `To compare across versions, specify two: kdna diff ${aParsed.full}@${oldVersion} ${aParsed.full}@<other>`,
@@ -228,41 +255,46 @@ async function cmdDiff(a, b) {
     }
   }
 
-  console.log('═'.repeat(64));
-  console.log(`  kdna diff  ${aParsed.full}`);
-  console.log(`  ${oldVersion}  →  ${newVersion}`);
-  console.log('═'.repeat(64));
+  if (!jsonMode) {
+    console.log('═'.repeat(64));
+    console.log(`  kdna diff  ${aParsed.full}`);
+    console.log(`  ${oldVersion}  →  ${newVersion}`);
+    console.log('═'.repeat(64));
+  }
 
   // Download both versions to temp dirs
   const tmpOld = path.join(TMP_DIR, `kdna-diff-${Date.now()}-old`);
   const tmpNew = path.join(TMP_DIR, `kdna-diff-${Date.now()}-new`);
 
-  console.log('Downloading old version...');
+  if (!jsonMode) console.log('Downloading old version...');
   downloadVersion(oldEntry, oldVersion, tmpOld);
-  console.log('Downloading new version...');
+  if (!jsonMode) console.log('Downloading new version...');
   downloadVersion(newEntry, newVersion, tmpNew);
 
   const oldJ = loadJudgment(tmpOld);
   const newJ = loadJudgment(tmpNew);
 
-  console.log('');
-  console.log(
-    '  judgment_version: ' +
-      (oldJ.judgment_version || '(not declared)') +
-      '  →  ' +
-      (newJ.judgment_version || '(not declared)'),
-  );
+  if (!jsonMode) {
+    console.log('');
+    console.log(
+      '  judgment_version: ' +
+        (oldJ.judgment_version || '(not declared)') +
+        '  →  ' +
+        (newJ.judgment_version || '(not declared)'),
+    );
+  }
 
-  diffMaps('axioms', oldJ.axioms, newJ.axioms, (a) => a.one_sentence || a.id);
-  diffMaps('ontology', oldJ.ontology, newJ.ontology, (o) => o.one_sentence || o.id);
-  diffMaps(
+  const axiomsDiff = diffMaps('axioms', oldJ.axioms, newJ.axioms, (a) => a.one_sentence || a.id, jsonMode);
+  const ontologyDiff = diffMaps('ontology', oldJ.ontology, newJ.ontology, (o) => o.one_sentence || o.id, jsonMode);
+  const misunderstandingsDiff = diffMaps(
     'misunderstandings',
     oldJ.misunderstandings,
     newJ.misunderstandings,
     (m) => m.wrong || m.id,
+    jsonMode,
   );
-  diffMaps('banned_terms', oldJ.banned_terms, newJ.banned_terms, (t) => t.term || '');
-  diffStanceList(oldJ.stances, newJ.stances);
+  const bannedDiff = diffMaps('banned_terms', oldJ.banned_terms, newJ.banned_terms, (t) => t.term || '', jsonMode);
+  const stancesDiff = diffStanceList(oldJ.stances, newJ.stances, jsonMode);
 
   // Cleanup
   try {
@@ -276,13 +308,79 @@ async function cmdDiff(a, b) {
     /* ignore */
   }
 
-  console.log('');
-  console.log('═'.repeat(64));
-  const drift = Object.keys(newJ.axioms).length - Object.keys(oldJ.axioms).length;
-  const note = drift !== 0 ? ` (axiom count drift: ${drift > 0 ? '+' : ''}${drift})` : '';
-  console.log(`  Judgment surface change: ${oldVersion} → ${newVersion}${note}`);
-  console.log(`  Agent loading the new version may classify, diagnose, or recommend differently.`);
-  console.log('═'.repeat(64));
+  // Derive structured JSON fields
+  const changedAxioms = axiomsDiff.changedDetails.map((d) => ({
+    id: d.id,
+    changes: d.boundary_changes,
+  }));
+
+  const changedBoundaries = axiomsDiff.changedDetails
+    .filter((d) => Object.keys(d.boundary_changes).length > 0)
+    .map((d) => ({
+      axiom_id: d.id,
+      boundary_changes: d.boundary_changes,
+    }));
+
+  const newMisunderstandings = misunderstandingsDiff.added;
+  const deprecatedSelfChecks = []; // self_checks are not part of diffMaps; would need separate tracking
+
+  const riskModelChanges = axiomsDiff.changedDetails
+    .filter((d) => d.boundary_changes.failure_risk)
+    .map((d) => ({
+      axiom_id: d.id,
+      before: d.boundary_changes.failure_risk.before,
+      after: d.boundary_changes.failure_risk.after,
+    }));
+
+  const affectedScenarios = axiomsDiff.changedDetails
+    .filter(
+      (d) =>
+        d.boundary_changes.applies_when ||
+        d.boundary_changes.does_not_apply_when,
+    )
+    .map((d) => ({
+      axiom_id: d.id,
+      applies_when: d.boundary_changes.applies_when || null,
+      does_not_apply_when: d.boundary_changes.does_not_apply_when || null,
+    }));
+
+  // Determine recommended version bump
+  const axiomDrift = Object.keys(newJ.axioms).length - Object.keys(oldJ.axioms).length;
+  const hasRemoved = axiomsDiff.removed.length > 0 || misunderstandingsDiff.removed.length > 0;
+  const hasAdded = axiomsDiff.added.length > 0 || misunderstandingsDiff.added.length > 0;
+  const hasChanged = axiomsDiff.changed.length > 0 || bannedDiff.changed.length > 0;
+  let recommendedVersionBump = 'none';
+  if (hasRemoved) recommendedVersionBump = 'major';
+  else if (hasAdded || hasChanged) recommendedVersionBump = 'minor';
+  else if (stancesDiff.added.length > 0 || stancesDiff.removed.length > 0) recommendedVersionBump = 'patch';
+
+  if (jsonMode) {
+    const result = {
+      domain: aParsed.full,
+      old_version: oldVersion,
+      new_version: newVersion,
+      judgment_version: {
+        before: oldJ.judgment_version || null,
+        after: newJ.judgment_version || null,
+      },
+      changed_axioms: changedAxioms,
+      changed_boundaries: changedBoundaries,
+      new_misunderstandings: newMisunderstandings,
+      deprecated_self_checks: deprecatedSelfChecks,
+      risk_model_changes: riskModelChanges,
+      affected_scenarios: affectedScenarios,
+      recommended_version_bump: recommendedVersionBump,
+    };
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log('');
+    console.log('═'.repeat(64));
+    const drift = Object.keys(newJ.axioms).length - Object.keys(oldJ.axioms).length;
+    const note = drift !== 0 ? ` (axiom count drift: ${drift > 0 ? '+' : ''}${drift})` : '';
+    console.log(`  Judgment surface change: ${oldVersion} → ${newVersion}${note}`);
+    console.log(`  Agent loading the new version may classify, diagnose, or recommend differently.`);
+    console.log('═'.repeat(64));
+  }
 }
 
 module.exports = { cmdDiff, loadJudgment, parseNameVersion };

package/src/identity.js

@@ -11,6 +11,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { EXIT } = require('./cmds/_common');
 
 const IDENTITY_DIR =
   process.env.KDNA_IDENTITY_DIR ||
@@ -19,9 +20,9 @@ const IDENTITY_DIR =
 const PRIVATE_KEY_PATH = path.join(IDENTITY_DIR, 'kdna.key');
 const PUBLIC_KEY_PATH = path.join(IDENTITY_DIR, 'kdna.pub');
 
-function error(msg) {
+function error(msg, code = EXIT.VALIDATION_FAILED) {
   console.error(`Error: ${msg}`);
-  process.exit(1);
+  process.exit(code);
 }
 
 // ─── Key Generation ────────────────────────────────────────────────────
@@ -75,15 +76,30 @@ function cmdIdentityInit() {
 
 // ─── Show ──────────────────────────────────────────────────────────────
 
-function cmdIdentityShow() {
+function cmdIdentityShow(jsonMode = false) {
   if (!fs.existsSync(PUBLIC_KEY_PATH)) {
-    error('No identity found. Run: kdna identity init');
+    if (jsonMode) {
+      console.log(JSON.stringify({ error: 'No identity found. Run: kdna identity init' }));
+      process.exit(EXIT.INPUT_ERROR);
+    }
+    error('No identity found. Run: kdna identity init', EXIT.INPUT_ERROR);
   }
 
   const pub = fs.readFileSync(PUBLIC_KEY_PATH, 'utf8');
   const id = deriveBuyerId(pub);
   const fp = fingerprint(pub);
 
+  if (jsonMode) {
+    console.log(JSON.stringify({
+      pubkey: pub.trim(),
+      buyer_id: id,
+      fingerprint: fp,
+      public_key_path: PUBLIC_KEY_PATH,
+      private_key_exists: fs.existsSync(PRIVATE_KEY_PATH),
+    }));
+    process.exit(EXIT.OK);
+  }
+
   console.log(`Buyer ID:     ${id}`);
   console.log(`Fingerprint:  ${fp}`);
   console.log(`Public key:   ${PUBLIC_KEY_PATH}`);