@aikdna/kdna-studio-cli 0.8.8 → 0.8.10

package/bin/kdna-studio.js

@@ -83,6 +83,8 @@ Create (three entry paths):
 
 Migrate (dev source or Studio project → canonical .kdna in one command):
   kdna-studio migrate <source-dir|project> --format v1 --out <file.kdna> --name <@scope/name> --by <id> --statement <text> [--allow-incomplete] [--sign] [--passphrase <pw>|--passphrase-stdin]
+  kdna-studio migrate <source-dir> --check --name <@scope/name>   # pre-flight: report which fields would block the export without writing the .kdna
+  kdna-studio audit-locks <project> [--type axiom|risk|stance|...] [--json]   # list cards with missing Human Lock fields (per-card-type, per-field)
 
 Authoring:
   kdna-studio import <project> <source-file-or-dir>               # import evidence (txt/md/json/yaml/csv/log/srt/vtt/html)
@@ -114,6 +116,7 @@ Distillation:
   kdna-studio candidate override <project> <candidate-id>        # override scope gate
   kdna-studio candidate promote <project>                        # promote accepted+scope_fit → cards
   kdna-studio report <project>
+  kdna-studio audit-locks <project>            # list all axioms/risk/stance missing Human Lock fields
 
 Project may be a directory containing studio.project.json or a project JSON file.`);
 }
@@ -255,23 +258,41 @@ function writeFiles(outDir, files) {
   }
 }
 
+const ARRAY_FIELD_NAMES = new Set([
+  'applies_when',
+  'does_not_apply_when',
+  'acceptable_exceptions',
+]);
+
 function parseFields(args) {
   const fields = {};
   for (const pair of optionsAll(args, '--field')) {
     const eq = pair.indexOf('=');
     if (eq < 1) fail(`Invalid --field "${pair}". Use key=value.`);
-    const key = pair.slice(0, eq);
+    let key = pair.slice(0, eq);
+    const appendArray = key.endsWith('[]');
+    if (appendArray) key = key.slice(0, -2);
     const raw = pair.slice(eq + 1);
+    let value;
     if (raw.startsWith('[') || raw.startsWith('{')) {
       try {
-        fields[key] = JSON.parse(raw);
+        value = JSON.parse(raw);
       } catch (_) {
-        fields[key] = raw;
+        value = raw;
       }
     } else if (raw.includes('|')) {
-      fields[key] = raw.split('|').map((s) => s.trim()).filter(Boolean);
+      value = raw.split('|').map((s) => s.trim()).filter(Boolean);
+    } else {
+      value = raw;
+    }
+
+    if (appendArray) {
+      const values = Array.isArray(value) ? value : [value];
+      fields[key] = [...(Array.isArray(fields[key]) ? fields[key] : []), ...values];
+    } else if (ARRAY_FIELD_NAMES.has(key) && typeof value === 'string') {
+      fields[key] = value.trim() ? [value.trim()] : [];
     } else {
-      fields[key] = raw;
+      fields[key] = value;
     }
   }
   return fields;
@@ -410,6 +431,8 @@ function cardsFromV1Payload(payload) {
       applies_when: ax.applies_when || [],
       does_not_apply_when: ax.does_not_apply_when || [],
       failure_risk: ax.failure_risk || '',
+      confidence: ax.confidence || '',
+      evidence_type: ax.evidence_type || '',
     }, ax.id || null);
   }
   for (const ont of (Array.isArray(payload.core?.ontology) ? payload.core?.ontology : [])) {
@@ -448,7 +471,8 @@ function cardsFromV1Payload(payload) {
     let fields = pattern;
     if (!type) {
       // Heuristics, in priority order — most specific to most general.
-      if ('wrong' in pattern && 'correct' in pattern) type = 'misunderstanding';
+      if ('logic' in pattern && ('so_what' in pattern || 'conclusion' in pattern)) type = 'reasoning';
+      else if ('wrong' in pattern && 'correct' in pattern) type = 'misunderstanding';
       else if ('term' in pattern && 'definition' in pattern) type = 'term';
       else if ('term' in pattern && 'why' in pattern && 'replace_with' in pattern) type = 'banned_term';
       else if ('what_it_looks_like' in pattern && 'how_to_fix' in pattern) type = 'pattern';
@@ -830,7 +854,7 @@ function importFromKdna(kdnaPath) {
       const core = JSON.parse(entries.get('KDNA_Core.json').toString());
       for (const ax of (Array.isArray(core.axioms) ? core.axioms : [])) {
         const fields = {};
-        for (const k of ['one_sentence','full_statement','why','applies_when','does_not_apply_when','failure_risk']) {
+        for (const k of ['one_sentence','full_statement','why','applies_when','does_not_apply_when','failure_risk','confidence','evidence_type']) {
           if (k in ax) fields[k] = ax[k];
         }
         importedCards.push(cardApi.createCard('axiom', fields));
@@ -848,7 +872,16 @@ function importFromKdna(kdnaPath) {
           acceptable_exceptions: b.acceptable_exceptions || [],
         }));
       }
-      for (const risk of (core.risks || core.risk_model || [])) {
+      // Accept risks as a top-level array (`risks`) or wrapped in `risk_model`
+      // (either as `{risks: [...]}` or as an array itself). Uses the same
+      // Array.isArray ladder pattern as the safe path at lines 1033-1040.
+      let risksSource = core.risks;
+      if (!Array.isArray(risksSource)) {
+        if (Array.isArray(core.risk_model)) risksSource = core.risk_model;
+        else if (Array.isArray(core.risk_model?.risks)) risksSource = core.risk_model.risks;
+        else risksSource = [];
+      }
+      for (const risk of risksSource) {
         importedCards.push(cardApi.createCard('risk', risk.fields || risk));
       }
       for (const stance of (Array.isArray(core.stances) ? core.stances : [])) {
@@ -941,7 +974,7 @@ function importFromKdna(kdnaPath) {
  * Reads KDNA_*.json files and converts entries to draft judgment cards.
  * Outputs a schema audit report.
  */
-function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
+function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity, opts = {}) {
   resetImportedIds();
   const absSource = path.resolve(sourceDir);
   if (!fs.existsSync(absSource)) fail(`Source folder not found: ${absSource}`);
@@ -1008,7 +1041,7 @@ function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
   if (core) {
     for (const ax of (Array.isArray(core.axioms) ? core.axioms : [])) {
       const fields = {};
-      for (const key of ['one_sentence', 'full_statement', 'why', 'applies_when', 'does_not_apply_when', 'failure_risk']) {
+      for (const key of ['one_sentence', 'full_statement', 'why', 'applies_when', 'does_not_apply_when', 'failure_risk', 'confidence', 'evidence_type']) {
         if (key in ax) fields[key] = ax[key];
         else audit.missingFields.push(`axiom.${ax.id || '?'}.${key}`);
       }
@@ -1040,7 +1073,7 @@ function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
     }
     // NEW: import stances
     for (const s of (Array.isArray(core.stances) ? core.stances : [])) {
-      const text = typeof s === 'string' ? s : s.stance || '';
+      const text = typeof s === 'string' ? s : s.statement || s.stance || '';
       importedCards.push(cardApi.createCard('stance', {
         statement: text,
         applies_when: s.applies_when || [],
@@ -1092,7 +1125,7 @@ function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
   }
 
   // NEW: import scenarios
-  if (scenarios && scenarios.scenes) {
+  if (scenarios && Array.isArray(scenarios.scenes)) {
     for (const scene of scenarios.scenes) {
       importedCards.push(cardApi.createCard('scenario', {
         name: scene.name || scene.id || '',
@@ -1102,7 +1135,7 @@ function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
   }
 
   // NEW: import cases
-  if (cases && cases.cases) {
+  if (cases && Array.isArray(cases.cases)) {
     for (const c of cases.cases) {
       importedCards.push(cardApi.createCard('case', {
         title: c.title || c.id || '',
@@ -1118,7 +1151,7 @@ function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
   // so the cards were silently rewritten as axiom-derived fallback chains
   // — looking identical to misunderstanding cards and losing the source's
   // identity.
-  if (reasoning && reasoning.reasoning_chains) {
+  if (reasoning && Array.isArray(reasoning.reasoning_chains)) {
     for (const rc of reasoning.reasoning_chains) {
       importedCards.push(cardApi.createCard('reasoning', {
         axiom: rc.axiom || '',
@@ -1133,7 +1166,7 @@ function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
   }
 
   // NEW: import evolution stages
-  if (evolution && evolution.stages) {
+  if (evolution && Array.isArray(evolution.stages)) {
     for (const stage of evolution.stages) {
       importedCards.push(cardApi.createCard('evolution_stage', {
         name: stage.name || stage.id || '',
@@ -1177,7 +1210,9 @@ function importFromFolder(sourceDir, projectDir, projectName, creatorIdentity) {
 
   fs.mkdirSync(projectDir, { recursive: true });
   writeProject(path.join(projectDir, 'studio.project.json'), project);
-  console.log(JSON.stringify({ audit, imported: importedCards.length, source_mode: 'source_folder' }, null, 2));
+  if (!opts.silent) {
+    console.log(JSON.stringify({ audit, imported: importedCards.length, source_mode: 'source_folder' }, null, 2));
+  }
   return { project, projectPath: path.join(projectDir, 'studio.project.json'), audit };
 }
 
@@ -1392,18 +1427,74 @@ const CARD_REQUIRED_FIELDS = {
   pattern: ['type', 'name', 'one_sentence', 'what_it_looks_like', 'how_to_fix', 'failure_risk'],
 };
 
+const CARD_FIELD_RULES = {
+  axiom: {
+    applies_when: { type: 'array' },
+    does_not_apply_when: { type: 'array' },
+    confidence: { allowed: ['low', 'medium', 'high'] },
+    evidence_type: { allowed: ['case_observation', 'theoretical', 'empirical', 'analogy', 'principle', 'practice'] },
+  },
+  boundary: {
+    acceptable_exceptions: { type: 'array', optional: true },
+  },
+  stance: {
+    applies_when: { type: 'array', optional: true },
+  },
+  misunderstanding: {
+    applies_when: { type: 'array', optional: true },
+    does_not_apply_when: { type: 'array', optional: true },
+  },
+};
+
+function fieldIssue(fields, name, rule = {}) {
+  const val = fields[name];
+  if (val === undefined || val === null || val === '' ||
+      (Array.isArray(val) && val.length === 0)) {
+    return rule.optional ? null : { field: name, issue: 'missing' };
+  }
+  if (rule.type === 'array' && !Array.isArray(val)) {
+    return { field: name, issue: 'wrong_type', have_type: typeof val, need_type: 'array' };
+  }
+  if (rule.allowed && !rule.allowed.includes(val)) {
+    return { field: name, issue: 'invalid_value', have: val, allowed: rule.allowed };
+  }
+  return null;
+}
+
+function formatFieldIssue(issue) {
+  if (issue.issue === 'missing') return issue.field;
+  if (issue.issue === 'wrong_type') return `${issue.field} (must be ${issue.need_type})`;
+  if (issue.issue === 'invalid_value') return `${issue.field} (must be one of: ${issue.allowed.join('|')})`;
+  return `${issue.field} (${issue.issue})`;
+}
+
 function checkRequiredFields(type, fields) {
   const required = CARD_REQUIRED_FIELDS[type];
   if (!required) return [];
-  const missing = [];
+  const issues = [];
   for (const f of required) {
-    const val = fields[f];
-    if (val === undefined || val === null || val === '' ||
-        (Array.isArray(val) && val.length === 0)) {
-      missing.push(f);
+    const issue = fieldIssue(fields, f, CARD_FIELD_RULES[type]?.[f] || {});
+    if (issue) issues.push(formatFieldIssue(issue));
+  }
+  for (const [name, rule] of Object.entries(CARD_FIELD_RULES[type] || {})) {
+    if (required.includes(name)) continue;
+    const issue = fieldIssue(fields, name, rule);
+    if (issue) issues.push(formatFieldIssue(issue));
+  }
+  return issues;
+}
+
+function criticalAxiomIssues(project) {
+  const issues = [];
+  for (const card of (Array.isArray(project.cards) ? project.cards : [])) {
+    if (card.type !== 'axiom') continue;
+    const fields = card.fields || {};
+    for (const field of ['applies_when', 'does_not_apply_when', 'failure_risk']) {
+      const issue = fieldIssue(fields, field, CARD_FIELD_RULES.axiom[field] || {});
+      if (issue) issues.push(`${card.id}: ${formatFieldIssue(issue)}`);
     }
   }
-  return missing;
+  return issues;
 }
 
 function cardStrictTemplate(type, fields) {
@@ -1487,21 +1578,54 @@ function cmdCard(args) {
       project.stages.judgment_cards.status = 'in_progress';
     }
     writeProject(projectPath, project);
-    console.log(`Added card: ${card.id}`);
+    if (args.includes('--json')) {
+      console.log(JSON.stringify({ added: true, card }, null, 2));
+    } else {
+      console.log(`Added card: ${card.id}`);
+    }
     return;
   }
   if (sub === 'update') {
     const projectInput = args[1];
     const cardId = args[2];
-    if (!projectInput || !cardId) fail('Usage: kdna-studio card update <project> <card-id> --field key=value');
+    if (!projectInput || !cardId) fail('Usage: kdna-studio card update <project> <card-id> --field key=value  OR  kdna-studio card update <project> <card-id> --from-file <path.json>');
     const { projectPath, project } = readProject(projectInput);
     const idx = (project.cards || []).findIndex((c) => c.id === cardId);
     if (idx < 0) fail(`Card not found: ${cardId}`);
     const card = project.cards[idx];
     if (card.locked) fail(`Cannot update locked card: ${cardId}. Unlock first with card unlock.`);
-    const updates = parseFields(args.slice(3));
-    for (const [k, v] of Object.entries(updates)) {
-      if (card.fields) card.fields[k] = v;
+    // Bug (UX pro-20 migration): prior version only accepted
+    // --field key=value, so an author migrating 20 source-tree
+    // assets had to run one CLI invocation per field. With
+    // confidence + evidence_type as 8th / 9th required fields on
+    // axiom, a 99-axiom asset became 99 * 2 = 198 invocations.
+    // The fix accepts --from-file <path.json> so an author can
+    // write a single JSON file per card (or per project) and
+    // apply it in one call. JSON shape: {field: value, ...}.
+    //   kdna-studio card update . ax_xxx --from-file ./fills/ax_xxx.json
+    // For batched updates across many cards, see the
+    // --from-file-projects variant below, which reads a list
+    // of {id, fields} records.
+    const fromFileIdx = args.indexOf('--from-file');
+    if (fromFileIdx >= 0) {
+      const filePath = args[fromFileIdx + 1];
+      if (!filePath) fail('--from-file requires a path');
+      if (!fs.existsSync(filePath)) fail(`--from-file: file not found: ${filePath}`);
+      const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      if (typeof data !== 'object' || Array.isArray(data) || data === null) {
+        fail(`--from-file: expected a JSON object mapping field names to values`);
+      }
+      for (const [k, v] of Object.entries(data)) {
+        if (k === 'id' || k === 'type' || k === 'status' || k === 'locked') {
+          fail(`--from-file: cannot edit reserved field "${k}"`);
+        }
+        if (card.fields) card.fields[k] = v;
+      }
+    } else {
+      const updates = parseFields(args.slice(3));
+      for (const [k, v] of Object.entries(updates)) {
+        if (card.fields) card.fields[k] = v;
+      }
     }
     project.cards[idx] = card;
     writeProject(projectPath, project);
@@ -1650,14 +1774,32 @@ function cmdLock(args) {
 }
 
 function cmdMigrate(args) {
+  // Bug (UX pro-20 migration): prior version of `migrate` always
+  // attempted the full pipeline — read source folder, import to
+  // Studio project, lock all cards, then export. An author migrating
+  // 20 source-tree assets had no way to know in advance whether
+  // the assets would pass the v1.7.2+ Human Lock gate. The fix
+  // adds `--check` which runs the import + the critical-missing
+  // check + the lock-gate check, then prints a report and exits
+  // without writing the .kdna file. Pair with `audit-locks` for
+  // the full pre-migration report.
+  //
+  // Usage:
+  //   kdna-studio migrate <source-dir> --check --name <@scope/name>
+  //
+  // Exit codes:
+  //   0 — would succeed
+  //   2 — INPUT_ERROR (missing args)
+  //   4 — would fail (Human Lock gate or critical axiom field)
+  const checkOnly = args.includes('--check');
   const sourceDir = args[0];
   const out = option(args, '--out');
   const by = option(args, '--by');
   const statement = option(args, '--statement');
   const requestedName = option(args, '--name');
   let name = requestedName || path.basename(path.resolve(sourceDir || '.'));
-  if (!sourceDir || !out || !by || !statement) {
-    fail('Usage: kdna-studio migrate <source-dir> --out <file.kdna> --name <@scope/name> --by <id> --statement <text> [--sign] [--passphrase <pw>|--passphrase-stdin]');
+  if (!sourceDir || (!out && !checkOnly) || (!by && !checkOnly) || (!statement && !checkOnly)) {
+    fail('Usage: kdna-studio migrate <source-dir> --out <file.kdna> --name <@scope/name> --by <id> --statement <text> [--check] [--sign] [--passphrase <pw>|--passphrase-stdin]');
   }
 
   const sourcePath = path.resolve(sourceDir);
@@ -1683,7 +1825,7 @@ function cmdMigrate(args) {
     if (!requestedName && project.name) name = project.name;
   } else {
     tmpDir = trackTempDir(fs.mkdtempSync(path.join(os.tmpdir(), 'kdna-migrate-')));
-    const imported = importFromFolder(sourceDir, tmpDir, name, creatorIdentity);
+    const imported = importFromFolder(sourceDir, tmpDir, name, creatorIdentity, { silent: true });
     project = imported.project;
     projectPath = path.join(tmpDir, 'studio.project.json');
   }
@@ -1695,17 +1837,8 @@ function cmdMigrate(args) {
   // always failing.
   const allowIncompleteEarly = args.includes('--allow-incomplete');
 
-  // Reject if critical judgment fields are missing from axioms
-  const criticalMissing = [];
-  for (const card of (Array.isArray(project.cards) ? project.cards : [])) {
-    if (card.type !== 'axiom') continue;
-    for (const field of ['applies_when', 'does_not_apply_when', 'failure_risk']) {
-      const val = card.fields && card.fields[field];
-      if (!val || (Array.isArray(val) && val.length === 0) || val === '') {
-        criticalMissing.push(`${card.id}: missing ${field}`);
-      }
-    }
-  }
+  // Reject if critical judgment fields are missing or malformed on axioms.
+  const criticalMissing = criticalAxiomIssues(project);
   if (criticalMissing.length > 0) {
     if (allowIncompleteEarly) {
       console.warn(
@@ -1724,6 +1857,41 @@ function cmdMigrate(args) {
     }
   }
 
+  // --check branch: print a pre-migration report and exit. The
+  // project object already has every card from the source tree
+  // imported, so we can run the same audit-locks logic here
+  // without re-reading the source. This is the single-call
+  // equivalent of `kdna-studio create --from-folder <src> &&
+  // kdna-studio audit-locks .` — but it requires no
+  // intermediate write.
+  if (checkOnly) {
+    const REQUIRED = {
+      axiom: ['confidence', 'evidence_type', 'one_sentence', 'full_statement', 'why',
+              'applies_when', 'does_not_apply_when', 'failure_risk'],
+      risk: ['name', 'description', 'mitigation'],
+      stance: ['statement', 'applies_when'],
+      misunderstanding: ['wrong', 'correct', 'key_distinction', 'why'],
+      boundary: ['scope', 'out_of_scope'],
+    };
+    const summary = { project: name, source: sourceDir, total: project.cards.length, by_type: {}, would_block: false };
+    for (const card of (project.cards || [])) {
+      const req = REQUIRED[card.type];
+      if (!req) continue;
+      const missing = [];
+      for (const f of req) {
+        const issue = fieldIssue(card.fields || {}, f, CARD_FIELD_RULES[card.type]?.[f] || {});
+        if (issue) missing.push(formatFieldIssue(issue));
+      }
+      if (missing.length > 0) {
+        if (!summary.by_type[card.type]) summary.by_type[card.type] = [];
+        summary.by_type[card.type].push({ id: card.id, missing });
+        summary.would_block = true;
+      }
+    }
+    console.log(JSON.stringify(summary, null, 2));
+    process.exit(summary.would_block ? EXIT.HUMAN_LOCK_REQUIRED : EXIT.OK);
+  }
+
   // Step 2: approve and Human Lock all cards
   let locked = 0;
   for (let i = 0; i < (project.cards || []).length; i++) {
@@ -1819,6 +1987,25 @@ function exportProjectV1(project, name, outPath, opts = {}) {
   if (!exportRuntime || typeof exportRuntime.exportRuntimeAsset !== 'function') {
     fail('@aikdna/kdna-studio-core with exportRuntime.exportRuntimeAsset is required for v1 export.', 2);
   }
+  const criticalIssues = criticalAxiomIssues(project);
+  if (criticalIssues.length > 0) {
+    if (opts.allowIncomplete) {
+      console.warn(
+        `--allow-incomplete: bypassing ${criticalIssues.length} critical axiom-field check(s). ` +
+        `The exported .kdna will load but kdna-loader may not match this domain on those signals.`,
+      );
+    } else {
+      fail(
+        `Cannot export v1: ${criticalIssues.length} critical axiom field issue(s).\n` +
+        `  These fields are required for domain routing (kdna-loader uses them to\n` +
+        `  decide when to load this domain). Fix them first, or pass\n` +
+        `  --allow-incomplete to bypass.\n` +
+        `  Issues:\n    ` + criticalIssues.slice(0, 10).join('\n    ') +
+        (criticalIssues.length > 10 ? `\n    ... and ${criticalIssues.length - 10} more` : ''),
+        EXIT.HUMAN_LOCK_REQUIRED,
+      );
+    }
+  }
   const gate = projectApi.checkHumanLockGate(project);
   if (gate.blocked) {
     if (opts.allowIncomplete) {
@@ -1996,7 +2183,7 @@ function manifestForSigning(manifest) {
 
 function canonicalPayload(files) {
   return ['mimetype', ...Object.keys(files).filter((k) => k !== 'mimetype').sort()]
-    .filter((name) => name !== 'signature.json' && name !== '.DS_Store')
+    .filter((name) => name !== 'signature.json' && name !== '.DS_Store' && name !== 'build-receipt.json' && !name.startsWith('reports/'))
     .map((name) => {
       let content = name === 'mimetype' ? 'application/vnd.aikdna.kdna+zip' : files[name];
       if (name.endsWith('.json')) {
@@ -2093,6 +2280,25 @@ function cmdExport(args) {
     return;
   }
   const { project, result } = compileProject(projectInput);
+  const criticalIssues = criticalAxiomIssues(project);
+  if (criticalIssues.length > 0) {
+    if (args.includes('--allow-incomplete')) {
+      console.warn(
+        `--allow-incomplete: bypassing ${criticalIssues.length} critical axiom-field check(s). ` +
+        `The exported .kdna will load but kdna-loader may not match this domain on those signals.`,
+      );
+    } else {
+      fail(
+        `Cannot export: ${criticalIssues.length} critical axiom field issue(s).\n` +
+        `  These fields are required for domain routing (kdna-loader uses them to\n` +
+        `  decide when to load this domain). Fix them first, or pass\n` +
+        `  --allow-incomplete to bypass.\n` +
+        `  Issues:\n    ` + criticalIssues.slice(0, 10).join('\n    ') +
+        (criticalIssues.length > 10 ? `\n    ... and ${criticalIssues.length - 10} more` : ''),
+        EXIT.HUMAN_LOCK_REQUIRED,
+      );
+    }
+  }
   const files = { ...result.files };
   files['README.md'] = compileApi.generateReadme(project);
   files.LICENSE = project.license?.type || 'UNSPECIFIED';
@@ -2167,15 +2373,16 @@ function cmdStudioInstall(args) {
 function cmdStudioUpdate(args) {
   const target = args[0];
   if (!target) fail('Usage: kdna-studio update <@scope/name>');
-  try {
-    const result = require('child_process').spawnSync('kdna', ['update', target], {
-      stdio: 'inherit', encoding: 'utf8',
-    });
-    if (result.status !== 0) process.exit(result.status);
-  } catch (e) {
-    console.error('Error spawning kdna CLI:', e.message);
-    fail('kdna CLI not found. Install with: npm install -g @aikdna/kdna-cli');
-  }
+  // kdna update does not exist in kdna-cli v0.28.x. The correct
+  // path is to re-install via npm or use kdna install to pull
+  // the latest published version of the asset.
+  console.log(`To update ${target}, run:`);
+  console.log(`  npm install -g @aikdna/kdna-cli@latest`);
+  console.log(`  kdna install ${target}`);
+  console.log(``);
+  console.log(`Or for a project-local install:`);
+  console.log(`  cd <project-dir> && npm install @aikdna/kdna-cli@latest`);
+  process.exit(0);
 }
 
 function cmdLlm(args) {
@@ -2250,6 +2457,140 @@ function cmdReport(args) {
   process.exit(gate.blocked ? EXIT.HUMAN_LOCK_REQUIRED : EXIT.OK);
 }
 
+// Audit-locks: list every card that would fail the v1.7.2+ Human Lock
+// gate because of missing or empty fields. Used during the
+// pre-migration review of source-tree assets (e.g. pro-20) so an
+// author can fill in the missing confidence / evidence_type / risk
+// description / stance statement BEFORE running `migrate --format v1`.
+//
+// Bug (UX pro-20 migration): prior version of `kdna-studio report`
+// returned a flat human_lock_gate.issues list, which mixed card
+// types and field names. An author migrating 20 source-tree
+// assets with 99 axioms + 140 risk cards + 70 stance cards had no
+// way to see, for a single asset, "which axioms are missing
+// confidence?" — they had to grep the project JSON. The fix adds
+// a per-type, per-field breakdown.
+function cmdAuditLocks(args) {
+  const { project } = readProject(args[0]);
+  const useJson = args.includes('--json');
+  const onlyType = option(args, '--type');  // 'axiom' | 'risk' | 'stance' | 'misunderstanding' | null
+
+  const cards = project.cards || [];
+  const findings = {
+    project: project.name,
+    card_count: cards.length,
+    locked_count: cards.filter(c => c.locked).length,
+    by_type: {},
+  };
+
+  // Per-card-type required field lists. Mirrors the v1.7.2+ lockCard
+  // gate (kdna-studio-core/src/cards/index.js) so the output is
+  // exactly the field set the gate will reject.
+  const REQUIRED = {
+    axiom: ['one_sentence', 'full_statement', 'why', 'applies_when',
+            'does_not_apply_when', 'failure_risk', 'confidence', 'evidence_type'],
+    risk: ['name', 'description', 'mitigation'],
+    stance: ['statement', 'applies_when'],
+    misunderstanding: ['wrong', 'correct', 'key_distinction', 'why'],
+    boundary: ['scope', 'out_of_scope'],
+    self_check: ['question'],
+  };
+  const THRESHOLDS = {
+    axiom: {
+      one_sentence: { min: 5, type: 'string' },
+      full_statement: { min: 20, type: 'string' },
+      why: { min: 20, type: 'string' },
+      applies_when: { type: 'array', minLength: 1 },
+      does_not_apply_when: { type: 'array', minLength: 1 },
+      failure_risk: { min: 1, type: 'string' },
+      confidence: { allowed: ['low', 'medium', 'high'] },
+      evidence_type: { allowed: ['case_observation', 'theoretical', 'empirical', 'analogy', 'principle', 'practice'] },
+    },
+    risk: {
+      name: { min: 1, type: 'string' },
+      description: { min: 20, type: 'string' },
+      mitigation: { min: 1, type: 'string' },
+    },
+    stance: {
+      statement: { min: 1, type: 'string' },
+      applies_when: { type: 'array', minLength: 0 },
+    },
+  };
+
+  function checkField(type, fields, name, rule) {
+    const value = fields[name];
+    if (value === undefined || value === null || value === '') {
+      return { field: name, issue: 'missing' };
+    }
+    if (rule.type === 'string' && rule.min && String(value).length < rule.min) {
+      return { field: name, issue: 'too_short', have_length: String(value).length, need_min: rule.min };
+    }
+    if (rule.allowed && !rule.allowed.includes(value)) {
+      return { field: name, issue: 'invalid_value', have: value, allowed: rule.allowed };
+    }
+    if (rule.type === 'array' && !Array.isArray(value)) {
+      return { field: name, issue: 'wrong_type', have_type: typeof value, need_type: 'array' };
+    }
+    if (rule.type === 'array' && rule.minLength && value.length < rule.minLength) {
+      return { field: name, issue: 'too_short', have_length: value.length, need_min: rule.minLength };
+    }
+    return null;
+  }
+
+  for (const card of cards) {
+    const req = REQUIRED[card.type];
+    if (!req) continue;
+    if (onlyType && card.type !== onlyType) continue;
+    const rule = THRESHOLDS[card.type] || {};
+    const missing = [];
+    for (const name of req) {
+      const issue = checkField(card.type, card.fields || {}, name, rule[name] || {});
+      if (issue) missing.push(issue);
+    }
+    if (missing.length > 0) {
+      if (!findings.by_type[card.type]) {
+        findings.by_type[card.type] = { missing_count: 0, cards: [] };
+      }
+      findings.by_type[card.type].missing_count += 1;
+      findings.by_type[card.type].cards.push({
+        id: card.id,
+        one_sentence: card.fields?.one_sentence || card.fields?.statement || card.fields?.question || '',
+        missing,
+      });
+    }
+  }
+
+  if (useJson) {
+    console.log(JSON.stringify(findings, null, 2));
+  } else {
+    console.log(`Project: ${findings.project}`);
+    console.log(`Cards: ${findings.card_count} (locked: ${findings.locked_count})`);
+    const types = Object.keys(findings.by_type);
+    if (types.length === 0) {
+      console.log('\nAll cards pass the v1.7.2+ Human Lock gate. Ready to migrate.');
+      return;
+    }
+    for (const t of types) {
+      const block = findings.by_type[t];
+      console.log(`\n${t}: ${block.missing_count} card(s) with missing fields`);
+      for (const card of block.cards) {
+        console.log(`  ${card.id}  ${(card.one_sentence || '').slice(0, 60)}`);
+        for (const m of card.missing) {
+          if (m.issue === 'missing') {
+            console.log(`    - ${m.field}: missing`);
+          } else if (m.issue === 'too_short') {
+            console.log(`    - ${m.field}: too short (have ${m.have_length}, need ≥ ${m.need_min})`);
+          } else if (m.issue === 'invalid_value') {
+            console.log(`    - ${m.field}: invalid value "${m.have}", allowed: ${m.allowed.join('|')}`);
+          } else {
+            console.log(`    - ${m.field}: ${m.issue}`);
+          }
+        }
+      }
+    }
+  }
+}
+
 // ─── Distillation Commands ──────────────────────────────────────────
 
 function cmdTarget(args) {
@@ -2504,6 +2845,7 @@ async function cmdFeynman(args) {
   const projectInput = args[0];
   const cardId = args[1];
   if (!projectInput || !cardId) fail('Usage: kdna-studio feynman <project> <card-id>');
+  const useJson = args.includes('--json');
   const { projectPath, project } = readProject(projectInput);
   const cardIdx = (project.cards || []).findIndex(c => c.id === cardId);
   if (cardIdx < 0) fail(`Card not found: ${cardId}`);
@@ -2539,7 +2881,7 @@ async function cmdFeynman(args) {
     console.warn(`No feynman_restatement on ${cardId}; using synthesised:\n  "${synthesised}"`);
   }
 
-  console.log(`Evaluating Feynman restatement for card: ${cardId}`);
+  if (!useJson) console.log(`Evaluating Feynman restatement for card: ${cardId}`);
 
   // Bug (#1 UX follow-up): if no LLM is configured and the caller
   // did not pass --no-llm, route through cmdNeedsLlm which either
@@ -2568,14 +2910,26 @@ async function cmdFeynman(args) {
   const score = result.score || 0;
   const passed = score >= 4;
 
-  console.log(`Score: ${score}/5 ${passed ? '✓ publishable' : '✗ below threshold (need 4/5)'}${llmGate.noLlm ? '  (--no-llm: static result)' : ''}`);
-  for (const [criterion, desc] of Object.entries(ai.feynman.CRITERIA)) {
-    const r = (result.criteria || {})[criterion] ? '✓' : '✗';
-    console.log(`  ${r} ${criterion}`);
-  }
-  if (result.suggestions && result.suggestions.length > 0) {
-    console.log('\nSuggestions:');
-    result.suggestions.forEach(s => console.log(`  - ${s}`));
+  if (useJson) {
+    console.log(JSON.stringify({
+      card_id: cardId,
+      score,
+      passed,
+      no_llm: !!llmGate.noLlm,
+      criteria: result.criteria || {},
+      suggestions: result.suggestions || [],
+      feynman_restatement: card.feynman_restatement,
+    }, null, 2));
+  } else {
+    console.log(`Score: ${score}/5 ${passed ? '✓ publishable' : '✗ below threshold (need 4/5)'}${llmGate.noLlm ? '  (--no-llm: static result)' : ''}`);
+    for (const [criterion, desc] of Object.entries(ai.feynman.CRITERIA)) {
+      const r = (result.criteria || {})[criterion] ? '✓' : '✗';
+      console.log(`  ${r} ${criterion}`);
+    }
+    if (result.suggestions && result.suggestions.length > 0) {
+      console.log('\nSuggestions:');
+      result.suggestions.forEach(s => console.log(`  - ${s}`));
+    }
   }
 
   card.feynman_evaluation = { score, criteria: result.criteria, suggestions: result.suggestions, evaluated_at: new Date().toISOString() };
@@ -2677,6 +3031,7 @@ try {
   else if (cmd === 'llm') cmdLlm(args.slice(1));
   else if (cmd === 'identity') cmdIdentity(args.slice(1));
   else if (cmd === 'report') cmdReport(args.slice(1));
+  else if (cmd === 'audit-locks') cmdAuditLocks(args.slice(1));
   else if (cmd === 'install') cmdStudioInstall(args.slice(1));
   else if (cmd === 'update') cmdStudioUpdate(args.slice(1));
   else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-studio-cli",
-  "version": "0.8.8",
+  "version": "0.8.10",
   "description": "Official KDNA Studio command-line authoring entry for creating, reviewing, compiling, and exporting .kdna judgment assets through the KDNA toolchain.",
   "type": "commonjs",
   "bin": {
@@ -39,12 +39,12 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@aikdna/kdna-studio-core": "^1.7.6",
+    "@aikdna/kdna-studio-core": "^1.7.7",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "cbor-x": "^1.6.4"
   },
   "devDependencies": {
-    "@aikdna/kdna-core": "^0.15.5"
+    "@aikdna/kdna-core": "^0.15.9"
   }
 }

package/src/ai/feynman.js

@@ -43,7 +43,9 @@ async function evaluate(config, card, options = {}) {
   const axiomText = fields.one_sentence || fields.full_statement || fields.question || '';
   const restatement = card.feynman_restatement
     || fields.feynman_restatement
-    || fields.feynman_text
+    // NOTE: fields.feynman_text was previously in this fallback chain
+    // but is intentionally excluded — no code path in @aikdna writes
+    // feynman_text. The canonical field is feynman_restatement.
     || '';
 
   if (!restatement) {