@jaimevalasek/aioson 1.23.0 → 1.23.1

package/src/commands/preflight-context.js

@@ -4,10 +4,11 @@
  * 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
+ *   aioson preflight:context . --agent=dev
+ *   aioson preflight:context . --agent=orchestrator --squad=content-team
+ *   aioson preflight:context . --agent=dev --mode=executing --task="create command" --paths=src/commands/foo.js
+ *   aioson preflight:context . --agent=dev --verbose
+ *   aioson preflight:context . --agent=dev --json
  */
 
 const path = require('node:path');
@@ -15,11 +16,14 @@ 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 });
+  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 mode = String(options.mode || 'planning').trim();
+  const task = String(options.task || options.goal || '').trim();
+  const paths = String(options.paths || options.path || '').trim();
+
+  const result = await estimateContext(targetDir, { agent, squad, verbose, mode, task, paths });
 
   if (options.json) return result;
 

package/src/commands/review-cycle.js

@@ -0,0 +1,328 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { ensureDir, exists } = require('../utils');
+
+const DEFAULT_MAX_CYCLES = 3;
+const EXECUTION_STATE_RELATIVE_PATH = '.aioson/context/workflow-execute.json';
+
+function resolveTargetDir(args) {
+  return path.resolve(process.cwd(), args[0] || '.');
+}
+
+function normalizeAgent(value, fallback) {
+  const normalized = String(value || fallback || '')
+    .trim()
+    .toLowerCase()
+    .replace(/^@/, '')
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return normalized || fallback;
+}
+
+function stateFileName(source, target) {
+  if (source === 'qa' && target === 'dev') return 'qa-dev-cycle.json';
+  return `review-cycle-${source}-${target}.json`;
+}
+
+function resolveStatePath(targetDir, source, target) {
+  return path.join(targetDir, '.aioson', 'runtime', stateFileName(source, target));
+}
+
+async function readJsonIfExists(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function writeJson(filePath, payload) {
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+function parseMax(value, fallback = DEFAULT_MAX_CYCLES) {
+  const parsed = Number.parseInt(String(value || ''), 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) return fallback;
+  return Math.max(1, Math.min(parsed, 10));
+}
+
+async function readAgenticPolicy(targetDir) {
+  const payload = await readJsonIfExists(path.join(targetDir, EXECUTION_STATE_RELATIVE_PATH));
+  return payload && payload.agentic_policy && payload.agentic_policy.enabled
+    ? payload.agentic_policy
+    : null;
+}
+
+async function resolveMaxCycles(targetDir, source, options = {}) {
+  const explicit = options['max-cycles'] || options.maxCycles;
+  if (explicit) return parseMax(explicit);
+
+  const policy = await readAgenticPolicy(targetDir);
+  const review = policy && policy.review_cycle ? policy.review_cycle : null;
+  if (!review) return DEFAULT_MAX_CYCLES;
+
+  if (source === 'qa') return parseMax(review.max_dev_qa_cycles, DEFAULT_MAX_CYCLES);
+  if (source === 'tester') return parseMax(review.max_tester_correction_cycles, DEFAULT_MAX_CYCLES);
+  if (source === 'pentester') return parseMax(review.max_pentester_correction_cycles, DEFAULT_MAX_CYCLES);
+  return DEFAULT_MAX_CYCLES;
+}
+
+function resolveSafeProjectPath(targetDir, filePath) {
+  if (!filePath) return null;
+  const absolute = path.isAbsolute(filePath) ? filePath : path.resolve(targetDir, filePath);
+  const relative = path.relative(targetDir, absolute);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) return null;
+  return absolute;
+}
+
+async function updatePlanStatus(targetDir, planPath, status) {
+  const absolute = resolveSafeProjectPath(targetDir, planPath);
+  if (!absolute || !(await exists(absolute))) {
+    return { ok: false, reason: 'plan_not_found' };
+  }
+
+  const relativePath = path.relative(targetDir, absolute).replace(/\\/g, '/');
+  const extension = path.extname(absolute).toLowerCase();
+  if (extension && extension !== '.md' && extension !== '.markdown') {
+    return {
+      ok: true,
+      skipped: true,
+      reason: 'non_markdown_plan',
+      path: relativePath,
+      status
+    };
+  }
+
+  const raw = await fs.readFile(absolute, 'utf8');
+  let next;
+  if (/^---\r?\n/.test(raw)) {
+    const endMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (endMatch) {
+      const frontmatter = endMatch[1];
+      const rest = raw.slice(endMatch[0].length);
+      const lines = frontmatter.split(/\r?\n/);
+      let found = false;
+      const updated = lines.map((line) => {
+        if (/^status\s*:/i.test(line)) {
+          found = true;
+          return `status: ${status}`;
+        }
+        return line;
+      });
+      if (!found) updated.push(`status: ${status}`);
+      next = `---\n${updated.join('\n')}\n---${rest}`;
+    }
+  }
+
+  if (!next) {
+    next = `---\nstatus: ${status}\n---\n\n${raw}`;
+  }
+
+  await fs.writeFile(absolute, next, 'utf8');
+  return {
+    ok: true,
+    path: relativePath,
+    status
+  };
+}
+
+function buildNextTask({ source, planPath }) {
+  if (source === 'qa') return `apply mandatory corrections from ${planPath}`;
+  if (source === 'tester') return `apply test-engineering corrections from ${planPath}`;
+  if (source === 'pentester') return `fix security findings from ${planPath}`;
+  return `apply review corrections from ${planPath}`;
+}
+
+async function readStatus(targetDir, source, target, options = {}) {
+  const statePath = resolveStatePath(targetDir, source, target);
+  const state = await readJsonIfExists(statePath);
+  const maxCycles = await resolveMaxCycles(targetDir, source, options);
+  return {
+    ok: true,
+    source,
+    target,
+    path: path.relative(targetDir, statePath).replace(/\\/g, '/'),
+    exists: Boolean(state),
+    max_cycles: maxCycles,
+    remaining_cycles: Math.max(0, maxCycles - Number(state?.cycle || 0)),
+    state
+  };
+}
+
+async function runAdvance(targetDir, source, target, options = {}) {
+  const feature = options.feature ? String(options.feature).trim() : null;
+  const planPath = options.plan ? String(options.plan).trim() : null;
+  const criticalSecurity = Boolean(options['critical-security'] || options.criticalSecurity);
+  const maxCycles = await resolveMaxCycles(targetDir, source, options);
+  const statePath = resolveStatePath(targetDir, source, target);
+
+  if (!feature) return { ok: false, reason: 'missing_feature' };
+  if (!planPath) return { ok: false, reason: 'missing_plan' };
+
+  if (criticalSecurity) {
+    return {
+      ok: true,
+      action: 'human_gate',
+      reason: 'critical_security',
+      feature,
+      source,
+      target,
+      max_cycles: maxCycles,
+      next_agent: null,
+      plan: planPath
+    };
+  }
+
+  const existing = await readJsonIfExists(statePath);
+  const sameFeature = existing && existing.slug === feature;
+  const currentCycle = sameFeature ? Number(existing.cycle || 0) : 0;
+
+  if (currentCycle >= maxCycles) {
+    try { await fs.unlink(statePath); } catch { /* absent is fine */ }
+    return {
+      ok: true,
+      action: 'stop_cycle_limit',
+      reason: 'cycle_limit_reached',
+      feature,
+      source,
+      target,
+      cycle: currentCycle,
+      max_cycles: maxCycles,
+      next_agent: null,
+      plan: planPath
+    };
+  }
+
+  const now = new Date().toISOString();
+  const nextCycle = currentCycle + 1;
+  const state = {
+    slug: feature,
+    source,
+    target,
+    cycle: nextCycle,
+    max_cycles: maxCycles,
+    status: 'open',
+    started_at: sameFeature && existing.started_at ? existing.started_at : now,
+    updated_at: now,
+    last_plan: planPath,
+    last_summary: options.summary ? String(options.summary).trim() : null
+  };
+
+  await writeJson(statePath, state);
+
+  return {
+    ok: true,
+    action: `invoke_${target}`,
+    feature,
+    source,
+    target,
+    next_agent: target,
+    cycle: nextCycle,
+    max_cycles: maxCycles,
+    remaining_cycles: Math.max(0, maxCycles - nextCycle),
+    plan: planPath,
+    task: buildNextTask({ source, planPath }),
+    state_path: path.relative(targetDir, statePath).replace(/\\/g, '/'),
+    state
+  };
+}
+
+async function runResolve(targetDir, source, target, options = {}) {
+  const feature = options.feature ? String(options.feature).trim() : null;
+  const planPath = options.plan ? String(options.plan).trim() : null;
+  const statePath = resolveStatePath(targetDir, source, target);
+  const existing = await readJsonIfExists(statePath);
+
+  if (!feature) return { ok: false, reason: 'missing_feature' };
+  if (!existing || existing.slug !== feature) {
+    return { ok: true, action: 'no_active_cycle', feature, source, target, next_agent: 'qa' };
+  }
+
+  let planUpdate = null;
+  if (planPath) {
+    planUpdate = await updatePlanStatus(targetDir, planPath, 'resolved');
+  }
+
+  const now = new Date().toISOString();
+  const state = {
+    ...existing,
+    status: 'resolved',
+    resolved_at: now,
+    updated_at: now,
+    resolved_plan: planPath || existing.last_plan || null
+  };
+  await writeJson(statePath, state);
+
+  return {
+    ok: true,
+    action: 'invoke_qa',
+    feature,
+    source,
+    target,
+    next_agent: 'qa',
+    state_path: path.relative(targetDir, statePath).replace(/\\/g, '/'),
+    plan_update: planUpdate,
+    state
+  };
+}
+
+async function runReset(targetDir, source, target, options = {}) {
+  const statePath = resolveStatePath(targetDir, source, target);
+  const existed = await exists(statePath);
+  if (existed) {
+    await fs.unlink(statePath);
+  }
+  return {
+    ok: true,
+    action: 'reset',
+    source,
+    target,
+    feature: options.feature ? String(options.feature).trim() : null,
+    removed: existed,
+    path: path.relative(targetDir, statePath).replace(/\\/g, '/')
+  };
+}
+
+async function runReviewCycle({ args, options = {}, logger }) {
+  const targetDir = resolveTargetDir(args);
+  const action = normalizeAgent(options.sub || options.action || 'status', 'status');
+  const source = normalizeAgent(options.source || options.agent, 'qa');
+  const target = normalizeAgent(options.to || options.target, 'dev');
+  let result;
+
+  if (action === 'status') {
+    result = await readStatus(targetDir, source, target, options);
+  } else if (action === 'advance' || action === 'start') {
+    result = await runAdvance(targetDir, source, target, options);
+  } else if (action === 'resolve') {
+    result = await runResolve(targetDir, source, target, options);
+  } else if (action === 'reset') {
+    result = await runReset(targetDir, source, target, options);
+  } else {
+    result = { ok: false, reason: 'unknown_review_cycle_action', action };
+  }
+
+  if (options.json) return result;
+
+  if (!result.ok) {
+    logger.error(`review-cycle:${action} failed: ${result.reason || 'unknown'}`);
+    return result;
+  }
+
+  logger.log(`review-cycle:${action} — ${result.action || 'status'}`);
+  if (result.feature) logger.log(`  feature: ${result.feature}`);
+  logger.log(`  route: @${source} -> @${target}`);
+  if (result.cycle !== undefined) logger.log(`  cycle: ${result.cycle}/${result.max_cycles}`);
+  if (result.next_agent) logger.log(`  next: @${result.next_agent}`);
+  if (result.task) logger.log(`  task: ${result.task}`);
+  return result;
+}
+
+module.exports = {
+  DEFAULT_MAX_CYCLES,
+  resolveStatePath,
+  runReviewCycle
+};

package/src/commands/runtime.js

@@ -1224,7 +1224,7 @@ async function runAgentDone({ args, options = {}, logger, t }) {
       }
 
       // F2 (workflow-handoff-integrity v1.9.5) — best-effort auto-advance workflow pointer
-      await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
+      const autoAdvance = await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
 
       if (isDocCreatingAgent(normalizedAgent)) {
         backupAiosonDocs(targetDir).catch(() => {});
@@ -1252,7 +1252,7 @@ async function runAgentDone({ args, options = {}, logger, t }) {
         });
       } catch { /* ignore — never blocks agent_done */ }
 
