@aikdna/studio-core 0.4.0 → 0.5.0

package/package.json

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

@@ -51,7 +51,8 @@ function compilePatterns(cards, project) {
     wrong: c.fields?.wrong || '',
     correct: c.fields?.correct || '',
     key_distinction: c.fields?.key_distinction || '',
-    failure_risk: c.fields?.failure_risk || null,
+    why: c.fields?.why || `What bad judgment results from believing "${(c.fields?.wrong || '').slice(0, 40)}"`,
+    failure_risk: c.fields?.failure_risk || 'No specific failure risk declared',
     applies_when: c.fields?.applies_when || [],
     does_not_apply_when: c.fields?.does_not_apply_when || [],
   }));
@@ -95,7 +96,7 @@ function compileReasoning(cards, project) {
     meta: makeMeta(project),
     reasoning_chains: lockedAxioms.map(ax => ({
       id: `chain_${ax.id}`,
-      from: ax.fields?.one_sentence || '',
+      one_sentence: ax.fields?.one_sentence || '',
       logic: [ax.fields?.full_statement || ''],
       so_what: ax.fields?.why || 'Agent judgment changes when this axiom is loaded.',
     })),
@@ -112,22 +113,27 @@ function compileEvolution(cards, project) {
     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 });
+      if (entry.event === 'locked') {
+        stages.push({
+          id: `stage_${card.id}`,
+          name: card.fields?.one_sentence || card.fields?.question || card.id,
+          description: `Card ${card.id} was locked by ${entry.by} at ${entry.at}. Type: ${card.type}.`,
+          indicators: [`${card.type} card locked`, 'Human judgment confirmed'],
+        });
       }
     }
   }
 
   return {
     meta: makeMeta(project),
-    stages: stages.sort((a, b) => a.at.localeCompare(b.at)),
-    capability_layers: [
-      { layer: 1, name: 'Foundation', description: 'Core axioms and patterns established.' },
+    stages: stages.sort((a, b) => a.id.localeCompare(b.id)),
+    evolution_layers: [
+      { id: 'layer_1', name: 'Foundation', capability: 'Core axioms and patterns established.', from_stage: stages[0]?.id || 'none', to_stage: stages[stages.length - 1]?.id || 'none' },
     ],
-    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 },
+    measurement: [
+      { id: 'meas_axioms', what: 'locked_axioms', how: 'Count of locked axiom cards', threshold: `${lockedCards.filter(c => c.type === 'axiom').length}` },
+      { id: 'meas_misunderstandings', what: 'locked_misunderstandings', how: 'Count of locked misunderstanding cards', threshold: `${lockedCards.filter(c => c.type === 'misunderstanding').length}` },
+      { id: 'meas_self_checks', what: 'self_checks', how: 'Count of locked self-check cards', threshold: `${lockedCards.filter(c => c.type === 'self_check').length}` },
     ],
   };
 }

package/src/index.js

@@ -21,6 +21,7 @@ const cards = require('./cards');
 const compile = require('./compile');
 const evidence = require('./evidence');
 const packaging = require('./packaging');
+const pipeline = require('./pipeline');
 const project = require('./project');
 const provenance = require('./provenance');
 const quality = require('./quality');
@@ -32,17 +33,23 @@ const validateCards = require('./quality/validate-cards');
 const delta = require('./testlab/delta');
 
 module.exports = {
+  // Stable
+  project,
   cards,
   compile,
-  evidence,
-  packaging,
-  project,
-  provenance,
   quality,
+  provenance,
+  pipeline,
+
+  // Experimental
+  evidence,
   testlab,
-  versioning,
+  delta,
   feynman,
   contradiction,
   validateCards,
-  delta,
+  versioning,
+
+  // Internal
+  packaging,
 };

package/src/pipeline.js

