@jaimevalasek/aioson 1.5.1 → 1.7.0

package/src/commands/skill.js

@@ -16,6 +16,47 @@ function resolveTargetDir(args) {
   return path.resolve(process.cwd(), args[0] || '.');
 }
 
+async function copyRecursive(src, dest) {
+  const stat = await fs.stat(src);
+  if (stat.isDirectory()) {
+    await ensureDir(dest);
+    const entries = await fs.readdir(src);
+    for (const entry of entries) {
+      await copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+    return;
+  }
+
+  await ensureDir(path.dirname(dest));
+  await fs.copyFile(src, dest);
+}
+
+async function replaceDirectory(srcDir, destDir) {
+  await fs.rm(destDir, { recursive: true, force: true });
+  await copyRecursive(srcDir, destDir);
+}
+
+async function readJsonIfExists(filePath) {
+  if (!(await exists(filePath))) return null;
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function writeSkillMeta(destDir, patch) {
+  const metaPath = path.join(destDir, '.skill-meta.json');
+  const existing = await readJsonIfExists(metaPath) || {};
+  const merged = {
+    ...existing,
+    ...patch
+  };
+
+  await fs.writeFile(metaPath, JSON.stringify(merged, null, 2), 'utf8');
+  return merged;
+}
+
 /**
  * Parse YAML frontmatter from a SKILL.md file.
  */
@@ -44,17 +85,7 @@ async function distributeToTool(targetDir, slug, skillDir) {
   for (const toolPath of TOOL_TARGETS) {
     const toolSkillDir = path.join(targetDir, toolPath, slug);
     try {
-      await ensureDir(toolSkillDir);
-      // Copy all files from the installed skill dir
-      const entries = await fs.readdir(skillDir);
-      for (const entry of entries) {
-        const src = path.join(skillDir, entry);
-        const dest = path.join(toolSkillDir, entry);
-        const stat = await fs.stat(src);
-        if (stat.isFile()) {
-          await fs.copyFile(src, dest);
-        }
-      }
+      await replaceDirectory(skillDir, toolSkillDir);
       results.push({ tool: toolPath, ok: true });
     } catch (err) {
       results.push({ tool: toolPath, ok: false, error: err.message });
@@ -187,12 +218,13 @@ async function installFromNpm(targetDir, slug, options, logger) {
 
       // Copy to .aioson/installed-skills/{slug}/
       const destDir = path.join(targetDir, INSTALLED_SKILLS_DIR, slug);
-      await ensureDir(destDir);
-
-      const entries = await fs.readdir(sourceDir);
-      for (const entry of entries) {
-        await fs.copyFile(path.join(sourceDir, entry), path.join(destDir, entry));
-      }
+      await replaceDirectory(sourceDir, destDir);
+      await writeSkillMeta(destDir, {
+        source: 'npm',
+        sourcePackage: '@tech-leads-club/agent-skills',
+        sourcePath: path.relative(targetDir, sourceDir),
+        installedAt: new Date().toISOString()
+      });
 
       resolve({ ok: true, sourceDir, destDir });
     });
@@ -248,15 +280,16 @@ async function installFromCloud(targetDir, slug, options, logger) {
   ].join('\n');
 
   const destDir = path.join(targetDir, INSTALLED_SKILLS_DIR, slug);
+  await fs.rm(destDir, { recursive: true, force: true });
   await ensureDir(destDir);
   await fs.writeFile(path.join(destDir, 'SKILL.md'), fm, 'utf8');
 
   // Write meta
-  await fs.writeFile(path.join(destDir, '.skill-meta.json'), JSON.stringify({
+  await writeSkillMeta(destDir, {
     source: 'cloud',
     cloudSlug: snapshot.skill.slug,
     installedAt: new Date().toISOString()
-  }, null, 2), 'utf8');
+  });
 
   return { ok: true, destDir };
 }
@@ -271,30 +304,32 @@ async function installFromLocal(targetDir, slug, filePath, logger) {
   }
 
   const destDir = path.join(targetDir, INSTALLED_SKILLS_DIR, slug);
-  await ensureDir(destDir);
-
   const stat = await fs.stat(absPath);
+  const samePath = path.resolve(absPath) === path.resolve(destDir);
+
+  if (!samePath) {
+    await fs.rm(destDir, { recursive: true, force: true });
+    await ensureDir(destDir);
+  } else if (!stat.isDirectory()) {
+    return { ok: false, error: 'Local self-install only supports skill directories' };
+  }
+
   if (stat.isDirectory()) {
-    // Copy entire directory
-    const entries = await fs.readdir(absPath);
-    for (const entry of entries) {
-      const src = path.join(absPath, entry);
-      const srcStat = await fs.stat(src);
-      if (srcStat.isFile()) {
-        await fs.copyFile(src, path.join(destDir, entry));
-      }
+    if (!samePath) {
+      await replaceDirectory(absPath, destDir);
     }
   } else {
     // Single file — copy as SKILL.md
+    await ensureDir(destDir);
     await fs.copyFile(absPath, path.join(destDir, 'SKILL.md'));
   }
 
   // Write meta
-  await fs.writeFile(path.join(destDir, '.skill-meta.json'), JSON.stringify({
+  await writeSkillMeta(destDir, {
     source: 'local',
     sourcePath: filePath,
     installedAt: new Date().toISOString()
-  }, null, 2), 'utf8');
+  });
 
   return { ok: true, destDir };
 }
@@ -362,6 +397,58 @@ async function runSkillInstall({ args, options = {}, logger, t }) {
   };
 }
 
+/**
+ * Parse a minimal extension.yml manifest if present in a skill directory.
+ * Reads only top-level scalar fields and one level of nesting.
+ * Returns null if the file is absent or unreadable.
+ */
+async function parseExtensionManifest(skillDir) {
+  const manifestPath = path.join(skillDir, 'extension.yml');
+  let raw;
+  try {
+    raw = await fs.readFile(manifestPath, 'utf8');
+  } catch {
+    return null; // file not present — this is the normal case for old skills
+  }
+
+  const manifest = {};
+  let currentSection = null;
+
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Detect top-level section (no leading spaces, ends with colon, no value)
+    if (/^\w[\w-]*:$/.test(trimmed)) {
+      currentSection = trimmed.slice(0, -1);
+      manifest[currentSection] = {};
+      continue;
+    }
+
+    // Nested key: value (indented with spaces or tab)
+    if (currentSection && /^\s+/.test(line)) {
+      const idx = trimmed.indexOf(':');
+      if (idx === -1) continue;
+      const key = trimmed.slice(0, idx).trim();
+      const val = trimmed.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+      if (key) manifest[currentSection][key] = val;
+      continue;
+    }
+
+    // Top-level scalar key: value
+    const idx = trimmed.indexOf(':');
+    if (idx === -1) continue;
+    const key = trimmed.slice(0, idx).trim();
+    const val = trimmed.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+    if (key) {
+      currentSection = null;
+      manifest[key] = val;
+    }
+  }
+
+  return manifest;
+}
+
 /**
  * Scan a directory for .md files with SKILL.md or frontmatter descriptions.
  * Returns array of { slug, name, description, type, path }.
@@ -429,17 +516,31 @@ async function runSkillList({ args, options = {}, logger, t }) {
       const fm = parseSkillFrontmatter(raw);
 
       let source = 'unknown';
+      let meta = null;
       try {
         const metaRaw = await fs.readFile(path.join(skillsDir, slug, '.skill-meta.json'), 'utf8');
-        const meta = JSON.parse(metaRaw);
+        meta = JSON.parse(metaRaw);
         source = meta.source || 'unknown';
       } catch { /* no meta */ }
 