-      return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'live_event', runKey: session.runKey };
+      return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'live_event', runKey: session.runKey, auto_advance: autoAdvance };
     }
 
     // No active session — create a standalone task+run and immediately complete it.
@@ -1297,7 +1297,7 @@ async function runAgentDone({ args, options = {}, logger, t }) {
     }
 
     // F2 (workflow-handoff-integrity v1.9.5) — best-effort auto-advance workflow pointer
-    await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
+    const autoAdvance = await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
 
     if (isDocCreatingAgent(normalizedAgent)) {
       backupAiosonDocs(targetDir).catch(() => {});
@@ -1325,7 +1325,7 @@ async function runAgentDone({ args, options = {}, logger, t }) {
       });
     } catch { /* ignore — never blocks agent_done */ }
 
-    return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'standalone', runKey, taskKey };
+    return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'standalone', runKey, taskKey, auto_advance: autoAdvance };
   } finally {
     db.close();
   }

package/src/commands/state-save.js

@@ -28,6 +28,7 @@
  *   sheldon      → sheldon-enrichment-{slug}.md
  *   design-doc   → design-doc-{slug}.md (falls back to design-doc.md)
  *   readiness    → readiness-{slug}.md (falls back to readiness.md)
+ *   ui-spec      → ui-spec.md
  *   dossier      → features/{slug}/dossier.md
  *   simple-plan  → simple-plans/{slug}.md
  *
