@jaimevalasek/aioson 1.36.0 → 1.37.1

package/src/commands/workflow-execute.js

@@ -8,7 +8,8 @@
  */
 
 const fs = require('node:fs/promises');
-const path = require('node:path');
+const path = require('node:path');
+const { initManifest, loadManifest } = require('../agent-execution/manifest');
 const {
   detectClassification,
   scanArtifacts,
@@ -27,6 +28,7 @@ const { readHandoff, readHandoffProtocol } = require('../session-handoff');
 const {
   STATE_RELATIVE_PATH,
   buildDefaultWorkflowConfig,
+  detectWorkflowMode,
   readWorkflowConfig,
   runWorkflowNext
 } = require('./workflow-next');
@@ -110,11 +112,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 +246,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 +273,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 +293,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 +376,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 +588,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(),
@@ -699,9 +752,12 @@ async function performRunnerTransition(targetDir, suggestion, tool, requestedMod
 async function runWorkflowExecute({ args, options = {}, logger }) {
   const targetDir = path.resolve(process.cwd(), args[0] || '.');
   const slug = options.feature ? String(options.feature).trim() : null;
-  const tool = options.tool ? String(options.tool).trim() : 'claude';
+  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);
@@ -733,9 +789,20 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
     return failure;
   }
 
-  const parallelGuard = laneIndex !== null
+  const parallelGuard = laneIndex !== null
     ? await runLaneGuardPreflight(targetDir, laneIndex)
-    : null;
+    : null;
+
+  let agentExecution = await loadManifest(targetDir, slug);
+  if (!dryRun && !agentExecution.exists) {
+    await initManifest(targetDir, slug, tool);
+    agentExecution = await loadManifest(targetDir, slug);
+  }
+  if (agentExecution.exists && !agentExecution.ok) {
+    const failure = { ok: false, reason: 'agent_execution_manifest_invalid', errors: agentExecution.errors, manifest_path: agentExecution.path };
+    if (!options.json) logger.error(`Invalid agent execution manifest: ${agentExecution.path}`);
+    return failure;
+  }
 
   if (parallelGuard && !parallelGuard.ok && !parallelGuard.skipped) {
     if (parallelGuard.reason === 'lane_not_found') {
@@ -792,14 +859,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(' ');
@@ -823,7 +894,8 @@ async function runWorkflowExecute({ args, options = {}, logger }) {
       status_snapshot: statusSnapshot,
       suggestion: statusSnapshot && statusSnapshot.suggestion ? statusSnapshot.suggestion : null,
       resume_command: resumeCommand,
-      agentic_policy: agenticPolicy,
+      agentic_policy: agenticPolicy,
+      agent_execution: agentExecution.exists ? { path: agentExecution.path, digest: agentExecution.digest } : { source: 'legacy' },
       parallel_guard: parallelGuard
     };
 
@@ -854,6 +926,66 @@ 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,
+      agent_execution: { path: agentExecution.path, digest: agentExecution.digest },
+      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;
     }

package/src/doctor.js

@@ -228,8 +228,10 @@ async function runDoctor(targetDir) {
   }
 
   // Autopilot handoff: protocol doc installed but flag never declared in the
-  // context frontmatter — autopilot stays silently inactive (absent = manual
-  // handoffs). An explicit true/false is a deliberate choice and passes.
+  // context frontmatter. Absent is no longer "silently manual" — @product asks
+  // the run mode on screen at each feature kickoff. Declaring an explicit
+  // true/false sets a project default (skip the kickoff question) and passes;
+  // the advisory just surfaces that a default can be set.
   const autopilotDocExists = await exists(path.join(targetDir, '.aioson/docs/autopilot-handoff.md'));
   if (autopilotDocExists && contextValidation.exists && contextValidation.data) {
     const autoHandoffDeclared = Object.prototype.hasOwnProperty.call(contextValidation.data, 'auto_handoff');

package/src/harness/criteria-runner.js

@@ -16,7 +16,10 @@
 
 const crypto = require('node:crypto');
 
-const DEFAULT_CHECK_TIMEOUT_MS = 120000;
+// Repository-wide quality gates can legitimately exceed two minutes on
+// Windows. Keep the CLI --timeout override, but give deterministic contract
+// checks enough headroom to avoid classifying a healthy full suite as failed.
+const DEFAULT_CHECK_TIMEOUT_MS = 300000;
 
 /**
  * Normaliza uma linha de erro para assinatura estável (D7):

package/src/i18n/messages/en.js

@@ -412,6 +412,7 @@ module.exports = {
   update: {
     not_installed: 'No AIOSON installation found in {targetDir}.',
     done_at: 'Update completed at: {targetDir}',
+    template_version: 'Template version applied: {version}',
     files_updated: 'Files updated: {count}',
     backups_created: 'Backups created: {count}',
     profile_renamed: 'i Profile `beginner` renamed to `creator` in project.context.md to better describe the user. Behavior unchanged. Edit the file to switch to `developer` if desired.',
@@ -491,7 +492,7 @@ module.exports = {
     features_dir_present: 'Features directory present (.aioson/context/features/)',
     features_dir_present_hint: 'Create .aioson/context/features/ to host per-feature dossiers (doctor --fix will create it).',
     auto_handoff_declared: 'Autopilot handoff flag declared (auto_handoff in project.context.md)',
-    auto_handoff_declared_hint: 'The autopilot-handoff protocol is installed but auto_handoff is not set in project.context.md frontmatter — autopilot stays inactive. Set auto_handoff: true to enable it, or auto_handoff: false to silence this warning.',
+    auto_handoff_declared_hint: 'The autopilot-handoff protocol is installed and auto_handoff is not set — @product asks the run mode on screen at each feature kickoff (Autopilot / Step by step / Always). Set auto_handoff: true to always autopilot and skip the question, or false to always go step-by-step.',
     claude_commands_present: 'Claude slash commands present ({missing} missing of {required})',
     claude_commands_present_hint: 'Missing: {paths}. Run `aioson doctor . --fix` to restore them from the template.',
     version_drift: 'CLI version matches project.context.md (context: {context}, CLI: {cli})',

package/src/i18n/messages/es.js

@@ -280,6 +280,7 @@ module.exports = {
   update: {
     not_installed: 'No se encontro instalacion de AIOSON en {targetDir}.',
     done_at: 'Actualizacion completada en: {targetDir}',
+    template_version: 'Version de template aplicada: {version}',
     files_updated: 'Archivos actualizados: {count}',
     backups_created: 'Backups creados: {count}',
     profile_renamed: 'i Perfil `beginner` renombrado a `creator` en project.context.md para describir mejor al usuario. Comportamiento sin cambios. Edita el archivo para cambiar a `developer` si lo prefieres.',
@@ -365,7 +366,7 @@ module.exports = {
     features_dir_present: 'Directorio de features presente (.aioson/context/features/)',
     features_dir_present_hint: 'Cree .aioson/context/features/ para hospedar dossiers por feature (doctor --fix lo crea).',
     auto_handoff_declared: 'Flag de autopilot handoff declarada (auto_handoff en project.context.md)',
-    auto_handoff_declared_hint: 'El protocolo autopilot-handoff esta instalado pero auto_handoff no esta definido en el frontmatter de project.context.md — el autopilot queda inactivo. Defina auto_handoff: true para activarlo, o auto_handoff: false para silenciar este aviso.',
+    auto_handoff_declared_hint: 'El protocolo autopilot-handoff esta instalado y auto_handoff no esta definido — @product pregunta el modo en pantalla al inicio de cada feature (Autopilot / Paso a paso / Siempre). Defina auto_handoff: true para siempre autopilot y omitir la pregunta, o false para siempre paso a paso.',
     claude_commands_present: 'Slash commands de Claude presentes ({missing} ausentes de {required})',
     claude_commands_present_hint: 'Ausentes: {paths}. Ejecute `aioson doctor . --fix` para restaurarlos.',
     version_drift: 'Version del CLI coincide con project.context.md (contexto: {context}, CLI: {cli})',

package/src/i18n/messages/fr.js

@@ -279,6 +279,7 @@ module.exports = {
   update: {
     not_installed: 'Aucune installation AIOSON trouvee dans {targetDir}.',
     done_at: 'Mise a jour terminee dans : {targetDir}',
+    template_version: 'Version du template appliquee : {version}',
     files_updated: 'Fichiers mis a jour : {count}',
     backups_created: 'Sauvegardes creees : {count}',
     profile_renamed: 'i Profil `beginner` renomme en `creator` dans project.context.md pour mieux decrire l utilisateur. Comportement inchange. Modifiez le fichier pour passer a `developer` si vous le souhaitez.',
@@ -364,7 +365,7 @@ module.exports = {
     features_dir_present: 'Repertoire features present (.aioson/context/features/)',
     features_dir_present_hint: 'Creez .aioson/context/features/ pour heberger les dossiers par feature (doctor --fix le cree).',
     auto_handoff_declared: 'Flag autopilot handoff declare (auto_handoff dans project.context.md)',
-    auto_handoff_declared_hint: 'Le protocole autopilot-handoff est installe mais auto_handoff n\'est pas defini dans le frontmatter de project.context.md — l\'autopilot reste inactif. Definissez auto_handoff: true pour l\'activer, ou auto_handoff: false pour faire taire cet avertissement.',
+    auto_handoff_declared_hint: 'Le protocole autopilot-handoff est installe et auto_handoff n\'est pas defini — @product demande le mode a l\'ecran au debut de chaque feature (Autopilot / Pas a pas / Toujours). Definissez auto_handoff: true pour toujours autopilot et sauter la question, ou false pour toujours pas a pas.',
     claude_commands_present: 'Slash commands de Claude presents ({missing} absents sur {required})',
     claude_commands_present_hint: 'Absents : {paths}. Executez `aioson doctor . --fix` pour les restaurer.',
     version_drift: 'Version du CLI conforme a project.context.md (contexte : {context}, CLI : {cli})',

package/src/i18n/messages/pt-BR.js

@@ -379,6 +379,7 @@ module.exports = {
   update: {
     not_installed: 'Nenhuma instalacao do AIOSON encontrada em {targetDir}.',
     done_at: 'Atualizacao concluida em: {targetDir}',
+    template_version: 'Versao do template aplicada: {version}',
     files_updated: 'Arquivos atualizados: {count}',
     backups_created: 'Backups criados: {count}',
     profile_renamed: 'i Perfil `beginner` renomeado para `creator` em project.context.md para descrever melhor o usuario. Comportamento inalterado. Edite o arquivo para mudar para `developer` se preferir.',
@@ -465,7 +466,7 @@ module.exports = {
     features_dir_present: 'Diretorio de features presente (.aioson/context/features/)',
     features_dir_present_hint: 'Crie .aioson/context/features/ para hospedar dossies por feature (doctor --fix cria automaticamente).',
     auto_handoff_declared: 'Flag de autopilot handoff declarada (auto_handoff no project.context.md)',
-    auto_handoff_declared_hint: 'O protocolo autopilot-handoff esta instalado mas auto_handoff nao esta definido no frontmatter do project.context.md — o autopilot fica inativo. Defina auto_handoff: true para ativar, ou auto_handoff: false para silenciar este aviso.',
+    auto_handoff_declared_hint: 'O protocolo autopilot-handoff esta instalado e auto_handoff nao esta definido — o @product pergunta o modo na tela no inicio de cada feature (Autopilot / Passo a passo / Sempre). Defina auto_handoff: true para sempre autopilot e pular a pergunta, ou false para sempre passo a passo.',
     claude_commands_present: 'Slash commands do Claude presentes ({missing} ausentes de {required})',
     claude_commands_present_hint: 'Ausentes: {paths}. Rode `aioson doctor . --fix` para restaurar a partir do template.',
     version_drift: 'Versao do CLI bate com project.context.md (contexto: {context}, CLI: {cli})',

package/src/lib/briefing-refiner/apply-feedback.js

@@ -39,7 +39,10 @@ function summarizeSkippedChanges(feedback) {
   return [...sectionChanges, ...decisionChanges];
 }
 
-async function applyDeclinedFeedback(projectDir, slug, feedback, { allowStale = false } = {}) {
+// Declining never writes to briefings.md, so a stale source hash is irrelevant
+// to safety — validating it would only dead-end the user whose briefing moved
+// on. Hence allowStale defaults to TRUE here (and only here).
+async function applyDeclinedFeedback(projectDir, slug, feedback, { allowStale = true } = {}) {
   const briefingPath = resolveBriefingPath(projectDir, slug, 'briefings.md');
   const currentMarkdown = await fs.readFile(briefingPath, 'utf8');
   const currentSourceHash = hashText(currentMarkdown);
@@ -57,10 +60,12 @@ async function applyDeclinedFeedback(projectDir, slug, feedback, { allowStale =
     source_hash: feedback.source_hash,
     applied_hash: currentSourceHash,
     status: 'declined',
+    round: feedback.round || 1,
     applied_changes: [],
     skipped_changes: skippedChanges,
     unresolved_comments: unresolvedComments,
     blocking_items: feedback.blocking_items || [],
+    findings: feedback.findings || [],
     next_action: 'rerun_review'
   });
 
@@ -104,15 +109,22 @@ async function applyConfirmedFeedback(projectDir, slug, feedback, { confirmed =
   if (returnedToDraft) {
     returnApprovedBriefingToDraft(registry, slug);
   }
+  // A blocking finding the user left pending blocks the PRD the same way an
+  // explicit blocking item does — even if the export step never mirrored it
+  // into blocking_items (hand-written feedback).
+  const pendingBlockingFindings = (feedback.findings || []).filter(
+    (finding) => finding.blocking && finding.status === 'pending'
+  );
+  const hasBlockers = (feedback.blocking_items || []).length > 0 || pendingBlockingFindings.length > 0;
   markRefinementState(registry, slug, {
-    refinement_status: feedback.blocking_items.length > 0 ? 'blocked' : 'applied',
+    refinement_status: hasBlockers ? 'blocked' : 'applied',
     review_html: `.aioson/briefings/${slug}/review.html`,
     refinement_report: `.aioson/briefings/${slug}/refinement-report.md`
   });
   await writeBriefingRegistry(projectDir, registry);
 
   const unresolvedComments = (feedback.comments || []).filter((comment) => !comment.resolved);
-  const nextAction = feedback.blocking_items.length > 0 ? 'resolve_blockers' : 'approve_briefing';
+  const nextAction = hasBlockers ? 'resolve_blockers' : 'approve_briefing';
   const report = buildRefinementReport({
     briefing_slug: slug,
     source_briefing_path: `.aioson/briefings/${slug}/briefings.md`,
@@ -120,15 +132,17 @@ async function applyConfirmedFeedback(projectDir, slug, feedback, { confirmed =
     source_hash: feedback.source_hash,
     applied_hash: appliedHash,
     status: 'applied',
+    round: feedback.round || 1,
     applied_changes: appliedChanges,
     skipped_changes: [],
     unresolved_comments: unresolvedComments,
     blocking_items: feedback.blocking_items || [],
+    findings: feedback.findings || [],
     next_action: nextAction
   });
   await fs.writeFile(resolveBriefingPath(projectDir, slug, 'refinement-report.md'), report, 'utf8');
 
-  return { ok: true, appliedChanges, nextAction, appliedHash, returnedToDraft };
+  return { ok: true, appliedChanges, nextAction, appliedHash, returnedToDraft, pendingBlockingFindings: pendingBlockingFindings.length };
 }
 
 module.exports = { applyConfirmedFeedback, applyDeclinedFeedback };