+      const author = meta?.author?.name || meta?.author_name || null;
+      const model =
+        meta?.generator?.model ||
+        meta?.generation?.model ||
+        meta?.generated_by_model ||
+        null;
+
+      // Read optional extension.yml manifest — additive, does not affect existing behavior
+      const extManifest = showAll ? await parseExtensionManifest(path.join(skillsDir, slug)) : null;
+
       installed.push({
         slug,
         name: fm.name || slug,
         description: fm.description || '',
         source,
+        author,
+        model,
+        manifest: extManifest,
         path: path.relative(targetDir, path.join(skillsDir, slug))
       });
     }
@@ -472,6 +573,17 @@ async function runSkillList({ args, options = {}, logger, t }) {
       if (s.description) {
         logger.log(`    ${s.description.slice(0, 100)}`);
       }
+      if (s.author) logger.log(`    author: ${s.author}`);
+      if (s.model) logger.log(`    model: ${s.model}`);
+      if (showAll && s.manifest) {
+        const ext = s.manifest.extension || {};
+        if (ext.version) logger.log(`    version: ${ext.version}`);
+        const hooks = s.manifest.hooks;
+        if (hooks && typeof hooks === 'object') {
+          const hookNames = Object.keys(hooks).filter(h => hooks[h]?.enabled !== 'false' && hooks[h]?.enabled !== false);
+          if (hookNames.length > 0) logger.log(`    hooks declared: ${hookNames.join(', ')}`);
+        }
+      }
       logger.log(`    ${s.path}/SKILL.md`);
       logger.log('');
     }

