@jaimevalasek/aioson 1.7.0 → 1.8.0

package/src/commands/workflow-next.js

@@ -3,11 +3,22 @@
 const fs = require('node:fs/promises');
 const path = require('node:path');
 const { getAgentDefinition, resolveInstructionPath, buildAgentPrompt } = require('../agents');
-const { resolveAgentLocale } = require('../locales');
-const { validateProjectContextFile } = require('../context');
+const { normalizeInteractionLanguage } = require('../locales');
+const { validateProjectContextFile, getInteractionLanguage } = require('../context');
 const { exists, ensureDir } = require('../utils');
 const { syncWorkflowRuntime } = require('../execution-gateway');
-const { writeHandoff, buildWorkflowHandoff } = require('../session-handoff');
+const { writeHandoff, buildWorkflowHandoff, buildWorkflowHandoffProtocol } = require('../session-handoff');
+const { runTechnicalGate, formatGateError } = require('../workflow-gates');
+const { buildTestBriefing } = require('../test-briefing');
+const { validateHandoffContract, formatContractError, getBlockingRevisions } = require('../handoff-contract');
+const { buildPathGuardBlock } = require('../path-guard');
+const { logError, buildHealingPrompt } = require('../self-healing');
+const { validateHandoffProtocol } = require('../handoff-validator');
+const { readAutonomyProtocol, resolveEffectiveMode } = require('../autonomy-policy');
+const { readAgentManifest, buildAgentCapabilitySummary } = require('../agent-manifests');
+const { inspectStagedChanges } = require('../lib/git-commit-guard');
+const { emitSecurityRuntimeEvent } = require('../lib/security/runtime-events');
+const { runSecurityAudit } = require('./security-audit');
 
 const STATE_RELATIVE_PATH = '.aioson/context/workflow.state.json';
 const CONFIG_RELATIVE_PATH = '.aioson/context/workflow.config.json';
@@ -16,7 +27,7 @@ const EVENTS_RELATIVE_PATH = '.aioson/context/workflow.events.jsonl';
 const DEFAULT_FEATURE_WORKFLOW_BY_CLASSIFICATION = {
   MICRO: ['product', 'dev', 'qa'],
   SMALL: ['product', 'analyst', 'dev', 'qa'],
-  MEDIUM: ['product', 'analyst', 'dev', 'qa']
+  MEDIUM: ['product', 'analyst', 'dev', 'pentester', 'qa']
 };
 
 function normalizeAgentName(input) {
@@ -63,7 +74,8 @@ function parseFeaturesMarkdown(markdown) {
       started: parts[3],
       completed: parts[4]
     }))
