@jaimevalasek/aioson 1.33.1 → 1.37.0

package/src/commands/workflow-execute.js

@@ -27,6 +27,7 @@ const { readHandoff, readHandoffProtocol } = require('../session-handoff');
 const {
   STATE_RELATIVE_PATH,
   buildDefaultWorkflowConfig,
+  detectWorkflowMode,
   readWorkflowConfig,
   runWorkflowNext
 } = require('./workflow-next');
@@ -37,17 +38,17 @@ const {
   extractStatusWritePathItems
 } = require('../parallel-workspace');
 
-const BAR = '━'.repeat(45);
-const EXECUTION_STATE_RELATIVE_PATH = '.aioson/context/workflow-execute.json';
-const DEFAULT_AGENTIC_MAX_CYCLES = 3;
+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 },
   product: { description: 'Generate PRD', gate_before: null, gate_after: null },
-  analyst: { description: 'Map requirements + spec', gate_before: null, gate_after: 'A' },
-  architect: { description: 'Architecture design', gate_before: 'A', gate_after: 'B' },
-  'discovery-design-doc': { description: 'Prepare design-doc and readiness contract', gate_before: 'B', gate_after: null },
-  'ux-ui': { description: 'UI/UX design', gate_before: 'A', gate_after: 'B', optional: true },
+  analyst: { description: 'Map requirements + spec', gate_before: null, gate_after: 'A' },
+  architect: { description: 'Architecture design', gate_before: 'A', gate_after: 'B' },
+  'discovery-design-doc': { description: 'Prepare design-doc and readiness contract', gate_before: 'B', gate_after: null },
+  'ux-ui': { description: 'UI/UX design', gate_before: 'A', gate_after: 'B', optional: true },
   pm: { description: 'Backlog + PM plan', gate_before: 'B', gate_after: 'C' },
   orchestrator: { description: 'Coordinate execution lanes', gate_before: 'C', gate_after: null },
   dev: { description: 'Implementation', gate_before: null, gate_after: 'C' },
@@ -89,105 +90,120 @@ function normalizeClassification(value, fallback = 'SMALL') {
   return ['MICRO', 'SMALL', 'MEDIUM'].includes(safe) ? safe : fallback;
 }
 
-function normalizeAgentName(value) {
-  return String(value || '').trim().toLowerCase().replace(/^@/, '');
-}
-
-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 = []) {
+function normalizeAgentName(value) {
+  return String(value || '').trim().toLowerCase().replace(/^@/, '');
+}
+
+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' ||
+    // Seeding the scheme IS turning on autopilot — the whole point of --seed is to
+    // persist an enabled agentic_policy the interactive agents then follow.
+    options.seed ||
+    options['seed-only']
+  );
+}
+
+function buildAgenticPolicy(options = {}, classification = 'SMALL') {
+  // --seed --step: the per-feature "step by step" choice. Writes an explicitly
+  // DISARMED scheme — resolveAutopilotSignal and the agent triggers treat it as
+  // the feature-level override that wins over a project-wide auto_handoff: true.
+  if (options.step) {
+    return {
+      enabled: false,
+      mode: 'step_by_step',
+      source: 'workflow:execute --step'
+    };
+  }
+
+  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;
 }