@@ -0,0 +1,98 @@
+/**
+ * createStudioPipeline(project, options) — Official convenience API.
+ *
+ * Provides the recommended Studio workflow as a single callable pipeline.
+ * Third-party apps should use this instead of manually calling individual modules.
+ *
+ * Stable API (semver guaranteed).
+ */
+
+const { validateProject } = require('./project');
+const { computeReadiness } = require('./quality');
+const { compileDomain, generateReadme } = require('./compile');
+const { buildProvenance } = require('./provenance');
+const { validateAllCards } = require('./quality/validate-cards');
+
+function createStudioPipeline(project, options = {}) {
+  return new StudioPipeline(project, options);
+}
+
+class StudioPipeline {
+  constructor(project, options = {}) {
+    this.project = project;
+    this.options = options;
+    this.results = {};
+  }
+
+  validateProject() {
+    const r = validateProject(this.project);
+    this.results.project_valid = r;
+    return this;
+  }
+
+  validateCards() {
+    const issues = validateAllCards(this.project);
+    this.results.card_validation = { total: issues.length, issues };
+    return this;
+  }
+
+  computeReadiness() {
+    const r = computeReadiness(this.project);
+    this.results.readiness = r;
+    return this;
+  }
+
+  compile() {
+    const r = compileDomain(this.project);
+    this.results.compile = r;
+    return this;
+  }
+
+  generateReadme(readmeOptions = {}) {
+    const r = generateReadme(this.project, readmeOptions);
+    this.results.readme = r;
+    return this;
+  }
+
+  buildProvenance() {
+    if (!this.results.compile) throw new Error('Must call compile() before buildProvenance()');
+    const r = buildProvenance(this.project, this.results.compile.files);
+    this.results.provenance = r;
+    return this;
+  }
+
+  runAll(options = {}) {
+    this.validateProject();
+    this.validateCards();
+    this.computeReadiness();
+    this.compile();
+    if (options.generateReadme !== false) this.generateReadme(options.readmeOptions);
+    if (options.buildProvenance !== false) this.buildProvenance();
+    return this.toResult();
+  }
+
+  get readyness() { return this.results.readiness; }
+  get compiled() { return this.results.compile; }
+  get kdnaFiles() { return this.results.compile?.files || {}; }
+  get isPublishable() { return this.results.readiness?.publishable === true; }
+
+  toResult() {
+    return {
+      project_valid: this.results.project_valid?.valid === true,
+      card_issues: this.results.card_validation?.total || 0,
+      readiness: this.results.readiness?.grade || 'unknown',
+      publishable: this.results.readiness?.publishable || false,
+      score: this.results.readiness?.score || 0,
+      kdna_files: this.results.compile?.stats?.kdna_files || 0,
+      locked_cards: this.results.compile?.stats?.locked_cards || 0,
+      excluded_cards: this.results.compile?.stats?.excluded_cards || 0,
+      build_id: this.results.provenance?.build_id || null,
+      fingerprint: this.results.provenance?.content_fingerprint || null,
+      blocking: this.results.readiness?.blocking || [],
+      warnings: this.results.readiness?.warnings || [],
+      next_step: this.results.readiness?.next_step || '',
+    };
+  }
+}
+
+module.exports = { createStudioPipeline };

package/tests/e2e.test.js