package/src/commands/spec-checkpoint.js

@@ -0,0 +1,177 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { openRuntimeDb, appendRunEvent } = require('../runtime-store');
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+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 colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
+    if (key) result[key] = value;
+  }
+  return result;
+}
+
+function extractLastCheckpoint(content) {
+  // Try frontmatter first
+  const fmMatch = content.match(/^---[\s\S]*?last_checkpoint:\s*(.+)/m);
+  if (fmMatch) return fmMatch[1].trim().replace(/^["']|["']$/g, '');
+  // Try section header
+  const sectionMatch = content.match(/##\s+last_checkpoint[^\n]*\n([\s\S]*?)(?=\n##|\s*$)/i);
+  if (sectionMatch) return sectionMatch[1].replace(/^[-*]\s*/, '').trim();
+  return null;
+}
+
+function extractPhaseGates(content) {
+  const fm = parseFrontmatter(content);
+  if (!fm.phase_gates) return null;
+  try {
+    return JSON.parse(fm.phase_gates.replace(/'/g, '"'));
+  } catch {
+    return null;
+  }
+}
+
+async function runSpecCheckpoint({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const featureSlug = options.feature ? String(options.feature).trim() : null;
+  const agentName = options.agent ? String(options.agent).trim() : 'dev';
+  const contextDir = path.join(targetDir, '.aioson', 'context');
+
+  if (!featureSlug) {
+    if (!options.json) logger.log('Error: --feature=<slug> is required.');
+    return { ok: false, reason: 'missing_feature' };
+  }
+
+  // Find spec file
+  const candidates = [
+    path.join(contextDir, `spec-${featureSlug}.md`),
+    path.join(contextDir, 'spec.md')
+  ];
+
+  let specPath = null;
+  let specContent = null;
+  for (const candidate of candidates) {
+    try {
+      specContent = await fs.readFile(candidate, 'utf8');
+      specPath = candidate;
+      break;
+    } catch { /* try next */ }
+  }
+
+  if (!specContent) {
+    if (!options.json) logger.log(`No spec file found for feature: ${featureSlug}`);
+    return { ok: false, reason: 'no_spec_file', featureSlug };
+  }
+
+  const lastCheckpoint = extractLastCheckpoint(specContent);
+  const phaseGates = extractPhaseGates(specContent);
+
+  if (!lastCheckpoint) {
+    if (!options.json) logger.log(`No last_checkpoint found in ${path.basename(specPath)}.`);
+    return { ok: false, reason: 'no_checkpoint', specPath };
+  }
+
+  const { db, dbPath } = await openRuntimeDb(targetDir, { mustExist: true });
+
+  if (!db) {
+    if (!options.json) logger.log('No runtime database found. Run aioson agent:done first.');
+    return { ok: false, reason: 'no_db' };
+  }
+
+  try {
+    // Find latest agent run for this feature
+    const run = db.prepare(`
+      SELECT r.run_key, r.status, r.summary, r.updated_at
+      FROM agent_runs r
+      WHERE r.agent_name = ?
+        AND (r.run_key LIKE ? OR r.task_key LIKE ?)
+      ORDER BY r.updated_at DESC
+      LIMIT 1
+    `).get(agentName, `%${featureSlug}%`, `%${featureSlug}%`);
+
+    // If no run with feature slug, try latest run by agent name
+    const activeRun = run || db.prepare(`
+      SELECT run_key, status, summary, updated_at
+      FROM agent_runs
+      WHERE agent_name = ? AND status IN ('running', 'completed')
+      ORDER BY updated_at DESC
+      LIMIT 1
+    `).get(agentName);
+
+    if (!activeRun) {
+      if (!options.json) {
+        logger.log(`No active run found for agent @${agentName}.`);
+        logger.log('Tip: run aioson runtime:start first, or specify --agent=<name>.');
+      }
+      return { ok: false, reason: 'no_run', featureSlug, agentName };
+    }
+
+    // Append checkpoint event
+    appendRunEvent(db, {
+      runKey: activeRun.run_key,
+      eventType: 'plan_checkpoint',
+      phase: 'spec',
+      status: 'in_progress',
+      message: lastCheckpoint,
+      payload: phaseGates ? { phase_gates: phaseGates } : null,
+      createdAt: nowIso()
+    });
+
+    // Update run summary to last_checkpoint if run is still in_progress
+    if (activeRun.status !== 'completed') {
+      db.prepare(
+        'UPDATE agent_runs SET summary = ?, updated_at = ? WHERE run_key = ?'
+      ).run(lastCheckpoint, nowIso(), activeRun.run_key);
+    }
+
+    if (options.json) {
+      return {
+        ok: true,
+        featureSlug,
+        specPath,
+        lastCheckpoint,
+        phaseGates,
+        runKey: activeRun.run_key,
+        dbPath
+      };
+    }
+
+    logger.log(`Reading ${path.basename(specPath)}...`);
+    logger.log(`last_checkpoint: "${lastCheckpoint}"`);
+    if (phaseGates) {
+      logger.log(`phase_gates: ${JSON.stringify(phaseGates)}`);
+    }
+    logger.log('');
+    logger.log('Checkpoint registered:');
+    logger.log(`  run_key: ${activeRun.run_key}`);
+    logger.log(`  summary: "${lastCheckpoint}"`);
+    logger.log(`  status: in_progress (checkpoint only — use agent:done to close)`);
+    logger.log('');
+    logger.log(`Next: continue with /${agentName} — start from last_checkpoint`);
+
+    return {
+      ok: true,
+      featureSlug,
+      specPath,
+      lastCheckpoint,
+      phaseGates,
+      runKey: activeRun.run_key,
+      dbPath
+    };
+  } finally {
+    db.close();
+  }
+}
+
+module.exports = { runSpecCheckpoint };

package/src/commands/spec-status.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { openRuntimeDb } = require('../runtime-store');
+
+async function runSpecStatus({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const { db, dbPath } = await openRuntimeDb(targetDir, { mustExist: true });
+
+  if (!db) {
+    if (!options.json) logger.log('No runtime database found. Run aioson agent:done first.');
+    return { ok: false, reason: 'no_db' };
+  }
+
+  try {
+    const plans = db.prepare(`
+      SELECT plan_id, feature_slug, status, phases_total, phases_completed, created_at, updated_at
+      FROM implementation_plans
+      WHERE status != 'archived'
+      ORDER BY updated_at DESC
+    `).all();
+
+    const rows = [];
+    for (const plan of plans) {
+      const lastRun = db.prepare(`
+        SELECT r.agent_name, r.summary, r.updated_at
+        FROM agent_runs r
+        JOIN tasks t ON r.task_key = t.task_key
+        WHERE r.status IN ('running', 'completed')
+          AND (t.session_key LIKE ? OR r.agent_name IS NOT NULL)
+        ORDER BY r.updated_at DESC
+        LIMIT 1
+      `).get(`%${plan.feature_slug || ''}%`);
+
+      rows.push({
+        feature: plan.feature_slug || '(project)',
+        phase: `${plan.phases_completed}/${plan.phases_total}`,
+        status: plan.status,
+        lastAgent: lastRun?.agent_name || '—',
+        checkpoint: lastRun?.summary ? lastRun.summary.slice(0, 60) : '—'
+      });
+    }
+
+    const totalLearnings = db.prepare(
+      "SELECT COUNT(*) as cnt FROM project_learnings WHERE status = 'active'"
+    ).get()?.cnt || 0;
+
+    const promotable = db.prepare(
+      "SELECT COUNT(*) as cnt FROM project_learnings WHERE status = 'active' AND frequency >= 3"
+    ).get()?.cnt || 0;
+
+    if (options.json) {
+      return { ok: true, features: rows, totalLearnings, promotable, dbPath };
+    }
+
+    logger.log(`Project Status — ${targetDir}`);
+    logger.log('─'.repeat(80));
+    logger.log('Feature'.padEnd(20) + 'Phase'.padEnd(10) + 'Status'.padEnd(16) + 'Last Agent'.padEnd(16) + 'Checkpoint');
+    logger.log('─'.repeat(80));
+    for (const r of rows) {
+      logger.log(
+        r.feature.padEnd(20) +
+        r.phase.padEnd(10) +
+        r.status.padEnd(16) +
+        r.lastAgent.padEnd(16) +
+        r.checkpoint
+      );
+    }
+    logger.log('─'.repeat(80));
+    logger.log(`Active learnings: ${totalLearnings}  |  Promotable (freq≥3): ${promotable}`);
+
+    return { ok: true, features: rows, totalLearnings, promotable, dbPath };
+  } finally {
+    db.close();
+  }
+}
+
+module.exports = { runSpecStatus };

package/src/commands/spec-sync.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { openRuntimeDb } = require('../runtime-store');
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function createLearningId() {
+  return `learning-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+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 colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
+    if (key) result[key] = value;
+  }
+  return result;
+}
+
+function extractSection(content, sectionName) {
+  const re = new RegExp(`^#{1,4}\\s+${sectionName}[\\s\\S]*?(?=^#{1,4}\\s|$)`, 'im');
+  const match = content.match(re);
+  if (!match) return '';
+  return match[0].replace(/^#{1,4}\s+\S.*\n/, '').trim();
+}
+
+function extractLearnings(content) {
+  const section = extractSection(content, 'Session Learnings');
+  const learnings = [];
+  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);
+    if (typeMatch) {
+      learnings.push({ type: typeMatch[1].toLowerCase(), title: typeMatch[2].trim() });
+    } else if (trimmed.length > 5) {
+      learnings.push({ type: 'process', title: trimmed });
+    }
+  }
+  return learnings;
+}
+
+function extractLastCheckpoint(content) {
+  const section = extractSection(content, 'last_checkpoint');
+  if (section) return section.replace(/^.*:\s*/, '').trim();
+  const fmMatch = content.match(/^---[\s\S]*?last_checkpoint:\s*(.+)/m);
+  return fmMatch ? fmMatch[1].trim().replace(/^["']|["']$/g, '') : null;
+}
+
+function upsertProjectLearning(db, { title, type, featureSlug, evidence, sourceSession }) {
+  const existing = db.prepare(
+    'SELECT learning_id, frequency FROM project_learnings WHERE title = ? AND feature_slug = ?'
+  ).get(title, featureSlug || null);
+
+  if (existing) {
+    db.prepare(
+      'UPDATE project_learnings SET frequency = ?, last_reinforced = ?, updated_at = ? WHERE learning_id = ?'
+    ).run(existing.frequency + 1, nowIso(), nowIso(), 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,
+       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());
+  return { action: 'inserted', learningId };
+}
+
+function syncPlanPhases(db, featureSlug, phaseGates) {
+  if (!phaseGates || typeof phaseGates !== 'object') return 0;
+  const plan = db.prepare(
+    "SELECT plan_id FROM implementation_plans WHERE feature_slug = ? AND status != 'archived' ORDER BY created_at DESC LIMIT 1"
+  ).get(featureSlug);
+  if (!plan) return 0;
+
+  let updated = 0;
+  const gateMap = { plan: 1, requirements: 2, design: 3 };
+  for (const [gate, status] of Object.entries(phaseGates)) {
+    const phaseNum = gateMap[gate];
+    if (!phaseNum) continue;
+    const phase = db.prepare(
+      'SELECT phase_number, status FROM plan_phases WHERE plan_id = ? AND phase_number = ?'
+    ).get(plan.plan_id, phaseNum);
+    if (!phase) continue;
+
+    const newStatus = status === 'approved' ? 'completed' : (status === 'pending' ? 'pending' : phase.status);
+    if (newStatus !== phase.status) {
+      db.prepare(
+        'UPDATE plan_phases SET status = ?, completed_at = ? WHERE plan_id = ? AND phase_number = ?'
+      ).run(newStatus, newStatus === 'completed' ? nowIso() : null, plan.plan_id, phaseNum);
+      updated++;
+    }
+  }
+  return updated;
+}
+
+async function syncSpecFile(db, specPath, { verbose = false } = {}) {
+  let content;
+  try {
+    content = await fs.readFile(specPath, 'utf8');
+  } catch {
+    return { skipped: true, reason: 'not_found' };
+  }
+
+  const filename = path.basename(specPath, '.md');
+  const featureSlug = filename.startsWith('spec-') ? filename.slice(5) : null;
+  const fm = parseFrontmatter(content);
+  const phaseGates = fm.phase_gates ? JSON.parse(fm.phase_gates.replace(/'/g, '"')).catch?.() || null : null;
+
+  const learnings = extractLearnings(content);
+  const lastCheckpoint = extractLastCheckpoint(content);
+
+  let learningsSynced = 0;
+  for (const { type, title } of learnings) {
+    upsertProjectLearning(db, { title, type, featureSlug, sourceSession: filename });
+    learningsSynced++;
+  }
+
+  let phasesSynced = 0;
+  if (featureSlug && fm.phase_gates) {
+    try {
+      const gates = JSON.parse(fm.phase_gates.replace(/'/g, '"'));
+      phasesSynced = syncPlanPhases(db, featureSlug, gates);
+    } catch { /* malformed phase_gates — skip */ }
+  }
+
+  return { featureSlug, learningsSynced, phasesSynced, lastCheckpoint };
+}
+
+async function runSpecSync({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const contextDir = path.join(targetDir, '.aioson', 'context');
+
+  let files;
+  try {
+    const entries = await fs.readdir(contextDir);
+    files = entries.filter((f) => f.startsWith('spec') && f.endsWith('.md'));
+  } catch {
+    if (!options.json) logger.log('No .aioson/context/ directory found.');
+    return { ok: false, reason: 'no_context_dir' };
+  }
+
+  const { db, dbPath } = await openRuntimeDb(targetDir);
+  const results = [];
+
+  try {
+    for (const file of files) {
+      const result = await syncSpecFile(db, path.join(contextDir, file), { verbose: options.verbose });
+      if (!result.skipped) {
+        results.push({ file, ...result });
+      }
+    }
+  } finally {
+    db.close();
+  }
+
+  const totalLearnings = results.reduce((s, r) => s + (r.learningsSynced || 0), 0);
+  const totalPhases = results.reduce((s, r) => s + (r.phasesSynced || 0), 0);
+
+  if (options.json) {
+    return { ok: true, files: results, totalLearnings, totalPhases, dbPath };
+  }
+
+  logger.log(`Spec Sync — ${targetDir}`);
+  logger.log('─'.repeat(50));
+  for (const r of results) {
+    logger.log(`${r.file}`);
+    if (r.learningsSynced > 0) logger.log(`  Learnings synced: ${r.learningsSynced}`);
+    if (r.phasesSynced > 0) logger.log(`  Plan phases updated: ${r.phasesSynced}`);
+    if (r.lastCheckpoint) logger.log(`  last_checkpoint: "${r.lastCheckpoint}"`);
+  }
+  logger.log('─'.repeat(50));
+  logger.log(`Summary: ${totalLearnings} learnings synced, ${totalPhases} plan phases updated`);
+
+  return { ok: true, files: results, totalLearnings, totalPhases, dbPath };
+}
+
+module.exports = { runSpecSync };