@@ -50,6 +51,7 @@ const CONTEXT_TYPE_MAP = {
   sheldon:       { rel: (slug) => `sheldon-enrichment-${slug}.md` },
   'design-doc':  { rel: (slug) => `design-doc-${slug}.md`, fallback: () => 'design-doc.md' },
   readiness:     { rel: (slug) => `readiness-${slug}.md`, fallback: () => 'readiness.md' },
+  'ui-spec':      { rel: () => 'ui-spec.md' },
   dossier:       { rel: (slug) => `features/${slug}/dossier.md` },
   'simple-plan': { rel: (slug) => `simple-plans/${slug}.md` }
 };

package/src/commands/workflow-execute.js

@@ -37,8 +37,9 @@ const {
   extractStatusWritePathItems
 } = require('../parallel-workspace');
 
-const BAR = '━'.repeat(45);
-const EXECUTION_STATE_RELATIVE_PATH = '.aioson/context/workflow-execute.json';
+const BAR = '━'.repeat(45);
+const EXECUTION_STATE_RELATIVE_PATH = '.aioson/context/workflow-execute.json';
+const DEFAULT_AGENTIC_MAX_CYCLES = 3;
 
 const STEP_META = {
   setup: { description: 'Initialize project context', gate_before: null, gate_after: null },
@@ -96,6 +97,96 @@ function quoteCliArg(value) {
   return `'${String(value || '').replace(/'/g, "'\\''")}'`;
 }
 
+function parsePositiveIntegerOption(value, fallback, min = 1, max = 10) {
+  const parsed = Number.parseInt(String(value || ''), 10);
+  if (!Number.isInteger(parsed)) return fallback;
+  if (parsed < min) return min;
+  if (parsed > max) return max;
+  return parsed;
+}
+
+function isAgenticRequested(options = {}) {
+  return Boolean(
+    options.agentic ||
+    options['agentic-run'] ||
+    options.autopilot === 'agentic' ||
+    options.autopilot === 'runtime'
+  );
+}
+
+function buildAgenticPolicy(options = {}, classification = 'SMALL') {
+  const enabled = isAgenticRequested(options);
+  if (!enabled) return null;
+
+  const maxDevQaCycles = parsePositiveIntegerOption(
+    options['max-dev-qa-cycles'] || options.maxDevQaCycles || options['max-cycles'],
+    DEFAULT_AGENTIC_MAX_CYCLES
+  );
+  const maxTesterCycles = parsePositiveIntegerOption(
+    options['max-tester-cycles'] || options.maxTesterCycles || options['max-specialist-cycles'],
+    DEFAULT_AGENTIC_MAX_CYCLES
+  );
+  const maxPentesterCycles = parsePositiveIntegerOption(
+    options['max-pentester-cycles'] || options.maxPentesterCycles || options['max-specialist-cycles'],
+    DEFAULT_AGENTIC_MAX_CYCLES
+  );
+
+  return {
+    enabled: true,
+    mode: 'runtime_policy',
+    source: 'workflow:execute',
+    stop_conditions: [
+      'feature_status_done',
+      'human_decision_required',
+      'gate_blocked',
+      'context_budget_exceeded',
+      'cycle_limit_reached',
+      'critical_security_human_gate',
+      'feature_close_human_gate'
+    ],
+    review_cycle: {
+      hub: 'qa',
+      max_dev_qa_cycles: maxDevQaCycles,
+      max_tester_correction_cycles: maxTesterCycles,
+      max_pentester_correction_cycles: maxPentesterCycles,
+      qa_fail_route: 'dev',
+      tester_route: 'tester after qa coverage trigger',
+      pentester_route: 'pentester after sensitive-surface trigger or MEDIUM sequence stage',
+      validator_route: 'validator when harness contract is present',
+      feature_close: 'human_gate'
+    },
+    lanes: {
+      enabled: classification === 'MEDIUM',
+      strategy: 'parallelize_only_independent_write_scopes',
+      guard_command: 'aioson parallel:guard . --lane=<n>',
+      conflict_action: 'block_lane'
+    },
+    sidecars: {
+      scouts: {
+        enabled: true,
+        read_only: true,
+        max_per_session: 3,
+        max_files_in_scope: 20,
+        allowed_parent_agents: ['deyvin', 'dev', 'product', 'briefing', 'orache']
+      },
+      research: {
+        enabled: true,
+        cache_dir: 'researchs/',
+        cache_ttl_days: 7
+      }
+    }
+  };
+}
+
+function formatAgenticPolicyLines(policy) {
+  if (!policy || !policy.enabled) return [];
+  return [
+    `Agentic policy: enabled (dev<->qa max ${policy.review_cycle.max_dev_qa_cycles} cycles)`,
+    `Review loop: qa fail -> dev; tester max ${policy.review_cycle.max_tester_correction_cycles}; pentester max ${policy.review_cycle.max_pentester_correction_cycles}; close=${policy.review_cycle.feature_close}`,
+    `Parallel lanes: ${policy.lanes.enabled ? 'enabled for independent write scopes' : 'disabled for this classification'}`
+  ];
+}
+
 function findNextFromSequence(sequence, completed, skipped = []) {
   const done = new Set([...(completed || []), ...(skipped || [])].map(normalizeAgentName));
   return sequence.find((stage) => !done.has(normalizeAgentName(stage))) || null;
@@ -474,9 +565,10 @@ async function writeExecutionCheckpoint(targetDir, payload) {
     checkpoint: payload.checkpoint || null,
     status_snapshot: payload.statusSnapshot || null,
     suggestion: payload.suggestion || null,
-    resume_command: payload.resumeCommand || null,
-    history
-  };
+    resume_command: payload.resumeCommand || null,
+    agentic_policy: payload.agenticPolicy || null,
+    history
+  };
   await writeJson(execPath, nextPayload);
   return nextPayload;
 }
