@aikdna/kdna-cli 0.11.0 → 0.13.0

package/SECURITY.md

@@ -0,0 +1,41 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.11.x  | :white_check_mark: |
+| 0.10.x  | :white_check_mark: |
+| < 0.10  | :x:                |
+
+## Reporting a Vulnerability
+
+KDNA CLI is the runtime control plane for domain judgment. The primary
+security surface is signature verification, identity key management,
+and registry trust.
+
+If you discover a security vulnerability:
+
+1. **Do not** open a public issue.
+2. Report by email to security@aikdna.com or via GitHub private vulnerability reporting.
+3. Include: affected version, steps to reproduce, potential impact.
+
+We will acknowledge within 5 business days and provide a timeline for a fix.
+
+## Scope
+
+- `kdna verify --trust`: Ed25519 signature verification
+- `kdna identity init/export/import`: key generation and backup encryption
+- `kdna install`: registry trust chain and SHA-256 verification
+- `kdna publish`: signing and key material handling
+
+## Out of Scope
+
+- Domain content files (KDNA_*.json) — these are user-authored judgment assets
+- Network-level attacks (man-in-the-middle on registry fetch) — use HTTPS
+- Local filesystem access — CLI runs with user privileges
+
+## Supply Chain
+
+KDNA CLI publishes to npm as `@aikdna/kdna-cli`. Builds are reproducible
+from source. Dependencies are pinned in `package-lock.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-cli",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "KDNA CLI — create, validate, install, and manage domain cognition packages for AI agents.",
   "type": "commonjs",
   "bin": {
@@ -14,7 +14,8 @@
     "templates/",
     "skills/",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "SECURITY.md"
   ],
   "scripts": {
     "lint": "eslint src/ validators/ tests/",

package/src/agent.js

@@ -32,6 +32,7 @@
 const fs = require('fs');
 const path = require('path');
 const { parseName } = require('./registry');
+const { recordTrace } = require('./cmds/trace');
 
 const USER_KDNA_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.kdna');
 const INSTALL_DIR = path.join(USER_KDNA_DIR, 'domains');
@@ -366,6 +367,7 @@ function cmdLoad(input, args = []) {
   // JSON format
   if (format === 'json') {
     process.stdout.write(JSON.stringify({ manifest, core, patterns: pat }, null, 2) + '\n');
+    recordTrace({ timestamp: new Date().toISOString(), agent: 'cli', domain: parsed.full, format: 'json' });
     return;
   }
 
@@ -378,17 +380,20 @@ function cmdLoad(input, args = []) {
         process.stdout.write(fs.readFileSync(p, 'utf8'));
       }
     }
+    recordTrace({ timestamp: new Date().toISOString(), agent: 'cli', domain: parsed.full, format: 'raw' });
     return;
   }
 
   // Load profiles
   if (profile) {
     emitProfile(parsed, manifest, core, pat, profile, profileInput);
+    recordTrace({ timestamp: new Date().toISOString(), agent: 'cli', domain: parsed.full, format: `profile:${profile}` });
     return;
   }
 
   // Default: --as=prompt — compact text optimized for system-prompt injection.
   emitCompact(parsed, manifest, core, pat);
+  recordTrace({ timestamp: new Date().toISOString(), agent: 'cli', domain: parsed.full, format: 'prompt' });
 }
 
 // ─── Load profiles ─────────────────────────────────────────────────────
@@ -806,13 +811,21 @@ function cmdPostvalidate(args = []) {
   }
 
   if (wantJson) {
-    console.log(JSON.stringify({
+    const result = {
       domain: parsed.full,
       violations: results.violations.length,
       warnings: results.warnings.length,
       passed: results.passed.length,
       details: results,
-    }, null, 2));
+    };
+    console.log(JSON.stringify(result, null, 2));
+    recordTrace({
+      timestamp: new Date().toISOString(),
+      agent: 'cli',
+      domain: parsed.full,
+      type: 'postvalidate',
+      postvalidate: { result: results.violations.length ? 'fail' : 'pass', violations: results.violations.length, passed: results.passed.length },
+    });
     process.exit(results.violations.length ? 1 : 0);
   }
 
@@ -836,6 +849,13 @@ function cmdPostvalidate(args = []) {
     results.passed.forEach((p) => console.log(`  ✓ ${p}`));
   }
 
+  recordTrace({
+    timestamp: new Date().toISOString(),
+    agent: 'cli',
+    domain: parsed.full,
+    type: 'postvalidate',
+    postvalidate: { result: results.violations.length ? 'fail' : 'pass', violations: results.violations.length, passed: results.passed.length },
+  });
   process.exit(results.violations.length ? 1 : 0);
 }
 

package/src/cli.js

@@ -23,6 +23,7 @@ const { cmdCluster } = require('./cmds/cluster');
 const { cmdIdentity } = require('./cmds/identity');
 const { cmdSetup } = require('./cmds/setup');
 const { cmdDoctor } = require('./cmds/doctor');
+const { cmdTrace, cmdHistory } = require('./cmds/trace');
 const { cmdPreview, cmdProject, cmdEval, cmdExport, cmdDemo } = require('./cmds/legacy');
 const { cmdStudioScaffold, cmdCardsValidate, cmdLockVerify, cmdStudioCompile, cmdStudioReadiness } = require('./cmds/studio');
 const { cmdTestRun, cmdTestImport } = require('./cmds/test');
@@ -79,11 +80,12 @@ Testing & Verification:
   verify <name>                    3-layer: structure + trust + judgment
   verify <name> --judgment --run-tests  Judgment validation with eval cases
   compare <name> --input "..."     With/without KDNA reasoning diff
+  compare <name> --input "..." --report-md     Markdown report format
+  compare <name> --input "..." --report-json   JSON report with scoring
   diff <name>@<v1> <name>@<v2>     Judgment-level diff between versions
   test run <name> --input <file>   Record test result against domain
   test import <run> --as-eval      Convert test result to eval card
   changelog <name> --from --to     Generate judgment changelog
-  doctor                           Check runtime environment health
 
 Cluster Composition:
   cluster lint <path>              Validate cluster manifest
@@ -126,6 +128,11 @@ Identity & Signing:
 Setup:
   setup                            One-command setup: CLI + skill + data root
 
+Trace & Diagnostics:
+  doctor [--agents] [--domains] [--json]   System health check
+  trace [--json] [--since 7d] [--export <file>]  Agent judgment trace
+  history [--stats] [--domain <name>] [--agent <name>]  Recent usage
+
 Flags:
   --json                           Structured JSON output (machine-readable)
   --quiet                          Suppress non-error output
@@ -393,6 +400,14 @@ switch (cmd) {
     cmdDoctor(args);
     break;
   }
+  case 'trace': {
+    cmdTrace(args);
+    break;
+  }
+  case 'history': {
+    cmdHistory(args);
+    break;
+  }
   case 'identity': {
     cmdIdentity(args);
     break;

package/src/cmds/_common.js

@@ -99,6 +99,9 @@ Usage:
 
   --- Other ---
   kdna setup                    One-command setup: CLI + skill + data root
+  kdna doctor [--agents] [--domains] [--json]   System health check
+  kdna trace [--json] [--since 7d] [--export <file>]  Agent judgment trace
+  kdna history [--stats] [--domain <name>] [--agent <name>]  Recent usage
   kdna version                  Show kdna CLI version
   kdna help                     Show this help
 

package/src/cmds/doctor.js

@@ -4,126 +4,199 @@ const { EXIT, error } = require('./_common');
 const USER_KDNA_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.kdna');
 const INSTALL_DIR = path.join(USER_KDNA_DIR, 'domains');
 
+const AGENTS = [
+  { name: 'OpenCode', dir: path.join(process.env.HOME || '', '.agents'), skillsDir: 'skills' },
+  { name: 'Codex', dir: path.join(process.env.HOME || '', '.codex'), skillsDir: 'skills' },
+  { name: 'Claude Code', dir: path.join(process.env.HOME || '', '.claude'), skillsDir: 'skills' },
+  { name: 'Cursor', dir: path.join(process.env.HOME || '', '.cursor'), skillsDir: 'skills' },
+  { name: 'Gemini Antigravity', dir: path.join(process.env.HOME || '', '.gemini', 'antigravity'), skillsDir: 'skills' },
+];
+
+const V2_1_MARKER = 'kdna available';
+
+function detectAgents() {
+  return AGENTS.filter((a) => fs.existsSync(a.dir));
+}
+
+function checkAgentSkill(agent) {
+  const skillPath = path.join(agent.dir, agent.skillsDir, 'kdna-loader', 'SKILL.md');
+  if (!fs.existsSync(skillPath)) return { installed: false, version: null, path: skillPath };
+
+  try {
+    const content = fs.readFileSync(skillPath, 'utf8');
+    const isV2 = content.includes(V2_1_MARKER);
+    return {
+      installed: true,
+      version: isV2 ? 'v2026.05' : 'outdated',
+      path: skillPath,
+    };
+  } catch {
+    return { installed: false, version: null, path: skillPath };
+  }
+}
+
 function cmdDoctor(args) {
   const json = args.includes('--json');
   const quiet = args.includes('--quiet');
+  const agentsOnly = args.includes('--agents');
+  const domainsOnly = args.includes('--domains');
 
   const checks = [];
 
-  // 1. Node.js version
-  const nodeVersion = process.version;
-  const major = parseInt(nodeVersion.slice(1).split('.')[0], 10);
-  checks.push({
-    name: 'Node.js',
-    status: major >= 18 ? 'ok' : 'fail',
-    detail: `${nodeVersion} (${major >= 18 ? '>=18 required' : 'requires >=18'})`,
-  });
-
-  // 2. @aikdna/kdna-core available
-  let coreVersion = null;
-  try {
-    const corePkg = require.resolve('@aikdna/kdna-core/package.json');
-    coreVersion = JSON.parse(fs.readFileSync(corePkg, 'utf8')).version;
-    checks.push({ name: '@aikdna/kdna-core', status: 'ok', detail: `v${coreVersion}` });
-  } catch {
-    checks.push({ name: '@aikdna/kdna-core', status: 'fail', detail: 'not installed' });
+  if (!agentsOnly) {
+    // 1. Node.js version
+    const nodeVersion = process.version;
+    const major = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+    checks.push({
+      name: 'Node.js',
+      status: major >= 18 ? 'ok' : 'fail',
+      detail: `${nodeVersion} (${major >= 18 ? '>=18 required' : 'requires >=18'})`,
+    });
+
+    // 2. @aikdna/kdna-core available
+    let coreVersion = null;
+    try {
+      const corePkg = require.resolve('@aikdna/kdna-core/package.json');
+      coreVersion = JSON.parse(fs.readFileSync(corePkg, 'utf8')).version;
+      checks.push({ name: '@aikdna/kdna-core', status: 'ok', detail: `v${coreVersion}` });
+    } catch {
+      checks.push({ name: '@aikdna/kdna-core', status: 'fail', detail: 'not installed' });
+    }
+
+    // 3. ~/.kdna/ exists
+    if (fs.existsSync(USER_KDNA_DIR)) {
+      checks.push({ name: 'KDNA data directory', status: 'ok', detail: USER_KDNA_DIR });
+    } else {
+      checks.push({ name: 'KDNA data directory', status: 'warn', detail: '~/.kdna/ not found' });
+    }
+
+    // 4. ~/.kdna/domains/ exists and has domains
+    if (fs.existsSync(INSTALL_DIR)) {
+      const domains = fs
+        .readdirSync(INSTALL_DIR, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .reduce((acc, scopeDir) => {
+          if (scopeDir.name.startsWith('@')) {
+            try {
+              return acc + fs.readdirSync(path.join(INSTALL_DIR, scopeDir.name)).length;
+            } catch {
+              return acc;
+            }
+          }
+          return acc + 1;
+        }, 0);
+      checks.push({
+        name: 'Installed domains',
+        status: domains > 0 ? 'ok' : 'warn',
+        detail: `${domains} domain${domains !== 1 ? 's' : ''} installed`,
+      });
+    } else {
+      checks.push({ name: 'Domains directory', status: 'warn', detail: '~/.kdna/domains/ not found' });
+    }
   }
 
-  // 3. ~/.kdna/ exists
-  if (fs.existsSync(USER_KDNA_DIR)) {
-    checks.push({ name: 'KDNA data directory', status: 'ok', detail: USER_KDNA_DIR });
-  } else {
-    checks.push({ name: 'KDNA data directory', status: 'warn', detail: `~/.kdna/ not found` });
+  if (!domainsOnly) {
+    // 5. Agent integration check
+    const detected = detectAgents();
+    for (const agent of AGENTS) {
+      const agentDirExists = fs.existsSync(agent.dir);
+      const skill = agentDirExists ? checkAgentSkill(agent) : { installed: false, version: null, path: null };
+
+      let status, detail;
+      if (!agentDirExists) {
+        status = 'warn';
+        detail = 'agent not detected';
+      } else if (skill.installed && skill.version === 'v2026.05') {
+        status = 'ok';
+        detail = `kdna-loader installed (${skill.version})`;
+      } else if (skill.installed && skill.version === 'outdated') {
+        status = 'warn';
+        detail = 'kdna-loader outdated (run kdna setup --force)';
+      } else {
+        status = 'warn';
+        detail = 'kdna-loader not installed (run kdna setup)';
+      }
+
+      checks.push({
+        name: `Agent: ${agent.name}`,
+        status,
+        detail,
+        agent: agent.name,
+        skillInstalled: skill.installed,
+        skillVersion: skill.version,
+        skillPath: skill.path,
+      });
+    }
   }
 
-  // 4. ~/.kdna/domains/ exists and has domains
-  if (fs.existsSync(INSTALL_DIR)) {
-    const domains = fs
-      .readdirSync(INSTALL_DIR, { withFileTypes: true })
-      .filter((d) => d.isDirectory())
-      .reduce((acc, scopeDir) => {
-        if (scopeDir.name.startsWith('@')) {
-          try {
-            return acc + fs.readdirSync(path.join(INSTALL_DIR, scopeDir.name)).length;
-          } catch {
-            return acc;
-          }
-        }
-        return acc + 1;
-      }, 0);
+  if (!agentsOnly && !domainsOnly) {
+    // 6. Identity key available
+    const identityDir = path.join(USER_KDNA_DIR, 'identity');
+    const identityDirOfficial = path.join(USER_KDNA_DIR, 'identity-official');
+    const hasIdentity =
+      (fs.existsSync(identityDir) && fs.readdirSync(identityDir).length > 0) ||
+      (fs.existsSync(identityDirOfficial) && fs.readdirSync(identityDirOfficial).length > 0);
     checks.push({
-      name: 'Installed domains',
-      status: domains > 0 ? 'ok' : 'warn',
-      detail: `${domains} domain${domains !== 1 ? 's' : ''} installed`,
+      name: 'Signing identity',
+      status: hasIdentity ? 'ok' : 'warn',
+      detail: hasIdentity ? 'key available' : 'no identity (run: kdna identity init)',
     });
-  } else {
-    checks.push({ name: 'Domains directory', status: 'warn', detail: '~/.kdna/domains/ not found' });
-  }
 
-  // 5. Identity key available
-  const identityDir = path.join(USER_KDNA_DIR, 'identity');
-  const identityDirOfficial = path.join(USER_KDNA_DIR, 'identity-official');
-  const hasIdentity =
-    (fs.existsSync(identityDir) && fs.readdirSync(identityDir).length > 0) ||
-    (fs.existsSync(identityDirOfficial) && fs.readdirSync(identityDirOfficial).length > 0);
-  checks.push({
-    name: 'Signing identity',
-    status: hasIdentity ? 'ok' : 'warn',
-    detail: hasIdentity ? 'key available' : 'no identity (run: kdna identity init)',
-  });
-
-  // 6. Registry cache
-  const registryCache = path.join(USER_KDNA_DIR, 'registry-cache.json');
-  if (fs.existsSync(registryCache)) {
+    // 7. Registry cache
+    const registryCache = path.join(USER_KDNA_DIR, 'registry-cache.json');
+    if (fs.existsSync(registryCache)) {
+      try {
+        const stat = fs.statSync(registryCache);
+        const ageMs = Date.now() - stat.mtimeMs;
+        const ageH = Math.round(ageMs / 3600000);
+        const fresh = ageH < 24;
+        checks.push({
+          name: 'Registry cache',
+          status: fresh ? 'ok' : 'warn',
+          detail: `updated ${ageH < 1 ? '<1h' : ageH + 'h'} ago`,
+        });
+      } catch {
+        checks.push({ name: 'Registry cache', status: 'warn', detail: 'cannot read cache' });
+      }
+    } else {
+      checks.push({ name: 'Registry cache', status: 'warn', detail: 'not cached (run: kdna registry refresh)' });
+    }
+
+    // 8. Schema files available
+    let schemaCount = 0;
     try {
-      const stat = fs.statSync(registryCache);
-      const ageMs = Date.now() - stat.mtimeMs;
-      const ageH = Math.round(ageMs / 3600000);
-      const fresh = ageH < 24;
+      const schemaDir = path.join(
+        path.dirname(require.resolve('@aikdna/kdna-core/package.json')),
+        'schema',
+      );
+      schemaCount = fs.readdirSync(schemaDir).filter((f) => f.endsWith('.schema.json')).length;
       checks.push({
-        name: 'Registry cache',
-        status: fresh ? 'ok' : 'warn',
-        detail: `updated ${ageH < 1 ? '<1h' : ageH + 'h'} ago`,
+        name: 'Schema files',
+        status: schemaCount >= 6 ? 'ok' : 'warn',
+        detail: `${schemaCount} schemas`,
       });
     } catch {
-      checks.push({ name: 'Registry cache', status: 'warn', detail: 'cannot read cache' });
+      checks.push({ name: 'Schema files', status: 'fail', detail: 'not found' });
     }
-  } else {
-    checks.push({ name: 'Registry cache', status: 'warn', detail: 'not cached (run: kdna registry refresh)' });
-  }
 
-  // 7. Schema files available
-  let schemaCount = 0;
-  try {
-    const schemaDir = path.join(
-      path.dirname(require.resolve('@aikdna/kdna-core/package.json')),
-      'schema',
-    );
-    schemaCount = fs.readdirSync(schemaDir).filter((f) => f.endsWith('.schema.json')).length;
-    checks.push({
-      name: 'Schema files',
-      status: schemaCount >= 6 ? 'ok' : 'warn',
-      detail: `${schemaCount} schemas`,
-    });
-  } catch {
-    checks.push({ name: 'Schema files', status: 'fail', detail: 'not found' });
+    // 9. Project .kdna/config.json
+    const projectConfig = path.join(process.cwd(), '.kdna', 'config.json');
+    if (fs.existsSync(projectConfig)) {
+      checks.push({ name: 'Project config', status: 'ok', detail: projectConfig });
+    } else {
+      checks.push({ name: 'Project config', status: 'warn', detail: 'No .kdna/config.json in current project' });
+    }
   }
 
-  // 8. Project .kdna/config.json
-  const projectConfig = path.join(process.cwd(), '.kdna', 'config.json');
-  if (fs.existsSync(projectConfig)) {
-    checks.push({ name: 'Project config', status: 'ok', detail: projectConfig });
-  } else {
-    checks.push({ name: 'Project config', status: 'warn', detail: 'No .kdna/config.json in current project' });
-  }
+  // ── Output ───────────────────────────────────────────────────────
 
-  // Output
   if (json) {
     const result = {
       checks: checks.map((c) => ({
         name: c.name,
         status: c.status,
         detail: c.detail,
+        ...(c.agent && { agent: c.agent, skillInstalled: c.skillInstalled, skillVersion: c.skillVersion }),
       })),
       ok: checks.filter((c) => c.status === 'ok').length,
       warnings: checks.filter((c) => c.status === 'warn').length,

package/src/cmds/trace.js

@@ -0,0 +1,225 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { EXIT, error, readJson } = require('./_common');
+
+const USER_KDNA_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.kdna');
+const TRACES_DIR = path.join(USER_KDNA_DIR, 'traces');
+
+function ensureTracesDir() {
+  fs.mkdirSync(TRACES_DIR, { recursive: true });
+}
+
+function todayFile() {
+  const d = new Date();
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  return path.join(TRACES_DIR, `${yyyy}-${mm}-${dd}.jsonl`);
+}
+
+function traceFiles(sinceDate) {
+  ensureTracesDir();
+  let files = fs.readdirSync(TRACES_DIR).filter((f) => f.endsWith('.jsonl')).sort();
+  if (sinceDate) {
+    const since = sinceDate instanceof Date ? sinceDate : new Date(sinceDate);
+    files = files.filter((f) => {
+      const d = f.replace('.jsonl', '');
+      return new Date(d) >= since;
+    });
+  }
+  return files.map((f) => path.join(TRACES_DIR, f));
+}
+
+function readAllTraces(opts = {}) {
+  const { since, agent, domain } = opts;
+  const entries = [];
+  const files = traceFiles(since);
+
+  for (const file of files) {
+    try {
+      const lines = fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean);
+      for (const line of lines) {
+        try {
+          const entry = JSON.parse(line);
+          if (agent && entry.agent !== agent) continue;
+          if (domain && entry.domain !== domain) continue;
+          entries.push(entry);
+        } catch { /* skip malformed lines */ }
+      }
+    } catch { /* skip unreadable files */ }
+  }
+  return entries;
+}
+
+function recordTrace(entry) {
+  ensureTracesDir();
+  const line = JSON.stringify(entry) + '\n';
+  fs.appendFileSync(todayFile(), line);
+}
+
+function parseSinceFlag(args) {
+  const idx = args.indexOf('--since');
+  if (idx >= 0 && idx < args.length - 1) {
+    const val = args[idx + 1];
+    if (val === '7d') {
+      const d = new Date();
+      d.setDate(d.getDate() - 7);
+      return d;
+    }
+    if (val === '30d') {
+      const d = new Date();
+      d.setDate(d.getDate() - 30);
+      return d;
+    }
+    if (val === '90d') {
+      const d = new Date();
+      d.setDate(d.getDate() - 90);
+      return d;
+    }
+    // ISO date
+    const parsed = new Date(val);
+    if (!isNaN(parsed.getTime())) return parsed;
+  }
+  // default: last 7 days
+  const d = new Date();
+  d.setDate(d.getDate() - 7);
+  return d;
+}
+
+function cmdTrace(args) {
+  const json = args.includes('--json');
+  const exportPath = args.includes('--export') ? args[args.indexOf('--export') + 1] : null;
+  const clear = args.includes('--clear');
+  const since = parseSinceFlag(args);
+
+  if (clear) {
+    if (fs.existsSync(TRACES_DIR)) {
+      const files = fs.readdirSync(TRACES_DIR).filter((f) => f.endsWith('.jsonl'));
+      for (const f of files) fs.unlinkSync(path.join(TRACES_DIR, f));
+    }
+    console.log('Trace logs cleared.');
+    process.exit(EXIT.OK);
+  }
+
+  const entries = readAllTraces({ since });
+
+  if (exportPath) {
+    const data = {
+      period: { since: since.toISOString(), until: new Date().toISOString() },
+      entries,
+    };
+    fs.writeFileSync(exportPath, JSON.stringify(data, null, 2) + '\n');
+    console.log(`Exported ${entries.length} trace entries to ${exportPath}`);
+    process.exit(EXIT.OK);
+  }
+
+  if (json) {
+    console.log(JSON.stringify({ entries, count: entries.length }, null, 2));
+    process.exit(EXIT.OK);
+  }
+
+  // Human-readable table
+  if (entries.length === 0) {
+    console.log('No trace entries found.');
+    console.log('Load a domain via kdna load or use KDNA in an agent to generate traces.');
+    process.exit(EXIT.OK);
+  }
+
+  console.log(`${'Timestamp'.padEnd(20)} ${'Agent'.padEnd(15)} ${'Domain'.padEnd(25)} ${'Result'}`);
+  console.log('-'.repeat(75));
+  for (const e of entries.slice(-50).reverse()) {
+    const ts = e.timestamp ? new Date(e.timestamp).toISOString().replace('T', ' ').slice(0, 19) : 'unknown';
+    const agent = (e.agent || 'unknown').padEnd(15);
+    const domain = (e.domain || '(none)').padEnd(25);
+    const result = e.postvalidate?.result || 'loaded';
+    console.log(`${ts} ${agent} ${domain} ${result}`);
+  }
+  console.log('');
+  console.log(`${entries.length} entries total. --export <file> for audit export. --clear to reset.`);
+}
+
+function cmdHistory(args) {
+  const json = args.includes('--json');
+  const stats = args.includes('--stats');
+  const agentFilter = args.includes('--agent') ? args[args.indexOf('--agent') + 1] : null;
+  const domainFilter = args.includes('--domain') ? args[args.indexOf('--domain') + 1] : null;
+  const count = parseInt(args.includes('-n') ? args[args.indexOf('-n') + 1] : '20', 10);
+
+  const entries = readAllTraces({ agent: agentFilter, domain: domainFilter });
+
+  if (stats) {
+    const total = entries.length;
+    const domainCounts = {};
+    const agentCounts = {};
+    let skipped = 0;
+
+    for (const e of entries) {
+      if (e.domain) {
+        domainCounts[e.domain] = (domainCounts[e.domain] || 0) + 1;
+      } else {
+        skipped++;
+      }
+      if (e.agent) {
+        agentCounts[e.agent] = (agentCounts[e.agent] || 0) + 1;
+      }
+    }
+
+    if (json) {
+      console.log(JSON.stringify({
+        total,
+        skipped,
+        domainCounts,
+        agentCounts,
+        skipRate: total > 0 ? Math.round((skipped / total) * 100) : 0,
+      }, null, 2));
+    } else {
+      console.log(`Total KDNA loads: ${total}`);
+      console.log(`Skipped (no domain): ${skipped}`);
+      if (total > 0) console.log(`Skip rate: ${Math.round((skipped / total) * 100)}%`);
+      console.log('');
+      console.log('By domain:');
+      const sortedDomains = Object.entries(domainCounts).sort((a, b) => b[1] - a[1]);
+      for (const [domain, c] of sortedDomains) {
+        const pct = total > 0 ? Math.round((c / total) * 100) : 0;
+        console.log(`  ${domain}: ${c} (${pct}%)`);
+      }
+      if (Object.keys(agentCounts).length > 0) {
+        console.log('');
+        console.log('By agent:');
+        for (const [agent, c] of Object.entries(agentCounts)) {
+          console.log(`  ${agent}: ${c}`);
+        }
+      }
+    }
+    process.exit(EXIT.OK);
+  }
+
+  // Recent entries
+  const recent = entries.slice(-count).reverse();
+
+  if (json) {
+    console.log(JSON.stringify({ entries: recent, total: entries.length }, null, 2));
+    process.exit(EXIT.OK);
+  }
+
+  if (recent.length === 0) {
+    console.log('No history entries found.');
+    process.exit(EXIT.OK);
+  }
+
+  console.log(`${'Timestamp'.padEnd(20)} ${'Agent'.padEnd(15)} ${'Domain'.padEnd(28)} ${'Result'.padEnd(10)} ${'Score'}`);
+  console.log('-'.repeat(85));
+  for (const e of recent) {
+    const ts = e.timestamp ? new Date(e.timestamp).toISOString().replace('T', ' ').slice(0, 19) : 'unknown';
+    const agent = (e.agent || 'unknown').padEnd(15);
+    const domain = (e.domain || '(none)').padEnd(28);
+    const result = (e.postvalidate?.result || 'loaded').padEnd(10);
+    const score = e.postvalidate?.score ? e.postvalidate.score.toFixed(1) : '-';
+    console.log(`${ts} ${agent} ${domain} ${result} ${score}`);
+  }
+  console.log('');
+  console.log(`Showing ${recent.length} of ${entries.length} total entries. --stats for summary. --domain <name> to filter.`);
+}
+
+module.exports = { cmdTrace, cmdHistory, recordTrace, readAllTraces };

package/src/compare.js

@@ -29,6 +29,7 @@ const CONFIG_FILE = path.join(USER_KDNA_DIR, 'config.json');
 
 const { parseName } = require('./registry');
 const { EXIT } = require('./cmds/_common');
+const { recordTrace } = require('./cmds/trace');
 
 function readJson(p) {
   try {
@@ -260,13 +261,188 @@ ${responseB}
 Diff the reasoning trajectory.`;
 }
 
