@jaimevalasek/aioson 1.5.1 → 1.7.0

package/src/commands/learning-rollback.js

@@ -0,0 +1,164 @@
+'use strict';
+
+/**
+ * aioson learning:rollback [projectDir] --evolution=<uuid> [--squad=<slug>]
+ *
+ * Reverts a specific evolution delta from evolution-log.jsonl.
+ *
+ * Steps:
+ *   1. Find the evolution entry by UUID in .aioson/evolution/evolution-log.jsonl
+ *   2. Revert the appended content from the target file
+ *   3. Mark the entry as rolled_back in the log
+ *   4. Mark source learnings as stale in SQLite
+ *
+ * Usage:
+ *   aioson learning:rollback . --evolution=<uuid>
+ *   aioson learning:rollback . --evolution=<uuid> --dry-run
+ *   aioson learning:rollback . --list   (show applied evolutions)
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { openRuntimeDb } = require('../runtime-store');
+
+const EVOLUTION_LOG = path.join('.aioson', 'evolution', 'evolution-log.jsonl');
+
+async function readEvolutionLog(projectDir) {
+  const logPath = path.resolve(projectDir, EVOLUTION_LOG);
+  try {
+    const content = await fs.readFile(logPath, 'utf8');
+    return content.trim().split('\n')
+      .filter(Boolean)
+      .map((line) => {
+        try { return JSON.parse(line); } catch { return null; }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+async function writeEvolutionLog(projectDir, entries) {
+  const logPath = path.resolve(projectDir, EVOLUTION_LOG);
+  await fs.mkdir(path.dirname(logPath), { recursive: true });
+  await fs.writeFile(logPath, entries.map((e) => JSON.stringify(e)).join('\n') + '\n', 'utf8');
+}
+
+async function runLearningRollback({ args = [], options = {}, logger = console } = {}) {
+  const projectDir = path.resolve(process.cwd(), args[0] || '.');
+  const dryRun = Boolean(options['dry-run'] || options.dry);
+
+  // ── List mode ──────────────────────────────────────────────────────────────
+  if (options.list) {
+    const entries = await readEvolutionLog(projectDir);
+    const applied = entries.filter((e) => e.status === 'applied');
+
+    if (applied.length === 0) {
+      logger.log('No applied evolutions found in evolution-log.jsonl');
+      return { ok: true, entries: [] };
+    }
+
+    logger.log(`Applied evolutions (${applied.length}):`);
+    for (const e of applied) {
+      logger.log(`  ${e.id.slice(0, 8)}... ${e.ts.slice(0, 16)} → ${e.file}`);
+      logger.log(`    ${e.learning_ids?.length || 0} learning(s) applied`);
+      if (e.squad) logger.log(`    Squad: ${e.squad}`);
+    }
+    logger.log('');
+    logger.log('Rollback: aioson learning:rollback . --evolution=<id>');
+
+    return { ok: true, entries: applied };
+  }
+
+  // ── Rollback mode ──────────────────────────────────────────────────────────
+  const evolutionId = String(options.evolution || '').trim();
+  if (!evolutionId) {
+    logger.error('Error: --evolution <uuid> is required (or --list to see applied evolutions)');
+    return { ok: false, error: 'missing_evolution_id' };
+  }
+
+  const entries = await readEvolutionLog(projectDir);
+  const entryIndex = entries.findIndex(
+    (e) => e.id === evolutionId || e.id.startsWith(evolutionId)
+  );
+
+  if (entryIndex === -1) {
+    logger.error(`Evolution "${evolutionId}" not found in evolution-log.jsonl`);
+    logger.log('Run: aioson learning:rollback . --list');
+    return { ok: false, error: 'evolution_not_found' };
+  }
+
+  const entry = entries[entryIndex];
+
+  if (entry.status === 'rolled_back') {
+    logger.log(`Evolution "${entry.id.slice(0, 8)}..." is already rolled back.`);
+    return { ok: true, alreadyRolledBack: true };
+  }
+
+  if (entry.status !== 'applied') {
+    logger.error(`Evolution "${entry.id.slice(0, 8)}..." has unexpected status: ${entry.status}`);
+    return { ok: false, error: 'unexpected_status' };
+  }
+
+  logger.log(`Rolling back evolution: ${entry.id}`);
+  logger.log(`  File: ${entry.file}`);
+  logger.log(`  Content to remove (${entry.content?.length || 0} chars)`);
+
+  if (dryRun) {
+    logger.log('[dry-run] No changes applied.');
+    return { ok: true, dryRun: true, entry };
+  }
+
+  // ── Revert file content ────────────────────────────────────────────────────
+  if (entry.content && entry.file) {
+    const filePath = path.isAbsolute(entry.file)
+      ? entry.file
+      : path.resolve(projectDir, entry.file);
+
+    try {
+      const current = await fs.readFile(filePath, 'utf8');
+      // Remove the exact content that was appended
+      const reverted = current.replace(entry.content, '').replace(/\n{3,}/g, '\n\n');
+      await fs.writeFile(filePath, reverted, 'utf8');
+      logger.log(`  ✓ Reverted: ${entry.file}`);
+    } catch (err) {
+      logger.error(`  ✗ Failed to revert ${entry.file}: ${err.message}`);
+      return { ok: false, error: 'file_revert_failed', detail: err.message };
+    }
+  }
+
+  // ── Mark entry as rolled_back ──────────────────────────────────────────────
+  entries[entryIndex] = {
+    ...entry,
+    status: 'rolled_back',
+    rollback_ts: new Date().toISOString(),
+    rollback_reason: options.reason || 'user request'
+  };
+  await writeEvolutionLog(projectDir, entries);
+
+  // ── Mark learnings as stale in SQLite ─────────────────────────────────────
+  const learningIds = entry.learning_ids || [];
+  if (learningIds.length > 0) {
+    const handle = await openRuntimeDb(projectDir, { mustExist: true });
+    if (handle) {
+      const { db } = handle;
+      try {
+        for (const id of learningIds) {
+          db.prepare(
+            `UPDATE squad_learnings SET status = 'stale', updated_at = datetime('now') WHERE learning_id = ?`
+          ).run(id);
+        }
+        logger.log(`  ✓ ${learningIds.length} learning(s) marked as stale`);
+      } finally {
+        db.close();
+      }
+    }
+  }
+
+  logger.log('');
+  logger.log(`✓ Evolution rolled back: ${entry.id}`);
+
+  return { ok: true, entry: entries[entryIndex] };
+}
+
+module.exports = { runLearningRollback };

package/src/commands/live.js

@@ -860,6 +860,20 @@ async function runLiveStart({ args, options = {}, logger, t }) {
     throw new Error(t('live.json_requires_no_launch'));
   }
 
+  // ── 5.3 Ambient Intelligence health check alert ────────────────────────────
+  if (!options.json && !options['no-health-check']) {
+    try {
+      const { runHealthCheck, formatHealthAlert } = require('../lib/health-check');
+      const health = await runHealthCheck(targetDir);
+      const alert = formatHealthAlert(health.items);
+      if (alert) {
+        logger.log('');
+        logger.log(alert);
+        logger.log('');
+      }
+    } catch { /* health check is non-fatal */ }
+  }
+
   const toolBinary = String(options['tool-bin'] || tool).trim();
   const binaryPath = await resolveExecutablePath(toolBinary);
   if (!binaryPath) {
@@ -1062,6 +1076,23 @@ async function runLiveStart({ args, options = {}, logger, t }) {
       logger.log(t('live.session_started', { agent: agentName, tool, session: sessionKey, dbPath }));
     }
 
+    // Ambient Intelligence: exibe digest de saúde ao iniciar sessão
+    if (!options.json && !options['no-health']) {
+      try {
+        const { getHealthDigest } = require('./health');
+        const items = await getHealthDigest(targetDir);
+        if (items && items.length > 0) {
+          logger.log('');
+          logger.log('AIOSON Health — itens pendentes:');
+          for (const item of items) {
+            logger.log(`  ● ${item}`);
+          }
+          logger.log('  → aioson health . para detalhes');
+          logger.log('');
+        }
+      } catch { /* não bloqueia o start */ }
+    }
+
     if (child) {
       childResult = await waitForChild(child);
     }
@@ -1190,6 +1221,11 @@ async function runRuntimeEmit({ args, options = {}, logger, t }) {
       }
     }
 