@@ -630,6 +722,7 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
   if (!classification) classification = await detectClassification(targetDir, slug);
   if (!classification) classification = 'SMALL';
   classification = normalizeClassification(classification, 'SMALL');
+  const agenticPolicy = buildAgenticPolicy(options, classification);
 
   const autonomyProtocol = await readAutonomyProtocol(targetDir);
   const toolPolicy = getToolPolicy(autonomyProtocol, tool);
@@ -698,7 +791,17 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
     `--feature=${quoteCliArg(slug)}`,
     `--tool=${quoteCliArg(tool)}`,
     ...(requestedMode ? [`--mode=${quoteCliArg(requestedMode)}`] : []),
-    ...(maxCheckpoints !== 1 ? [`--max-checkpoints=${quoteCliArg(maxCheckpoints)}`] : [])
+    ...(maxCheckpoints !== 1 ? [`--max-checkpoints=${quoteCliArg(maxCheckpoints)}`] : []),
+    ...(agenticPolicy ? ['--agentic'] : []),
+    ...(agenticPolicy && agenticPolicy.review_cycle.max_dev_qa_cycles !== DEFAULT_AGENTIC_MAX_CYCLES
+      ? [`--max-dev-qa-cycles=${quoteCliArg(agenticPolicy.review_cycle.max_dev_qa_cycles)}`]
+      : []),
+    ...(agenticPolicy && agenticPolicy.review_cycle.max_tester_correction_cycles !== DEFAULT_AGENTIC_MAX_CYCLES
+      ? [`--max-tester-cycles=${quoteCliArg(agenticPolicy.review_cycle.max_tester_correction_cycles)}`]
+      : []),
+    ...(agenticPolicy && agenticPolicy.review_cycle.max_pentester_correction_cycles !== DEFAULT_AGENTIC_MAX_CYCLES
+      ? [`--max-pentester-cycles=${quoteCliArg(agenticPolicy.review_cycle.max_pentester_correction_cycles)}`]
+      : [])
   ].join(' ');
 
   if (dryRun) {
@@ -718,10 +821,11 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
       blocked_steps: blockedSteps.length,
       gates: planData.gates,
       status_snapshot: statusSnapshot,
-      suggestion: statusSnapshot && statusSnapshot.suggestion ? statusSnapshot.suggestion : null,
-      resume_command: resumeCommand,
-      parallel_guard: parallelGuard
-    };
+      suggestion: statusSnapshot && statusSnapshot.suggestion ? statusSnapshot.suggestion : null,
+      resume_command: resumeCommand,
+      agentic_policy: agenticPolicy,
+      parallel_guard: parallelGuard
+    };
 
     if (options.json) return result;
 