-    .filter((row) => row.slug && row.slug !== 'slug');
+    .filter((row) => row.slug && row.slug !== 'slug')
+    .filter((row) => !/^-+$/ .test(row.slug));
 }
 
 async function readJsonIfExists(filePath) {
@@ -155,11 +167,11 @@ async function readWorkflowConfig(targetDir) {
 
 async function resolveLocaleForTarget(targetDir, options) {
   const fromOption = options.language || options.lang;
-  if (fromOption) return resolveAgentLocale(fromOption);
+  if (fromOption) return normalizeInteractionLanguage(fromOption);
 
   const context = await validateProjectContextFile(targetDir);
-  if (context.parsed && context.data && context.data.conversation_language) {
-    return resolveAgentLocale(context.data.conversation_language);
+  if (context.parsed && context.data) {
+    return getInteractionLanguage(context.data, 'en');
   }
 
   return 'en';
@@ -270,12 +282,134 @@ function findNextFromSequence(sequence, completed, skipped) {
   return sequence.find((stage) => !done.has(normalizeAgentName(stage))) || null;
 }
 
+function reconcileWorkflowState(state) {
+  if (!state || typeof state !== 'object' || !Array.isArray(state.sequence)) {
+    return { state, changed: false };
+  }
+
+  const sequence = state.sequence.map(normalizeAgentName);
+  const completed = Array.from(new Set((state.completed || []).map(normalizeAgentName).filter(Boolean)));
+  const skippedSet = new Set((state.skipped || []).map(normalizeAgentName).filter(Boolean));
+  const detour = state.detour && typeof state.detour === 'object'
+    ? {
+        ...state.detour,
+        agent: normalizeAgentName(state.detour.agent),
+        returnTo: normalizeAgentName(state.detour.returnTo)
+      }
+    : null;
+  let changed = false;
+
+  // If a later stage is already completed, any unresolved earlier stage was
+  // effectively bypassed outside the workflow and must not remain "active".
+  const furthestCompletedIndex = sequence.reduce((max, stage, index) => (
+    completed.includes(stage) ? Math.max(max, index) : max
+  ), -1);
+
+  if (furthestCompletedIndex >= 0) {
+    for (let index = 0; index < furthestCompletedIndex; index += 1) {
+      const stage = sequence[index];
+      if (!completed.includes(stage) && !skippedSet.has(stage)) {
+        skippedSet.add(stage);
+        changed = true;
+      }
+    }
+  }
+
+  const skipped = sequence.filter((stage) => skippedSet.has(stage));
+  const resolved = new Set([...completed, ...skipped]);
+  let current = state.current ? normalizeAgentName(state.current) : null;
+  let next = state.next ? normalizeAgentName(state.next) : null;
+  const currentIsActiveDetour = Boolean(
+    detour &&
+    detour.active &&
+    current &&
+    current === detour.agent
+  );
+
+  if (current && ((!sequence.includes(current) && !currentIsActiveDetour) || resolved.has(current))) {
+    current = null;
+    changed = true;
+  }
+
+  if (!detour || !detour.active) {
+    if (current) {
+      const currentIndex = sequence.indexOf(current);
+      const expectedQueuedNext = sequence.find(
+        (stage, index) => index > currentIndex && !resolved.has(stage)
+      ) || null;
+      if (next && next !== current && next !== expectedQueuedNext) {
+        next = expectedQueuedNext || current;
+        changed = true;
+      } else if (!next) {
+        next = expectedQueuedNext || current;
+        changed = true;
+      }
+    } else {
+      const inferredNext = findNextFromSequence(sequence, completed, skipped);
+      if (next !== inferredNext) {
+        next = inferredNext;
+        changed = true;
+      }
+    }
+  }
+
+  if (!changed) {
+    return { state, changed: false };
+  }
+
+  return {
+    changed: true,
+    state: buildStatePayload({
+      ...state,
+      sequence,
+      completed,
+      skipped,
+      current,
+      next,
+      detour
+    })
+  };
+}
+
 function isInferableStage(stage) {
   return ['setup', 'product', 'analyst', 'architect', 'ux-ui', 'orchestrator'].includes(
     normalizeAgentName(stage)
   );
 }
 
+function isSecurityGateBlocked(contractCheck, state, stageName) {
+  if (normalizeAgentName(stageName) !== 'qa' || state.mode !== 'feature' || !state.featureSlug) {
+    return false;
+  }
+  return contractCheck.missing.some((item) =>
+    item.includes('security:') ||
+    item.includes(`security-findings-${state.featureSlug}.json`)
+  );
+}
+
+function buildQaSecurityAuditBriefing(result, targetDir) {
+  if (!result) return '';
+
+  if (result.ok === false && result.reason) {
+    return [
+      '## Secure by Default audit',
+      `- Auto-run failed before QA review: ${result.reason}.`,
+      '- Gate D will remain blocked until a valid `security-findings-{slug}.json` artifact exists.',
+      '- If CLI is unavailable in your client, use the fallback checklist and record the limitation explicitly in the QA report and `project-pulse.md`.'
+    ].join('\n');
+  }
+
+  return [
+    '## Secure by Default audit',
+    `- Auto-ran \`security:audit\` for feature \`${result.slug}\` at QA activation.`,
+    `- Exit code: ${result.exitCode}. Findings: ${result.findingsCount}.`,
+    `- Summary: critical=${result.summary.critical}, high=${result.summary.high}, medium=${result.summary.medium}, low=${result.summary.low}, inconclusive=${result.summary.inconclusive}.`,
+    `- Artifact: \`${path.relative(targetDir, result.artifactPath)}\`.`,
+    '- If the audit or manual heuristics indicate auth, money, or ownership risk, invoke `@pentester` with `--mode=app_target --feature=<slug> --scope=<target>` before final Gate D sign-off.',
+    '- If CLI is unavailable in your client, use the fallback checklist and record the limitation explicitly in the QA report and `project-pulse.md`.'
+  ].join('\n');
+}
+
 async function inferCompletedStages(targetDir, draftState) {
   const completed = [];
   for (const stage of draftState.sequence) {
@@ -291,7 +425,11 @@ async function loadOrCreateState(targetDir, options = {}) {
   const statePath = path.join(targetDir, STATE_RELATIVE_PATH);
   const existing = await readJsonIfExists(statePath);
   if (existing && typeof existing === 'object' && Array.isArray(existing.sequence)) {
-    return { statePath, state: existing, created: false };
+    const reconciled = reconcileWorkflowState(existing);
+    if (reconciled.changed) {
+      await writeJson(statePath, reconciled.state);
+    }
+    return { statePath, state: reconciled.state, created: false };
   }
 
   const context = await validateProjectContextFile(targetDir);
@@ -371,6 +509,27 @@ async function finalizeCurrentStage(targetDir, config, state, stageName) {
     throw new Error('No stage is active to complete.');
   }
 
+  // ── Harness Done Gate ───────────────────────────────────────────────────
+  if (state.mode === 'feature' && state.featureSlug) {
+    const contractPath = path.join(targetDir, '.aioson', 'plans', state.featureSlug, 'harness-contract.json');
+    const progressPath = path.join(targetDir, '.aioson', 'plans', state.featureSlug, 'progress.json');
+    
+    // Se contrato existe, verificamos o progresso
+    const fs = require('node:fs');
+    if (fs.existsSync(contractPath) && fs.existsSync(progressPath)) {
+      try {
+        const progress = JSON.parse(fs.readFileSync(progressPath, 'utf8'));
+        // Bloqueia se não estiver pronto para o gate E o estágio for crítico (dev/qa)
+        if (!progress.ready_for_done_gate && (normalizedStage === 'dev' || normalizedStage === 'qa')) {
+          throw new Error(`[Harness Block] A feature "${state.featureSlug}" não passou na validação contratual. Execute 'aioson harness:validate' e resolva os problemas antes de concluir o estágio @${normalizedStage}.`);
+        }
+      } catch (err) {
+        if (err.message.includes('[Harness Block]')) throw err;
+        // Se erro de parse, ignoramos para não quebrar o workflow por corrupção
+      }
+    }
+  }
+
   if (state.detour && state.detour.active && normalizeAgentName(state.detour.agent) === normalizedStage) {
     const validDetour = await validateStageArtifacts(targetDir, state, normalizedStage);
     if (!validDetour) {
@@ -391,6 +550,56 @@ async function finalizeCurrentStage(targetDir, config, state, stageName) {
     throw new Error(`Cannot complete ${normalizedStage}; expected artifacts are missing.`);
   }
 
+  // ── Handoff Contract Gate ───────────────────────────────────────────────
+  const contractCheck = await validateHandoffContract(targetDir, state, normalizedStage);
+  if (!contractCheck.ok) {
+    if (isSecurityGateBlocked(contractCheck, state, normalizedStage)) {
+      await emitSecurityRuntimeEvent({
+        targetDir,
+        eventType: 'security_gate_blocked',
+        message: `Gate D blocked for ${state.featureSlug} at @qa`,
+        status: 'failed',
+        agentName: 'qa',
+        source: 'workflow',
+        workflowState: state,
+        workflowStage: 'qa',
+        payload: {
+          feature_slug: state.featureSlug,
+          classification: state.classification,
+          blockers: contractCheck.missing
+        }
+      });
+    }
+    const errMsg = formatContractError(contractCheck);
+    await logError(targetDir, normalizedStage, errMsg, 'contract');
+    throw new Error(errMsg);
+  }
+
+  // ── Revision Gate (Phase 2) ─────────────────────────────────────────────
+  const blockingRevisions = await getBlockingRevisions(targetDir, state.featureSlug);
+  if (blockingRevisions.length > 0) {
+    const ids = blockingRevisions.map((r) => r.id).join(', ');
+    const errMsg = [
+      `[Revision Gate BLOCKED]`,
+      `Feature: ${state.featureSlug}`,
+      ``,
+      `Pending blocking revision(s): ${ids}`,
+      ``,
+      `Resolve each revision before completing this stage:`,
+      ...blockingRevisions.map((r) => `  aioson revision:resolve . --slug=${state.featureSlug} --rev-id=${r.id} --approve|--reject`)
+    ].join('\n');
+    await logError(targetDir, normalizedStage, errMsg, 'revision');
+    throw new Error(errMsg);
+  }
+
+  // ── Technical Compilation/Test Gate ─────────────────────────────────────
+  const techGate = await runTechnicalGate(targetDir, normalizedStage);
+  if (!techGate.ok) {
+    const errMsg = formatGateError(techGate);
+    await logError(targetDir, normalizedStage, errMsg, 'technical');
+    throw new Error(errMsg);
+  }
+
   const completed = Array.from(new Set([...(state.completed || []), normalizedStage]));
   const next = findNextFromSequence(state.sequence, completed, state.skipped || []);
   const nextState = buildStatePayload({
@@ -423,7 +632,7 @@ function applySkip(config, state, target) {
   });
 }
 
-async function activateStage(targetDir, state, locale, tool, explicitAgent = null) {
+async function activateStage(targetDir, state, locale, tool, explicitAgent = null, requestedMode = null) {
   const stageName = normalizeAgentName(explicitAgent || state.current || state.next);
   if (!stageName) {
     return {
@@ -434,13 +643,109 @@ async function activateStage(targetDir, state, locale, tool, explicitAgent = nul
     };
   }
 
+  // ── Committer Safety Gate ───────────────────────────────────────────────
+  if (stageName === 'committer') {
+    const guard = await inspectStagedChanges(targetDir, { allowWarnings: false });
+    if (guard.summary.stagedCount === 0) {
+      throw new Error(
+        `[Committer Gate BLOCKED] Nenhum arquivo no stage para commit. ` +
+        `Execute primeiro: aioson commit:prepare . --agent-safe --staged-only --mode=headless`
+      );
+    }
+    if (!guard.ok) {
+      throw new Error(
+        `[Committer Gate BLOCKED] Arquivos proibidos detectados no stage ` +
+        `(node_modules, build artifacts, secrets, etc.). ` +
+        `Execute 'aioson git:guard .' para ver detalhes, corrija e rode 'aioson commit:prepare . --agent-safe --staged-only --mode=headless' antes de ativar @committer.`
+      );
+    }
+  }
+
+  // ── Test Briefing Injection for qa/tester ───────────────────────────────
+  let testBriefing = '';
+  let securityAuditBriefing = '';
+  if (stageName === 'qa' || stageName === 'tester') {
+    try {
+      testBriefing = await buildTestBriefing(targetDir);
+    } catch {
+      // Non-fatal: if briefing generation fails, proceed without it
+      testBriefing = '';
+    }
+  }
+
+  if (
+    stageName === 'qa' &&
+    state.mode === 'feature' &&
+    state.classification === 'MEDIUM' &&
+    state.featureSlug
+  ) {
+    try {
+      const auditResult = await runSecurityAudit({
+        args: [targetDir],
+        options: {
+          slug: state.featureSlug,
+          json: true,
+          runtimeAgentName: 'qa',
+          runtimeSource: 'workflow',
+          runtimeState: state,
+          runtimeWorkflowStage: 'qa'
+        },
+        logger: { log() {}, error() {}, warn() {} }
+      });
+      securityAuditBriefing = buildQaSecurityAuditBriefing(auditResult, targetDir);
+    } catch {
+      securityAuditBriefing = buildQaSecurityAuditBriefing({
+        ok: false,
+        reason: 'audit_runtime_failure'
+      }, targetDir);
+    }
+  }
+
+  // ── Path Guard Injection for implementation agents ────────────────────────
+  let pathGuardBlock = '';
+  if (['dev', 'architect', 'ux-ui', 'pentester', 'qa', 'tester', 'committer'].includes(stageName)) {
+    try {
+      pathGuardBlock = await buildPathGuardBlock(targetDir);
+    } catch {
+      pathGuardBlock = '';
+    }
+  }
+
   const agent = getAgentDefinition(stageName);
   if (!agent) {
     throw new Error(`Unknown agent: ${stageName}`);
   }
 
+  const autonomyProtocol = await readAutonomyProtocol(targetDir);
+  const agentManifest = await readAgentManifest(targetDir, agent.id);
+  const effectiveMode = resolveEffectiveMode({
+    protocol: autonomyProtocol,
+    tool,
+    agentId: agent.id,
+    manifest: agentManifest,
+    requestedMode
+  });
+
   const instructionPath = await resolveExistingInstructionPath(targetDir, agent, locale);
-  const prompt = buildAgentPrompt(agent, tool, { instructionPath, targetDir });
+  let prompt = buildAgentPrompt(agent, tool, {
+    instructionPath,
+    targetDir,
+    interactionLanguage: locale,
+    autonomyMode: effectiveMode,
+    capabilitySummary: buildAgentCapabilitySummary(agentManifest, tool)
+  });
+
+  if (testBriefing) {
+    prompt += '\n\n' + testBriefing;
+  }
+
+  if (securityAuditBriefing) {
+    prompt += '\n\n' + securityAuditBriefing;
+  }
+
+  if (pathGuardBlock) {
+    prompt += '\n\n' + pathGuardBlock;
+  }
 
   let nextState = state;
   if (explicitAgent && stageName !== normalizeAgentName(state.next)) {
@@ -464,11 +769,23 @@ async function activateStage(targetDir, state, locale, tool, explicitAgent = nul
     state: nextState,
     agent: stageName,
     instructionPath,
-    prompt
+    prompt,
+    effectiveMode
   };
 }
 
 async function runWorkflowNext({ args, options, logger, t }) {
+  if (options.status || options.suggest) {
+    const { runWorkflowStatus } = require('./workflow-status');
+    return runWorkflowStatus({ args, options, logger, t });
+  }
+
+  const logErrorLine = typeof logger.error === 'function'
+    ? logger.error.bind(logger)
+    : typeof logger.log === 'function'
+      ? logger.log.bind(logger)
+      : () => {};
+
   const targetDir = path.resolve(process.cwd(), args[0] || '.');
   const tool = options.tool || 'codex';
   const locale = await resolveLocaleForTarget(targetDir, options);
@@ -478,14 +795,119 @@ async function runWorkflowNext({ args, options, logger, t }) {
   let completedStage = null;
 
   if (options.complete || options['complete-current']) {
-    const result = await finalizeCurrentStage(
-      targetDir,
-      config,
-      state,
-      options.complete === true ? state.current || state.next : options.complete
-    );
-    state = result.state;
-    completedStage = result.completedStage;
+    let finalized;
+    try {
+      finalized = await finalizeCurrentStage(
+        targetDir,
+        config,
+        state,
+        options.complete === true ? state.current || state.next : options.complete
+      );
+    } catch (err) {
+      // ── Auto-heal intercept ───────────────────────────────────────────────
+      const autoHeal = Boolean(options['auto-heal'] || options.autoHeal);
+      const isHealabled = autoHeal && (
+        err.message.includes('[Technical Gate BLOCKED]') ||
+        err.message.includes('[Handoff Contract BLOCKED]')
+      );
+      if (isHealabled) {
+        const failedStage = normalizeAgentName(options.complete === true ? state.current || state.next : options.complete);
+        await logError(targetDir, failedStage, err.message, 'technical');
+        const retryCount = await require('../self-healing').getRetryCount(targetDir, failedStage);
+        if (retryCount < require('../self-healing').MAX_RETRIES) {
+          await require('../self-healing').incrementRetryCount(targetDir, failedStage, err.message.substring(0, 200));
+          // Build healing activation
+          const baseActivation = await activateStage(targetDir, state, locale, tool, failedStage, options.mode || null);
+          const healingPrompt = buildHealingPrompt(
+            baseActivation.prompt || '',
+            failedStage,
+            { error: err.message },
+            retryCount + 1
+          );
+          const healedState = {
+            ...baseActivation.state,
+            current: failedStage,
+            detour: null
+          };
+          await persistState(targetDir, healedState);
+          const eventPayload = {
+            id: Date.now(),
+            kind: 'workflow',
+            createdAt: new Date().toISOString(),
+            eventType: 'heal',
+            message: `Auto-heal @${failedStage} — retry ${retryCount + 1}/3`,
+            mode: state.mode,
+            classification: state.classification,
+            featureSlug: state.featureSlug,
+            current: failedStage,
+            next: state.next,
+            completed: state.completed,
+            skipped: state.skipped,
+            sequence: state.sequence,
+            healing: true,
+            retryCount: retryCount + 1,
+            autonomyMode: baseActivation.effectiveMode || null
+          };
+          await appendWorkflowEvent(targetDir, eventPayload);
+          const runtime = await syncWorkflowRuntime(targetDir, {
+            state: healedState,
+            eventPayload,
+            activationAgent: failedStage,
+            completedStage: null
+          });
+          const healingHandoff = buildWorkflowHandoff(healedState, null, failedStage);
+          healingHandoff.protocol = buildWorkflowHandoffProtocol(healedState, null, failedStage, {
+            autonomyMode: baseActivation.effectiveMode || null,
+            handoffContractOk: true,
+            technicalGateOk: false,
+            artifactUris: []
+          });
+          const healingValidation = await validateHandoffProtocol(targetDir, healingHandoff.protocol);
+          if (!healingValidation.ok) {
+            logErrorLine('Handoff protocol warning:');
+            for (const err of healingValidation.errors) logErrorLine(`  - ${err}`);
+          }
+          await writeHandoff(targetDir, healingHandoff);
+          logger.log(t('workflow_heal.title', { stage: `@${failedStage}`, count: retryCount + 1 }));
+          logger.log(healingPrompt);
+          return {
+            ok: true,
+            targetDir,
+            locale,
+            tool,
+            statePath: STATE_RELATIVE_PATH,
+            configPath: CONFIG_RELATIVE_PATH,
+            created: loaded.created,
+            mode: state.mode,
+            classification: state.classification,
+            current: healedState.current,
+            next: healedState.next,
+            detour: healedState.detour,
+            completed: healedState.completed,
+            skipped: healedState.skipped,
+            completedStage: null,
+            featureSlug: state.featureSlug,
+            runtime,
+            agent: failedStage,
+            instructionPath: baseActivation.instructionPath,
+            prompt: healingPrompt,
+            autoHealed: true,
+            effectiveMode: baseActivation.effectiveMode || null
+          };
+        }
+      }
+      throw err;
+    }
+    state = finalized.state;
+    completedStage = finalized.completedStage;
+    await require('../self-healing').incrementRetryCount(targetDir, completedStage, '');
+    const { getRetryCount } = require('../self-healing');
+    const retries = await getRetryCount(targetDir, completedStage);
+    if (retries > 0) {
+      // Reset retry count on successful completion after healing
+      const retriesPath = path.join(targetDir, '.aioson/context/pipeline-retries', `${completedStage}.json`);
+      try { await fs.unlink(retriesPath); } catch { /* ignore */ }
+    }
   }
 
   if (options.skip) {
@@ -493,7 +915,7 @@ async function runWorkflowNext({ args, options, logger, t }) {
   }
 
   const requestedAgent = options.agent ? normalizeAgentName(options.agent) : null;
-  const activation = await activateStage(targetDir, state, locale, tool, requestedAgent);
+  const activation = await activateStage(targetDir, state, locale, tool, requestedAgent, options.mode || null);
   state = activation.state;
   const statePath = await persistState(targetDir, state);
   const eventPayload = {
@@ -518,7 +940,8 @@ async function runWorkflowNext({ args, options, logger, t }) {
     requestedAgent: options.requestedAgent ? normalizeAgentName(options.requestedAgent) : null,
     completed: state.completed,
     skipped: state.skipped,
-    sequence: state.sequence
+    sequence: state.sequence,
+    autonomyMode: activation.effectiveMode || null
   };
   await appendWorkflowEvent(targetDir, eventPayload);
   const runtime = await syncWorkflowRuntime(targetDir, {
@@ -531,6 +954,18 @@ async function runWorkflowNext({ args, options, logger, t }) {
   // Generate session handoff when a stage completes or workflow finishes
   if (completedStage || !activation.agent) {
     const handoffData = buildWorkflowHandoff(state, completedStage, activation.agent);
+    handoffData.autonomyMode = activation.effectiveMode || null;
+    handoffData.protocol = buildWorkflowHandoffProtocol(state, completedStage, activation.agent, {
+      autonomyMode: activation.effectiveMode || null,
+      handoffContractOk: true,
+      technicalGateOk: true,
+      artifactUris: []
+    });
+    const handoffValidation = await validateHandoffProtocol(targetDir, handoffData.protocol);
+    if (!handoffValidation.ok) {
+      logErrorLine('Handoff protocol warning:');
+      for (const err of handoffValidation.errors) logErrorLine(`  - ${err}`);
+    }
     await writeHandoff(targetDir, handoffData);
   }
 
@@ -553,6 +988,7 @@ async function runWorkflowNext({ args, options, logger, t }) {
     featureSlug: state.featureSlug,
     runtime,
     agent: activation.agent,
+    effectiveMode: activation.effectiveMode || null,
     instructionPath: activation.instructionPath,
     prompt: activation.prompt
   };
@@ -595,7 +1031,9 @@ module.exports = {
   readWorkflowConfig,
   detectWorkflowMode,
   loadOrCreateState,
+  reconcileWorkflowState,
   finalizeCurrentStage,
   applySkip,
+  activateStage,
   runWorkflowNext
 };