@jaimevalasek/aioson 1.7.0 → 1.8.0

package/src/commands/parallel-status.js

@@ -4,8 +4,21 @@ const fs = require('node:fs/promises');
 const path = require('node:path');
 const { exists } = require('../utils');
 const { recordRuntimeOperation } = require('../execution-gateway');
+const {
+  WORKSPACE_MANIFEST_RELATIVE_PATH,
+  OWNERSHIP_MAP_RELATIVE_PATH,
+  MERGE_PLAN_RELATIVE_PATH,
+  buildLaneOwnershipEntries,
+  collectOwnershipConflicts,
+  collectWritePathConflicts,
+  extractStatusDependencyItems,
+  extractStatusMergeRank,
+  extractStatusWritePathItems,
+  buildMachineSyncReport,
+  collectDependencyIssues
+} = require('../parallel-workspace');
 
-const KNOWN_STATUSES = ['pending', 'in_progress', 'completed', 'blocked'];
+const KNOWN_STATUSES = ['pending', 'in_progress', 'completed', 'merged', 'blocked'];
 
 function parseLaneIndex(fileName) {
   const match = String(fileName || '').match(/^agent-(\d+)\.status\.md$/);
@@ -103,6 +116,7 @@ function createStatusCounts() {
     pending: 0,
     in_progress: 0,
     completed: 0,
+    merged: 0,
     blocked: 0,
     other: 0
   };
@@ -115,6 +129,7 @@ function formatStatusLabel(status, t) {
   if (normalized === 'pending') return t('parallel_status.status_pending');
   if (normalized === 'in_progress') return t('parallel_status.status_in_progress');
   if (normalized === 'completed') return t('parallel_status.status_completed');
+  if (normalized === 'merged') return t('parallel_status.status_merged');
   if (normalized === 'blocked') return t('parallel_status.status_blocked');
   return t('parallel_status.status_other');
 }
@@ -130,6 +145,9 @@ async function parseLaneFile(parallelDir, index) {
   const scopeItems = sanitizeScopeItems(extractSectionBullets(content, 'Scope'));
   const blockerItems = sanitizeBlockerItems(extractSectionBullets(content, 'Blockers'));
   const deliverables = parseDeliverables(content);
+  const dependencyItems = extractStatusDependencyItems(content);
+  const mergeRank = extractStatusMergeRank(content, index);
+  const writePathItems = extractStatusWritePathItems(content);
 
   return {
     lane: index,
@@ -139,10 +157,15 @@ async function parseLaneFile(parallelDir, index) {
     priority,
     updatedAt,
     scopeCount: scopeItems.length,
+    dependencyCount: dependencyItems.length,
     blockerCount: blockerItems.length,
     deliverables,
     scopeItems,
-    blockerItems
+    blockerItems,
+    dependencyItems,
+    mergeRank,
+    writePathItems,
+    writePathCount: writePathItems.length
   };
 }
 
@@ -189,6 +212,57 @@ async function runParallelStatus({ args, options = {}, logger, t }) {
   const sharedDecisionEntries = sharedExists
     ? countDecisionRows(await fs.readFile(sharedPath, 'utf8'))
     : 0;
+  const manifestPath = path.join(targetDir, WORKSPACE_MANIFEST_RELATIVE_PATH);
+  const ownershipPath = path.join(targetDir, OWNERSHIP_MAP_RELATIVE_PATH);
+  const mergePlanPath = path.join(targetDir, MERGE_PLAN_RELATIVE_PATH);
+  const manifestExists = await exists(manifestPath);
+  const ownershipExists = await exists(ownershipPath);
+  const mergePlanExists = await exists(mergePlanPath);
+
+  let workspaceManifest = null;
+  let ownershipMap = null;
+  let mergePlan = null;
+  try {
+    workspaceManifest = manifestExists ? JSON.parse(await fs.readFile(manifestPath, 'utf8')) : null;
+  } catch {
+    workspaceManifest = null;
+  }
+  try {
+    ownershipMap = ownershipExists ? JSON.parse(await fs.readFile(ownershipPath, 'utf8')) : null;
+  } catch {
+    ownershipMap = null;
+  }
+  try {
+    mergePlan = mergePlanExists ? JSON.parse(await fs.readFile(mergePlanPath, 'utf8')) : null;
+  } catch {
+    mergePlan = null;
+  }
+
+  const ownershipConflicts = collectOwnershipConflicts(ownershipMap);
+  const laneEntries = buildLaneOwnershipEntries(
+    lanes.map((lane) => ({
+      lane: lane.lane,
+      items: lane.scopeItems,
+      owner: lane.owner,
+      dependsOn: lane.dependencyItems,
+      writePaths: lane.writePathItems,
+      mergeRank: lane.mergeRank
+    }))
+  );
+  const sync = buildMachineSyncReport({
+    laneEntries,
+    workspaceManifest,
+    ownershipMap,
+    mergePlan
+  });
+  const dependencies = collectDependencyIssues({
+    lanes,
+    mergeOrder: mergePlan && Array.isArray(mergePlan.order) ? mergePlan.order : []
+  });
+  const writePaths = collectWritePathConflicts(lanes);
+  const assignedPathLaneCount = lanes.filter((lane) => lane.writePathCount > 0).length;
+  const uncoveredAssignedLaneCount = lanes.filter((lane) => lane.scopeCount > 0 && lane.writePathCount === 0).length;
+  const totalWritePathCount = lanes.reduce((sum, lane) => sum + lane.writePathCount, 0);
 
   const output = {
     ok: true,
@@ -206,6 +280,35 @@ async function runParallelStatus({ args, options = {}, logger, t }) {
       exists: sharedExists,
       entries: sharedDecisionEntries
     },
+    machineFiles: {
+      workspaceManifest: manifestExists,
+      ownershipMap: ownershipExists,
+      mergePlan: mergePlanExists
+    },
+    ownership: {
+      assignedScopeCount: ownershipMap && Array.isArray(ownershipMap.lanes)
+        ? ownershipMap.lanes.reduce((sum, lane) => sum + (Array.isArray(lane.scope_keys) ? lane.scope_keys.length : 0), 0)
+        : 0,
+      conflictCount: ownershipConflicts.length,
+      conflicts: ownershipConflicts
+    },
+    writeScope: {
+      laneCount: assignedPathLaneCount,
+      totalPathCount: totalWritePathCount,
+      uncoveredAssignedLaneCount,
+      invalidPatternCount: writePaths.invalidCount,
+      invalidPatterns: writePaths.invalid,
+      conflictCount: writePaths.conflictCount,
+      conflicts: writePaths.conflicts
+    },
+    dependencies,
+    merge: {
+      strategy: mergePlan && mergePlan.strategy ? mergePlan.strategy : null,
+      order: mergePlan && Array.isArray(mergePlan.order) ? mergePlan.order : [],
+      laneCount: mergePlan && Array.isArray(mergePlan.lanes) ? mergePlan.lanes.length : 0,
+      orderViolationCount: dependencies.orderViolationCount
+    },
+    sync,
     lanes: lanes.map((lane) => ({
       lane: lane.lane,
       file: lane.file,
@@ -214,6 +317,11 @@ async function runParallelStatus({ args, options = {}, logger, t }) {
       priority: lane.priority,
       updatedAt: lane.updatedAt,
       scopeCount: lane.scopeCount,
+      dependencyCount: lane.dependencyCount,
+      dependencies: lane.dependencyItems,
+      mergeRank: lane.mergeRank,
+      writePathCount: lane.writePathCount,
+      writePaths: lane.writePathItems,
       blockerCount: lane.blockerCount,
       deliverables: lane.deliverables
     }))
@@ -237,7 +345,13 @@ async function runParallelStatus({ args, options = {}, logger, t }) {
       scopeCount,
       blockerCount,
       deliverables: output.deliverables,
-      sharedDecisions: output.sharedDecisions
+      sharedDecisions: output.sharedDecisions,
+      machineFiles: output.machineFiles,
+      ownership: output.ownership,
+      writeScope: output.writeScope,
+      dependencies: output.dependencies,
+      merge: output.merge,
+      sync: output.sync
     }
   });
 
@@ -269,6 +383,36 @@ async function runParallelStatus({ args, options = {}, logger, t }) {
       count: sharedDecisionEntries
     })
   );
+  logger.log(
+    t('parallel_status.ownership_conflicts', {
+      count: output.ownership.conflictCount
+    })
+  );
+  logger.log(
+    t('parallel_status.write_scope_summary', {
+      lanes: output.writeScope.laneCount,
+      paths: output.writeScope.totalPathCount,
+      uncovered: output.writeScope.uncoveredAssignedLaneCount,
+      conflicts: output.writeScope.conflictCount,
+      invalid: output.writeScope.invalidPatternCount
+    })
+  );
+  logger.log(
+    t('parallel_status.dependencies_summary', {
+      declared: output.dependencies.declaredCount,
+      invalid: output.dependencies.invalidCount,
+      blocked: output.dependencies.blockedCount,
+      orderViolations: output.dependencies.orderViolationCount
+    })
+  );
+  logger.log(
+    t('parallel_status.sync_summary', {
+      count: output.sync.staleFiles.length
+    })
+  );
+  for (const file of output.sync.staleFiles) {
+    logger.log(t('parallel_status.sync_stale_line', { file }));
+  }
   for (const lane of output.lanes) {
     logger.log(
       t('parallel_status.lane_line', {

package/src/commands/preflight.js

@@ -16,6 +16,7 @@ const path = require('node:path');
 const {
   loadProjectContext,
   scanArtifacts,
+  scanActiveManifest,
   readPhaseGates,
   readDevState,
   readProjectPulse,
@@ -23,8 +24,10 @@ const {
   detectFramework,
   detectTestRunner,
   discoverRules,
+  discoverDesignDocs,
   buildContextPackage,
   evaluateReadiness,
+  detectStaleDevState,
   extractSpecVersion,
   extractLastCheckpoint,
   GATE_NAMES
@@ -47,6 +50,7 @@ async function runPreflight({ args, options = {}, logger }) {
   // --- Gather all data ---
   const ctx = await loadProjectContext(targetDir);
   const artifacts = await scanArtifacts(targetDir, slug);
+  const manifest = await scanActiveManifest(targetDir, slug);
   const phaseGates = await readPhaseGates(targetDir, slug);
   const devState = await readDevState(targetDir);
   const pulse = await readProjectPulse(targetDir);
@@ -56,8 +60,17 @@ async function runPreflight({ args, options = {}, logger }) {
   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);
+  const designDocs = agent ? await discoverDesignDocs(targetDir, agent) : [];
+  const contextPackage = buildContextPackage(agent || 'dev', slug, classification, artifacts, devState, manifest);
+  const readiness = evaluateReadiness(artifacts, phaseGates, classification, agent, devState, slug);
+
+  // Determine active execution artifact (AC-SDLC-24)
+  const activeExecutionArtifact = manifest && manifest.exists && manifest.is_active
+    ? manifest.path
+    : (artifacts.implementation_plan.exists ? artifacts.implementation_plan.path : null);
+
+  // Stale dev-state detection (AC-SDLC-12)
+  const staleDevStateWarning = devState.exists ? detectStaleDevState(devState, slug) : null;
 
   // Determine mode
   const mode = slug
@@ -105,10 +118,25 @@ async function runPreflight({ args, options = {}, logger }) {
       plan: phaseGates.plan || 'pending',
       execution: phaseGates.execution || 'pending'
     },
+    active_execution_artifact: activeExecutionArtifact,
+    manifest: manifest ? {
+      exists: manifest.exists,
+      path: manifest.path || null,
+      status: manifest.status || null,
+      is_active: manifest.is_active || false,
+      next_pending_phase: manifest.next_pending_phase || null
+    } : { exists: false },
     context_package: contextPackage,
     rules,
+    design_governance: designDocs,
+    context_layers: {
+      rules,
+      design_governance: designDocs
+    },
     readiness: readiness.status,
     readiness_blockers: readiness.blockers,
+    readiness_warnings: readiness.warnings || [],
+    stale_dev_state: staleDevStateWarning || null,
     pulse: {
       last_agent: pulse.last_agent || null,
       last_gate: pulse.last_gate || null,
@@ -165,13 +193,31 @@ async function runPreflight({ args, options = {}, logger }) {
     logger.log(`  ${gateIcon(status)} Gate ${letter} (${name}): ${status}`);
   }
 
-  if (devState.exists && devState.next_step) {
+  if (manifest && manifest.exists) {
+    logger.log('');
+    logger.log('Active execution artifact:');
+    const manifestIcon = manifest.is_active ? '  ✓' : '  ○';
+    logger.log(`${manifestIcon} ${manifest.path} (status: ${manifest.status || 'unknown'})${manifest.is_active ? ' [PRIMARY]' : ' [complete — not active]'}`);
+    if (manifest.is_active && manifest.next_pending_phase) {
+      const p = manifest.next_pending_phase;
+      logger.log(`  → Next pending phase: Phase ${p.phase} — ${p.file} (status: ${p.status})`);
+    }
+    if (!manifest.is_active && artifacts.implementation_plan.exists) {
+      logger.log(`  ✓ ${artifacts.implementation_plan.path || `implementation-plan-${slug}.md`} [primary — manifest complete]`);
+    }
+  }
+
+  if (devState.exists) {
     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.next_step) logger.log(`  next_step: "${devState.next_step}"`);
     if (devState.last_spec_version) logger.log(`  last_spec_version: ${devState.last_spec_version}`);
+    if (devState.status) logger.log(`  status: ${devState.status}`);
+    if (staleDevStateWarning) {
+      logger.log(`  ⚠ STALE: ${staleDevStateWarning}`);
+    }
   }
 
   if (contextPackage.length > 0) {
@@ -185,6 +231,12 @@ async function runPreflight({ args, options = {}, logger }) {
     logger.log(`Rules loaded: ${rules.join(', ')}`);
   }
 
+  if (designDocs.length > 0) {
+    logger.log('');
+    logger.log('Design governance (load if implementation or structural planning touches code):');
+    designDocs.forEach((p, i) => logger.log(`  ${i + 1}. ${p}`));
+  }
+
   if (pulse.last_agent) {
     logger.log('');
     logger.log('Project pulse:');
@@ -196,9 +248,16 @@ async function runPreflight({ args, options = {}, logger }) {
   logger.log('');
   if (readiness.status === 'READY') {
     logger.log(`Readiness: READY — proceed`);
+  } else if (readiness.status === 'READY_WITH_WARNINGS') {
+    logger.log(`Readiness: READY_WITH_WARNINGS — can proceed but review warnings`);
+    for (const w of readiness.warnings || []) logger.log(`  ⚠ ${w}`);
   } else {
     logger.log(`Readiness: BLOCKED`);
     for (const b of readiness.blockers) logger.log(`  ✗ ${b}`);
+    if ((readiness.warnings || []).length > 0) {
+      logger.log('  Warnings:');
+      for (const w of readiness.warnings) logger.log(`    ⚠ ${w}`);
+    }
   }
   logger.log('');
 

package/src/commands/qa-init.js

@@ -3,7 +3,7 @@
 const path = require('node:path');
 const fs = require('node:fs/promises');
 const { readTextIfExists, ensureDir, exists } = require('../utils');
-const { validateProjectContextFile } = require('../context');
+const { validateProjectContextFile, getInteractionLanguage } = require('../context');
 
 const DEFAULT_PERSONAS = ['naive', 'hacker', 'power', 'mobile'];
 
@@ -28,9 +28,14 @@ const DEFAULT_PERFORMANCE_THRESHOLDS = {
 
 function extractFrontmatterValue(markdown, key) {
   if (!markdown) return '';
-  const regex = new RegExp(`^-\\s*${key}:\\s*(.*)$`, 'im');
-  const match = String(markdown).match(regex);
-  return match ? String(match[1] || '').trim() : '';
+  // Try list-style first: "- key: value"
+  const listRegex = new RegExp(`^-\\s*${key}:\\s*(.*)$`, 'im');
+  const listMatch = String(markdown).match(listRegex);
+  if (listMatch) return String(listMatch[1] || '').trim();
+  // Fallback to pure YAML: "key: value"
+  const yamlRegex = new RegExp(`^${key}:\\s*(.*)$`, 'im');
+  const yamlMatch = String(markdown).match(yamlRegex);
+  return yamlMatch ? String(yamlMatch[1] || '').trim().replace(/^['"]|['"]$/g, '') : '';
 }
 
 function extractYamlValue(markdown, key) {
@@ -90,7 +95,7 @@ async function runQaInit({ args, options = {}, logger, t }) {
   }
 
   const projectName = String(contextData.project_name || path.basename(targetDir) || 'Project');
-  const language = String(contextData.conversation_language || 'en');
+  const language = getInteractionLanguage(contextData, 'en');
 
   // Parse prd.md for AC items
   const acItems = parseAcItems(prdContent);

package/src/commands/revision.js

@@ -0,0 +1,235 @@
+'use strict';
+
+/**
+ * aioson revision:open / revision:list / revision:resolve — Phase 2
+ *
+ * Usage:
+ *   aioson revision:open . --slug=feature-x --requested-by=analyst --target=product
+ *     --target-artifact=.aioson/context/prd-feature-x.md --reason="..." --severity=blocking
+ *   aioson revision:list . --slug=feature-x [--status=pending]
+ *   aioson revision:resolve . --rev-id=rev-001 --slug=feature-x --approve|--reject [--force-revision]
+ */
+
+const path = require('node:path');
+
+const revStore = require('../dossier/revision-store');
+const { isValidSlug } = require('../dossier/schema');
+
+function resolveContextDir(targetDir) {
+  return path.join(path.resolve(process.cwd(), targetDir || '.'), '.aioson', 'context');
+}
+
+function pickSlug(options) {
+  const raw = options.slug || options.feature;
+  return raw ? String(raw) : null;
+}
+
+async function runRevisionOpen({ args = [], options = {}, logger } = {}) {
+  const targetDir = args[0] || '.';
+  const slug = pickSlug(options);
+  const jsonOut = Boolean(options.json);
+  const log = (msg) => { if (logger && !jsonOut) logger.log(msg); };
+
+  if (!slug) {
+    if (jsonOut) return { ok: false, reason: 'missing_slug' };
+    log('--slug=<feature-slug> is required.');
+    return { ok: false };
+  }
+  if (!isValidSlug(slug)) {
+    if (jsonOut) return { ok: false, reason: 'invalid_slug', slug };
+    log(`Invalid slug "${slug}".`);
+    return { ok: false };
+  }
+
+  const requestedBy = options['requested-by'] || options.requestedBy;
+  const target = options.target;
+  const targetArtifact = options['target-artifact'] || options.targetArtifact;
+  const reason = options.reason;
+  const severity = options.severity || 'advisory';
+  const evidenceCodeRefs = options['evidence-code-refs']
+    ? String(options['evidence-code-refs']).split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
+
+  if (!requestedBy) {
+    if (jsonOut) return { ok: false, reason: 'missing_requested_by' };
+    log('--requested-by=<agent> is required.');
+    return { ok: false };
+  }
+  if (!target) {
+    if (jsonOut) return { ok: false, reason: 'missing_target' };
+    log('--target=<agent> is required.');
+    return { ok: false };
+  }
+  if (!targetArtifact) {
+    if (jsonOut) return { ok: false, reason: 'missing_target_artifact' };
+    log('--target-artifact=<path> is required.');
+    return { ok: false };
+  }
+  if (!reason) {
+    if (jsonOut) return { ok: false, reason: 'missing_reason' };
+    log('--reason="..." is required.');
+    return { ok: false };
+  }
+
+  const ctxDir = resolveContextDir(targetDir);
+
+  try {
+    const revision = await revStore.open({
+      slug,
+      contextDir: ctxDir,
+      requestedBy,
+      target,
+      targetArtifact,
+      reason,
+      severity,
+      evidenceCodeRefs
+    });
+
+    if (jsonOut) return { ok: true, slug, revision };
+    log(`Revision opened: ${revision.id}`);
+    log(`  slug: ${slug}`);
+    log(`  requested_by: ${revision.requested_by} → target: ${revision.target}`);
+    log(`  severity: ${revision.severity}   status: ${revision.status}`);
+    if (revision.severity === 'blocking') {
+      log(`  ⚠ Handoff will be blocked until resolved.`);
+      log(`  Resolve with: aioson revision:resolve . --slug=${slug} --rev-id=${revision.id} --approve|--reject`);
+    }
+    return { ok: true, slug, revision };
+  } catch (err) {
+    if (err && err.code === 'EREVAGENT') {
+      if (jsonOut) return { ok: false, reason: 'invalid_agent', message: err.message };
+      log(err.message);
+      return { ok: false };
+    }
+    if (err && err.code === 'EREVSCHEMA') {
+      if (jsonOut) return { ok: false, reason: 'schema_error', message: err.message };
+      log(err.message);
+      return { ok: false };
+    }
+    throw err;
+  }
+}
+
+async function runRevisionList({ args = [], options = {}, logger } = {}) {
+  const targetDir = args[0] || '.';
+  const slug = pickSlug(options);
+  const jsonOut = Boolean(options.json);
+  const log = (msg) => { if (logger && !jsonOut) logger.log(msg); };
+
+  if (!slug) {
+    if (jsonOut) return { ok: false, reason: 'missing_slug' };
+    log('--slug=<feature-slug> is required.');
+    return { ok: false };
+  }
+  if (!isValidSlug(slug)) {
+    if (jsonOut) return { ok: false, reason: 'invalid_slug', slug };
+    log(`Invalid slug "${slug}".`);
+    return { ok: false };
+  }
+
+  const filterStatus = options.status ? String(options.status) : null;
+  const ctxDir = resolveContextDir(targetDir);
+
+  const revisions = await revStore.list({ slug, contextDir: ctxDir, status: filterStatus });
+
+  if (jsonOut) return { ok: true, slug, revisions, count: revisions.length };
+
+  if (revisions.length === 0) {
+    log(`No revisions found for "${slug}"${filterStatus ? ` with status=${filterStatus}` : ''}.`);
+    return { ok: true, slug, revisions: [], count: 0 };
+  }
+
+  log(`Revisions for "${slug}"${filterStatus ? ` (status=${filterStatus})` : ''}:`);
+  for (const r of revisions) {
+    const flag = r.severity === 'blocking' ? '⚠' : '·';
+    log(`  ${flag} ${r.id}  ${r.status.padEnd(10)}  ${r.requested_by} → ${r.target}  [${r.severity}]`);
+    log(`      ${r.reason.slice(0, 80)}${r.reason.length > 80 ? '...' : ''}`);
+  }
+  return { ok: true, slug, revisions, count: revisions.length };
+}
+
+async function runRevisionResolve({ args = [], options = {}, logger } = {}) {
+  const targetDir = args[0] || '.';
+  const slug = pickSlug(options);
+  const revId = options['rev-id'] || options.revId;
+  const jsonOut = Boolean(options.json);
+  const forceRevision = Boolean(options['force-revision'] || options.forceRevision);
+  const log = (msg) => { if (logger && !jsonOut) logger.log(msg); };
+
+  if (!slug) {
+    if (jsonOut) return { ok: false, reason: 'missing_slug' };
+    log('--slug=<feature-slug> is required.');
+    return { ok: false };
+  }
+  if (!isValidSlug(slug)) {
+    if (jsonOut) return { ok: false, reason: 'invalid_slug', slug };
+    log(`Invalid slug "${slug}".`);
+    return { ok: false };
+  }
+  if (!revId) {
+    if (jsonOut) return { ok: false, reason: 'missing_rev_id' };
+    log('--rev-id=<rev-NNN> is required.');
+    return { ok: false };
+  }
+
+  const hasApprove = Boolean(options.approve);
+  const hasReject = Boolean(options.reject);
+  if (!hasApprove && !hasReject) {
+    if (jsonOut) return { ok: false, reason: 'missing_action' };
+    log('Either --approve or --reject is required.');
+    return { ok: false };
+  }
+  if (hasApprove && hasReject) {
+    if (jsonOut) return { ok: false, reason: 'conflicting_action' };
+    log('Cannot use --approve and --reject together.');
+    return { ok: false };
+  }
+
+  const action = hasApprove ? 'approve' : 'reject';
+  const ctxDir = resolveContextDir(targetDir);
+
+  try {
+    const { revision, gateIncremented } = await revStore.resolve({
+      slug,
+      contextDir: ctxDir,
+      revId,
+      action,
+      forceRevision
+    });
+
+    if (jsonOut) return { ok: true, slug, revision, gateIncremented };
+
+    if (action === 'reject') {
+      log(`Revision ${revId} rejected.`);
+      log(`  Blocking revisions (if any) removed — handoff may now proceed.`);
+    } else {
+      log(`Revision ${revId} approved.`);
+      if (gateIncremented) {
+        log(`  Gate '${gateIncremented.gate}' revision round: ${gateIncremented.rounds}/${revStore.MAX_REVISION_ROUNDS}`);
+      }
+      log(`  Re-run @${revision.target} with revision context:`);
+      log(`    aioson agent:prompt ${revision.target} . --revision-context=${revId}`);
+    }
+    return { ok: true, slug, revision, gateIncremented };
+  } catch (err) {
+    if (err && err.code === 'EREVNOTFOUND') {
+      if (jsonOut) return { ok: false, reason: 'not_found', revId };
+      log(err.message);
+      return { ok: false };
+    }
+    if (err && err.code === 'EREVNOTPENDING') {
+      if (jsonOut) return { ok: false, reason: 'not_pending', revId, status: err.status };
+      log(err.message);
+      return { ok: false };
+    }
+    if (err && err.code === 'EREVLOOP') {
+      if (jsonOut) return { ok: false, reason: 'anti_loop', gate: err.gate, rounds: err.rounds, max: revStore.MAX_REVISION_ROUNDS };
+      log(`Anti-loop: gate '${err.gate}' reached max revision rounds (${err.rounds}/${revStore.MAX_REVISION_ROUNDS}).`);
+      log(`  Use --force-revision to override.`);
+      return { ok: false };
+    }
+    throw err;
+  }
+}
+
+module.exports = { runRevisionOpen, runRevisionList, runRevisionResolve };