@@ -740,11 +844,14 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
     logger.log('');
     logger.log(`Blocked steps: ${blockedSteps.length} | Remaining: ${activePlan.length}`);
     logger.log(`Resume state: ${seeded.resumed ? 'existing workflow state reused' : 'new workflow state seeded'}`);
-    if (statusSnapshot && statusSnapshot.suggestion && statusSnapshot.suggestion.command) {
-      logger.log(`Suggested command: ${statusSnapshot.suggestion.command}`);
-    }
-    logger.log('');
-    return result;
+    if (statusSnapshot && statusSnapshot.suggestion && statusSnapshot.suggestion.command) {
+      logger.log(`Suggested command: ${statusSnapshot.suggestion.command}`);
+    }
+    for (const line of formatAgenticPolicyLines(agenticPolicy)) {
+      logger.log(line);
+    }
+    logger.log('');
+    return result;
   }
 
   const executionTransitions = [];
@@ -824,10 +931,11 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
     resumed: seeded.resumed,
     status: activation && activation.agent ? 'active' : 'completed',
     checkpoint: buildCheckpointPayload(activation, handoff, handoffProtocol),
-    statusSnapshot: refreshedStatus,
-    suggestion: refreshedStatus && refreshedStatus.suggestion ? refreshedStatus.suggestion : null,
-    resumeCommand
-  });
+    statusSnapshot: refreshedStatus,
+    suggestion: refreshedStatus && refreshedStatus.suggestion ? refreshedStatus.suggestion : null,
+    resumeCommand,
+    agenticPolicy
+  });
 
   const result = {
     ok: true,
@@ -842,9 +950,10 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
     checkpoint: executionState.checkpoint,
     execution_state: executionState,
     status_snapshot: refreshedStatus,
-    suggestion: refreshedStatus && refreshedStatus.suggestion ? refreshedStatus.suggestion : null,
-    resume_command: resumeCommand,
-    transitions: executionTransitions,
+    suggestion: refreshedStatus && refreshedStatus.suggestion ? refreshedStatus.suggestion : null,
+    resume_command: resumeCommand,
+    agentic_policy: agenticPolicy,
+    transitions: executionTransitions,
     active_stage: activation && activation.agent ? activation.agent : null,
     next_stage: activation && activation.next ? activation.next : null,
     handoff,
@@ -862,9 +971,10 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
   return result;
 }
 