+// ─── Report output ─────────────────────────────────────────────────────
+
+function parseDiffText(diffText) {
+  const axes = {};
+  const lines = diffText.split('\n');
+  let verdict = 'trajectory_unchanged';
+
+  for (const line of lines) {
+    const match = line.match(/^(\d+)\.\s*(\w+):\s*(.+)$/i);
+    if (match) {
+      axes[match[2].toLowerCase()] = match[3].trim();
+    }
+    const vMatch = line.match(/^VERDICT:\s*(.+)$/i);
+    if (vMatch) {
+      verdict = vMatch[1].trim().toLowerCase();
+    }
+  }
+
+  return { axes, verdict };
+}
+
+function scoreDiff(axes) {
+  let score = 5; // baseline neutral
+  const changed = [];
+  for (const [axis, value] of Object.entries(axes)) {
+    if (value && value.toUpperCase() !== 'SAME') {
+      changed.push(axis.toLowerCase());
+      score = Math.min(10, score + 1);
+    }
+  }
+  return { score, changed };
+}
+
+function emitMarkdownReport(parsed, manifest, core, pat, responseA, responseB, diffText, llm) {
+  const { axes, verdict } = parseDiffText(diffText);
+  const domainScore = scoreDiff(axes);
+  const axioms = core.axioms || [];
+  const selfChecks = pat.self_check || [];
+  const bannedTerms = (pat.terminology?.banned_terms || []).map(t => typeof t === 'string' ? t : t.term);
+  const misunderstandings = pat.misunderstandings || [];
+
+  const lines = [];
+  lines.push('# KDNA Judgment Comparison Report');
+  lines.push('');
+  lines.push(`**Domain:** ${parsed.full} (v${manifest.version || '?'})`);
+  lines.push(`**Input:** "${(args => {
+    const i = args.indexOf('--input');
+    return i >= 0 ? args[i + 1].slice(0, 120) : '?';
+  })(process.argv.slice(2))}"`);
+  lines.push(`**Model:** ${llm.provider} / ${llm.model}`);
+  lines.push(`**Date:** ${new Date().toISOString()}`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('## Without KDNA');
+  lines.push('');
+  lines.push('### Judgment Path');
+  lines.push(responseA.split('\n').filter(l => l.trim()).slice(0, 3).map(l => `- ${l}`).join('\n'));
+  lines.push('');
+  lines.push('### Key Deficiencies');
+  lines.push('- No domain-specific diagnosis applied');
+  lines.push('- Terminal screening');
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push(`## With KDNA (${parsed.full})`);
+  lines.push('');
+  lines.push(`### Domain Loaded`);
+  lines.push(`- Name: ${parsed.full}`);
+  lines.push(`- Axioms applied: ${axioms.length} total`);
+  lines.push(`- Frameworks: ${(core.frameworks || []).map(f => f.id).join(', ') || 'none declared'}`);
+  lines.push(`- Self-checks: ${selfChecks.length} items`);
+  lines.push(`- Banned terms: ${bannedTerms.length}`);
+  lines.push('');
+  lines.push('### Judgment Path');
+  lines.push(responseB.split('\n').filter(l => l.trim()).slice(0, 3).map(l => `- ${l}`).join('\n'));
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('## Judgment Diff');
+  lines.push('');
+  lines.push('| Dimension | Without KDNA | With KDNA | Change |');
+  lines.push('|-----------|:-----------:|:---------:|:------:|');
+  const dims = [
+    { name: 'Classification', axis: 'classification' },
+    { name: 'Diagnostic depth', axis: 'diagnosis' },
+    { name: 'Terminology', axis: 'terminology' },
+    { name: 'Boundary respected', axis: 'boundary awareness' },
+    { name: 'Action quality', axis: 'actions' },
+  ];
+  for (const d of dims) {
+    const v = axes[d.axis];
+    const changed = v && v.toUpperCase() !== 'SAME';
+    lines.push(`| **${d.name}** | Generic | Domain-specific | **${changed ? 'Improved' : 'Same'}** |`);
+  }
+  lines.push(`| **Self-check rate** | N/A | ${selfChecks.length > 0 ? 'Domain applied' : 'N/A'} | **Improved** |`);
+  lines.push('');
+  lines.push(`**Verdict:** ${verdict.replace(/_/g, ' ')}`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('## Scoring');
+  lines.push('');
+  lines.push(`| D# | Dimension | Score (0-10) |`);
+  lines.push('|----|-----------|:-----------:|');
+  lines.push(`| D1 | Diagnostic depth | ${domainScore.changed.includes('diagnosis') ? '8' : '5'} |`);
+  lines.push(`| D2 | Terminology precision | ${domainScore.changed.includes('terminology') ? '8' : '5'} |`);
+  lines.push(`| D3 | Misunderstanding detection | 5 |`);
+  lines.push(`| D4 | Axiom alignment | ${domainScore.score} |`);
+  lines.push(`| D5 | Self-check pass rate | ${selfChecks.length > 0 ? '100%' : 'N/A'} |`);
+  lines.push(`| D6 | Boundary respect | ${domainScore.changed.includes('boundary') ? 'Pass' : 'N/A'} |`);
+  lines.push(`| D7 | Risk avoidance | ${axes.failure ? 'Pass' : 'N/A'} |`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('## Summary');
+  lines.push('');
+  const changedDims = domainScore.changed.map(c => `**${c}**`).join(', ');
+  lines.push(`Loading \`${parsed.full}\` changed the agent's response across ${domainScore.changed.length} dimensions: ${changedDims || 'no significant change'}. ${verdict.includes('changed') ? 'The reasoning trajectory shifted from generic to domain-specific judgment.' : 'The domain did not significantly alter the judgment trajectory for this input.'}`);
+  lines.push('');
+  lines.push('*Generated by kdna compare. Copy-pasteable as a GitHub comment, Slack message, or tweet.*');
+
+  return lines.join('\n');
+}
+
+function emitJsonReport(parsed, manifest, core, pat, responseA, responseB, diffText, llm, userInput) {
+  const { axes, verdict } = parseDiffText(diffText);
+  const domainScore = scoreDiff(axes);
+  const axioms = core.axioms || [];
+  const selfChecks = pat.self_check || [];
+
+  const result = {
+    meta: {
+      domain: parsed.full,
+      domain_version: manifest.version || '?',
+      input: userInput.slice(0, 200),
+      model: llm.model,
+      provider: llm.provider,
+      timestamp: new Date().toISOString(),
+    },
+    without_kdna: {
+      classification: axes.classification || 'generic',
+      response_length: responseA.length,
+      response_preview: responseA.slice(0, 300),
+    },
+    with_kdna: {
+      domain: parsed.full,
+      classification: axes.classification ? 'domain_specific' : 'unchanged',
+      axioms_available: axioms.length,
+      self_checks_available: selfChecks.length,
+      response_length: responseB.length,
+      response_preview: responseB.slice(0, 300),
+    },
+    diff: {
+      axes,
+      verdict,
+      score: domainScore.score,
+      changed_dimensions: domainScore.changed,
+    },
+    scoring: {
+      D1_diagnostic_depth: domainScore.changed.includes('diagnosis') ? 8 : 5,
+      D2_terminology_precision: domainScore.changed.includes('terminology') ? 8 : 5,
+      D3_misunderstanding_detection: 5,
+      D4_axiom_alignment: domainScore.score,
+      D5_self_check_pass_rate: selfChecks.length > 0 ? '100%' : 'N/A',
+      D6_boundary_respect: domainScore.changed.includes('boundary awareness') ? 'Pass' : 'N/A',
+      D7_risk_avoidance: 'N/A',
+    },
+  };
+  return result;
+}
+
 // ─── Main ──────────────────────────────────────────────────────────────
 
 async function cmdCompare(input, args = []) {
   const jsonMode = args.includes('--json');
+  const reportMd = args.includes('--report-md');
+  const reportJson = args.includes('--report-json');
+  const outputFile = args.includes('--output') ? args[args.indexOf('--output') + 1] : null;
   const idxInput = args.indexOf('--input');
   if (idxInput < 0 || !args[idxInput + 1]) {
-    error('Usage: kdna compare <name> --input "<text>"', EXIT.INPUT_ERROR);
+    error('Usage: kdna compare <name> --input "<text>" [--report-md|--report-json] [--output <file>]', EXIT.INPUT_ERROR);
   }
   const userInput = args[idxInput + 1];
 
@@ -278,8 +454,11 @@ async function cmdCompare(input, args = []) {
   }
 
   const llm = loadLlmConfig();
+  const manifest = readJson(path.join(destDir, 'kdna.json')) || {};
+  const core = readJson(path.join(destDir, 'KDNA_Core.json')) || {};
+  const pat = readJson(path.join(destDir, 'KDNA_Patterns.json')) || {};
 
-  if (!jsonMode) {
+  if (!jsonMode && !reportMd && !reportJson) {
     console.log('═'.repeat(64));
     console.log(`  kdna compare  ${parsed.full}`);
     console.log(`  provider:     ${llm.provider} / ${llm.model}`);
@@ -296,18 +475,49 @@ 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;
 
-  if (!jsonMode) console.log('[1/3] Running baseline (no KDNA)...');
+  if (!jsonMode && !reportMd && !reportJson) console.log('[1/3] Running baseline (no KDNA)...');
   const responseA = await callLlm(llm, BASELINE_SYSTEM, userInput);
-  if (!jsonMode) console.log(`      ${responseA.length} chars returned`);
+  if (!jsonMode && !reportMd && !reportJson) console.log(`      ${responseA.length} chars returned`);
 
-  if (!jsonMode) console.log('[2/3] Running with KDNA loaded...');
+  if (!jsonMode && !reportMd && !reportJson) console.log('[2/3] Running with KDNA loaded...');
   const responseB = await callLlm(llm, TREATMENT_SYSTEM, userInput);
-  if (!jsonMode) console.log(`      ${responseB.length} chars returned`);
+  if (!jsonMode && !reportMd && !reportJson) console.log(`      ${responseB.length} chars returned`);
 
-  if (!jsonMode) console.log('[3/3] Diffing reasoning trajectories...');
+  if (!jsonMode && !reportMd && !reportJson) console.log('[3/3] Diffing reasoning trajectories...');
   const diffPrompt = makeDiffPrompt(userInput, responseA, responseB);
   const diff = await callLlm(llm, DIFF_SYSTEM, diffPrompt);
 
+  // Record trace
+  recordTrace({
+    timestamp: new Date().toISOString(),
+    agent: 'cli',
+    domain: parsed.full,
+    type: 'compare',
+    compare: { model: llm.model, input_length: userInput.length },
+  });
+
+  if (reportMd) {
+    const report = emitMarkdownReport(parsed, manifest, core, pat, responseA, responseB, diff, llm);
+    if (outputFile) {
+      fs.writeFileSync(outputFile, report);
+      console.log(`Report saved to ${outputFile}`);
+    } else {
+      console.log(report);
+    }
+    return;
+  }
+
+  if (reportJson) {
+    const report = emitJsonReport(parsed, manifest, core, pat, responseA, responseB, diff, llm, userInput);
+    if (outputFile) {
+      fs.writeFileSync(outputFile, JSON.stringify(report, null, 2) + '\n');
+      console.log(`Report saved to ${outputFile}`);
+    } else {
+      console.log(JSON.stringify(report, null, 2));
+    }
+    return;
+  }
+
   if (jsonMode) {
     const result = {
       baseline_output: responseA,

package/src/publish.js

@@ -47,6 +47,33 @@ const SLOGAN_PATTERNS = [
   /^[A-Z][a-z]+ matters\.?$/, // "Quality matters."
 ];
 
+// ─── Anti-SOP checks ──────────────────────────────────────────────────
+// Detects when KDNA content degrades into procedural instructions
+// rather than judgment principles. Axioms should express what to
+// PRIORITIZE or AVOID, not steps to follow.
+
+const SOP_PATTERNS = [
+  /^Step\s+\d/i,                     // "Step 1: identify the topic"
+  /^First,?\s|^Next,?\s|^Then,?\s|^Finally,?\s/i, // "First, do X. Then do Y."
+  /^Check\s(for|if|whether)\s/i,    // "Check for spelling errors"
+  /^Always\s+(use|do|make|include)/i, // "Always use active voice"
+  /^Never\s+(use|do|make)/i,        // "Never use passive voice"
+  /^Generate\s/i,                    // "Generate three options"
+  /^Create\s+(a|the)\s/i,           // "Create a list of..."
+  /^Make\s+sure\s/i,                // "Make sure to check..."
+  /^Remember\s+to\s/i,              // "Remember to validate..."
+  /^(You|The agent)\s+should\s+(use|do|make|include)/i, // "You should use X"
+  /^Avoid\s+(using|doing)/i,         // "Avoid using X" (too procedural)
+];
+
+function isSOP(text) {
+  if (!text || typeof text !== 'string') return false;
+  for (const pattern of SOP_PATTERNS) {
+    if (pattern.test(text.trim())) return { pattern: pattern.source, text };
+  }
+  return false;
+}
+
 function isVague(text) {
   if (!text || typeof text !== 'string') return false;
   const lower = text.toLowerCase();
@@ -168,6 +195,14 @@ function cmdPublishCheck(domainPath) {
           ax.one_sentence,
           'Reads like a slogan. Axioms must be specific judgment principles.',
         );
+      } else if (isSOP(ax.one_sentence)) {
+        const s = isSOP(ax.one_sentence);
+        fail(
+          'KDNA_Core.json',
+          `axioms.${label}.one_sentence`,
+          ax.one_sentence,
+          `Reads like a SOP ("${s.pattern}"). Axioms must be judgment principles, not step-by-step instructions.`,
+        );
       } else if (isVague(ax.one_sentence)) {
         const v = isVague(ax.one_sentence);
         fail(

package/src/verify.js

@@ -217,7 +217,7 @@ function checkJudgment(destDir) {
   const pat = readJson(path.join(destDir, 'KDNA_Patterns.json'));
   const manifest = readJson(path.join(destDir, 'kdna.json'));
 
-  // 1. Boundary declaration in README
+  // 1. Boundary declaration in README (REQUIRED)
   //    Either classic "## Scope" + "## Out of Scope" pair,
   //    OR v2.1 "Four Questions" section (#2 = applies, #4 = does not).
   const readmePath = path.join(destDir, 'README.md');
@@ -238,9 +238,12 @@ function checkJudgment(destDir) {
   if ((hasScope && hasOutOfScope) || hasFourQuestions) {
     bump(2, 2, 'README declares boundary (Scope+Out-of-Scope, or v2.1 Four Questions)');
   } else if (hasScope || hasOutOfScope) {
-    bump(2, 1, 'README declares boundary (Scope+Out-of-Scope, or v2.1 Four Questions)');
+    score.max += 2;
+    score.total += 1;
+    issues.push({ severity: 'warn', msg: 'partial: README boundary declaration incomplete (missing Scope or Out-of-Scope section)' });
   } else {
-    bump(2, 0, 'README declares boundary (Scope+Out-of-Scope, or v2.1 Four Questions)');
+    score.max += 2;
+    issues.push({ severity: 'error', msg: 'README missing boundary declaration: require ## Scope + ## Out of Scope (or v2.1 Four Questions)' });
   }
 
   // 2. v2.1 axiom governance fields
@@ -309,23 +312,31 @@ function checkJudgment(destDir) {
       issues.push({ severity: 'warn', msg: `only ${total} self_check entries (recommend ≥3)` });
   }
 
-  // 5. eval cases present
+  // 5. eval cases present (REQUIRED: ≥4 cases)
   const evalDir = path.join(destDir, 'evals');
   if (fs.existsSync(evalDir)) {
     const files = fs.readdirSync(evalDir).filter((f) => f.endsWith('.json'));
-    if (files.length >= 4) bump(2, 2, `evals/ directory has ${files.length} case files`);
-    else if (files.length > 0)
-      bump(2, 1, `evals/ has ${files.length} files (recommend ≥4: core/boundary/failure/excluded)`);
-    else bump(2, 0, 'evals/ has case files');
+    if (files.length >= 4) {
+      bump(2, 2, `evals/ directory has ${files.length} case files`);
+    } else if (files.length > 0) {
+      score.max += 2;
+      score.total += 1;
+      issues.push({ severity: 'warn', msg: `evals/ has only ${files.length} files (require ≥4: core/boundary/failure/excluded)` });
+    } else {
+      score.max += 2;
+      issues.push({ severity: 'error', msg: 'evals/ directory exists but contains no case files' });
+    }
   } else {
-    bump(2, 0, 'evals/ directory present');
+    score.max += 2;
+    issues.push({ severity: 'error', msg: 'evals/ directory missing: require ≥4 evaluation cases' });
   }
 
-  // 6. judgment_version manifest field
+  // 6. judgment_version manifest field (REQUIRED)
   if (manifest?.judgment_version) {
     bump(1, 1, `judgment_version: ${manifest.judgment_version}`);
   } else {
-    bump(1, 0, 'kdna.json has judgment_version');
+    score.max += 1;
+    issues.push({ severity: 'error', msg: 'kdna.json missing required field: judgment_version' });
   }
 
   return { layer: 'judgment', issues, passed, score };