+    const workerStatus = options['worker-status'] ? String(options['worker-status']).trim() : null;
+    const verdict = options.verdict ? String(options.verdict).trim().toUpperCase() : null;
+    const tokenCount = options['token-count'] != null ? Number(options['token-count']) || null : null;
+    const progressPct = options['progress-pct'] != null ? Number(options['progress-pct']) || null : null;
+
     appendRunEvent(db, {
       runKey: context.run.run_key,
       eventType,
@@ -1197,7 +1233,12 @@ async function runRuntimeEmit({ args, options = {}, logger, t }) {
       status: context.run.status || 'running',
       message: summary,
       payload: Object.keys(payload).length > 0 ? payload : null,
-      createdAt: now
+      createdAt: now,
+      planStepId: planStep || null,
+      workerStatus,
+      verdict,
+      tokenCount,
+      progressPct
     });
 
     const eventRecord = createLiveEventRecord(context, {
@@ -1508,6 +1549,23 @@ async function runLiveClose({ args, options = {}, logger, t }) {
       logger.log(t('live.session_closed', { agent: context.agentName, session: context.sessionKey, dbPath }));
     }
 
+    // Ambient Intelligence: sugere evolução se há learnings acumulados
+    if (!options.json && !options['no-health']) {
+      try {
+        const { getHealthDigest } = require('./health');
+        const items = await getHealthDigest(targetDir);
+        if (items && items.length > 0) {
+          logger.log('');
+          logger.log('AIOSON Health — itens após sessão:');
+          for (const item of items) {
+            logger.log(`  ● ${item}`);
+          }
+          logger.log('  → aioson health . para detalhes e ações');
+          logger.log('');
+        }
+      } catch { /* não bloqueia o close */ }
+    }
+
     return {
       ok: true,
       targetDir,

package/src/commands/pattern-detect.js

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * aioson pattern:detect — Detect automation candidates from squad learnings
+ *
+ * Usage:
+ *   aioson pattern:detect . --squad=content-team
+ *   aioson pattern:detect . --squad=content-team --min-occurrences=2
+ *   aioson pattern:detect . --squad=content-team --json
+ */
+
+const path = require('node:path');
+const { detectPatterns, formatPatternReport } = require('../squad/pattern-detector');
+
+async function runPatternDetect({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const squadSlug = String(options.squad || options.s || '').trim();
+
+  if (!squadSlug) {
+    logger.error('Error: --squad is required');
+    return { ok: false, error: 'missing_squad' };
+  }
+
+  const minOccurrences = Number(options['min-occurrences'] || options.min || 3);
+  const result = await detectPatterns(targetDir, squadSlug, { minOccurrences });
+
+  if (options.json) return result;
+
+  logger.log(formatPatternReport(result));
+  return { ok: true, ...result };
+}
+
+module.exports = { runPatternDetect };

package/src/commands/preflight-context.js

@@ -0,0 +1,30 @@
+'use strict';
+
+/**
+ * aioson preflight:context — Estimate context budget before a session
+ *
+ * Usage:
+ *   aioson preflight:context . --agent=dev
+ *   aioson preflight:context . --agent=orchestrator --squad=content-team
+ *   aioson preflight:context . --agent=dev --verbose
+ *   aioson preflight:context . --agent=dev --json
+ */
+
+const path = require('node:path');
+const { estimateContext, formatReport } = require('../squad/preflight-context');
+
+async function runPreflightContext({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const agent = String(options.agent || options.a || 'dev').trim();
+  const squad = options.squad ? String(options.squad).trim() : undefined;
+  const verbose = Boolean(options.verbose || options.v);
+
+  const result = await estimateContext(targetDir, { agent, squad, verbose });
+
+  if (options.json) return result;
+
+  logger.log(formatReport(result));
+  return { ok: result.exitCode === 0, ...result };
+}
+
+module.exports = { runPreflightContext };

package/src/commands/preflight.js

@@ -0,0 +1,208 @@
+'use strict';
+
+/**
+ * aioson preflight — consolidated pre-flight analysis for any agent session.
+ *
+ * Replaces 10+ manual file checks with one command. Returns mode, context package,
+ * readiness, phase gates, and next step — deterministically, with no LLM calls.
+ *
+ * Usage:
+ *   aioson preflight . --agent=dev --feature=checkout
+ *   aioson preflight . --agent=qa --feature=checkout --json
+ *   aioson preflight .   (project-level, no feature)
+ */
+
+const path = require('node:path');
+const {
+  loadProjectContext,
+  scanArtifacts,
+  readPhaseGates,
+  readDevState,
+  readProjectPulse,
+  detectClassification,
+  detectFramework,
+  detectTestRunner,
+  discoverRules,
+  buildContextPackage,
+  evaluateReadiness,
+  extractSpecVersion,
+  extractLastCheckpoint,
+  GATE_NAMES
+} = require('../preflight-engine');
+
+const BAR = '━'.repeat(55);
+
+function gateIcon(status) {
+  if (!status) return '○';
+  if (status === 'approved') return '✓';
+  if (status === 'pending') return '○';
+  return '✗';
+}
+
+async function runPreflight({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const agent = options.agent ? String(options.agent) : null;
+  const slug = options.feature ? String(options.feature) : null;
+
+  // --- Gather all data ---
+  const ctx = await loadProjectContext(targetDir);
+  const artifacts = await scanArtifacts(targetDir, slug);
+  const phaseGates = await readPhaseGates(targetDir, slug);
+  const devState = await readDevState(targetDir);
+  const pulse = await readProjectPulse(targetDir);
+
+  let classification = await detectClassification(targetDir, slug);
+  const framework = ctx.data.framework || ctx.data.stack || await detectFramework(targetDir);
+  const testRunnerInfo = await detectTestRunner(targetDir);
+  const testRunner = testRunnerInfo ? testRunnerInfo.name : (ctx.data.test_runner || null);
+  const rules = agent ? await discoverRules(targetDir, agent) : [];
+  const contextPackage = buildContextPackage(agent || 'dev', slug, classification, artifacts, devState);
+  const readiness = evaluateReadiness(artifacts, phaseGates, classification, agent);
+
+  // Determine mode
+  const mode = slug
+    ? (artifacts.prd.exists ? 'feature' : 'continuation')
+    : (artifacts.project_context.exists ? 'project' : 'greenfield');
+
+  // Spec version + checkpoint
+  const specVersion = extractSpecVersion(artifacts.spec);
+  const lastCheckpoint = extractLastCheckpoint(artifacts.spec);
+
+  const result = {
+    ok: true,
+    mode,
+    feature_slug: slug,
+    agent,
+    classification,
+    framework: framework || null,
+    test_runner: testRunner,
+    artifacts: {
+      project_context: { exists: artifacts.project_context.exists, path: artifacts.project_context.path || null },
+      prd: { exists: artifacts.prd.exists, path: artifacts.prd.path || null },
+      sheldon_enrichment: { exists: artifacts.sheldon_enrichment.exists },
+      requirements: { exists: artifacts.requirements.exists, path: artifacts.requirements.path || null },
+      spec: {
+        exists: artifacts.spec.exists,
+        path: artifacts.spec.path || null,
+        version: specVersion,
+        last_checkpoint: lastCheckpoint
+      },
+      architecture: { exists: artifacts.architecture.exists },
+      implementation_plan: {
+        exists: artifacts.implementation_plan.exists,
+        path: artifacts.implementation_plan.path || null,
+        status: artifacts.implementation_plan.exists ? (artifacts.implementation_plan.frontmatter.status || null) : null
+      },
+      conformance: { exists: artifacts.conformance.exists },
+      dev_state: {
+        exists: devState.exists,
+        next_step: devState.next_step || null
+      }
+    },
+    phase_gates: {
+      requirements: phaseGates.requirements || 'pending',
+      design: phaseGates.design || 'pending',
+      plan: phaseGates.plan || 'pending',
+      execution: phaseGates.execution || 'pending'
+    },
+    context_package: contextPackage,
+    rules,
+    readiness: readiness.status,
+    readiness_blockers: readiness.blockers,
+    pulse: {
+      last_agent: pulse.last_agent || null,
+      last_gate: pulse.last_gate || null,
+      blockers: pulse.blockers || 'none'
+    },
+    dev_state: {
+      active_feature: devState.active_feature || null,
+      active_phase: devState.active_phase || null,
+      next_step: devState.next_step || null,
+      last_spec_version: devState.last_spec_version || null
+    }
+  };
+
+  if (options.json) return result;
+
+  // --- Human output ---
+  const header = agent && slug
+    ? `AIOSON Pre-flight — @${agent} / ${slug}`
+    : agent
+      ? `AIOSON Pre-flight — @${agent}`
+      : 'AIOSON Pre-flight';
+
+  logger.log('');
+  logger.log(header);
+  logger.log(BAR);
+  logger.log('');
+  logger.log(`Mode: ${mode}${classification ? ' | Classification: ' + classification : ''}${framework ? ' | Framework: ' + framework : ''}${testRunner ? ' | Test runner: ' + testRunner : ''}`);
+  logger.log('');
+
+  logger.log('Artifacts:');
+  const checks = [
+    ['project.context.md', artifacts.project_context.exists, null],
+    slug ? [`prd-${slug}.md`, artifacts.prd.exists, null] : null,
+    slug ? [`sheldon-enrichment-${slug}.md`, artifacts.sheldon_enrichment.exists, 'optional'] : null,
+    slug ? [`requirements-${slug}.md`, artifacts.requirements.exists, null] : null,
+    slug
+      ? [`spec-${slug}.md`, artifacts.spec.exists, specVersion ? `version: ${specVersion}${lastCheckpoint ? ', last: "' + lastCheckpoint + '"' : ''}` : null]
+      : null,
+    ['architecture.md', artifacts.architecture.exists, null],
+    slug ? [`implementation-plan-${slug}.md`, artifacts.implementation_plan.exists, artifacts.implementation_plan.exists ? `status: ${artifacts.implementation_plan.frontmatter.status || 'unknown'}` : null] : null,
+    slug ? [`conformance-${slug}.yaml`, artifacts.conformance.exists, classification === 'SMALL' || classification === 'MICRO' ? 'MEDIUM only — not required' : null] : null
+  ].filter(Boolean);
+
+  for (const [name, exists, note] of checks) {
+    const icon = exists ? '  ✓' : '  ✗';
+    const suffix = note ? ` (${note})` : '';
+    logger.log(`${icon} ${name}${suffix}`);
+  }
+
+  logger.log('');
+  logger.log('Phase gates:');
+  for (const [letter, name] of Object.entries(GATE_NAMES)) {
+    const status = phaseGates[name] || 'pending';
+    logger.log(`  ${gateIcon(status)} Gate ${letter} (${name}): ${status}`);
+  }
+
+  if (devState.exists && devState.next_step) {
+    logger.log('');
+    logger.log('Dev state:');
+    if (devState.active_feature) logger.log(`  active_feature: ${devState.active_feature}`);
+    if (devState.active_phase) logger.log(`  active_phase: ${devState.active_phase}`);
+    logger.log(`  next_step: "${devState.next_step}"`);
+    if (devState.last_spec_version) logger.log(`  last_spec_version: ${devState.last_spec_version}`);
+  }
+
+  if (contextPackage.length > 0) {
+    logger.log('');
+    logger.log('Context package (load these):');
+    contextPackage.forEach((p, i) => logger.log(`  ${i + 1}. ${p}`));
+  }
+
+  if (rules.length > 0) {
+    logger.log('');
+    logger.log(`Rules loaded: ${rules.join(', ')}`);
+  }
+
+  if (pulse.last_agent) {
+    logger.log('');
+    logger.log('Project pulse:');
+    if (pulse.last_agent) logger.log(`  last_agent: @${pulse.last_agent}`);
+    if (pulse.last_gate) logger.log(`  last_gate: ${pulse.last_gate}`);
+    logger.log(`  blockers: ${pulse.blockers || 'none'}`);
+  }
+
+  logger.log('');
+  if (readiness.status === 'READY') {
+    logger.log(`Readiness: READY — proceed`);
+  } else {
+    logger.log(`Readiness: BLOCKED`);
+    for (const b of readiness.blockers) logger.log(`  ✗ ${b}`);
+  }
+  logger.log('');
+
+  return result;
+}
+
+module.exports = { runPreflight };

package/src/commands/pulse-update.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * aioson pulse:update — update project-pulse.md at session end.
+ *
+ * Replaces the manual project-pulse.md editing block in 7+ agents.
+ * Keeps last 3 recent activity entries.
+ *
+ * Usage:
+ *   aioson pulse:update . --agent=dev --feature=checkout --gate="Gate C: approved" \
+ *     --action="Implemented payment webhook handler" --next="Continue with phase 4"
+ *   aioson pulse:update . --agent=qa --verdict=PASS --feature=checkout
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { contextDir, readFileSafe, parseFrontmatter } = require('../preflight-engine');
+
+function nowDate() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+async function runPulseUpdate({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const agent = options.agent ? String(options.agent) : null;
+  const slug = options.feature ? String(options.feature) : null;
+  const gate = options.gate ? String(options.gate) : null;
+  const action = options.action ? String(options.action) : null;
+  const next = options.next ? String(options.next) : null;
+  const phase = options.phase ? String(options.phase) : null;
+  const verdict = options.verdict ? String(options.verdict).toUpperCase() : null;
+
+  if (!agent) {
+    if (options.json) return { ok: false, reason: 'missing_agent' };
+    logger.log('--agent is required. Example: aioson pulse:update . --agent=dev --feature=checkout');
+    return { ok: false };
+  }
+
+  const pulsePath = path.join(contextDir(targetDir), 'project-pulse.md');
+  const existing = await readFileSafe(pulsePath);
+
+  // Parse existing frontmatter
+  const fm = existing ? parseFrontmatter(existing) : {};
+
+  // Extract existing recent_activity lines (keep last 2 to add 1 new = 3 total)
+  const existingActivities = [];
+  if (existing) {
+    const activityMatch = existing.match(/## Recent Activity\n([\s\S]*?)(?=\n##|\s*$)/);
+    if (activityMatch) {
+      const lines = activityMatch[1].split('\n').filter((l) => l.trim().startsWith('-'));
+      existingActivities.push(...lines.slice(-2));
+    }
+  }
+
+  // Build new activity line
+  const today = nowDate();
+  let activityLine = `- ${today} @${agent}`;
+  if (slug) activityLine += ` → ${slug}`;
+  if (phase) activityLine += ` phase ${phase}`;
+  if (gate) activityLine += ` (${gate})`;
+  if (verdict) activityLine += ` VERDICT: ${verdict}`;
+  if (action) activityLine += `: ${action}`;
+
+  const recentActivities = [...existingActivities, activityLine];
+
+  // Build active work entry
+  let activeWork = fm.active_work || '';
+  if (slug) {
+    const phaseStr = phase ? ` → phase ${phase}` : '';
+    const statusStr = verdict ? (verdict === 'PASS' ? 'done' : 'in_progress') : 'in_progress';
+    activeWork = `${slug}${phaseStr} → @${agent} → ${statusStr}`;
+  }
+
+  // Build next recommendation
+  const nextRec = next || fm.next_recommendation || '';
+
+  // Write pulse file
+  const lines = [
+    '---',
+    `last_updated: ${today}`,
+    `last_agent: ${agent}`,
+    gate ? `last_gate: ${gate}` : (fm.last_gate ? `last_gate: ${fm.last_gate}` : null),
+    slug ? `active_feature: ${slug}` : (fm.active_feature ? `active_feature: ${fm.active_feature}` : null),
+    activeWork ? `active_work: "${activeWork}"` : null,
+    'blockers: none',
+    nextRec ? `next_recommendation: "${nextRec}"` : null,
+    '---',
+    '',
+    '# Project Pulse',
+    '',
+    '## Status',
+    '',
+    `- **Last agent:** @${agent}`,
+    gate ? `- **Last gate:** ${gate}` : null,
+    slug ? `- **Active feature:** ${slug}` : null,
+    activeWork ? `- **Active work:** ${activeWork}` : null,
+    nextRec ? `- **Next:** ${nextRec}` : null,
+    '',
+    '## Recent Activity',
+    '',
+    ...recentActivities,
+    ''
+  ].filter((l) => l !== null);
+
+  await fs.mkdir(path.dirname(pulsePath), { recursive: true });
+  await fs.writeFile(pulsePath, lines.join('\n'), 'utf8');
+
+  const result = {
+    ok: true,
+    path: path.relative(targetDir, pulsePath),
+    last_agent: agent,
+    last_gate: gate,
+    active_feature: slug,
+    active_work: activeWork,
+    next_recommendation: nextRec
+  };
+
+  if (options.json) return result;
+
+  logger.log('Project pulse updated:');
+  logger.log(`  last_agent: ${agent}`);
+  if (gate) logger.log(`  last_gate: ${gate}`);
+  if (slug) logger.log(`  active_work: ${activeWork}`);
+  logger.log(`  Recent activity: +1 entry (kept last 3)`);
+  if (next) logger.log(`  Next: ${next}`);
+
+  return result;
+}
+
+module.exports = { runPulseUpdate };