@jaimevalasek/aioson 1.21.7 → 1.22.0

package/src/commands/workflow-next.js

@@ -26,16 +26,24 @@ const { emitDossierEvent } = require('../lib/dossier-telemetry');
 
 const STATE_RELATIVE_PATH = '.aioson/context/workflow.state.json';
 const CONFIG_RELATIVE_PATH = '.aioson/context/workflow.config.json';
-const EVENTS_RELATIVE_PATH = '.aioson/context/workflow.events.jsonl';
-const SCOPE_CHECK_MODES = new Set(['pre-dev', 'post-dev', 'post-fix', 'final']);
+const EVENTS_RELATIVE_PATH = '.aioson/context/workflow.events.jsonl';
+const SCOPE_CHECK_MODES = new Set(['pre-dev', 'post-dev', 'post-fix', 'final']);
+
+const DEFAULT_FEATURE_WORKFLOW_BY_CLASSIFICATION = {
+  MICRO: ['product', 'dev', 'qa'],
+  SMALL: ['product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'dev', 'qa'],
+  // MEDIUM routes through @pm after discovery-design-doc (mirrors the
+  // project-mode position): Gate C requires implementation-plan-{slug}.md and
+  // @pm is its canonical owner (AC-SDLC-15/16) — without the stage, the
+  // sequence dead-ends at @dev preflight with no agent to produce the plan.
+  MEDIUM: ['product', 'analyst', 'architect', 'discovery-design-doc', 'pm', 'scope-check', 'dev', 'pentester', 'qa']
+};
 
-const DEFAULT_FEATURE_WORKFLOW_BY_CLASSIFICATION = {
-  MICRO: ['product', 'dev', 'qa'],
-  SMALL: ['product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'dev', 'qa'],
-  MEDIUM: ['product', 'analyst', 'architect', 'discovery-design-doc', 'scope-check', 'dev', 'pentester', 'qa']
-};
+// Stages eligible for autopilot handoff (auto_handoff: true in project.context.md).
+// The chain always breaks at the @dev handoff — see .aioson/docs/autopilot-handoff.md.
+const AUTOPILOT_HANDOFF_STAGES = new Set(['analyst', 'scope-check', 'architect', 'discovery-design-doc', 'pm']);
 
-function normalizeAgentName(input) {
+function normalizeAgentName(input) {
   return String(input || '')
     .trim()
     .toLowerCase()
@@ -51,11 +59,11 @@ function normalizeClassification(value, fallback = 'MICRO') {
 function buildDefaultWorkflowConfig() {
   return {
     version: 1,
-    project: {
-      MICRO: ['setup', 'dev'],
-      SMALL: ['setup', 'product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'dev', 'qa'],
-      MEDIUM: ['setup', 'product', 'analyst', 'architect', 'discovery-design-doc', 'ux-ui', 'pm', 'orchestrator', 'scope-check', 'dev', 'qa']
-    },
+    project: {
+      MICRO: ['setup', 'dev'],
+      SMALL: ['setup', 'product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'dev', 'qa'],
+      MEDIUM: ['setup', 'product', 'analyst', 'architect', 'discovery-design-doc', 'ux-ui', 'pm', 'orchestrator', 'scope-check', 'dev', 'qa']
+    },
     feature: DEFAULT_FEATURE_WORKFLOW_BY_CLASSIFICATION,
     rules: {
       required: ['dev'],
@@ -64,9 +72,9 @@ function buildDefaultWorkflowConfig() {
   };
 }
 
-function parseFeaturesMarkdown(markdown) {
-  return String(markdown || '')
-    .split(/\r?\n/)
+function parseFeaturesMarkdown(markdown) {
+  return String(markdown || '')
+    .split(/\r?\n/)
     .slice(3)
     .map((line) => line.trim())
     .filter(Boolean)
@@ -79,39 +87,39 @@ function parseFeaturesMarkdown(markdown) {
       started: parts[3],
       completed: parts[4]
     }))
-    .filter((row) => row.slug && row.slug !== 'slug')
-    .filter((row) => !/^-+$/ .test(row.slug));
-}
-
-function normalizeScopeCheckMode(input) {
-  const mode = String(input || '').trim().toLowerCase();
-  return SCOPE_CHECK_MODES.has(mode) ? mode : null;
-}
-
-function getScopeCheckModeOption(options = {}) {
-  return normalizeScopeCheckMode(
-    options.scopeMode ||
-    options['scope-mode'] ||
-    options.checkMode ||
-    options['check-mode'] ||
-    options.mode
-  );
-}
-
-function chooseActiveFeature(features, preferredSlug = null) {
-  const activeFeatures = (features || []).filter((feature) => feature.status === 'in_progress');
-  if (preferredSlug) {
-    const preferred = activeFeatures.find((feature) => feature.slug === preferredSlug);
-    if (preferred) return preferred;
-  }
-  return activeFeatures.length > 0 ? activeFeatures[activeFeatures.length - 1] : null;
-}
-
-async function readJsonIfExists(filePath) {
-  if (!(await exists(filePath))) return null;
-  const content = await fs.readFile(filePath, 'utf8');
-  return JSON.parse(content);
-}
+    .filter((row) => row.slug && row.slug !== 'slug')
+    .filter((row) => !/^-+$/ .test(row.slug));
+}
+
+function normalizeScopeCheckMode(input) {
+  const mode = String(input || '').trim().toLowerCase();
+  return SCOPE_CHECK_MODES.has(mode) ? mode : null;
+}
+
+function getScopeCheckModeOption(options = {}) {
+  return normalizeScopeCheckMode(
+    options.scopeMode ||
+    options['scope-mode'] ||
+    options.checkMode ||
+    options['check-mode'] ||
+    options.mode
+  );
+}
+
+function chooseActiveFeature(features, preferredSlug = null) {
+  const activeFeatures = (features || []).filter((feature) => feature.status === 'in_progress');
+  if (preferredSlug) {
+    const preferred = activeFeatures.find((feature) => feature.slug === preferredSlug);
+    if (preferred) return preferred;
+  }
+  return activeFeatures.length > 0 ? activeFeatures[activeFeatures.length - 1] : null;
+}
+
+async function readJsonIfExists(filePath) {
+  if (!(await exists(filePath))) return null;
+  const content = await fs.readFile(filePath, 'utf8');
+  return JSON.parse(content);
+}
 
 async function writeJson(filePath, payload) {
   await ensureDir(path.dirname(filePath));
@@ -213,19 +221,19 @@ async function resolveExistingInstructionPath(targetDir, agent, locale) {
   return agent.path;
 }
 
-async function detectWorkflowMode(targetDir) {
-  const prdPath = path.join(targetDir, '.aioson/context/prd.md');
-  const featuresPath = path.join(targetDir, '.aioson/context/features.md');
-  const handoffPath = path.join(targetDir, '.aioson/context/last-handoff.json');
-  const hasProjectPrd = await exists(prdPath);
-  const featuresMarkdown = await fs.readFile(featuresPath, 'utf8').catch(() => '');
-  const features = parseFeaturesMarkdown(featuresMarkdown);
-  const lastHandoff = await readJsonIfExists(handoffPath).catch(() => null);
-  const preferredSlug = lastHandoff && lastHandoff.feature_slug ? lastHandoff.feature_slug : null;
-  const activeFeature = chooseActiveFeature(features, preferredSlug);
-
-  if (activeFeature) {
-    return {
+async function detectWorkflowMode(targetDir) {
+  const prdPath = path.join(targetDir, '.aioson/context/prd.md');
+  const featuresPath = path.join(targetDir, '.aioson/context/features.md');
+  const handoffPath = path.join(targetDir, '.aioson/context/last-handoff.json');
+  const hasProjectPrd = await exists(prdPath);
+  const featuresMarkdown = await fs.readFile(featuresPath, 'utf8').catch(() => '');
+  const features = parseFeaturesMarkdown(featuresMarkdown);
+  const lastHandoff = await readJsonIfExists(handoffPath).catch(() => null);
+  const preferredSlug = lastHandoff && lastHandoff.feature_slug ? lastHandoff.feature_slug : null;
+  const activeFeature = chooseActiveFeature(features, preferredSlug);
+
+  if (activeFeature) {
+    return {
       mode: 'feature',
       featureSlug: activeFeature.slug,
       features
@@ -245,15 +253,15 @@ function getSequenceForMode(config, mode, classification) {
   return Array.isArray(sequence) && sequence.length > 0 ? [...sequence] : [];
 }
 
-async function validateStageArtifacts(targetDir, state, stage) {
-  const base = path.join(targetDir, '.aioson/context');
-  const slug = state.featureSlug;
-  const anyExists = async (candidates) => {
-    for (const candidate of candidates) {
-      if (await exists(candidate)) return true;
-    }
-    return false;
-  };
+async function validateStageArtifacts(targetDir, state, stage) {
+  const base = path.join(targetDir, '.aioson/context');
+  const slug = state.featureSlug;
+  const anyExists = async (candidates) => {
+    for (const candidate of candidates) {
+      if (await exists(candidate)) return true;
+    }
+    return false;
+  };
 
   if (stage === 'setup') {
     const context = await validateProjectContextFile(targetDir);
@@ -269,41 +277,51 @@ async function validateStageArtifacts(targetDir, state, stage) {
     return await exists(path.join(base, 'prd.md'));
   }
 
-  if (stage === 'analyst') {
-    if (state.mode === 'feature' && slug) {
-      const requirements = path.join(base, `requirements-${slug}.md`);
-      const spec = path.join(base, `spec-${slug}.md`);
-      return (await exists(requirements)) && (await exists(spec));
-    }
-    return await exists(path.join(base, 'discovery.md'));
-  }
-
-  if (stage === 'scope-check') {
-    if (state.mode === 'feature' && slug) {
-      return await exists(path.join(base, `scope-check-${slug}.md`));
-    }
-    return await exists(path.join(base, 'scope-check.md'));
-  }
-
-  if (stage === 'architect') {
-    return await exists(path.join(base, 'architecture.md'));
-  }
-
-  if (stage === 'ux-ui') {
-    return await exists(path.join(base, 'ui-spec.md'));
-  }
-
-  if (stage === 'discovery-design-doc') {
-    const designDocCandidates = slug
-      ? [path.join(base, `design-doc-${slug}.md`), path.join(base, 'design-doc.md')]
-      : [path.join(base, 'design-doc.md')];
-    const readinessCandidates = slug
-      ? [path.join(base, `readiness-${slug}.md`), path.join(base, 'readiness.md')]
-      : [path.join(base, 'readiness.md')];
-    return (await anyExists(designDocCandidates)) && (await anyExists(readinessCandidates));
-  }
-
-  if (stage === 'orchestrator') {
+  if (stage === 'analyst') {
+    if (state.mode === 'feature' && slug) {
+      const requirements = path.join(base, `requirements-${slug}.md`);
+      const spec = path.join(base, `spec-${slug}.md`);
+      return (await exists(requirements)) && (await exists(spec));
+    }
+    return await exists(path.join(base, 'discovery.md'));
+  }
+
+  if (stage === 'scope-check') {
+    if (state.mode === 'feature' && slug) {
+      return await exists(path.join(base, `scope-check-${slug}.md`));
+    }
+    return await exists(path.join(base, 'scope-check.md'));
+  }
+
+  if (stage === 'architect') {
+    return await exists(path.join(base, 'architecture.md'));
+  }
+
+  if (stage === 'ux-ui') {
+    return await exists(path.join(base, 'ui-spec.md'));
+  }
+
+  if (stage === 'discovery-design-doc') {
+    const designDocCandidates = slug
+      ? [path.join(base, `design-doc-${slug}.md`), path.join(base, 'design-doc.md')]
+      : [path.join(base, 'design-doc.md')];
+    const readinessCandidates = slug
+      ? [path.join(base, `readiness-${slug}.md`), path.join(base, 'readiness.md')]
+      : [path.join(base, 'readiness.md')];
+    return (await anyExists(designDocCandidates)) && (await anyExists(readinessCandidates));
+  }
+
+  if (stage === 'pm') {
+    // Feature mode: @pm's canonical artifact is the implementation plan
+    // (Gate C input). Project mode has no single canonical pm artifact —
+    // the handoff contract covers feature MEDIUM (AC-SDLC-16).
+    if (state.mode === 'feature' && slug) {
+      return await exists(path.join(base, `implementation-plan-${slug}.md`));
+    }
+    return true;
+  }
+
+  if (stage === 'orchestrator') {
     return await exists(path.join(base, 'parallel'));
   }
 
@@ -426,11 +444,17 @@ function reconcileWorkflowState(state) {
   };
 }
 
-function isInferableStage(stage) {
-  return ['setup', 'product', 'analyst', 'scope-check', 'architect', 'ux-ui', 'orchestrator'].includes(
-    normalizeAgentName(stage)
-  );
-}
+function isInferableStage(stage) {
+  // discovery-design-doc is inferable from its design-doc + readiness artifacts
+  // (it has both a validateStageArtifacts branch and a handoff contract). Without
+  // it, MEDIUM sequences — where scope-check sits AFTER discovery-design-doc —
+  // could never infer scope-check as completed during stale-state recovery.
+  // pm is inferable from implementation-plan-{slug}.md for the same reason:
+  // it sits before scope-check in the MEDIUM feature sequence.
+  return ['setup', 'product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'ux-ui', 'pm', 'orchestrator'].includes(
+    normalizeAgentName(stage)
+  );
+}
 
 function isSecurityGateBlocked(contractCheck, state, stageName) {
   if (normalizeAgentName(stageName) !== 'qa' || state.mode !== 'feature' || !state.featureSlug) {
@@ -465,58 +489,58 @@ function buildQaSecurityAuditBriefing(result, targetDir) {
   ].join('\n');
 }
 
-async function inferCompletedStages(targetDir, draftState) {
-  const completed = [];
-  for (const stage of draftState.sequence) {
-    if (!isInferableStage(stage)) break;
-    const valid = await validateStageArtifacts(targetDir, draftState, stage);
-    if (!valid) break;
-    const contractCheck = await validateHandoffContract(targetDir, draftState, normalizeAgentName(stage));
-    if (!contractCheck.ok) break;
-    completed.push(normalizeAgentName(stage));
-  }
-  return completed;
-}
-
-function mergeInferredCompletedStages(state, inferredCompleted) {
-  if (!state || !Array.isArray(state.sequence) || !Array.isArray(inferredCompleted)) {
-    return { state, changed: false };
-  }
-
-  const sequence = state.sequence.map(normalizeAgentName);
-  const completedSet = new Set((state.completed || []).map(normalizeAgentName).filter(Boolean));
-  const skippedSet = new Set((state.skipped || []).map(normalizeAgentName).filter(Boolean));
-  let changed = false;
-
-  for (const stage of inferredCompleted.map(normalizeAgentName).filter(Boolean)) {
-    if (!sequence.includes(stage)) continue;
-    if (!completedSet.has(stage)) {
-      completedSet.add(stage);
-      changed = true;
-    }
-    if (skippedSet.delete(stage)) {
-      changed = true;
-    }
-  }
-
-  if (!changed) return { state, changed: false };
-
-  return {
-    changed: true,
-    state: buildStatePayload({
-      ...state,
-      sequence,
-      completed: sequence.filter((stage) => completedSet.has(stage)),
-      skipped: sequence.filter((stage) => skippedSet.has(stage))
-    })
-  };
-}
-
-// SF-project-18: cross-check workflow.state.json#completed against runtime
-// telemetry. Stages claimed as completed without a corresponding agent_done
-// event in .aioson/runtime/aios.sqlite are surfaced as a warning. Detection
-// is best-effort — if the runtime DB is unavailable, the check is silently
-// skipped (the framework still works in environments without telemetry).
+async function inferCompletedStages(targetDir, draftState) {
+  const completed = [];
+  for (const stage of draftState.sequence) {
+    if (!isInferableStage(stage)) break;
+    const valid = await validateStageArtifacts(targetDir, draftState, stage);
+    if (!valid) break;
+    const contractCheck = await validateHandoffContract(targetDir, draftState, normalizeAgentName(stage));
+    if (!contractCheck.ok) break;
+    completed.push(normalizeAgentName(stage));
+  }
+  return completed;
+}
+
+function mergeInferredCompletedStages(state, inferredCompleted) {
+  if (!state || !Array.isArray(state.sequence) || !Array.isArray(inferredCompleted)) {
+    return { state, changed: false };
+  }
+
+  const sequence = state.sequence.map(normalizeAgentName);
+  const completedSet = new Set((state.completed || []).map(normalizeAgentName).filter(Boolean));
+  const skippedSet = new Set((state.skipped || []).map(normalizeAgentName).filter(Boolean));
+  let changed = false;
+
+  for (const stage of inferredCompleted.map(normalizeAgentName).filter(Boolean)) {
+    if (!sequence.includes(stage)) continue;
+    if (!completedSet.has(stage)) {
+      completedSet.add(stage);
+      changed = true;
+    }
+    if (skippedSet.delete(stage)) {
+      changed = true;
+    }
+  }
+
+  if (!changed) return { state, changed: false };
+
+  return {
+    changed: true,
+    state: buildStatePayload({
+      ...state,
+      sequence,
+      completed: sequence.filter((stage) => completedSet.has(stage)),
+      skipped: sequence.filter((stage) => skippedSet.has(stage))
+    })
+  };
+}
+
+// SF-project-18: cross-check workflow.state.json#completed against runtime
+// telemetry. Stages claimed as completed without a corresponding agent_done
+// event in .aioson/runtime/aios.sqlite are surfaced as a warning. Detection
+// is best-effort — if the runtime DB is unavailable, the check is silently
+// skipped (the framework still works in environments without telemetry).
 async function detectUnsubstantiatedCompletions(targetDir, completedStages, logger = null) {
   if (!Array.isArray(completedStages) || completedStages.length === 0) return [];
   let runtimeStore;
@@ -529,35 +553,48 @@ async function detectUnsubstantiatedCompletions(targetDir, completedStages, logg
   let dbExists;
   try { dbExists = await runtimeStore.runtimeStoreExists(targetDir); } catch { return []; }
   if (!dbExists) return [];
-  let db;
+  let handle;
   try {
-    db = await runtimeStore.openRuntimeDb(targetDir);
+    handle = await runtimeStore.openRuntimeDb(targetDir);
   } catch {
     return [];
   }
+  // openRuntimeDb resolves to { db, dbPath, runtimeDir } — the raw better-sqlite3
+  // handle lives on `.db`.
+  const db = handle && handle.db;
   if (!db || typeof db.prepare !== 'function') {
     try { if (db && typeof db.close === 'function') db.close(); } catch { /* ignore */ }
     return [];
   }
-  const unsubstantiated = [];
+  let unsubstantiated = [];
   try {
     let stmt;
     try {
+      // agent identity lives on execution_events.agent_name (agent_events has no
+      // agent column). agent_done/stage_completed events are written there by
+      // appendRunEvent for every tracked run.
       stmt = db.prepare(
-        "SELECT 1 FROM agent_events WHERE agent = ? AND event_type IN ('agent_done', 'stage_completed') LIMIT 1"
+        "SELECT 1 FROM execution_events WHERE agent_name = ? AND event_type IN ('agent_done', 'stage_completed') LIMIT 1"
       );
     } catch {
       // schema differences across versions — abort the cross-check.
       return [];
     }
+    const missing = [];
+    let substantiated = 0;
     for (const stage of completedStages) {
       try {
-        const row = stmt.get(stage);
-        if (!row) unsubstantiated.push(stage);
+        if (stmt.get(stage)) substantiated += 1;
+        else missing.push(stage);
       } catch {
         return [];
       }
     }
+    // Only treat missing stages as suspicious when the workflow demonstrably
+    // emits per-stage telemetry (≥1 completed stage has an agent_done event).
+    // Projects that never emit per-stage telemetry would otherwise warn on every
+    // run — keep the cross-check best-effort and silent for them.
+    unsubstantiated = substantiated > 0 ? missing : [];
   } finally {
     try { db.close(); } catch { /* ignore */ }
   }
@@ -574,39 +611,39 @@ async function loadOrCreateState(targetDir, options = {}) {
   const statePath = path.join(targetDir, STATE_RELATIVE_PATH);
   let existing = await readJsonIfExists(statePath);
 
-  // Mode/feature-transition guard: if the persisted state no longer matches
-  // the current mode from features.md, it is stale. This covers both directions:
-  // a feature was paused/closed and project mode should resume, or a new
-  // feature was opened while a project workflow state still exists.
-  if (existing) {
-    const modeInfo = await detectWorkflowMode(targetDir);
-    if (
-      existing.mode !== modeInfo.mode ||
-      (modeInfo.mode === 'feature' && existing.featureSlug !== modeInfo.featureSlug) ||
-      (modeInfo.mode !== 'feature' && existing.featureSlug)
-    ) {
-      existing = null;
-    }
-  }
-
-  if (existing && typeof existing === 'object' && Array.isArray(existing.sequence)) {
-    // SF-project-18: warn-on-mismatch only, never refuse — preserves
-    // backwards-compat with environments that lack runtime telemetry.
-    if (Array.isArray(existing.completed) && existing.completed.length > 0 && options.logger) {
-      await detectUnsubstantiatedCompletions(targetDir, existing.completed, options.logger);
-    }
-    const reconciled = reconcileWorkflowState(existing);
-    const inferredCompleted = (reconciled.state.current || (reconciled.state.detour && reconciled.state.detour.active))
-      ? []
-      : await inferCompletedStages(targetDir, reconciled.state);
-    const merged = mergeInferredCompletedStages(reconciled.state, inferredCompleted);
-    const finalReconciled = merged.changed ? reconcileWorkflowState(merged.state) : reconciled;
-    const changed = reconciled.changed || merged.changed || finalReconciled.changed;
-    if (changed) {
-      await writeJson(statePath, finalReconciled.state);
-    }
-    return { statePath, state: finalReconciled.state, created: false };
-  }
+  // Mode/feature-transition guard: if the persisted state no longer matches
+  // the current mode from features.md, it is stale. This covers both directions:
+  // a feature was paused/closed and project mode should resume, or a new
+  // feature was opened while a project workflow state still exists.
+  if (existing) {
+    const modeInfo = await detectWorkflowMode(targetDir);
+    if (
+      existing.mode !== modeInfo.mode ||
+      (modeInfo.mode === 'feature' && existing.featureSlug !== modeInfo.featureSlug) ||
+      (modeInfo.mode !== 'feature' && existing.featureSlug)
+    ) {
+      existing = null;
+    }
+  }
+
+  if (existing && typeof existing === 'object' && Array.isArray(existing.sequence)) {
+    // SF-project-18: warn-on-mismatch only, never refuse — preserves
+    // backwards-compat with environments that lack runtime telemetry.
+    if (Array.isArray(existing.completed) && existing.completed.length > 0 && options.logger) {
+      await detectUnsubstantiatedCompletions(targetDir, existing.completed, options.logger);
+    }
+    const reconciled = reconcileWorkflowState(existing);
+    const inferredCompleted = (reconciled.state.current || (reconciled.state.detour && reconciled.state.detour.active))
+      ? []
+      : await inferCompletedStages(targetDir, reconciled.state);
+    const merged = mergeInferredCompletedStages(reconciled.state, inferredCompleted);
+    const finalReconciled = merged.changed ? reconcileWorkflowState(merged.state) : reconciled;
+    const changed = reconciled.changed || merged.changed || finalReconciled.changed;
+    if (changed) {
+      await writeJson(statePath, finalReconciled.state);
+    }
+    return { statePath, state: finalReconciled.state, created: false };
+  }
 
   const context = await validateProjectContextFile(targetDir);
   const modeInfo = await detectWorkflowMode(targetDir);
@@ -856,7 +893,7 @@ function applySkip(config, state, target) {
   });
 }
 
-async function ensureFeatureDossier(targetDir, state) {
+async function ensureFeatureDossier(targetDir, state) {
   if (state.mode !== 'feature' || !state.featureSlug) return;
   const classification = String(state.classification || '').toUpperCase();
   if (classification !== 'SMALL' && classification !== 'MEDIUM') return;
@@ -912,205 +949,205 @@ async function ensureFeatureDossier(targetDir, state) {
         mode
       }
     });
-  }
-}
-
-async function readTextIfExists(filePath) {
-  try {
-    return await fs.readFile(filePath, 'utf8');
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return null;
-    throw err;
-  }
-}
-
-function parseDevStateContextPackage(raw) {
-  if (!raw) return [];
-  const section = raw.match(/## Context package\r?\n\r?\n([\s\S]*?)(?:\r?\n\r?\n## |\s*$)/);
-  if (!section) return [];
-  return section[1]
-    .split(/\r?\n/)
-    .map((line) => {
-      const match = line.trim().match(/^\d+\.\s+(.+)$/);
-      return match ? match[1].trim() : null;
-    })
-    .filter(Boolean);
-}
-
-function parseDevStateFrontmatter(raw) {
-  if (!raw) return {};
-  const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!fmMatch) return {};
-  const fm = {};
-  for (const line of fmMatch[1].split(/\r?\n/)) {
-    const idx = line.indexOf(':');
-    if (idx === -1) continue;
-    const key = line.slice(0, idx).trim();
-    const value = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
-    if (key) fm[key] = value;
-  }
-  return fm;
-}
-
-function shouldUseDevStateForFeature(raw, featureSlug) {
-  if (!raw) return false;
-  const fm = parseDevStateFrontmatter(raw);
-  if (!fm.active_feature) return false;
-  const status = String(fm.status || '').toLowerCase();
-  if (status === 'done' || status === 'abandoned') return false;
-  if (fm.active_feature !== featureSlug) return false;
-  return true;
-}
-
-function normalizeContextDependency(relPath) {
-  const cleaned = String(relPath || '').trim().replace(/\\/g, '/');
-  if (!cleaned) return null;
-  if (cleaned.startsWith('.aioson/')) return cleaned;
-  return `.aioson/context/${cleaned}`;
-}
-
-async function resolveStageDependencies(targetDir, state, stageName, agent) {
-  if (stageName === 'scope-check') {
-    const contextDir = path.join(targetDir, '.aioson', 'context');
-    const slug = state.featureSlug;
-    const candidates = [
-      'project.context.md',
-      'features.md',
-      slug ? `prd-${slug}.md` : 'prd.md',
-      slug ? `requirements-${slug}.md` : 'discovery.md',
-      slug ? `spec-${slug}.md` : 'spec.md',
-      slug ? `sheldon-enrichment-${slug}.md` : 'sheldon-enrichment.md',
-      'architecture.md',
-      slug ? `design-doc-${slug}.md` : null,
-      slug ? `readiness-${slug}.md` : null,
-      'design-doc.md',
-      'readiness.md',
-      'ui-spec.md',
-      slug ? `implementation-plan-${slug}.md` : 'implementation-plan.md',
-      'dev-state.md',
-      'last-handoff.json',
-      'project-pulse.md'
-    ].filter(Boolean);
-    const existing = [];
-    for (const candidate of candidates) {
-      if (await exists(path.join(contextDir, candidate))) {
-        existing.push(normalizeContextDependency(candidate));
-      }
-    }
-    return existing.length > 0 ? existing : agent.dependsOn;
-  }
-
-  if (stageName === 'discovery-design-doc') {
-    const contextDir = path.join(targetDir, '.aioson', 'context');
-    const slug = state.featureSlug;
-    const candidates = [
-      'project.context.md',
-      slug ? `prd-${slug}.md` : 'prd.md',
-      slug ? `requirements-${slug}.md` : 'discovery.md',
-      slug ? `spec-${slug}.md` : 'spec.md',
-      'architecture.md',
-      slug ? `design-doc-${slug}.md` : null,
-      slug ? `readiness-${slug}.md` : null,
-      'design-doc.md',
-      'readiness.md',
-      'project-map.md'
-    ].filter(Boolean);
-    const existing = [];
-    for (const candidate of candidates) {
-      if (await exists(path.join(contextDir, candidate))) {
-        existing.push(normalizeContextDependency(candidate));
-      }
-    }
-    return existing.length > 0 ? existing : agent.dependsOn;
-  }
-
-  if (stageName !== 'dev' || state.mode !== 'feature' || !state.featureSlug) {
-    return agent.dependsOn;
-  }
-
-  const contextDir = path.join(targetDir, '.aioson', 'context');
-  const devStatePath = path.join(contextDir, 'dev-state.md');
-  const devStateRaw = await readTextIfExists(devStatePath);
-  const devStatePackage = shouldUseDevStateForFeature(devStateRaw, state.featureSlug)
-    ? parseDevStateContextPackage(devStateRaw)
-      .map(normalizeContextDependency)
-      .filter(Boolean)
-    : [];
-
-  if (devStatePackage.length > 0) {
-    return Array.from(new Set(['.aioson/context/dev-state.md', ...devStatePackage]));
-  }
-
-  const slug = state.featureSlug;
-  const candidates = [
-    'project.context.md',
-    `prd-${slug}.md`,
-    `requirements-${slug}.md`,
-    `spec-${slug}.md`,
-    `design-doc-${slug}.md`,
-    `readiness-${slug}.md`,
-    'design-doc.md',
-    'readiness.md',
-    `scope-check-${slug}.md`,
-    'scope-check.md',
-    `implementation-plan-${slug}.md`
-  ];
-  const existing = [];
-  for (const candidate of candidates) {
-    if (await exists(path.join(contextDir, candidate))) {
-      existing.push(normalizeContextDependency(candidate));
-    }
-  }
-  return existing.length > 0 ? existing : agent.dependsOn;
-}
-
-function inferScopeCheckMode(state, requestedMode = null) {
-  if (requestedMode) return requestedMode;
-  const completed = Array.isArray(state.completed) ? state.completed.map(normalizeAgentName) : [];
-  const current = normalizeAgentName(state.current || state.next);
-  if (completed.includes('dev')) return 'post-dev';
-  if (completed.includes('qa') || completed.includes('tester') || completed.includes('pentester')) return 'post-fix';
-  if (current === 'scope-check') return 'pre-dev';
-  return 'pre-dev';
-}
-
-function buildScopeCheckActivationContext(state, mode) {
-  const resolvedMode = inferScopeCheckMode(state, mode);
-  const lines = [
-    `Scope-check mode: ${resolvedMode}`,
-    `Workflow mode: ${state.mode || 'unknown'}`,
-    `Classification: ${state.classification || 'unknown'}`
-  ];
-  if (state.featureSlug) lines.push(`Feature slug: ${state.featureSlug}`);
-  if (resolvedMode === 'pre-dev') {
-    lines.push('Compare user intent against planning artifacts before implementation.');
-  } else if (resolvedMode === 'post-dev') {
-    lines.push('Compare the approved scope-check/design artifacts against the actual implementation diff and changed files before QA.');
-  } else if (resolvedMode === 'post-fix') {
-    lines.push('Compare approved scope, QA/tester/pentester findings, and the correction diff; confirm the fix did not change product intent.');
-  } else if (resolvedMode === 'final') {
-    lines.push('Reconcile intent, plan, delivered behavior, and remaining exclusions before close/commit/release.');
-  }
-  return lines.join('\n');
-}
-
-function buildStageActivationContext(state, stageName, dependencies, scopeCheckMode = null) {
-  if (stageName === 'scope-check') {
-    return buildScopeCheckActivationContext(state, scopeCheckMode);
-  }
-
-  if (stageName !== 'dev' || state.mode !== 'feature' || !state.featureSlug) return '';
-  return [
-    `Feature slug: ${state.featureSlug}`,
-    `Workflow mode: ${state.mode}`,
-    `Classification: ${state.classification || 'unknown'}`,
-    dependencies.includes('.aioson/context/dev-state.md')
-      ? 'Resume source: .aioson/context/dev-state.md'
-      : 'Resume source: active feature artifacts'
-  ].join('\n');
-}
-
-async function activateStage(targetDir, state, locale, tool, explicitAgent = null, requestedMode = null, scopeCheckMode = null) {
+  }
+}
+
+async function readTextIfExists(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+function parseDevStateContextPackage(raw) {
+  if (!raw) return [];
+  const section = raw.match(/## Context package\r?\n\r?\n([\s\S]*?)(?:\r?\n\r?\n## |\s*$)/);
+  if (!section) return [];
+  return section[1]
+    .split(/\r?\n/)
+    .map((line) => {
+      const match = line.trim().match(/^\d+\.\s+(.+)$/);
+      return match ? match[1].trim() : null;
+    })
+    .filter(Boolean);
+}
+
+function parseDevStateFrontmatter(raw) {
+  if (!raw) return {};
+  const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return {};
+  const fm = {};
+  for (const line of fmMatch[1].split(/\r?\n/)) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+    if (key) fm[key] = value;
+  }
+  return fm;
+}
+
+function shouldUseDevStateForFeature(raw, featureSlug) {
+  if (!raw) return false;
+  const fm = parseDevStateFrontmatter(raw);
+  if (!fm.active_feature) return false;
+  const status = String(fm.status || '').toLowerCase();
+  if (status === 'done' || status === 'abandoned') return false;
+  if (fm.active_feature !== featureSlug) return false;
+  return true;
+}
+
+function normalizeContextDependency(relPath) {
+  const cleaned = String(relPath || '').trim().replace(/\\/g, '/');
+  if (!cleaned) return null;
+  if (cleaned.startsWith('.aioson/')) return cleaned;
+  return `.aioson/context/${cleaned}`;
+}
+
+async function resolveStageDependencies(targetDir, state, stageName, agent) {
+  if (stageName === 'scope-check') {
+    const contextDir = path.join(targetDir, '.aioson', 'context');
+    const slug = state.featureSlug;
+    const candidates = [
+      'project.context.md',
+      'features.md',
+      slug ? `prd-${slug}.md` : 'prd.md',
+      slug ? `requirements-${slug}.md` : 'discovery.md',
+      slug ? `spec-${slug}.md` : 'spec.md',
+      slug ? `sheldon-enrichment-${slug}.md` : 'sheldon-enrichment.md',
+      'architecture.md',
+      slug ? `design-doc-${slug}.md` : null,
+      slug ? `readiness-${slug}.md` : null,
+      'design-doc.md',
+      'readiness.md',
+      'ui-spec.md',
+      slug ? `implementation-plan-${slug}.md` : 'implementation-plan.md',
+      'dev-state.md',
+      'last-handoff.json',
+      'project-pulse.md'
+    ].filter(Boolean);
+    const existing = [];
+    for (const candidate of candidates) {
+      if (await exists(path.join(contextDir, candidate))) {
+        existing.push(normalizeContextDependency(candidate));
+      }
+    }
+    return existing.length > 0 ? existing : agent.dependsOn;
+  }
+
+  if (stageName === 'discovery-design-doc') {
+    const contextDir = path.join(targetDir, '.aioson', 'context');
+    const slug = state.featureSlug;
+    const candidates = [
+      'project.context.md',
+      slug ? `prd-${slug}.md` : 'prd.md',
+      slug ? `requirements-${slug}.md` : 'discovery.md',
+      slug ? `spec-${slug}.md` : 'spec.md',
+      'architecture.md',
+      slug ? `design-doc-${slug}.md` : null,
+      slug ? `readiness-${slug}.md` : null,
+      'design-doc.md',
+      'readiness.md',
+      'project-map.md'
+    ].filter(Boolean);
+    const existing = [];
+    for (const candidate of candidates) {
+      if (await exists(path.join(contextDir, candidate))) {
+        existing.push(normalizeContextDependency(candidate));
+      }
+    }
+    return existing.length > 0 ? existing : agent.dependsOn;
+  }
+
+  if (stageName !== 'dev' || state.mode !== 'feature' || !state.featureSlug) {
+    return agent.dependsOn;
+  }
+
+  const contextDir = path.join(targetDir, '.aioson', 'context');
+  const devStatePath = path.join(contextDir, 'dev-state.md');
+  const devStateRaw = await readTextIfExists(devStatePath);
+  const devStatePackage = shouldUseDevStateForFeature(devStateRaw, state.featureSlug)
+    ? parseDevStateContextPackage(devStateRaw)
+      .map(normalizeContextDependency)
+      .filter(Boolean)
+    : [];
+
+  if (devStatePackage.length > 0) {
+    return Array.from(new Set(['.aioson/context/dev-state.md', ...devStatePackage]));
+  }
+
+  const slug = state.featureSlug;
+  const candidates = [
+    'project.context.md',
+    `prd-${slug}.md`,
+    `requirements-${slug}.md`,
+    `spec-${slug}.md`,
+    `design-doc-${slug}.md`,
+    `readiness-${slug}.md`,
+    'design-doc.md',
+    'readiness.md',
+    `scope-check-${slug}.md`,
+    'scope-check.md',
+    `implementation-plan-${slug}.md`
+  ];
+  const existing = [];
+  for (const candidate of candidates) {
+    if (await exists(path.join(contextDir, candidate))) {
+      existing.push(normalizeContextDependency(candidate));
+    }
+  }
+  return existing.length > 0 ? existing : agent.dependsOn;
+}
+
+function inferScopeCheckMode(state, requestedMode = null) {
+  if (requestedMode) return requestedMode;
+  const completed = Array.isArray(state.completed) ? state.completed.map(normalizeAgentName) : [];
+  const current = normalizeAgentName(state.current || state.next);
+  if (completed.includes('dev')) return 'post-dev';
+  if (completed.includes('qa') || completed.includes('tester') || completed.includes('pentester')) return 'post-fix';
+  if (current === 'scope-check') return 'pre-dev';
+  return 'pre-dev';
+}
+
+function buildScopeCheckActivationContext(state, mode) {
+  const resolvedMode = inferScopeCheckMode(state, mode);
+  const lines = [
+    `Scope-check mode: ${resolvedMode}`,
+    `Workflow mode: ${state.mode || 'unknown'}`,
+    `Classification: ${state.classification || 'unknown'}`
+  ];
+  if (state.featureSlug) lines.push(`Feature slug: ${state.featureSlug}`);
+  if (resolvedMode === 'pre-dev') {
+    lines.push('Compare user intent against planning artifacts before implementation.');
+  } else if (resolvedMode === 'post-dev') {
+    lines.push('Compare the approved scope-check/design artifacts against the actual implementation diff and changed files before QA.');
+  } else if (resolvedMode === 'post-fix') {
+    lines.push('Compare approved scope, QA/tester/pentester findings, and the correction diff; confirm the fix did not change product intent.');
+  } else if (resolvedMode === 'final') {
+    lines.push('Reconcile intent, plan, delivered behavior, and remaining exclusions before close/commit/release.');
+  }
+  return lines.join('\n');
+}
+
+function buildStageActivationContext(state, stageName, dependencies, scopeCheckMode = null) {
+  if (stageName === 'scope-check') {
+    return buildScopeCheckActivationContext(state, scopeCheckMode);
+  }
+
+  if (stageName !== 'dev' || state.mode !== 'feature' || !state.featureSlug) return '';
+  return [
+    `Feature slug: ${state.featureSlug}`,
+    `Workflow mode: ${state.mode}`,
+    `Classification: ${state.classification || 'unknown'}`,
+    dependencies.includes('.aioson/context/dev-state.md')
+      ? 'Resume source: .aioson/context/dev-state.md'
+      : 'Resume source: active feature artifacts'
+  ].join('\n');
+}
+
+async function activateStage(targetDir, state, locale, tool, explicitAgent = null, requestedMode = null, scopeCheckMode = null) {
   const stageName = normalizeAgentName(explicitAgent || state.current || state.next);
   if (!stageName) {
     return {
@@ -1209,17 +1246,32 @@ async function activateStage(targetDir, state, locale, tool, explicitAgent = nul
     requestedMode
   });
 
-  const instructionPath = await resolveExistingInstructionPath(targetDir, agent, locale);
-  const dependencies = await resolveStageDependencies(targetDir, state, stageName, agent);
-  let prompt = buildAgentPrompt(agent, tool, {
-    instructionPath,
-    targetDir,
-    interactionLanguage: locale,
-    autonomyMode: effectiveMode,
-    capabilitySummary: buildAgentCapabilitySummary(agentManifest, tool),
-    dependsOn: dependencies,
-    activationContext: buildStageActivationContext(state, stageName, dependencies, scopeCheckMode)
-  });
+  let autoHandoff = false;
+  if (
+    AUTOPILOT_HANDOFF_STAGES.has(stageName) &&
+    state.mode === 'feature' &&
+    (state.classification === 'SMALL' || state.classification === 'MEDIUM')
+  ) {
+    try {
+      const projectContext = await validateProjectContextFile(targetDir);
+      autoHandoff = Boolean(projectContext && projectContext.data && projectContext.data.auto_handoff === true);
+    } catch {
+      autoHandoff = false;
+    }
+  }
+
+  const instructionPath = await resolveExistingInstructionPath(targetDir, agent, locale);
+  const dependencies = await resolveStageDependencies(targetDir, state, stageName, agent);
+  let prompt = buildAgentPrompt(agent, tool, {
+    instructionPath,
+    targetDir,
+    interactionLanguage: locale,
+    autonomyMode: effectiveMode,
+    capabilitySummary: buildAgentCapabilitySummary(agentManifest, tool),
+    dependsOn: dependencies,
+    autoHandoff,
+    activationContext: buildStageActivationContext(state, stageName, dependencies, scopeCheckMode)
+  });
 
   if (testBriefing) {
     prompt += '\n\n' + testBriefing;
@@ -1489,10 +1541,10 @@ async function runWorkflowNext({ args, options, logger, t }) {
     requestedAgent = 'validator';
   }
 
-  const activationAgent = normalizeAgentName(requestedAgent || state.current || state.next);
-  const scopeCheckMode = activationAgent === 'scope-check' ? getScopeCheckModeOption(options) : null;
-  const requestedAutonomyMode = scopeCheckMode && activationAgent === 'scope-check' ? null : options.mode || null;
-  const activation = await activateStage(targetDir, state, locale, tool, requestedAgent, requestedAutonomyMode, scopeCheckMode);
+  const activationAgent = normalizeAgentName(requestedAgent || state.current || state.next);
+  const scopeCheckMode = activationAgent === 'scope-check' ? getScopeCheckModeOption(options) : null;
+  const requestedAutonomyMode = scopeCheckMode && activationAgent === 'scope-check' ? null : options.mode || null;
+  const activation = await activateStage(targetDir, state, locale, tool, requestedAgent, requestedAutonomyMode, scopeCheckMode);
   state = activation.state;
 
   // ── Living Memory: if a reflect manifest is pending (created above by the
@@ -1624,14 +1676,14 @@ module.exports = {
   EVENTS_RELATIVE_PATH,
   buildDefaultWorkflowConfig,
   parseFeaturesMarkdown,
-  readWorkflowConfig,
-  detectWorkflowMode,
-  loadOrCreateState,
-  persistState,
-  appendWorkflowEvent,
-  resolveLocaleForTarget,
-  reconcileWorkflowState,
-  finalizeCurrentStage,
+  readWorkflowConfig,
+  detectWorkflowMode,
+  loadOrCreateState,
+  persistState,
+  appendWorkflowEvent,
+  resolveLocaleForTarget,
+  reconcileWorkflowState,
+  finalizeCurrentStage,
   applySkip,
   activateStage,
   runWorkflowNext,