@jaimevalasek/aioson 1.21.0 → 1.21.4

package/src/commands/artifact-validate.js

@@ -70,8 +70,9 @@ async function runArtifactValidate({ args, options = {}, logger }) {
     reqCount = `${new Set(reqs).size} REQs, ${new Set(acs).size} ACs`;
   }
 
-  // Conformance required?
-  const conformanceRequired = classification === 'MEDIUM';
+  // Conformance required?
+  const conformanceRequired = classification === 'MEDIUM';
+  const designDocRequired = classification === 'SMALL' || classification === 'MEDIUM';
 
   // Build chain items
   const chain = [
@@ -110,15 +111,29 @@ async function runArtifactValidate({ args, options = {}, logger }) {
       required: true,
       indent: 1
     },
-    {
-      name: 'architecture.md',
-      exists: artifacts.architecture.exists,
-      detail: null,
-      required: true,
-      indent: 1
-    },
-    {
-      name: `implementation-plan-${slug}.md`,
+    {
+      name: 'architecture.md',
+      exists: artifacts.architecture.exists,
+      detail: null,
+      required: true,
+      indent: 1
+    },
+    {
+      name: 'design-doc.md',
+      exists: artifacts.design_doc.exists,
+      detail: designDocRequired ? 'pre-dev design governance contract' : `SMALL/MEDIUM only — NOT required for ${classification || 'MICRO'}`,
+      required: designDocRequired,
+      indent: 1
+    },
+    {
+      name: 'readiness.md',
+      exists: artifacts.readiness.exists,
+      detail: designDocRequired ? 'pre-dev readiness contract' : `SMALL/MEDIUM only — NOT required for ${classification || 'MICRO'}`,
+      required: designDocRequired,
+      indent: 1
+    },
+    {
+      name: `implementation-plan-${slug}.md`,
       exists: artifacts.implementation_plan.exists,
       detail: planStatus ? `status: ${planStatus}` : null,
       required: true,
@@ -143,9 +158,11 @@ async function runArtifactValidate({ args, options = {}, logger }) {
   const ARTIFACT_OWNER_MAP = {
     'project.context.md': { agent: '@setup', reason: 'setup not complete' },
     [`prd-${slug}.md`]: { agent: '@product', reason: 'PRD not produced yet' },
-    [`requirements-${slug}.md`]: { agent: '@analyst', reason: 'requirements not produced yet (Gate A)' },
-    'architecture.md': { agent: '@architect', reason: 'architecture not produced yet (Gate B)' },
-    [`implementation-plan-${slug}.md`]: { agent: '@pm', reason: 'implementation plan not produced yet (Gate C)' },
+    [`requirements-${slug}.md`]: { agent: '@analyst', reason: 'requirements not produced yet (Gate A)' },
+    'architecture.md': { agent: '@architect', reason: 'architecture not produced yet (Gate B)' },
+    'design-doc.md': { agent: '@discovery-design-doc', reason: 'design governance contract not produced yet' },
+    'readiness.md': { agent: '@discovery-design-doc', reason: 'readiness contract not produced yet' },
+    [`implementation-plan-${slug}.md`]: { agent: '@pm', reason: 'implementation plan not produced yet (Gate C)' },
     [`spec-${slug}.md`]: { agent: '@analyst', reason: 'spec not produced yet — @analyst seeds the feature memory' },
     [`conformance-${slug}.yaml`]: { agent: '@analyst', reason: 'conformance contract missing — @analyst creates it for MEDIUM features' }
   };

package/src/commands/context-health.js

@@ -21,21 +21,145 @@ function formatTokens(n) {
   return `~${n.toLocaleString()}`;
 }
 
-async function loadFeatureStatuses(contextDir) {
-  const featuresPath = path.join(contextDir, 'features.md');
-  try {
-    const content = await fs.readFile(featuresPath, 'utf8');
-    const done = new Set();
-    for (const line of content.split(/\r?\n/)) {
-      // Match lines like: - auth: done or | auth | done |
-      const m = line.match(/[-|]\s*([a-z0-9_-]+)\s*[:|]\s*done/i);
-      if (m) done.add(m[1].toLowerCase());
-    }
-    return done;
-  } catch {
-    return new Set();
-  }
-}
+async function loadFeatureStatuses(contextDir) {
+  const registry = await loadFeatureRegistry(contextDir);
+  return new Set(registry.done.map((feature) => feature.slug.toLowerCase()));
+}
+
+async function loadFeatureRegistry(contextDir) {
+  const featuresPath = path.join(contextDir, 'features.md');
+  try {
+    const content = await fs.readFile(featuresPath, 'utf8');
+    const features = [];
+    for (const line of content.split(/\r?\n/)) {
+      const table = line.match(/^\|\s*([a-z0-9_-]+)\s*\|\s*([a-z_ -]+)\s*\|/i);
+      if (table && table[1] !== 'slug') {
+        features.push({ slug: table[1].trim(), status: table[2].trim().toLowerCase() });
+        continue;
+      }
+
+      const list = line.match(/^-\s*([a-z0-9_-]+)\s*:\s*([a-z_ -]+)/i);
+      if (list) {
+        features.push({ slug: list[1].trim(), status: list[2].trim().toLowerCase() });
+      }
+    }
+    return {
+      all: features,
+      active: features.filter((feature) => feature.status === 'in_progress'),
+      done: features.filter((feature) => feature.status === 'done')
+    };
+  } catch {
+    return { all: [], active: [], done: [] };
+  }
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+
+  const result = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    value = value.replace(/^["']|["']$/g, '');
+    result[key] = value;
+  }
+  return result;
+}
+
+async function readProjectClassification(contextDir) {
+  try {
+    const content = await fs.readFile(path.join(contextDir, 'project.context.md'), 'utf8');
+    return parseFrontmatter(content).classification || null;
+  } catch {
+    return null;
+  }
+}
+
+async function readWorkflowState(contextDir) {
+  try {
+    const raw = await fs.readFile(path.join(contextDir, 'workflow.state.json'), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function readPulseActiveFeature(contextDir) {
+  try {
+    const content = await fs.readFile(path.join(contextDir, 'project-pulse.md'), 'utf8');
+    const frontmatter = parseFrontmatter(content);
+    return normalizePulseFeature(frontmatter.active_feature || null);
+  } catch {
+    return null;
+  }
+}
+
+function normalizePulseFeature(value) {
+  if (!value) return null;
+  const normalized = String(value).trim().replace(/^["']|["']$/g, '');
+  if (!normalized || ['none', 'project', '(none)', '-', '—'].includes(normalized.toLowerCase())) return null;
+  return normalized;
+}
+
+async function buildDriftWarnings(contextDir) {
+  const warnings = [];
+  const projectClassification = await readProjectClassification(contextDir);
+  const workflowState = await readWorkflowState(contextDir);
+  const featureRegistry = await loadFeatureRegistry(contextDir);
+  const pulseActiveFeature = await readPulseActiveFeature(contextDir);
+
+  if (
+    projectClassification &&
+    workflowState?.mode === 'feature' &&
+    workflowState.classification &&
+    projectClassification.toUpperCase() !== String(workflowState.classification).toUpperCase()
+  ) {
+    warnings.push({
+      id: 'classification_drift',
+      severity: 'warning',
+      message: `Project classification is ${projectClassification}; active workflow feature classification is ${workflowState.classification}.`,
+      suggested_command: 'aioson context:health . --json'
+    });
+  }
+
+  if (featureRegistry.active.length > 1) {
+    warnings.push({
+      id: 'multiple_active_features',
+      severity: 'warning',
+      message: `features.md has multiple in_progress features: ${featureRegistry.active.map((feature) => feature.slug).join(', ')}.`,
+      suggested_command: 'aioson feature:sweep . --dry-run'
+    });
+  }
+
+  const activeFeature = featureRegistry.active[0]?.slug || null;
+  if (activeFeature && pulseActiveFeature && activeFeature !== pulseActiveFeature) {
+    warnings.push({
+      id: 'active_state_drift',
+      severity: 'warning',
+      message: `features.md active feature is ${activeFeature}; project-pulse.md active_feature is ${pulseActiveFeature}.`,
+      suggested_command: 'aioson pulse:update . --feature=' + activeFeature
+    });
+  } else if (activeFeature && pulseActiveFeature === null) {
+    warnings.push({
+      id: 'active_state_drift',
+      severity: 'warning',
+      message: `features.md active feature is ${activeFeature}; project-pulse.md has no active_feature.`,
+      suggested_command: 'aioson pulse:update . --feature=' + activeFeature
+    });
+  } else if (!activeFeature && pulseActiveFeature) {
+    warnings.push({
+      id: 'active_state_drift',
+      severity: 'warning',
+      message: `project-pulse.md active_feature is ${pulseActiveFeature}, but features.md has no in_progress feature with that slug.`,
+      suggested_command: 'aioson pulse:update .'
+    });
+  }
+
+  return warnings;
+}
 
 async function getCacheHitRate(db) {
   if (!db) return null;
@@ -84,9 +208,37 @@ async function runContextHealth({ args, options = {}, logger }) {
     } catch { /* skip unreadable files */ }
   }
 
+  // bootstrap/*.md is the per-activation memory layer: dev/qa/architect/deyvin
+  // read it on every session start, so it dominates the real activation cost.
+  // It lives in a subdir, so the top-level scan above missed it entirely —
+  // include it here so the heaviest layer is visible, not hidden (P0 of the
+  // agent-loading-contract). Backward-compatible: no bootstrap/ dir → no change.
+  const bootstrapDir = path.join(contextDir, 'bootstrap');
+  let bootstrapFiles = [];
+  try {
+    // Exclude *-archive.md: cold storage is never loaded at activation, so
+    // counting it would inflate the report and mislabel intended bulk as CRITICAL.
+    bootstrapFiles = (await fs.readdir(bootstrapDir))
+      .filter((f) => f.endsWith('.md') && !f.endsWith('-archive.md'));
+  } catch { /* no bootstrap dir — pre-Living-Memory projects */ }
+  for (const file of bootstrapFiles) {
+    try {
+      const content = await fs.readFile(path.join(bootstrapDir, file), 'utf8');
+      const tokens = estimateTokens(content);
+      totalTokens += tokens;
+      report.push({
+        file: `bootstrap/${file}`,
+        sizeBytes: content.length,
+        tokens,
+        heavy: tokens > HEAVY_TOKEN_THRESHOLD,
+        critical: tokens > CRITICAL_TOKEN_THRESHOLD
+      });
+    } catch { /* skip unreadable files */ }
+  }
+
   report.sort((a, b) => b.tokens - a.tokens);
 
-  const doneFeatures = await loadFeatureStatuses(contextDir);
+  const doneFeatures = await loadFeatureStatuses(contextDir);
   const staleSpecs = report.filter((r) => {
     if (!r.file.startsWith('spec-')) return false;
     const slug = r.file.replace(/^spec-/, '').replace(/\.md$/, '');
@@ -109,17 +261,19 @@ async function runContextHealth({ args, options = {}, logger }) {
     db.close();
   }
 
-  const skeletonPresent = entries.includes('skeleton-system.md') || entries.includes('skeleton.md');
-
-  if (options.json) {
-    return {
-      ok: true,
-      totalTokens,
-      files: report,
-      staleSpecs: staleSpecs.map((s) => s.file),
-      cacheHitRate,
-      skeletonPresent,
-      dbPath
+  const skeletonPresent = entries.includes('skeleton-system.md') || entries.includes('skeleton.md');
+  const driftWarnings = await buildDriftWarnings(contextDir);
+
+  if (options.json) {
+    return {
+      ok: true,
+      totalTokens,
+      files: report,
+      staleSpecs: staleSpecs.map((s) => s.file),
+      driftWarnings,
+      cacheHitRate,
+      skeletonPresent,
+      dbPath
     };
   }
 
@@ -150,13 +304,18 @@ async function runContextHealth({ args, options = {}, logger }) {
     for (const r of heavyFiles) {
       const label = r.critical ? 'CRITICAL' : 'heavy';
       logger.log(`⚠  ${r.file} is ${label} (${formatBytes(r.sizeBytes)}). Consider:`);
-      logger.log(`   → Run: aioson context:pack . --scope=<feature>`);
-      logger.log(`     Creates a scoped context for a specific feature`);
+      if (r.file === 'bootstrap/current-state.md') {
+        logger.log(`   → Run: aioson memory:trim . --dry-run`);
+        logger.log(`     Archives old log entries out of the hot bootstrap (every agent reads this at activation)`);
+      } else {
+        logger.log(`   → Run: aioson context:pack . --scope=<feature>`);
+        logger.log(`     Creates a scoped context for a specific feature`);
+      }
     }
     logger.log('');
   }
 
-  if (staleSpecs.length > 0) {
+  if (staleSpecs.length > 0) {
     logger.log(`⚠  ${staleSpecs.length} stale spec file(s) (features: done):`);
     for (const s of staleSpecs) {
       const slug = s.file.replace(/^spec-/, '').replace(/\.md$/, '');
@@ -164,7 +323,16 @@ async function runContextHealth({ args, options = {}, logger }) {
     }
     logger.log(`   Run: aioson feature:archive . --feature=<slug> to archive them`);
     logger.log('');
-  }
+  }
+
+  if (driftWarnings.length > 0) {
+    logger.log(`⚠  ${driftWarnings.length} context drift warning(s):`);
+    for (const warning of driftWarnings) {
+      logger.log(`   → ${warning.message}`);
+      if (warning.suggested_command) logger.log(`     ${warning.suggested_command}`);
+    }
+    logger.log('');
+  }
 
   if (cacheHitRate !== null) {
     logger.log(`✓  Cache hit rate: ${cacheHitRate}% (last 7 days)`);
@@ -175,11 +343,12 @@ async function runContextHealth({ args, options = {}, logger }) {
 
   return {
     ok: true,
-    totalTokens,
-    files: report,
-    staleSpecs: staleSpecs.map((s) => s.file),
-    cacheHitRate,
-    skeletonPresent,
+    totalTokens,
+    files: report,
+    staleSpecs: staleSpecs.map((s) => s.file),
+    driftWarnings,
+    cacheHitRate,
+    skeletonPresent,
     dbPath
   };
 }

package/src/commands/devlog-process.js

@@ -50,11 +50,20 @@ function extractTaggedLearnings(content) {
   for (const line of section.split(/\r?\n/)) {
     const trimmed = line.replace(/^[-*]\s*/, '').trim();
     if (!trimmed) continue;
-    const typeMatch = trimmed.match(/^\[(process|domain|quality|preference)\]\s+(.+)/i);
+    const typeMatch = trimmed.match(/^\[(process|domain|quality|preference|gotcha|resolution)\]\s+(.+)/i);
     if (typeMatch) {
-      learnings.push({ type: typeMatch[1].toLowerCase(), title: typeMatch[2].trim() });
+      const tag = typeMatch[1].toLowerCase();
+      const title = typeMatch[2].trim();
+      // cross-tool-project-knowledge: gotcha/resolution are project-knowledge
+      // signals — persisted under type='quality' with the real signal in `kind`
+      // (project_learnings.type CHECK only allows the 4 base types).
+      if (tag === 'gotcha' || tag === 'resolution') {
+        learnings.push({ type: 'quality', kind: tag, title });
+      } else {
+        learnings.push({ type: tag, kind: null, title });
+      }
     } else if (trimmed.length > 5) {
-      learnings.push({ type: 'process', title: trimmed });
+      learnings.push({ type: 'process', kind: null, title: trimmed });
     }
   }
   return learnings;
@@ -69,25 +78,38 @@ function extractSummary(content) {
   return firstHeading ? firstHeading[1].trim() : null;
 }
 
-function upsertProjectLearning(db, { title, type, featureSlug, evidence, sourceSession }) {
+// cross-tool-project-knowledge: app-level allow-list for project_learnings.kind.
+// The column carries no schema CHECK by repo convention (see
+// learning-loop-migration.js Phase 4). NULL = not a project-knowledge learning.
+const ALLOWED_LEARNING_KINDS = new Set(['gotcha', 'resolution']);
+
+function normalizeKind(kind) {
+  return ALLOWED_LEARNING_KINDS.has(kind) ? kind : null;
+}
+
+function upsertProjectLearning(db, { title, type, kind, featureSlug, evidence, sourceSession }) {
+  const safeKind = normalizeKind(kind);
   const existing = db.prepare(
-    'SELECT learning_id, frequency FROM project_learnings WHERE title = ? AND (feature_slug = ? OR (feature_slug IS NULL AND ? IS NULL))'
+    'SELECT learning_id, frequency, kind FROM project_learnings WHERE title = ? AND (feature_slug = ? OR (feature_slug IS NULL AND ? IS NULL))'
   ).get(title, featureSlug || null, featureSlug || null);
 
   if (existing) {
+    // Enrich kind only when previously unset — a plain re-tag must not clobber
+    // an existing classification.
+    const nextKind = existing.kind || safeKind || null;
     db.prepare(
-      'UPDATE project_learnings SET frequency = ?, last_reinforced = ?, updated_at = ? WHERE learning_id = ?'
-    ).run(existing.frequency + 1, nowIso(), nowIso(), existing.learning_id);
+      'UPDATE project_learnings SET frequency = ?, last_reinforced = ?, updated_at = ?, kind = ? WHERE learning_id = ?'
+    ).run(existing.frequency + 1, nowIso(), nowIso(), nextKind, existing.learning_id);
     return { action: 'updated', learningId: existing.learning_id };
   }
 
   const learningId = createLearningId();
   db.prepare(`
     INSERT INTO project_learnings
-      (learning_id, feature_slug, type, title, confidence, frequency, last_reinforced,
+      (learning_id, feature_slug, type, kind, title, confidence, frequency, last_reinforced,
        applies_to, source_session, evidence, status, created_at, updated_at)
-    VALUES (?, ?, ?, ?, 'medium', 1, ?, 'project', ?, ?, 'active', ?, ?)
-  `).run(learningId, featureSlug || null, type, title, nowIso(), sourceSession || null, evidence || null, nowIso(), nowIso());
+    VALUES (?, ?, ?, ?, ?, 'medium', 1, ?, 'project', ?, ?, 'active', ?, ?)
+  `).run(learningId, featureSlug || null, type, safeKind, title, nowIso(), sourceSession || null, evidence || null, nowIso(), nowIso());
   return { action: 'inserted', learningId };
 }
 
@@ -168,8 +190,8 @@ async function processDevlogFile(db, filePath) {
 
   // Upsert learnings
   const learnings = extractTaggedLearnings(body);
-  for (const { type, title } of learnings) {
-    upsertProjectLearning(db, { title, type, featureSlug, sourceSession: sessionKey || path.basename(filePath) });
+  for (const { type, title, kind } of learnings) {
+    upsertProjectLearning(db, { title, type, kind, featureSlug, sourceSession: sessionKey || path.basename(filePath) });
   }
 
   // Log verdict if present
@@ -291,4 +313,4 @@ async function runDevlogProcess({ args, options = {}, logger }) {
   return { ok: true, results, processed: processed.length, skipped: skipped.length, malformed: malformed.length, totalArtifacts, totalLearnings, dbPath };
 }
 
-module.exports = { runDevlogProcess, processDevlogFile };
+module.exports = { runDevlogProcess, processDevlogFile, extractTaggedLearnings, upsertProjectLearning };

package/src/commands/feature-close.js

@@ -25,6 +25,12 @@ const { loadConfig } = require('../sub-task-engine');
 const { runDistillation, readFeatureClassification } = require('../learning-loop-engine');
 const { openRuntimeDb } = require('../runtime-store');
 const { runNotify } = require('./notify');
+const { splitCurrentState, buildArchiveContent, parseActiveSlugs } = require('../current-state-trim');
+
+// P0 agent-loading-contract: a feature closing is the natural cadence to roll
+// aged-out current-state.md entries into the cold archive. Conservative window
+// (gentle, automatic) — manual `memory:trim --keep=<N>` can trim harder.
+const AUTO_CLOSE_KEEP = 25;
 
 function nowDate() {
   return new Date().toISOString().slice(0, 10);
@@ -531,6 +537,36 @@ async function runFeatureClose({ args, options = {}, logger }) {
     updates.push('distill: skipped (--no-distill flag)');
   }
 
+  // Auto-rollup bootstrap/current-state.md (P0 agent-loading-contract). The
+  // just-closed slug is already `done` in features.md, so it no longer counts as
+  // an active-slug exemption — its aged entries become eligible. Best-effort and
+  // non-blocking: a failure here must never break the closure. Opt out: --no-trim.
+  // SECURITY (TS-LC-02): the trim hook calls the engine directly, bypassing the
+  // AIOSON_RUNTIME_HOOK guard that memory:trim enforces. Honor that guard here
+  // too, so a tier-2 memory mutation never fires inside a hook/automation context.
+  const skipTrim = options['no-trim'] === true || options.trim === false
+    || process.env.AIOSON_RUNTIME_HOOK === '1';
+  if (verdict === 'PASS' && !skipTrim) {
+    try {
+      const csPath = path.join(targetDir, '.aioson/context/bootstrap/current-state.md');
+      const csContent = await readFileSafe(csPath);
+      if (csContent) {
+        const activeSlugs = parseActiveSlugs((await readFileSafe(path.join(targetDir, '.aioson/context/features.md'))) || '');
+        const split = splitCurrentState(csContent, { keep: AUTO_CLOSE_KEEP, activeSlugs });
+        if (split.ok && split.archivedEntries.length > 0) {
+          const archPath = path.join(targetDir, '.aioson/context/bootstrap/current-state-archive.md');
+          const eol = /\r\n/.test(csContent) ? '\r\n' : '\n';
+          const existingArchive = (await readFileSafe(archPath)) || '';
+          await fs.writeFile(archPath, buildArchiveContent(existingArchive, split.archivedEntries, nowDate(), eol), 'utf8');
+          await fs.writeFile(csPath, split.hotContent, 'utf8');
+          updates.push(`trim: archived ${split.archivedEntries.length} aged current-state entries (kept ${split.stats.kept})`);
+        }
+      }
+    } catch (err) {
+      updates.push(`trim: hook error (${(err && err.message) || err})`);
+    }
+  }
+
   const result = {
     ok: true,
     feature: slug,

package/src/commands/learning.js

@@ -1,13 +1,19 @@
 'use strict';
 
-const path = require('node:path');
-const {
-  openRuntimeDb,
-  listProjectLearnings,
+const path = require('node:path');
+const {
+  openRuntimeDb,
+  listProjectLearnings,
   getProjectLearning,
-  promoteProjectLearning,
-  getProjectLearningStats
-} = require('../runtime-store');
+  promoteProjectLearning,
+  getProjectLearningStats
+} = require('../runtime-store');
+const {
+  loadClaudeMemoryCandidates,
+  parseSelection,
+  isSelected
+} = require('../learning-import-claude');
+const { upsertProjectLearning } = require('./devlog-process');
 
 /**
  * Subcommand: list [--status=active|stale|archived|promoted]
@@ -78,7 +84,7 @@ async function handleStats(projectDir, { logger, t }) {
  * Subcommand: promote <learning-id> --to=<rule-path>
  * Promotes a learning to a project rule.
  */
-async function handlePromote(projectDir, learningId, promotedTo, { logger, t }) {
+async function handlePromote(projectDir, learningId, promotedTo, { logger, t }) {
   if (!learningId) {
     logger.error(t('learning.promote_usage'));
     return { promoted: false };
@@ -106,7 +112,77 @@ async function handlePromote(projectDir, learningId, promotedTo, { logger, t })
   } finally {
     db.close();
   }
-}
+}
+
+/**
+ * Subcommand: import-from-claude [--project-hash=<hash>] [--dry-run] [--select=1,2|all]
+ * Imports technical Claude Code project memory into project_learnings.
+ */
+async function handleImportFromClaude(projectDir, options, { logger }) {
+  let loaded;
+  try {
+    loaded = await loadClaudeMemoryCandidates({
+      targetDir: projectDir,
+      projectHash: options['project-hash'] || options.projectHash,
+      claudeHome: options['claude-home'] || options.claudeHome
+    });
+  } catch (err) {
+    logger.error(err.message);
+    return { ok: false, error: err.code || 'import_failed', candidates: [], promoted: 0 };
+  }
+
+  const selection = parseSelection(options.select);
+  const dryRun = Boolean(options['dry-run'] || options.dryRun);
+  const candidates = loaded.candidates;
+
+  logger.log(`Claude memory candidates (${candidates.length}) — ${loaded.hash}`);
+  for (const candidate of candidates) {
+    const marker = candidate.kind ? candidate.kind : candidate.classification;
+    logger.log(`  [${candidate.index}] ${marker}: ${candidate.title} (${candidate.source})`);
+  }
+
+  if (dryRun || !selection) {
+    if (!selection) logger.log('Run again with --select=<n[,n]|all> to import technical candidates.');
+    return {
+      ok: true,
+      dryRun: true,
+      requiresSelection: !selection,
+      projectHash: loaded.hash,
+      candidates,
+      promoted: 0,
+      skipped: 0
+    };
+  }
+
+  const handle = await openRuntimeDb(projectDir);
+  const { db } = handle;
+  const promoted = [];
+  const skipped = [];
+  try {
+    for (const candidate of candidates) {
+      if (!isSelected(selection, candidate.index)) continue;
+      if (!candidate.kind) {
+        skipped.push({ index: candidate.index, title: candidate.title, reason: candidate.classification });
+        continue;
+      }
+      const result = upsertProjectLearning(db, {
+        title: candidate.title,
+        type: 'quality',
+        kind: candidate.kind,
+        featureSlug: options.feature || null,
+        evidence: candidate.evidence,
+        sourceSession: `claude-memory:${loaded.hash}:${candidate.source}`
+      });
+      promoted.push({ ...result, index: candidate.index, title: candidate.title, kind: candidate.kind });
+    }
+  } finally {
+    db.close();
+  }
+
+  logger.log(`Imported: ${promoted.length}`);
+  if (skipped.length > 0) logger.log(`Skipped: ${skipped.length}`);
+  return { ok: true, dryRun: false, projectHash: loaded.hash, candidates, promoted, skipped };
+}
 
 /**
  * Entry point for CLI integration.
@@ -122,13 +198,16 @@ async function runLearning({ args = [], options = {}, logger = console, t = (k)
   if (sub === 'stats') {
     return handleStats(projectDir, context);
   }
-  if (sub === 'promote') {
-    const learningId = args[2] || options.id;
-    return handlePromote(projectDir, learningId, options.to || null, context);
-  }
-
-  logger.error(`Unknown subcommand: ${sub}. Available: list, stats, promote`);
-  return { error: true };
-}
-
-module.exports = { runLearning, handleList, handleStats, handlePromote };
+  if (sub === 'promote') {
+    const learningId = args[2] || options.id;
+    return handlePromote(projectDir, learningId, options.to || null, context);
+  }
+  if (sub === 'import-from-claude') {
+    return handleImportFromClaude(projectDir, options, context);
+  }
+
+  logger.error(`Unknown subcommand: ${sub}. Available: list, stats, promote, import-from-claude`);
+  return { error: true };
+}
+
+module.exports = { runLearning, handleList, handleStats, handlePromote, handleImportFromClaude };