@@ -229,6 +245,18 @@ function inferCompletedStagesFromArtifacts(sequence, artifacts, gates) {
       inferred = Boolean(artifacts.requirements && artifacts.requirements.exists && gates.requirements === 'approved');
     } else if (normalized === 'architect') {
       inferred = Boolean(artifacts.architecture && artifacts.architecture.exists && gates.design === 'approved');
+    } else if (normalized === 'sheldon' || normalized === 'orchestrator') {
+      // Single spec authorities (lean @sheldon / maestro @orchestrator) collapse
+      // Gates A/B/C into one hop — done once the spec package exists with the
+      // collapsed gates approved. Without this, a seed run AFTER the spec stage
+      // finished reported `next: sheldon|orchestrator` and pointed the whole
+      // agentic scheme backwards.
+      inferred = Boolean(
+        artifacts.spec && artifacts.spec.exists &&
+        gates.requirements === 'approved' &&
+        gates.design === 'approved' &&
+        gates.plan === 'approved'
+      );
     } else if (normalized === 'pm') {
       inferred = Boolean(artifacts.implementation_plan && artifacts.implementation_plan.exists && gates.plan === 'approved');
     } else if (normalized === 'qa') {
@@ -244,9 +272,17 @@ function inferCompletedStagesFromArtifacts(sequence, artifacts, gates) {
   return completed;
 }
 
-async function seedFeatureWorkflowState(targetDir, slug, classification, startFrom) {
-  const statePath = path.join(targetDir, STATE_RELATIVE_PATH);
-  const existing = await readJsonIfExists(statePath);
+/**
+ * Reads the persisted workflow state for a seed/preview of `slug`, applying the
+ * SAME staleness guard as loadOrCreateState: a state whose feature is no longer
+ * the features.md-active feature is stale and gets discarded (the loader would
+ * throw it away one command later anyway — hard-failing the seed on it just
+ * silently disarmed autopilot). The refusal survives only for a genuinely
+ * active different feature.
+ */
+async function resolveExistingFeatureState(targetDir, slug) {
+  const statePath = path.join(targetDir, STATE_RELATIVE_PATH);
+  let existing = await readJsonIfExists(statePath);
   const focusStage = getFocusStage(existing);
 
   if (
@@ -256,14 +292,41 @@ async function seedFeatureWorkflowState(targetDir, slug, classification, startFr
     existing.featureSlug !== slug &&
     focusStage
   ) {
-    return {
-      ok: false,
-      reason: 'different_active_feature',
-      active_feature: existing.featureSlug,
-      active_stage: focusStage
-    };
+    let modeInfo = null;
+    try {
+      modeInfo = await detectWorkflowMode(targetDir);
+    } catch {
+      modeInfo = null;
+    }
+    const existingIsActive = Boolean(
+      modeInfo && modeInfo.mode === 'feature' && modeInfo.featureSlug === existing.featureSlug
+    );
+    const requestedIsActive = Boolean(
+      modeInfo && modeInfo.mode === 'feature' && modeInfo.featureSlug === slug
+    );
+    if (!existingIsActive || requestedIsActive) {
+      existing = null; // stale pointer — reseed for the requested feature
+    } else {
+      return {
+        existing: null,
+        refusal: {
+          ok: false,
+          reason: 'different_active_feature',
+          active_feature: existing.featureSlug,
+          active_stage: focusStage
+        }
+      };
+    }
   }
 
+  return { existing, refusal: null };
+}
+
+async function seedFeatureWorkflowState(targetDir, slug, classification, startFrom) {
+  const statePath = path.join(targetDir, STATE_RELATIVE_PATH);
+  const { existing, refusal } = await resolveExistingFeatureState(targetDir, slug);
+  if (refusal) return refusal;
+
   if (existing && existing.mode === 'feature' && existing.featureSlug === slug) {
     return {
       ok: true,
@@ -301,141 +364,126 @@ async function seedFeatureWorkflowState(targetDir, slug, classification, startFr
     detour: null,
     updatedAt: new Date().toISOString()
   };
-
-  await writeJson(statePath, state);
-  return {
-    ok: true,
+
+  await writeJson(statePath, state);
+  return {
+    ok: true,
     resumed: false,
     state,
     statePath: STATE_RELATIVE_PATH
-  };
-}
-
-async function previewFeatureWorkflowState(targetDir, slug, classification, startFrom) {
-  const existing = await readJsonIfExists(path.join(targetDir, STATE_RELATIVE_PATH));
-  const focusStage = getFocusStage(existing);
-
-  if (
-    existing &&
-    existing.mode === 'feature' &&
-    existing.featureSlug &&
-    existing.featureSlug !== slug &&
-    focusStage
-  ) {
-    return {
-      ok: false,
-      reason: 'different_active_feature',
-      active_feature: existing.featureSlug,
-      active_stage: focusStage
-    };
-  }
-
-  if (existing && existing.mode === 'feature' && existing.featureSlug === slug) {
-    return {
-      ok: true,
-      resumed: true,
-      state: existing,
-      statePath: STATE_RELATIVE_PATH
-    };
-  }
-
-  const artifacts = await scanArtifacts(targetDir, slug);
-  const gates = await readPhaseGates(targetDir, slug);
-  const sequence = await resolveFeatureSequence(targetDir, classification);
-  const completed = inferCompletedStagesFromArtifacts(sequence, artifacts, gates);
-  const normalizedStartFrom = startFrom ? normalizeAgentName(startFrom) : null;
-
-  let skipped = [];
-  let next = findNextFromSequence(sequence, completed, skipped);
-
-  if (normalizedStartFrom && sequence.includes(normalizedStartFrom)) {
-    const targetIndex = sequence.indexOf(normalizedStartFrom);
-    skipped = sequence.slice(0, targetIndex).filter((stage) => !completed.includes(stage));
-    next = normalizedStartFrom;
-  }
-
-  return {
-    ok: true,
-    resumed: false,
-    state: {
-      version: 1,
-      mode: 'feature',
-      classification,
-      sequence,
-      current: null,
-      next,
-      completed,
-      skipped,
-      featureSlug: slug,
-      detour: null,
-      updatedAt: new Date().toISOString()
-    },
-    statePath: STATE_RELATIVE_PATH
-  };
-}
-
-function buildDryRunSuggestion(planData) {
-  const active = planData.steps.find((step) => step.status === 'active');
-  if (active) {
-    return {
-      action: active.predicted_blockers.length > 0 ? 'complete_stage' : 'continue_stage',
-      agent: active.agent,
-      command: `aioson workflow:next . --complete=${active.agent}`,
-      reason: `Preview stage @${active.agent}.`
-    };
-  }
-
-  const next = planData.steps.find((step) => step.status !== 'completed' && step.status !== 'skipped');
-  if (!next) {
-    return {
-      action: 'workflow_complete',
-      agent: null,
-      command: null,
-      reason: 'Preview workflow has no pending stage.'
-    };
-  }
-
-  return {
-    action: next.status === 'blocked' ? 'blocked' : 'activate_stage',
-    agent: next.agent,
-    command: `aioson workflow:next . --agent=${next.agent}`,
-    reason: next.status === 'blocked'
-      ? `Preview stage @${next.agent} is blocked.`
-      : `Preview next official stage is @${next.agent}.`
-  };
-}
-
-function buildDryRunArtifactsSummary(artifacts) {
-  return Object.entries(artifacts || {}).map(([id, artifact]) => ({
-    id,
-    label: artifact && artifact.path ? path.basename(artifact.path) : id,
-    file: artifact && artifact.path ? artifact.path : null,
-    exists: Boolean(artifact && artifact.exists)
-  }));
-}
-
-function buildDryRunStatusSnapshot({ targetDir, slug, classification, workflowState, planData, tool }) {
-  const suggestion = buildDryRunSuggestion(planData);
-  return {
-    ok: true,
-    projectName: path.basename(targetDir),
-    classification,
-    mode: 'feature',
-    featureSlug: slug,
-    tool,
-    state: workflowState,
-    stateCreated: false,
-    dryRun: true,
-    activeStage: workflowState.current || workflowState.next || null,
-    queuedNextStage: workflowState.next || null,
-    pendingGates: [],
-    contractCheck: null,
-    artifacts: buildDryRunArtifactsSummary(planData.artifacts),
-    suggestion
-  };
-}
-
-async function buildExecutionPlan(targetDir, slug, classification, workflowState = null, startFrom = null) {
+  };
+}
+
+async function previewFeatureWorkflowState(targetDir, slug, classification, startFrom) {
+  const { existing, refusal } = await resolveExistingFeatureState(targetDir, slug);
+  if (refusal) return refusal;
+
+  if (existing && existing.mode === 'feature' && existing.featureSlug === slug) {
+    return {
+      ok: true,
+      resumed: true,
+      state: existing,
+      statePath: STATE_RELATIVE_PATH
+    };
+  }
+
+  const artifacts = await scanArtifacts(targetDir, slug);
+  const gates = await readPhaseGates(targetDir, slug);
+  const sequence = await resolveFeatureSequence(targetDir, classification);
+  const completed = inferCompletedStagesFromArtifacts(sequence, artifacts, gates);
+  const normalizedStartFrom = startFrom ? normalizeAgentName(startFrom) : null;
+
+  let skipped = [];
+  let next = findNextFromSequence(sequence, completed, skipped);
+
+  if (normalizedStartFrom && sequence.includes(normalizedStartFrom)) {
+    const targetIndex = sequence.indexOf(normalizedStartFrom);
+    skipped = sequence.slice(0, targetIndex).filter((stage) => !completed.includes(stage));
+    next = normalizedStartFrom;
+  }
+
+  return {
+    ok: true,
+    resumed: false,
+    state: {
+      version: 1,
+      mode: 'feature',
+      classification,
+      sequence,
+      current: null,
+      next,
+      completed,
+      skipped,
+      featureSlug: slug,
+      detour: null,
+      updatedAt: new Date().toISOString()
+    },
+    statePath: STATE_RELATIVE_PATH
+  };
+}
+
+function buildDryRunSuggestion(planData) {
+  const active = planData.steps.find((step) => step.status === 'active');
+  if (active) {
+    return {
+      action: active.predicted_blockers.length > 0 ? 'complete_stage' : 'continue_stage',
+      agent: active.agent,
+      command: `aioson workflow:next . --complete=${active.agent}`,
+      reason: `Preview stage @${active.agent}.`
+    };
+  }
+
+  const next = planData.steps.find((step) => step.status !== 'completed' && step.status !== 'skipped');
+  if (!next) {
+    return {
+      action: 'workflow_complete',
+      agent: null,
+      command: null,
+      reason: 'Preview workflow has no pending stage.'
+    };
+  }
+
+  return {
+    action: next.status === 'blocked' ? 'blocked' : 'activate_stage',
+    agent: next.agent,
+    command: `aioson workflow:next . --agent=${next.agent}`,
+    reason: next.status === 'blocked'
+      ? `Preview stage @${next.agent} is blocked.`
+      : `Preview next official stage is @${next.agent}.`
+  };
+}
+
+function buildDryRunArtifactsSummary(artifacts) {
+  return Object.entries(artifacts || {}).map(([id, artifact]) => ({
+    id,
+    label: artifact && artifact.path ? path.basename(artifact.path) : id,
+    file: artifact && artifact.path ? artifact.path : null,
+    exists: Boolean(artifact && artifact.exists)
+  }));
+}
+
+function buildDryRunStatusSnapshot({ targetDir, slug, classification, workflowState, planData, tool }) {
+  const suggestion = buildDryRunSuggestion(planData);
+  return {
+    ok: true,
+    projectName: path.basename(targetDir),
+    classification,
+    mode: 'feature',
+    featureSlug: slug,
+    tool,
+    state: workflowState,
+    stateCreated: false,
+    dryRun: true,
+    activeStage: workflowState.current || workflowState.next || null,
+    queuedNextStage: workflowState.next || null,
+    pendingGates: [],
+    contractCheck: null,
+    artifacts: buildDryRunArtifactsSummary(planData.artifacts),
+    suggestion
+  };
+}
+
+async function buildExecutionPlan(targetDir, slug, classification, workflowState = null, startFrom = null) {
   const sequence = workflowState && Array.isArray(workflowState.sequence) && workflowState.sequence.length > 0
     ? [...workflowState.sequence]
     : await resolveFeatureSequence(targetDir, classification);
@@ -472,11 +520,11 @@ async function buildExecutionPlan(targetDir, slug, classification, workflowState
     else if (focusStage === agent) status = 'active';
 
     const predictedBlockers = [];
-    if (status !== 'completed' && status !== 'skipped' && meta.gate_before && !isGateApproved(gates, meta.gate_before)) {
-      const responsible = GATE_RESPONSIBLE_AGENT[meta.gate_before] || 'previous agent';
-      const featureArg = slug ? ` --feature=${quoteCliArg(slug)}` : '';
-      predictedBlockers.push(
-        `Gate ${meta.gate_before} (${GATE_NAMES[meta.gate_before] || meta.gate_before}) not approved — ` +
+    if (status !== 'completed' && status !== 'skipped' && meta.gate_before && !isGateApproved(gates, meta.gate_before)) {
+      const responsible = GATE_RESPONSIBLE_AGENT[meta.gate_before] || 'previous agent';
+      const featureArg = slug ? ` --feature=${quoteCliArg(slug)}` : '';
+      predictedBlockers.push(
+        `Gate ${meta.gate_before} (${GATE_NAMES[meta.gate_before] || meta.gate_before}) not approved — ` +
         `responsible: ${responsible} — ` +
         `approve with: aioson gate:approve .${featureArg} --gate=${meta.gate_before}`
       );
@@ -539,7 +587,11 @@ function buildCheckpointPayload(activation, handoff, handoffProtocol) {
 async function writeExecutionCheckpoint(targetDir, payload) {
   const execPath = path.join(targetDir, EXECUTION_STATE_RELATIVE_PATH);
   const existing = await readJsonIfExists(execPath);
-  const history = Array.isArray(existing && existing.history) ? [...existing.history] : [];
+  // History is per-feature: never carry a previous feature's checkpoints into
+  // a new feature's scheme.
+  const history = existing && existing.feature === payload.feature && Array.isArray(existing.history)
+    ? [...existing.history]
+    : [];
   if (payload.checkpoint) {
     history.push({
       at: new Date().toISOString(),
@@ -565,10 +617,10 @@ async function writeExecutionCheckpoint(targetDir, payload) {
     checkpoint: payload.checkpoint || null,
     status_snapshot: payload.statusSnapshot || null,
     suggestion: payload.suggestion || null,
-    resume_command: payload.resumeCommand || null,
-    agentic_policy: payload.agenticPolicy || null,
-    history
-  };
+    resume_command: payload.resumeCommand || null,
+    agentic_policy: payload.agenticPolicy || null,
+    history
+  };
   await writeJson(execPath, nextPayload);
   return nextPayload;
 }
@@ -702,6 +754,9 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
   const tool = options.tool ? String(options.tool).trim() : 'claude';
   const requestedMode = options.mode ? String(options.mode).trim() : null;
   const dryRun = Boolean(options['dry-run'] || options.dry);
+  // --step (disarm) is by definition record-only: it writes the disarmed scheme
+  // and never drives stage transitions, with or without an explicit --seed.
+  const seedOnly = Boolean(options.seed || options['seed-only'] || options.step);
   const startFrom = options['start-from'] ? String(options['start-from']).trim() : null;
   const skipOptional = Boolean(options['skip-optional']);
   const parsedMaxCheckpoints = Number.parseInt(String(options['max-checkpoints'] || '1'), 10);
@@ -718,11 +773,11 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
     return { ok: false };
   }
 
-  let classification = options.classification ? String(options.classification).toUpperCase() : null;
-  if (!classification) classification = await detectClassification(targetDir, slug);
-  if (!classification) classification = 'SMALL';
-  classification = normalizeClassification(classification, 'SMALL');
-  const agenticPolicy = buildAgenticPolicy(options, classification);
+  let classification = options.classification ? String(options.classification).toUpperCase() : null;
+  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);
@@ -756,9 +811,9 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
     }
   }
 
-  const seeded = dryRun
-    ? await previewFeatureWorkflowState(targetDir, slug, classification, startFrom)
-    : await seedFeatureWorkflowState(targetDir, slug, classification, startFrom);
+  const seeded = dryRun
+    ? await previewFeatureWorkflowState(targetDir, slug, classification, startFrom)
+    : await seedFeatureWorkflowState(targetDir, slug, classification, startFrom);
   if (!seeded.ok) {
     if (options.json) return seeded;
     logger.error(
@@ -781,28 +836,32 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
 
   const activePlan = planData.steps.filter((step) => step.status !== 'completed' && !(skipOptional && step.optional));
   const blockedSteps = planData.steps.filter((step) => step.predicted_blockers.length > 0);
-  const statusSnapshot = dryRun
-    ? buildDryRunStatusSnapshot({ targetDir, slug, classification, workflowState: seeded.state, planData, tool })
-    : await readStatusSnapshot(targetDir, tool, t);
-  const resumeCommand = [
-    'aioson',
-    'workflow:execute',
-    quoteCliArg(targetDir),
-    `--feature=${quoteCliArg(slug)}`,
-    `--tool=${quoteCliArg(tool)}`,
-    ...(requestedMode ? [`--mode=${quoteCliArg(requestedMode)}`] : []),
-    ...(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(' ');
+  const statusSnapshot = dryRun
+    ? buildDryRunStatusSnapshot({ targetDir, slug, classification, workflowState: seeded.state, planData, tool })
+    : await readStatusSnapshot(targetDir, tool, t);
+  const resumeCommand = [
+    'aioson',
+    'workflow:execute',
+    quoteCliArg(targetDir),
+    `--feature=${quoteCliArg(slug)}`,
+    `--tool=${quoteCliArg(tool)}`,
+    ...(requestedMode ? [`--mode=${quoteCliArg(requestedMode)}`] : []),
+    ...(maxCheckpoints !== 1 ? [`--max-checkpoints=${quoteCliArg(maxCheckpoints)}`] : []),
+    // A seed run must resume as a seed run — `--agentic` (the CLI-advancing
+    // runner) is the opposite of the seed-only contract. A disarm run keeps
+    // its --step so replaying it never re-arms the scheme.
+    ...(seedOnly ? ['--seed'] : agenticPolicy && agenticPolicy.enabled ? ['--agentic'] : []),
+    ...(options.step ? ['--step'] : []),
+    ...(agenticPolicy && agenticPolicy.review_cycle && 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 && 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 && 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) {
     const result = {
@@ -821,11 +880,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,
-      agentic_policy: agenticPolicy,
-      parallel_guard: parallelGuard
-    };
+      suggestion: statusSnapshot && statusSnapshot.suggestion ? statusSnapshot.suggestion : null,
+      resume_command: resumeCommand,
+      agentic_policy: agenticPolicy,
+      parallel_guard: parallelGuard
+    };
 
     if (options.json) return result;
 
@@ -844,14 +903,73 @@ 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}`);
-    }
-    for (const line of formatAgenticPolicyLines(agenticPolicy)) {
-      logger.log(line);
-    }
-    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;
+  }
+
+  // --seed: persist the workflow.state.json + workflow-execute.json (with an
+  // enabled agentic_policy) and STOP. Unlike a full run, it does not drive stage
+  // transitions from the CLI — in an interactive Claude Code session the agents
+  // themselves follow the scheme. This is what the spec->dev handoff calls so a
+  // feature built the normal way carries the autopilot contract without the user
+  // running anything. Idempotent: re-seeding the same slug reuses existing state.
+  if (seedOnly) {
+    const handoff = await readHandoff(targetDir);
+    const handoffProtocol = await readHandoffProtocol(targetDir);
+    const nextStage = seeded.state ? (seeded.state.current || seeded.state.next || null) : null;
+    const executionState = await writeExecutionCheckpoint(targetDir, {
+      feature: slug,
+      classification,
+      tool,
+      requestedMode,
+      resumed: seeded.resumed,
+      status: nextStage ? 'active' : 'completed',
+      checkpoint: buildCheckpointPayload(null, handoff, handoffProtocol),
+      statusSnapshot,
+      suggestion: statusSnapshot && statusSnapshot.suggestion ? statusSnapshot.suggestion : null,
+      resumeCommand,
+      agenticPolicy
+    });
+
+    const result = {
+      ok: true,
+      feature: slug,
+      classification,
+      tool,
+      requested_mode: requestedMode,
+      seeded: true,
+      resumed: seeded.resumed,
+      state_path: seeded.statePath,
+      execution_state_path: EXECUTION_STATE_RELATIVE_PATH,
+      next_stage: nextStage,
+      checkpoint: executionState.checkpoint,
+      execution_state: executionState,
+      status_snapshot: statusSnapshot,
+      suggestion: statusSnapshot && statusSnapshot.suggestion ? statusSnapshot.suggestion : null,
+      resume_command: resumeCommand,
+      agentic_policy: agenticPolicy,
+      parallel_guard: parallelGuard
+    };
+
+    if (options.json) return result;
+
+    logger.log('');
+    logger.log(`Agentic workflow scheme seeded → ${EXECUTION_STATE_RELATIVE_PATH}`);
+    logger.log(`Feature: ${slug} (${classification})   Next stage: @${nextStage || 'none'}`);
+    logger.log(
+      `Autopilot: ${agenticPolicy && agenticPolicy.enabled
+        ? 'enabled — interactive agents run the chain to feature:close (human gate)'
+        : 'disabled'}`
+    );
+    for (const line of formatAgenticPolicyLines(agenticPolicy)) logger.log(line);
+    logger.log('');
+    return result;
   }
 
   const executionTransitions = [];
@@ -931,11 +1049,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,
-    agenticPolicy
-  });
+    statusSnapshot: refreshedStatus,
+    suggestion: refreshedStatus && refreshedStatus.suggestion ? refreshedStatus.suggestion : null,
+    resumeCommand,
+    agenticPolicy
+  });
 
   const result = {
     ok: true,
@@ -950,10 +1068,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,
-    agentic_policy: agenticPolicy,
-    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,
@@ -971,10 +1089,10 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
   return result;
 }
 
-module.exports = {
-  EXECUTION_STATE_RELATIVE_PATH,
-  buildAgenticPolicy,
-  buildExecutionPlan,
-  seedFeatureWorkflowState,
-  runWorkflowExecute
-};
+module.exports = {
+  EXECUTION_STATE_RELATIVE_PATH,
+  buildAgenticPolicy,
+  buildExecutionPlan,
+  seedFeatureWorkflowState,
+  runWorkflowExecute
+};