-module.exports = {
-  EXECUTION_STATE_RELATIVE_PATH,
-  buildExecutionPlan,
-  seedFeatureWorkflowState,
-  runWorkflowExecute
-};
+module.exports = {
+  EXECUTION_STATE_RELATIVE_PATH,
+  buildAgenticPolicy,
+  buildExecutionPlan,
+  seedFeatureWorkflowState,
+  runWorkflowExecute
+};

package/src/commands/workflow-next.js

@@ -41,8 +41,9 @@ const DEFAULT_FEATURE_WORKFLOW_BY_CLASSIFICATION = {
 
 // Stages eligible for autopilot handoff (auto_handoff: true in project.context.md).
 // Two segments — see .aioson/docs/autopilot-handoff.md:
-//   1. analyst → dev: deterministic pre-dev chain; STOPS before the first @dev entry
-//      (human clears context and starts implementation).
+//   1. analyst -> dev: deterministic pre-dev chain. Prompt-only clients stop
+//      before the first @dev entry; workflow:execute --agentic may resume it
+//      through a fresh checkpointed activation.
 //   2. post-dev review cycle: @dev → @qa → @tester/@pentester (when their @qa triggers
 //      fire) → @validator → STOPS before feature:close (human approves the close).
 const AUTOPILOT_HANDOFF_STAGES = new Set([