@jaimevalasek/aioson 1.36.0 → 1.37.0

package/src/commands/live.js

@@ -235,14 +235,30 @@ async function resolveExecutablePath(command) {
     .map((entry) => entry.trim())
     .filter(Boolean);
 
-  const extensions = process.platform === 'win32'
-    ? Array.from(new Set([...String(process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';').map((entry) => entry.toLowerCase())]))
-    : [''];
+  // No Windows NUNCA testamos o arquivo sem extensão: o npm instala um shim
+  // extensionless (script sh) ao lado do .cmd, e ele não é executável via
+  // CreateProcess — spawná-lo dá ENOENT mesmo com o arquivo existindo.
+  // filter(Boolean) descarta segmentos vazios de um PATHEXT malformado
+  // (";.COM;..."), que viravam candidato sem extensão.
+  let extensions;
+  if (process.platform === 'win32') {
+    extensions = Array.from(new Set(
+      String(process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM')
+        .split(';')
+        .map((entry) => entry.trim().toLowerCase())
+        .filter(Boolean)
+    ));
+    if (extensions.length === 0) {
+      extensions = ['.exe', '.cmd', '.bat', '.com'];
+    }
+  } else {
+    extensions = [''];
+  }
 
   for (const dir of pathEntries) {
     for (const ext of extensions) {
-      const candidate = process.platform === 'win32' && ext && !binary.toLowerCase().endsWith(ext)
-        ? path.join(dir, `${binary}${ext}`)
+      const candidate = process.platform === 'win32'
+        ? (binary.toLowerCase().endsWith(ext) ? path.join(dir, binary) : path.join(dir, `${binary}${ext}`))
         : path.join(dir, binary);
       if (await exists(candidate)) {
         return candidate;
@@ -673,10 +689,30 @@ function createLiveEventRecord(context, options = {}) {
   };
 }
 
+// Latch de spawn: entre o spawn() e o await de waitForChild existem awaits
+// (writeLiveState etc.). Se o spawn falhar nessa janela, o 'error' emitia sem
+// listener e DERRUBAVA o node ("Unhandled 'error' event"). Guardamos o
+// desfecho no próprio child pra waitForChild resolver/rejeitar mesmo quando o
+// evento já passou.
+function trackChild(child) {
+  child.aiosonSpawnError = null;
+  child.aiosonExit = null;
+  child.on('error', (err) => {
+    if (!child.aiosonSpawnError) child.aiosonSpawnError = err;
+  });
+  child.on('close', (code, signal) => {
+    child.aiosonExit = { code: Number(code || 0), signal: signal || null };
+  });
+  return child;
+}
+
 function waitForChild(child) {
   return new Promise((resolve, reject) => {
+    if (child.aiosonSpawnError) return reject(child.aiosonSpawnError);
+    if (child.aiosonExit) return resolve(child.aiosonExit);
     child.once('error', reject);
     child.once('close', (code, signal) => {
+      if (child.aiosonSpawnError) return reject(child.aiosonSpawnError);
       resolve({ code: Number(code || 0), signal: signal || null });
     });
   });
@@ -1319,12 +1355,12 @@ async function runLiveStart({ args, options = {}, logger, t }) {
           let attachResult = null;
 
           if (attach && !noLaunch) {
-            attachChild = spawn(spawnExecutable(binaryPath), buildLaunchArgs(options, tool), {
+            attachChild = trackChild(spawn(spawnExecutable(binaryPath), buildLaunchArgs(options, tool), {
               cwd: targetDir,
               env: process.env,
               stdio: 'inherit',
               shell: process.platform === 'win32'
-            });
+            }));
             state.child_pid = attachChild.pid || null;
             if (existing.task?.task_key) {
               const taskMeta = parseTaskMeta(existing.task);
@@ -1428,12 +1464,12 @@ async function runLiveStart({ args, options = {}, logger, t }) {
           });
         } else {
           // Fallback to normal spawn if tmux not available
-          child = spawn(spawnExecutable(binaryPath), buildLaunchArgs(options, tool), {
+          child = trackChild(spawn(spawnExecutable(binaryPath), buildLaunchArgs(options, tool), {
             cwd: targetDir,
             env: process.env,
             stdio: 'inherit',
             shell: process.platform === 'win32'
-          });
+          }));
           taskMeta.child_pid = child.pid || null;
           updateTask(db, {
             taskKey,
@@ -1441,12 +1477,12 @@ async function runLiveStart({ args, options = {}, logger, t }) {
           });
         }
       } else {
-        child = spawn(spawnExecutable(binaryPath), buildLaunchArgs(options, tool), {
+        child = trackChild(spawn(spawnExecutable(binaryPath), buildLaunchArgs(options, tool), {
           cwd: targetDir,
           env: process.env,
           stdio: 'inherit',
           shell: process.platform === 'win32'
-        });
+        }));
         taskMeta.child_pid = child.pid || null;
         updateTask(db, {
           taskKey,

package/src/commands/update.js

@@ -5,6 +5,7 @@ const { detectFramework } = require('../detector');
 const { updateInstallation } = require('../updater');
 const { validateProjectContextFile, getInteractionLanguage } = require('../context');
 const { applyAgentLocale } = require('../locales');
+const { getCliVersionLabelSync } = require('../version');
 
 async function runUpdate({ args, options, logger, t }) {
   const targetDir = path.resolve(process.cwd(), args[0] || '.');
@@ -36,10 +37,13 @@ async function runUpdate({ args, options, logger, t }) {
       (result.savedProfile && result.savedProfile.locale
         ? result.savedProfile.locale
         : 'en');
-    localeSync = await applyAgentLocale(targetDir, language, { dryRun, selectiveUpdate: selective && !all });
+    localeSync = await applyAgentLocale(targetDir, language, { dryRun, selectiveUpdate: selective && !all });
   }
 
   logger.log(t('update.done_at', { targetDir }));
+  // Surface WHICH template landed — stale-template updates used to be silent
+  // (the copy comes from the installed CLI's own bundle, not from npm latest).
+  logger.log(t('update.template_version', { version: getCliVersionLabelSync() }));
   logger.log(t('update.files_updated', { count: result.copied.length }));
   logger.log(t('update.backups_created', { count: result.backedUp.length }));
   if (result.migrations && result.migrations.profileRename && result.migrations.profileRename.changed) {

package/src/commands/verification-plan.js

@@ -24,6 +24,22 @@ const {
 const BAR = '─'.repeat(60);
 const CLASSIFICATIONS = ['MICRO', 'SMALL', 'MEDIUM'];
 
+// A loud, deterministic instruction the phase loop echoes back to @dev at every
+// phase boundary. On a per-phase trigger with auto_continue it is the fresh
+// tool-result that stops the agent from ending its turn to "report" after a
+// phase — the exact failure the phase loop exists to prevent. It never tells the
+// agent to /compact: context is shed transparently by the host's auto-compact,
+// without ending the turn.
+function buildContinuationDirective(trigger, phaseLoop) {
+  if (trigger === 'end-of-feature') {
+    return 'END-OF-FEATURE — last phase: run the full runtime smoke (build + migrate + boot + Core happy-path), then hand off through the post-dev review cycle. Do not close/publish — that is the human gate.';
+  }
+  if (phaseLoop && phaseLoop.auto_continue) {
+    return 'CONTINUE-NOW — a clean report is a checkpoint, not a stop. Go DIRECTLY into the next phase in this same turn: do not stop, do not ask "continue?", do not summarize-and-end, and never self-issue /compact (the host auto-compacts transparently). Halt only on a failing gate/verification after retries or a genuine hard stop.';
+  }
+  return 'PAUSE — auto_continue is off: after this phase report, stop and wait for confirmation before the next phase.';
+}
+
 async function readFileSafe(filePath) {
   try {
     return await fs.readFile(filePath, 'utf8');
@@ -52,7 +68,16 @@ async function runVerificationPlan({ args, options = {}, logger }) {
   const slug = (options.feature || options.slug || '').toString().trim() || null;
 
   const triggerRaw = (options.trigger || 'per-phase').toString().trim().toLowerCase();
-  const trigger = TRIGGERS.includes(triggerRaw) ? triggerRaw : 'per-phase';
+  // An unknown trigger must fail loudly. Silently coercing it to per-phase used
+  // to emit an imperative CONTINUE-NOW directive on what was actually a typo'd
+  // end-of-feature call — steering @dev into a phase that does not exist.
+  if (!TRIGGERS.includes(triggerRaw)) {
+    const failure = { ok: false, reason: 'invalid_trigger', trigger: triggerRaw, valid_triggers: [...TRIGGERS] };
+    if (options.json) return failure;
+    logger.error(`Invalid --trigger=${triggerRaw}. Valid triggers: ${TRIGGERS.join(', ')}.`);
+    return failure;
+  }
+  const trigger = triggerRaw;
 
   const config = await readVerificationConfig(targetDir);
   const host = resolveHost(config, options.host);
@@ -92,6 +117,7 @@ async function runVerificationPlan({ args, options = {}, logger }) {
     phase_loop: getPhaseLoop(config),
     budget: getBudget(config)
   };
+  result.continuation_directive = buildContinuationDirective(trigger, result.phase_loop);
 
   if (options.json) return result;
 
@@ -108,6 +134,7 @@ async function runVerificationPlan({ args, options = {}, logger }) {
   logger.log(BAR);
   const pl = result.phase_loop;
   logger.log(`Phase loop: auto_continue=${pl.auto_continue}  compact_between_phases=${pl.compact_between_phases}  max_fix_retries=${pl.max_fix_retries_per_phase}`);
+  logger.log(`▶ ${result.continuation_directive}`);
   logger.log('');
 
   return result;

package/src/commands/verify-artifact.js

@@ -179,7 +179,7 @@ const RULESETS = {
 
 // Kinds whose target file path is keyed by --slug; without it we cannot resolve
 // the artifact, so fail with a clear usage error instead of a `null/` path.
-const REQUIRES_SLUG = new Set(['genome', 'research-report', 'enriched-profile', 'hybrid-skill', 'copy']);
+const REQUIRES_SLUG = new Set(['genome', 'research-report', 'enriched-profile', 'hybrid-skill', 'copy', 'review']);
 
 // Kinds whose artifact has a date-stamped / caller-known path — resolved via
 // --file=<path> rather than derived from a slug.
@@ -374,6 +374,69 @@ const ADAPTERS = {
     return { ok: issues.length === 0, issues, warnings, checks: [{ id: 'site', ok: issues.length === 0, detail: issues.join('; ') || null }] };
   },
 
+  // briefing-refiner — the review surface must be the deterministic, fully
+  // self-contained artifact `aioson briefing:review` renders: export fallbacks
+  // present, no external resources, an embedded source_hash, and a feedback
+  // JSON that passes the canonical schema. Staleness (briefings.md changed
+  // after generation, e.g. right after an apply) is a warning, not a failure.
+  review: async (ctx) => {
+    if (!ctx.slug) {
+      return { ok: false, issues: ['kind=review requires --slug=<briefing-slug>'], warnings: [], checks: [] };
+    }
+    const { hashText } = require('../lib/briefing-refiner/briefing-sections');
+    const { validateFeedback } = require('../lib/briefing-refiner/feedback-schema');
+    const briefingDir = path.resolve(ctx.targetDir, '.aioson', 'briefings', ctx.slug);
+    const issues = [];
+    const warnings = [];
+
+    let html = null;
+    try {
+      html = fs.readFileSync(path.join(briefingDir, 'review.html'), 'utf8');
+    } catch {
+      issues.push(`review.html not found for briefing "${ctx.slug}" — run: aioson briefing:review . --slug=${ctx.slug}`);
+    }
+    if (html) {
+      if (!html.includes('aioson:review')) {
+        issues.push('review.html lacks the aioson:review marker (hand-rolled surface) — regenerate with `aioson briefing:review`');
+      }
+      if (!/id="download"/.test(html)) issues.push('review.html has no download fallback button (id="download")');
+      if (!/id="copy"/.test(html)) issues.push('review.html has no copy-JSON fallback button (id="copy")');
+      // User content is HTML-escaped by the generator (quotes become &quot;),
+      // so a real external reference can only be generator-emitted markup —
+      // match those forms only, or briefing text quoting HTML/CSS would
+      // false-positive the gate.
+      if (/<script[^>]+\bsrc=|<link[^>]+href=["']https?:|\bsrc=["']https?:/i.test(html)) {
+        issues.push('review.html references external resources — it must be fully self-contained');
+      }
+      const hashMatch = html.match(/source_hash=([0-9a-f]{64})/);
+      if (!hashMatch) {
+        issues.push('review.html has no embedded source_hash');
+      } else {
+        try {
+          const currentHash = hashText(fs.readFileSync(path.join(briefingDir, 'briefings.md'), 'utf8'));
+          if (hashMatch[1] !== currentHash) {
+            warnings.push('review.html is stale: source_hash differs from the current briefings.md — regenerate the review for the next round');
+          }
+        } catch {
+          issues.push('briefings.md not found next to review.html');
+        }
+      }
+    }
+
+    try {
+      const feedback = JSON.parse(fs.readFileSync(path.join(briefingDir, 'refinement-feedback.json'), 'utf8'));
+      const res = validateFeedback(feedback, { slug: ctx.slug, allowStale: true });
+      if (!res.ok) {
+        for (const err of res.errors) issues.push(`refinement-feedback.json: ${err}`);
+      }
+    } catch {
+      // Absent right after an apply (it gets archived) — only a warning.
+      warnings.push('refinement-feedback.json missing or unreadable — expected right after review generation');
+    }
+
+    return { ok: issues.length === 0, issues, warnings, checks: [{ id: `review:${ctx.slug}`, ok: issues.length === 0, detail: issues.join('; ') || null }] };
+  },
+
   // committer — advisory subject-quality audit. Reads --file if given, else the
   // HEAD commit message (post-commit, so the agent can amend before push).
   'commit-message': async (ctx) => {

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');
@@ -110,11 +111,26 @@ function isAgenticRequested(options = {}) {
     options.agentic ||
     options['agentic-run'] ||
     options.autopilot === 'agentic' ||
-    options.autopilot === 'runtime'
+    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;
 
@@ -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) {
+/**
+ * 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);
-  const existing = await readJsonIfExists(statePath);
+  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,
@@ -312,23 +375,8 @@ async function seedFeatureWorkflowState(targetDir, slug, classification, startFr
 }
 
 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
-    };
-  }
+  const { existing, refusal } = await resolveExistingFeatureState(targetDir, slug);
+  if (refusal) return refusal;
 
   if (existing && existing.mode === 'feature' && existing.featureSlug === slug) {
     return {
@@ -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(),
@@ -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);
@@ -792,14 +847,18 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
     `--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
+    // 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.max_tester_correction_cycles !== DEFAULT_AGENTIC_MAX_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.max_pentester_correction_cycles !== DEFAULT_AGENTIC_MAX_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(' ');
@@ -854,6 +913,65 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
     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 = [];
   let activation = null;
   let currentStatus = statusSnapshot;

package/src/commands/workflow-next.js

@@ -16,6 +16,7 @@ const { logError, buildHealingPrompt } = require('../self-healing');
 const { validateHandoffProtocol } = require('../handoff-validator');
 const { readAutonomyProtocol, resolveEffectiveMode } = require('../autonomy-policy');
 const { readAgentManifest, buildAgentCapabilitySummary } = require('../agent-manifests');
+const { resolveAutopilotSignal } = require('../autopilot-signal');
 const { runMemoryReflectPrepare } = require('./memory-reflect-prepare');
 const { inspectStagedChanges } = require('../lib/git-commit-guard');
 const { emitSecurityRuntimeEvent } = require('../lib/security/runtime-events');
@@ -61,19 +62,18 @@ const DEFAULT_FEATURE_WORKFLOW_BY_CLASSIFICATION = {
   MEDIUM: ['product', 'orchestrator', 'dev', 'pentester', 'qa']
 };
 
-// Stages eligible for autopilot handoff (auto_handoff: true in project.context.md).
-// Two segments — see .aioson/docs/autopilot-handoff.md:
-//   1. analyst -> dev: deterministic pre-dev chain. Prompt-only clients stop
-//      before the first @dev entry; workflow:execute --agentic may resume it
-//      through a fresh checkpointed activation.
-//   2. post-dev review cycle: @dev → @qa → @tester/@pentester (when their @qa triggers
-//      fire) → @validator → STOPS before feature:close (human approves the close).
-// @product and @sheldon are intentionally absent: per config.md, upstream agents
-// (@briefing/@product/@sheldon) always hand off MANUALLY. In the lean lane
-// (product → sheldon → dev → qa) this means auto_handoff is a deliberate no-op
-// pre-dev — @sheldon is the only pre-dev agent and hands off by hand — and is
-// active only on the post-dev cycle (dev → qa). This is by design, not an omission.
+// Stages eligible for autopilot handoff — the FULL feature chain (see
+// .aioson/docs/autopilot-handoff.md). Activation = auto_handoff: true in
+// project.context.md OR the seeded scheme (resolveAutopilotSignal). Two segments:
+//   1. spec → dev chain: @product seeds the agentic scheme and invokes the spec
+//      authority (@sheldon lean / @orchestrator maestro), which crosses into
+//      @dev via the dev-state.md cold-start packet once its own gates/decisions
+//      are settled. Detour agents (analyst/architect/pm/...) chain only when an
+//      opt-in detour adds them to the active sequence.
+//   2. post-dev review cycle: @dev → @qa → @tester/@pentester (when their @qa
+//      triggers fire) → @validator → STOPS before feature:close (human gate).
 const AUTOPILOT_HANDOFF_STAGES = new Set([
+  'product', 'sheldon', 'orchestrator',
   'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'pm',
   'dev', 'qa', 'tester', 'pentester', 'validator'
 ]);
@@ -99,6 +99,14 @@ function isMaestroOrchestratorState(state) {
   return idx !== -1 && sequence[idx + 1] === 'dev';
 }
 
+// Lean lane (SMALL, sheldon → dev): @sheldon is the single spec authority.
+// Mirrors isLeanSheldonState in handoff-contract.js.
+function isLeanSheldonState(state) {
+  const sequence = Array.isArray(state && state.sequence) ? state.sequence.map(normalizeAgentName) : [];
+  const idx = sequence.indexOf('sheldon');
+  return idx !== -1 && sequence[idx + 1] === 'dev';
+}
+
 function buildDefaultWorkflowConfig() {
   return {
     version: 1,
@@ -376,6 +384,29 @@ async function validateStageArtifacts(targetDir, state, stage) {
     return true;
   }
 
+  if (stage === 'sheldon') {
+    // Lean lane (SMALL, sheldon → dev): @sheldon is the single spec authority —
+    // "done" once the collapsed spec package exists (mirrors the orchestrator
+    // maestro branch below; the handoff contract re-checks Gates A/B/C). Without
+    // this branch nothing ever marks the sheldon stage resolved, and a later
+    // `--complete=dev` computes `next: sheldon` — the state machine walking
+    // BACKWARDS into the spec agent after implementation.
+    if (state.mode === 'feature' && slug && isLeanSheldonState(state)) {
+      const designDoc = [path.join(base, `design-doc-${slug}.md`), path.join(base, 'design-doc.md')];
+      const readiness = [path.join(base, `readiness-${slug}.md`), path.join(base, 'readiness.md')];
+      return (await exists(path.join(base, `sheldon-enrichment-${slug}.md`)))
+        && (await exists(path.join(base, `requirements-${slug}.md`)))
+        && (await exists(path.join(base, `spec-${slug}.md`)))
+        && (await exists(path.join(base, `implementation-plan-${slug}.md`)))
+        && (await anyExists(designDoc))
+        && (await anyExists(readiness));
+    }
+    if (state.mode === 'feature' && slug) {
+      return await exists(path.join(base, `sheldon-enrichment-${slug}.md`));
+    }
+    return await exists(path.join(base, 'sheldon-enrichment.md'));
+  }
+
   if (stage === 'orchestrator') {
     // Maestro lane (MEDIUM, orchestrator → dev): the orchestrator is the single
     // spec authority — "done" once the gated spec package exists (mirrors how the
@@ -519,7 +550,10 @@ function isInferableStage(stage) {
   // 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(
+  // sheldon (lean lane) and orchestrator (maestro lane) are the single spec
+  // authorities — both inferable from their collapsed spec package so stale-state
+  // recovery and mid-lane seeding never re-activate a finished spec stage.
+  return ['setup', 'product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'ux-ui', 'pm', 'sheldon', 'orchestrator'].includes(
     normalizeAgentName(stage)
   );
 }
@@ -993,8 +1027,15 @@ async function finalizeCurrentStage(targetDir, config, state, stageName) {
     detour: null
   });
 
+  // Reconcile eagerly: completing a later stage must never leave `next` pointing
+  // at an earlier unresolved stage (e.g. lean-lane sheldon that only chained via
+  // prompt). Without this, `--complete=dev` re-activated the spec agent and the
+  // reconcile only healed on the NEXT load — after the backwards activation had
+  // already been printed and persisted.
+  const reconciled = reconcileWorkflowState(nextState);
+
   return {
-    state: nextState,
+    state: reconciled.changed ? reconciled.state : nextState,
     completedStage: normalizedStage,
     ...(auditCodeSummary ? { auditCode: auditCodeSummary } : {})
   };
@@ -1560,9 +1601,12 @@ async function activateStage(
     state.mode === 'feature' &&
     (state.classification === 'SMALL' || state.classification === 'MEDIUM')
   ) {
+    // Frontmatter flag OR the seeded scheme (slug-scoped) — the per-feature
+    // "Autopilot" choice only seeds workflow-execute.json and never writes
+    // auto_handoff, so reading the frontmatter alone silently disabled it.
     try {
-      const projectContext = await validateProjectContextFile(targetDir);
-      autoHandoff = Boolean(projectContext && projectContext.data && projectContext.data.auto_handoff === true);
+      const signal = await resolveAutopilotSignal(targetDir, { slug: state.featureSlug });
+      autoHandoff = signal.enabled;
     } catch {
       autoHandoff = false;
     }