@@ -0,0 +1,276 @@
+/**
+ * End-to-end validation: prove Studio Core output passes KDNA SPEC validation.
+ *
+ * Tests:
+ *   1. compile → write files → kdna validate passes
+ *   2. compile → kdna pack → kdna inspect returns valid container
+ *   3. compile output matches KDNA SPEC reference structure
+ *   4. kdna-core schema validation on compiled output
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { createProject } = require('../src/project');
+const { createCard, lockCard, transitionCard, createFeynmanRestatement, attachRestatementToLock } = require('../src/cards');
+const { compileDomain } = require('../src/compile');
+const { buildProvenance } = require('../src/provenance');
+
+function makeLockedCard(type, fields, id) {
+  const card = createCard(type, fields, id);
+  transitionCard(card, 'revised', { by: 'expert' });
+  lockCard(card, { by: 'expert', statement: 'I confirm this judgment.', checked: { applies_when: true, does_not_apply_when: true, failure_risk: true } });
+  return card;
+}
+
+function createFullProject() {
+  const project = createProject('leadership_decisions', 'domain', {
+    author: { name: 'Leadership Expert', id: 'expert_001' },
+  });
+  project.release = { version: '0.1.0', description: 'Leadership decision-making judgment — diagnose whether execution failures are really decision voids.' };
+
+  // Axioms
+  const ax1 = makeLockedCard('axiom', {
+    one_sentence: 'Execution failure is often decision failure in disguise.',
+    full_statement: 'When a team fails to execute, first check whether a real decision (with named owner, deadline, and criteria) was ever made. Most "execution problems" are decision voids.',
+    why: 'Without this axiom, managers address symptoms (motivation, process) while missing the root cause.',
+    applies_when: ['Team reports being stuck', 'Deadline was missed', 'Project not progressing'],
+    does_not_apply_when: ['Clear decision exists with owner', 'External blocker (vendor, regulation)'],
+    failure_risk: 'May cause over-scrutiny of decision quality when issue is resource availability.',
+  }, 'ax_001');
+  project.cards.push(ax1);
+
+  const ax2 = makeLockedCard('axiom', {
+    one_sentence: 'Broad agreement is not commitment. Only named ownership is commitment.',
+    full_statement: 'A decision without a single named owner with a deadline has no commitment. Multiple owners = no owner.',
+    why: 'Teams confuse "everyone nodding" with actual commitment. Without a named owner, no one wakes up responsible.',
+    applies_when: ['Meeting ends with "sounds good"', 'Decision without deadline', 'Multiple people assigned'],
+    does_not_apply_when: ['Solo work with clear self-accountability', 'Informal team alignment'],
+    failure_risk: 'May create unnecessary formality for trivial decisions.',
+  }, 'ax_002');
+  project.cards.push(ax2);
+
+  const ax3 = makeLockedCard('axiom', {
+    one_sentence: 'The cost of a slow decision is usually higher than the cost of an imperfect decision.',
+    full_statement: 'In leadership, decision speed compounds. A two-week delay for a perfect decision often costs more than an 80% decision made today.',
+    why: 'Leaders who wait for perfect information create organizational bottlenecks.',
+    applies_when: ['Decision is reversible', 'Stakes are below team/org level', 'More information unlikely to change outcome'],
+    does_not_apply_when: ['Safety-critical decisions', 'Irreversible resource commitments', 'Legal/compliance required decisions'],
+    failure_risk: 'May encourage premature decisions in high-stakes, irreversible situations.',
+  }, 'ax_003');
+  project.cards.push(ax3);
+
+  // Misunderstandings
+  const ms1 = makeLockedCard('misunderstanding', {
+    wrong: 'If the team is not executing, they lack motivation or skills.',
+    correct: 'If the team is not executing, first check whether a real decision was ever made with owner, deadline, and criteria.',
+    key_distinction: 'Motivation gaps produce gradual decline over weeks. Decision voids produce sudden stalls within days. The pattern is fundamentally different.',
+  }, 'ms_001');
+  project.cards.push(ms1);
+
+  const ms2 = makeLockedCard('misunderstanding', {
+    wrong: 'Consensus means everyone agrees with the decision.',
+    correct: 'Consensus means everyone understands the decision, knows their role in executing it, and commits to not blocking it — even if they disagree.',
+    key_distinction: 'Agreement is an emotional state. Commitment to execute is a behavioral contract. You need the latter, not the former.',
+  }, 'ms_002');
+  project.cards.push(ms2);
+
+  // Self-checks
+  for (let i = 0; i < 5; i++) {
+    const checks = [
+      'Before concluding execution is the problem, did I verify that a named owner with a deadline exists?',
+      'Does this decision have exactly one person who will wake up responsible for it tomorrow?',
+      'Is this decision reversible enough that speed matters more than perfection?',
+      'Did I check whether this is a decision void disguised as an execution gap?',
+      'If I asked the team "who owns this?", would everyone point to the same person?',
+    ];
+    const sc = makeLockedCard('self_check', { question: checks[i] }, `sc_00${i + 1}`);
+    project.cards.push(sc);
+  }
+
+  // Feynman for axioms
+  attachRestatementToLock(ax1, createFeynmanRestatement(ax1,
+    'When your team is stuck and nothing is moving forward, do not immediately assume they lack skills or motivation. First ask: was there a clear decision? Meaning: someone specific was named, a date was given, and everyone knows what "done" looks like. If any of these is missing, you have a decision problem pretending to be an execution problem.'));
+  attachRestatementToLock(ax2, createFeynmanRestatement(ax2,
+    'After a meeting where everyone seems to agree, do not assume commitment happened. If you cannot name one specific person who knows they are accountable by a specific date, you do not have a decision — you have a discussion. Multiple owners means zero owners.'));
+  attachRestatementToLock(ax3, createFeynmanRestatement(ax3,
+    'Waiting three weeks for the perfect answer is usually worse than making a good-enough decision today. The only exception is when the decision is irreversible — like hiring someone you cannot fire, or spending money you cannot get back. But most daily leadership decisions are reversible, so speed beats perfection.'));
+
+  return project;
+}
+
+const TMPDIR = fs.mkdtempSync(path.join(os.tmpdir(), 'kdna-studio-e2e-'));
+
+// ─── E2E: compile → kdna validate ────────────────────────────────────
+
+describe('E2E: compile → validate', () => {
+  test('compiled output passes kdna validate', () => {
+    const project = createFullProject();
+    const result = compileDomain(project);
+    const domainDir = path.join(TMPDIR, 'test-domain');
+
+    fs.mkdirSync(domainDir, { recursive: true });
+    for (const [filename, content] of Object.entries(result.files)) {
+      fs.writeFileSync(path.join(domainDir, filename), content);
+    }
+
+    try {
+      const validateResult = execFileSync('kdna', ['validate', domainDir], {
+        encoding: 'utf8', timeout: 30000,
+      });
+      assert.match(validateResult, /valid|✓/i);
+    } catch (e) {
+      const stderr = (e.stderr || '').toString();
+      // If kdna CLI not installed, skip gracefully
+      if (stderr.includes('kdna') || stderr.includes('not found')) {
+        console.log('  (kdna CLI not available — skipping validate test)');
+        return;
+      }
+      throw e;
+    }
+  });
+
+  test('compiled output structure matches KDNA SPEC', () => {
+    const project = createFullProject();
+    const result = compileDomain(project);
+
+    // Verify KDNA_Core.json has all SPEC-required fields
+    const core = JSON.parse(result.files['KDNA_Core.json']);
+    assert.ok(core.meta, 'meta required');
+    assert.equal(core.meta.domain, 'leadership_decisions');
+    assert.equal(core.meta.version, '0.1.0');
+    assert.ok(core.meta.purpose);
+    assert.ok(core.meta.load_condition);
+    assert.ok(Array.isArray(core.axioms), 'axioms array required');
+    assert.equal(core.axioms.length, 3);
+    assert.ok(Array.isArray(core.ontology), 'ontology array required');
+    assert.ok(Array.isArray(core.frameworks), 'frameworks array required');
+    assert.ok(Array.isArray(core.stances), 'stances array required');
+    assert.ok(Array.isArray(core.core_structure), 'core_structure array required');
+
+    // Verify KDNA_Patterns.json
+    const patterns = JSON.parse(result.files['KDNA_Patterns.json']);
+    assert.ok(patterns.meta, 'Patterns meta required');
+    assert.ok(Array.isArray(patterns.misunderstandings));
+    assert.equal(patterns.misunderstandings.length, 2);
+    assert.ok(Array.isArray(patterns.self_check));
+    assert.equal(patterns.self_check.length, 5);
+
+    // Verify kdna.json manifest
+    const manifest = JSON.parse(result.files['kdna.json']);
+    assert.equal(manifest.name, 'leadership_decisions');
+    assert.equal(manifest.kdna_spec, '1.0-rc');
+    assert.ok(manifest.file_count >= 2, `file_count should be >= 2, got ${manifest.file_count}`);
+
+    // Verify KDNA_Reasoning.json (should exist since we have axioms)
+    assert.ok('KDNA_Reasoning.json' in result.files, 'Reasoning file should exist');
+    const reasoning = JSON.parse(result.files['KDNA_Reasoning.json']);
+    assert.ok(reasoning.meta);
+    assert.ok(Array.isArray(reasoning.reasoning_chains));
+    assert.ok(reasoning.reasoning_chains.every(c => 'so_what' in c), 'Every chain must have so_what');
+    assert.ok(reasoning.reasoning_chains.every(c => 'one_sentence' in c), 'Every chain must have one_sentence');
+
+    // Verify KDNA_Evolution.json
+    assert.ok('KDNA_Evolution.json' in result.files, 'Evolution file should exist');
+    const evolution = JSON.parse(result.files['KDNA_Evolution.json']);
+    assert.ok(evolution.meta);
+    assert.ok(Array.isArray(evolution.measurement));
+  });
+
+  test('compiled axioms have required fields', () => {
+    const project = createFullProject();
+    const result = compileDomain(project);
+    const core = JSON.parse(result.files['KDNA_Core.json']);
+
+    for (const ax of core.axioms) {
+      assert.ok(ax.one_sentence, `${ax.id}: missing one_sentence`);
+      assert.ok(ax.full_statement, `${ax.id}: missing full_statement`);
+      assert.ok(ax.why, `${ax.id}: missing why`);
+      assert.ok(Array.isArray(ax.applies_when), `${ax.id}: applies_when must be array`);
+      assert.ok(Array.isArray(ax.does_not_apply_when), `${ax.id}: does_not_apply_when must be array`);
+      assert.ok(ax.failure_risk, `${ax.id}: missing failure_risk`);
+    }
+  });
+
+  test('compiled misunderstandings have key_distinction', () => {
+    const project = createFullProject();
+    const result = compileDomain(project);
+    const patterns = JSON.parse(result.files['KDNA_Patterns.json']);
+
+    for (const ms of patterns.misunderstandings) {
+      assert.ok(ms.key_distinction, `${ms.id}: missing key_distinction`);
+      assert.ok(ms.key_distinction.length >= 20, `${ms.id}: key_distinction too short`);
+    }
+  });
+});
+
+// ─── E2E: compile → pack → inspect ───────────────────────────────────
+
+describe('E2E: compile → pack → inspect', () => {
+  test('compiled output survives pack→inspect round-trip', () => {
+    const project = createFullProject();
+    const result = compileDomain(project);
+    const domainDir = path.join(TMPDIR, 'pack-test');
+
+    fs.mkdirSync(domainDir, { recursive: true });
+    for (const [filename, content] of Object.entries(result.files)) {
+      fs.writeFileSync(path.join(domainDir, filename), content);
+    }
+
+    try {
+      // Pack
+      const packResult = execFileSync('kdna', ['pack', domainDir, '--output', TMPDIR], {
+        encoding: 'utf8', timeout: 60000,
+      });
+      assert.match(packResult, /Packed|✓/);
+
+      // Find the .kdna file
+      const kdnaFile = fs.readdirSync(TMPDIR).find(f => f.endsWith('.kdna'));
+      assert.ok(kdnaFile, 'Should produce a .kdna file');
+
+      // Inspect
+      const inspectResult = execFileSync('kdna', ['inspect', path.join(TMPDIR, kdnaFile), '--json'], {
+        encoding: 'utf8', timeout: 15000,
+      });
+      const inspected = JSON.parse(inspectResult);
+      assert.equal(inspected.name, 'leadership_decisions');
+      assert.equal(inspected.version, '0.1.0');
+    } catch (e) {
+      const stderr = (e.stderr || '').toString();
+      if (stderr.includes('kdna') || stderr.includes('not found')) {
+        console.log('  (kdna CLI not available — skipping pack/inspect test)');
+        return;
+      }
+      throw e;
+    }
+  });
+});
+
+// ─── E2E: provenance ─────────────────────────────────────────────────
+
+describe('E2E: provenance completeness', () => {
+  test('provenance covers all required metadata', () => {
+    const project = createFullProject();
+    const result = compileDomain(project);
+    const prov = buildProvenance(project, result.files);
+
+    assert.equal(prov.studio_core, 'knowledge-dna/kdna-studio');
+    assert.ok(prov.studio_core_version);
+    assert.ok(prov.build_id);
+    assert.ok(prov.project_id);
+    assert.equal(prov.author_id, 'expert_001');
+    assert.equal(prov.locked_card_count, 10); // 3 axioms + 2 misunderstandings + 5 self-checks
+    assert.equal(prov.test_case_count, 0);
+    assert.ok(prov.built_at);
+    assert.ok(prov.content_fingerprint.startsWith('sha256:'));
+  });
+});
+
+// Cleanup
+process.on('exit', () => {
+  try { fs.rmSync(TMPDIR, { recursive: true, force: true }); } catch {}
+});

package/tests/milestone2.test.js

@@ -221,8 +221,8 @@ describe('Full Compile', () => {
     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);
+    assert.equal(evo.measurement[0].what, 'locked_axioms');
+    assert.equal(evo.measurement[0].threshold, '1');
   });
 });