openfeel 1.2.1 → 1.2.3

package/dist/commands/flow.js

@@ -1,15 +1,16 @@
 import { execSync } from 'node:child_process';
 import { existsSync, copyFileSync, readFileSync, rmSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { FlowManager, isFlowConcurrentError, normalizeAgentName, detectFillState, MODE_DERIVED_TIER, PHASE_PATH_MAX_DEPTH } from '../core/flow-manager.js';
-import { PipelinePhaseSchema, PIPELINE_PHASES, REVIEW_TIERS, TIER_PRUNED_PHASES } from '../core/pipeline-schema.js';
+import { FlowManager, isFlowConcurrentError, normalizeAgentName, detectFillState, MODE_DERIVED_TIER, listStageBlockingOpenReviews, PHASE_PATH_MAX_DEPTH } from '../core/flow-manager.js';
+import { PipelinePhaseSchema, PIPELINE_PHASES, REVIEW_TIERS, TIER_PRUNED_PHASES, DEFAULT_EFFECTIVE_REVIEW_TIER } from '../core/pipeline-schema.js';
 import { validateStageId, suggestStageId, normalizeStageId, findStageStatusPath, isArchivedVersionOf } from '../core/plan/path.js';
 import { getConfigFieldLegalValues, setConfigValue } from '../core/config.js';
 import { parse as parseYaml } from 'yaml';
 import { MetricsStore, PHASE_AGENT_MAP } from '../core/metrics.js';
 import { runtimeLog } from '../core/runtime-log.js';
 import { addReviewEntry } from '../core/view/entry.js';
-import { handleAddStageError, handleConcurrentConflict } from './shared/errors.js';
+import { failCli, failInternal, handleAddStageError, handleConcurrentConflict } from './shared/errors.js';
+import { withSchemaVersion, isJsonMode, emitJson } from './shared/json-output.js'; // JSON 契约助手（stage-95 op-001/op-002）
 import { t, getCliLang } from '../core/i18n.js';
 import { ARCHIVE_SCHEMA_VERSION } from '../core/flow-archive/archive-file.js';
 import { listArchivableCandidates, listBlockingOpenRevsForVersion, splitForArchive } from '../core/flow-archive/grouping.js';
@@ -142,6 +143,109 @@ export function registerFlowCommand(program) {
             }
         }
     });
+    // flow next — 当前阶段调度决策（只读；P0-1）
+    flow
+        .command('next')
+        .description('显示当前阶段的调度决策（负责 Agent / 合法下一相位 / 建议命令 / 守卫 / 阻塞项；只读）')
+        .option('--json', 'Output as JSON (machine-readable, single JSON document)')
+        .action(() => {
+        const lang = getCliLang(process.cwd());
+        const mgr = createManager();
+        if (!mgr.isLoaded()) {
+            const message = t('common.errorNoInit', lang);
+            failCli({ code: 'NO_INIT', message, detail: null, stderrLines: [message] });
+            return;
+        }
+        const data = mgr.getData();
+        const rawStage = data.pipeline.current.stage || '';
+        // 双键回退（与 core resolveCurrentPhase / advanceStagePhase 同范式）：归一化键优先，其次原始键
+        const normalized = rawStage ? (normalizeStageId(rawStage) ?? rawStage) : '';
+        const activeKey = rawStage
+            ? (data.stages[normalized] ? normalized : (data.stages[rawStage] ? rawStage : null))
+            : null;
+        let phase = null;
+        let phaseLabel = null;
+        let responsibleAgent = 'feel'; // 无活跃阶段显式约定
+        let workflowMode = null;
+        let reviewTier = null;
+        let effectiveReviewTier = null;
+        let legalNextPhases = [];
+        let suggestedCommand = null;
+        const guards = [];
+        let blockingReviews = [];
+        if (activeKey) {
+            const currentPhase = data.stages[activeKey].phase;
+            phase = currentPhase;
+            phaseLabel = mgr.getPhaseLabels(lang)[currentPhase] ?? currentPhase;
+            responsibleAgent = mgr.getResponsibleAgent(currentPhase);
+            workflowMode = mgr.resolveStageWorkflowMode(activeKey).value;
+            reviewTier = MODE_DERIVED_TIER[workflowMode];
+            effectiveReviewTier = DEFAULT_EFFECTIVE_REVIEW_TIER;
+            legalNextPhases = mgr.getAvailablePhases(activeKey);
+            suggestedCommand = legalNextPhases.length > 0
+                ? `openfeel flow advance --stage ${activeKey} --to ${legalNextPhases[0]}`
+                : null;
+            blockingReviews = listStageBlockingOpenReviews(data.reviews, activeKey).map((r) => ({
+                id: r.id, title: r.title, priority: r.priority, op: r.op,
+            }));
+            // 守卫顺序契约固定（§12.1）：auto-advance → blocking → 无目标 → 档位差
+            if (mgr.resolveEffectiveConfig()['auto_advance']?.value === 'disabled') {
+                guards.push(t('flow.next.guardAutoAdvanceDisabled', lang));
+            }
+            if (blockingReviews.length > 0) {
+                guards.push(t('flow.next.guardBlockingReviewsTmpl', lang, { n: String(blockingReviews.length) }));
+            }
+            if (legalNextPhases.length === 0) {
+                guards.push(t('flow.next.guardNoLegalTargets', lang));
+            }
+            if (reviewTier !== effectiveReviewTier) {
+                guards.push(t('flow.next.guardTierDiffTmpl', lang, { display: reviewTier, effective: effectiveReviewTier }));
+            }
+        }
+        else {
+            guards.push(t('flow.next.guardNoActiveStage', lang));
+        }
+        const doc = withSchemaVersion({
+            stage: activeKey ?? (rawStage || null),
+            phase,
+            phaseLabel,
+            responsibleAgent,
+            workflowMode,
+            reviewTier,
+            effectiveReviewTier,
+            legalNextPhases,
+            suggestedCommand,
+            guards,
+            blockingReviews,
+        });
+        // JSON 模式单点（stage-95 不变量 2）：命令层只读 isJsonMode()
+        if (isJsonMode()) {
+            emitJson(doc);
+            return;
+        }
+        // 人类输出（逐行标签；空值统一 t('common.none', lang)）
+        console.log(t('flow.next.title', lang));
+        console.log(`  ${t('flow.next.stageLabel', lang)}: ${doc.stage ?? t('common.none', lang)}`);
+        console.log(`  ${t('flow.next.phaseLabel', lang)}: ${doc.phase ?? t('common.none', lang)}${doc.phaseLabel ? ` (${doc.phaseLabel})` : ''}`);
+        console.log(`  ${t('flow.next.responsibleAgentLabel', lang)}: ${doc.responsibleAgent}`);
+        console.log(`  ${t('flow.next.workflowModeLabel', lang)}: ${doc.workflowMode ?? t('common.none', lang)}`);
+        console.log(`  ${t('flow.next.displayTierLabel', lang)}: ${doc.reviewTier ?? t('common.none', lang)}`);
+        console.log(`  ${t('flow.next.effectiveTierLabel', lang)}: ${doc.effectiveReviewTier ?? t('common.none', lang)}`);
+        console.log(`  ${t('flow.next.legalNextPhasesLabel', lang)}: ${doc.legalNextPhases.length > 0 ? `[${doc.legalNextPhases.join(', ')}]` : t('common.none', lang)}`);
+        console.log(`  ${t('flow.next.suggestedCommandLabel', lang)}: ${doc.suggestedCommand ?? t('common.none', lang)}`);
+        if (doc.guards.length > 0) {
+            console.log(`  ${t('flow.next.guardsLabel', lang)}:`);
+            for (const g of doc.guards) {
+                console.log(`    - ${g}`);
+            }
+        }
+        if (doc.blockingReviews.length > 0) {
+            console.log(`  ${t('flow.next.blockingReviewsLabel', lang)}:`);
+            for (const r of doc.blockingReviews) {
+                console.log(`    - ${t('flow.next.blockingReviewItemTmpl', lang, { id: r.id, title: r.title, priority: r.priority, op: r.op })}`);
+            }
+        }
+    });
     // flow overview — 全状态可视化（openfeel flow overview 的后端实现）
     flow
         .command('overview')
@@ -360,8 +464,13 @@ export function registerFlowCommand(program) {
         if (options.mode !== undefined) {
             const allowed = getConfigFieldLegalValues('workflow_mode') ?? [];
             if (!allowed.includes(options.mode)) {
-                console.error(t('stage.set.invalidValueTmpl', lang, { field: '工作流模式', value: options.mode, allowed: allowed.join(', ') }));
-                process.exit(1);
+                const message = t('stage.set.invalidValueTmpl', lang, { field: '工作流模式', value: options.mode, allowed: allowed.join(', ') });
+                failCli({
+                    code: 'INVALID_ARGUMENT',
+                    message,
+                    detail: { field: 'workflowMode', value: options.mode, allowed },
+                    stderrLines: [message],
+                });
                 return;
             }
             explicitMode = options.mode;
@@ -371,17 +480,15 @@ export function registerFlowCommand(program) {
         if (options.stage !== undefined) {
             const v = validateStageId(options.stage);
             if (!v.ok) {
-                console.error(t('common.stageIdInvalidTmpl', lang, { input: options.stage }));
-                console.error(t('common.stageIdSuggestTmpl', lang, { suggest: suggestStageId(projectPath, options.stage) }));
-                process.exit(1);
+                const stderrLines = stageIdErrorLines(lang, projectPath, options.stage);
+                failCli({ code: 'INVALID_ARGUMENT', message: stderrLines[0], detail: { stage: options.stage }, stderrLines });
                 return;
             }
             stageArg = normalizeStageId(options.stage) ?? options.stage;
             const known = new Set(Object.keys(mgr.isLoaded() ? mgr.getData().stages : {}).map((k) => normalizeStageId(k) ?? k));
             if (!known.has(stageArg) && !findStageStatusPath(projectPath, stageArg)) {
-                console.error(t('common.stageIdInvalidTmpl', lang, { input: options.stage }));
-                console.error(t('common.stageIdSuggestTmpl', lang, { suggest: suggestStageId(projectPath, options.stage) }));
-                process.exit(1);
+                const stderrLines = stageIdErrorLines(lang, projectPath, options.stage);
+                failCli({ code: 'STAGE_NOT_FOUND', message: stderrLines[0], detail: { stage: options.stage }, stderrLines });
                 return;
             }
         }
@@ -401,7 +508,9 @@ export function registerFlowCommand(program) {
             // advanceAccepted = 内置 15 phase（flow advance 的推进白名单），与 phases（运行时存在视图，可含自定义）显式区分
             // 既有三字段（phases/transitions/advanceAccepted）+ transitionsDiff 逐字保留；schemaVersion 与 workflowMode 追加于末位（B1-6 / stage-75 op-002）
             // reviewTier 再追加于末位（stage-92 op-001；既有 6 键逐字保留、顺序不变）
-            console.log(JSON.stringify({ schemaVersion: 1, phases, transitions, advanceAccepted: [...PIPELINE_PHASES], transitionsDiff, workflowMode: derivedMode, reviewTier: MODE_DERIVED_TIER[derivedMode] }, null, 2));
+            // stage-96 op-002：末位再追加 displayReviewTier（与 reviewTier 同值显式名）与 effectiveReviewTier（推进缺省档位，恒 full）
+            const displayTier = MODE_DERIVED_TIER[derivedMode];
+            console.log(JSON.stringify({ schemaVersion: 1, phases, transitions, advanceAccepted: [...PIPELINE_PHASES], transitionsDiff, workflowMode: derivedMode, reviewTier: displayTier, displayReviewTier: displayTier, effectiveReviewTier: DEFAULT_EFFECTIVE_REVIEW_TIER }, null, 2));
             return;
         }
         console.log(t('flow.phases.title', lang));
@@ -456,18 +565,16 @@ export function registerFlowCommand(program) {
         if (options.stage !== undefined) {
             const v = validateStageId(options.stage);
             if (!v.ok) {
-                console.error(t('common.stageIdInvalidTmpl', lang, { input: options.stage }));
-                console.error(t('common.stageIdSuggestTmpl', lang, { suggest: suggestStageId(projectPath, options.stage) }));
-                process.exit(1);
+                const stderrLines = stageIdErrorLines(lang, projectPath, options.stage);
+                failCli({ code: 'INVALID_ARGUMENT', message: stderrLines[0], detail: { stage: options.stage }, stderrLines });
                 return;
             }
             key = normalizeStageId(options.stage) ?? options.stage;
             // 存在性：已注册（flow.json）或有 status.md；二者皆无 → exit 1（防 typo 静默落 config 层）
             const known = new Set(Object.keys(mgr.isLoaded() ? mgr.getData().stages : {}).map((k) => normalizeStageId(k) ?? k));
             if (!known.has(key) && !findStageStatusPath(projectPath, key)) {
-                console.error(t('common.stageIdInvalidTmpl', lang, { input: options.stage }));
-                console.error(t('common.stageIdSuggestTmpl', lang, { suggest: suggestStageId(projectPath, options.stage) }));
-                process.exit(1);
+                const stderrLines = stageIdErrorLines(lang, projectPath, options.stage);
+                failCli({ code: 'STAGE_NOT_FOUND', message: stderrLines[0], detail: { stage: options.stage }, stderrLines });
                 return;
             }
         }
@@ -599,9 +706,10 @@ export function registerFlowCommand(program) {
             console.log(t('flow.stage.remove.okTmpl', lang, { stage: stageArg }));
         }
         catch (err) {
-            // 并发写冲突：统一单点（i18n 文案 + 退出码 2）；其余走通用错误
+            // 并发写冲突：统一单点（i18n 文案 + 退出码 2）；JSON 模式置码返回 → 显式 return 防落入通用分支
             if (isFlowConcurrentError(err)) {
                 handleConcurrentConflict(err, lang);
+                return;
             }
             const msg = err instanceof Error ? err.message : String(err);
             console.error(t('common.errorTmpl', lang, { msg }));
@@ -658,8 +766,10 @@ export function registerFlowCommand(program) {
             mgr.setStageDeps(stageId, deps);
         }
         catch (err) {
+            // 并发写冲突：统一单点（i18n 文案 + 退出码 2）；JSON 模式置码返回 → 显式 return 防落入通用分支
             if (isFlowConcurrentError(err)) {
                 handleConcurrentConflict(err, lang);
+                return;
             }
             const msg = err instanceof Error ? err.message : String(err);
             console.error(t('common.errorTmpl', lang, { msg }));
@@ -710,9 +820,10 @@ export function registerFlowCommand(program) {
             }));
         }
         catch (err) {
-            // 并发写冲突：统一单点（i18n 文案 + 退出码 2）；其余走通用错误
+            // 并发写冲突：统一单点（i18n 文案 + 退出码 2）；JSON 模式置码返回 → 显式 return 防落入通用分支
             if (isFlowConcurrentError(err)) {
                 handleConcurrentConflict(err, lang);
+                return;
             }
             const msg = err instanceof Error ? err.message : String(err);
             console.error(t('common.errorTmpl', lang, { msg }));
@@ -728,32 +839,49 @@ export function registerFlowCommand(program) {
         .option('--stage <id>', '阶段 ID（如 stage-03），必须指定')
         .option('--force', '强制执行（跳过非法 phase 校验和阶段跳跃检查，但不可绕过 REV 阻塞检查）')
         .option('--dry-run', '仅验证不执行修改（预览输出）。与 --force 组合时跳过校验但仍不执行修改')
-        .option('--review-tier <tier>', '审查档位（full / lean / skip；缺省=按模式派生；仅显式声明时裁剪审查关，不可绕过 REV 阻塞检查）')
+        .option('--review-tier <tier>', '审查档位（full / lean / skip；缺省=full（零裁剪）；仅显式声明时裁剪审查关，不可绕过 REV 阻塞检查）')
+        .option('--json', '以 JSON 输出错误封装（仅失败时；成功输出保持人类文本）')
         .option('--quiet', '静默非错误输出（成功确认与 Git 警告均不打印）')
         .action((options) => {
         const lang = getCliLang(process.cwd());
+        // JSON 模式（--json 为错误封装开关）下，失败前的人类进展行改走 stderr，保证 stdout 仅一个 envelope；
+        // 成功路径的人类输出保持 console.log（advance 成功不 JSON 化，契约 §7/§8）。
+        const info = (line) => {
+            if (isJsonMode()) {
+                console.error(line);
+                return;
+            }
+            console.log(line);
+        };
         // 自定义 --stage 必选校验（提供中文错误提示）
         if (!options.stage) {
-            console.error(t('flow.advance.errorNoStage', lang));
-            process.exit(1);
+            const message = t('flow.advance.errorNoStage', lang);
+            failCli({ code: 'INVALID_ARGUMENT', message, detail: { required: '--stage' }, stderrLines: [message] });
+            return;
         }
         // 审查档位值域校验（stage-92 op-001；fail-fast 且**先于任何取值 / 路径解析 / autoRepair 写盘**）
         // 复用 stage.set.invalidValueTmpl（与 flow phases --mode 同款，零新增键）；非法 → exit 1 零写盘
         let explicitTier;
         if (options.reviewTier !== undefined) {
             if (!REVIEW_TIERS.includes(options.reviewTier)) {
-                console.error(t('stage.set.invalidValueTmpl', lang, { field: '审查档位', value: options.reviewTier, allowed: REVIEW_TIERS.join(', ') }));
-                process.exit(1);
+                const message = t('stage.set.invalidValueTmpl', lang, { field: '审查档位', value: options.reviewTier, allowed: REVIEW_TIERS.join(', ') });
+                failCli({
+                    code: 'INVALID_ARGUMENT',
+                    message,
+                    detail: { field: 'reviewTier', value: options.reviewTier, allowed: REVIEW_TIERS },
+                    stderrLines: [message],
+                });
                 return;
             }
             explicitTier = options.reviewTier;
         }
-        // 生效档位：显式声明 ?? full（**不传 = 零裁剪**；派生档仅用于 `flow phases` 展示与提示，不改变推进语义）
-        const effTier = explicitTier ?? 'full';
+        // 生效档位：显式声明 ?? DEFAULT_EFFECTIVE_REVIEW_TIER（**不传 = 零裁剪**；派生档仅用于 `flow phases` 展示与提示，不改变推进语义）
+        const effTier = explicitTier ?? DEFAULT_EFFECTIVE_REVIEW_TIER;
         const mgr = createManager();
         if (!mgr.isLoaded()) {
-            console.error(t('common.errorNoInit', lang));
-            process.exit(1);
+            const message = t('common.errorNoInit', lang);
+            failCli({ code: 'NO_INIT', message, detail: null, stderrLines: [message] });
+            return;
         }
         // REV-005：命令层归一化（短名 → 全名），与 plan.ts / flow.ts 其它 stage 解析点同范式
         const stageArg = normalizeStageId(options.stage) ?? options.stage;
@@ -762,7 +890,8 @@ export function registerFlowCommand(program) {
             // B1 修复：dry-run 走预览模式（不写内存/不写盘），仅在非 dry-run 时 save()
             const repairResult = mgr.autoRepairInconsistency(stageArg, { dryRun: options.dryRun });
             if (repairResult.fixed) {
-                console.log(options.dryRun
+                // JSON 模式下改走 stderr（失败时 stdout 仅保留一个 envelope）
+                info(options.dryRun
                     ? t('flow.advance.autoRepairPreview', lang) + `: ${repairResult.detail}`
                     : t('flow.advance.autoRepaired', lang) + `: ${repairResult.detail}`);
                 if (!options.dryRun) {
@@ -776,23 +905,35 @@ export function registerFlowCommand(program) {
             for (const w of warnings) {
                 console.warn(`[WARN] ${w}`);
             }
-            console.log(t('flow.advance.warnAutoCorrect', lang));
+            // JSON 模式下改走 stderr（失败时 stdout 仅保留一个 envelope）
+            info(t('flow.advance.warnAutoCorrect', lang));
         }
         if (!valid) {
-            console.error(t('flow.advance.errorInvalidFormat', lang));
-            for (const err of errors) {
-                console.error(`  - ${err}`);
-            }
-            process.exit(1);
+            const message = t('flow.advance.errorInvalidFormat', lang);
+            failCli({
+                code: 'INVALID_ARGUMENT',
+                message,
+                detail: { errors },
+                stderrLines: [message, ...errors.map((e) => '  - ' + e)],
+            });
+            return;
         }
         // 非法 phase 校验（P1）：拒绝不在枚举中的目标 phase；--force 可跳过此项，但不可绕过 REV 阻塞检查
         if (!options.force) {
             const phaseResult = PipelinePhaseSchema.safeParse(options.to);
             if (!phaseResult.success) {
-                console.error(t('flow.advance.errorInvalidPhaseTmpl', lang, { phase: options.to }));
-                console.error(t('flow.advance.labelValidPhases', lang) + `: [${PIPELINE_PHASES.join(', ')}]`);
-                console.error(t('flow.advance.hintUseForceFuzzy', lang));
-                process.exit(1);
+                const message = t('flow.advance.errorInvalidPhaseTmpl', lang, { phase: options.to });
+                failCli({
+                    code: 'PHASE_TRANSITION_ILLEGAL',
+                    message,
+                    detail: { stage: stageArg, to: options.to, allowed: [...PIPELINE_PHASES] },
+                    stderrLines: [
+                        message,
+                        t('flow.advance.labelValidPhases', lang) + `: [${PIPELINE_PHASES.join(', ')}]`,
+                        t('flow.advance.hintUseForceFuzzy', lang),
+                    ],
+                });
+                return;
             }
         }
         // 阶段路径解析（B5-1）：非 --force 时求「当前 phase → to」的唯一可达路径
@@ -806,36 +947,47 @@ export function registerFlowCommand(program) {
                 const data = mgr.getData();
                 const currentPhase = data?.stages[stageArg]?.phase ?? t('common.unknown', lang);
                 const availableTargets = mgr.getAvailablePhases(stageArg, effTier);
+                const stderrLines = [];
                 if (pathResult.reason === 'ambiguous') {
-                    console.error(t('flow.advance.ambiguousTmpl', lang));
+                    stderrLines.push(t('flow.advance.ambiguousTmpl', lang));
                 }
                 else if (pathResult.reason === 'depth-exceeded') {
-                    console.error(t('flow.advance.depthExceededTmpl', lang, { max: String(PHASE_PATH_MAX_DEPTH) }));
+                    stderrLines.push(t('flow.advance.depthExceededTmpl', lang, { max: String(PHASE_PATH_MAX_DEPTH) }));
                 }
                 else {
                     // general（无流水线）→ 显式错误引导（防御路径：常规写路径不产生 general 阶段态；REV-90-005 / D-90-3）
                     if (mgr.resolveStageWorkflowMode(stageArg).value === 'general') {
-                        console.error(t('flow.advance.generalNoPipeline', lang, { stage: stageArg }));
-                        process.exit(1);
+                        const message = t('flow.advance.generalNoPipeline', lang, { stage: stageArg });
+                        failCli({
+                            code: 'PHASE_PATH_NOT_FOUND',
+                            message,
+                            detail: { stage: stageArg, from: currentPhase, to: options.to, reason: pathResult.reason, targets: availableTargets },
+                            stderrLines: [message],
+                        });
                         return;
                     }
-                    console.error(t('flow.advance.noPathTmpl', lang, {
+                    stderrLines.push(t('flow.advance.noPathTmpl', lang, {
                         from: currentPhase,
                         to: options.to,
                         targets: availableTargets.length > 0 ? `[${availableTargets.join(', ')}]` : t('common.none', lang),
                     }));
                 }
                 // 保留既有跳转诊断（可达目标）——与现状一致
-                console.error(t('flow.advance.errorPhaseJumpTmpl', lang, { stage: stageArg, to: options.to }));
-                console.error(t('flow.advance.currentPhaseTmpl', lang, { phase: currentPhase }));
+                stderrLines.push(t('flow.advance.errorPhaseJumpTmpl', lang, { stage: stageArg, to: options.to }));
+                stderrLines.push(t('flow.advance.currentPhaseTmpl', lang, { phase: currentPhase }));
                 if (availableTargets.length > 0) {
-                    console.error(t('flow.advance.availableTargets', lang) + `: [${availableTargets.join(', ')}]`);
+                    stderrLines.push(t('flow.advance.availableTargets', lang) + `: [${availableTargets.join(', ')}]`);
                 }
                 else {
-                    console.error(t('flow.advance.noAvailableTargets', lang));
+                    stderrLines.push(t('flow.advance.noAvailableTargets', lang));
                 }
-                console.error(t('flow.advance.hintUseForce', lang));
-                process.exit(1);
+                stderrLines.push(t('flow.advance.hintUseForce', lang));
+                failCli({
+                    code: 'PHASE_PATH_NOT_FOUND',
+                    message: stderrLines[0],
+                    detail: { stage: stageArg, from: currentPhase, to: options.to, reason: pathResult.reason, targets: availableTargets },
+                    stderrLines,
+                });
                 return;
             }
             if (pathResult.reason === 'already-at-target') {
@@ -870,9 +1022,13 @@ export function registerFlowCommand(program) {
                 if (options.force) {
                     console.warn(t('flow.advance.forceRevRefused', lang));
                 }
-                console.error(t('flow.advance.blockingRevRefused', lang));
-                console.error(t('flow.advance.blockingRevHint', lang));
-                process.exit(1);
+                const message = t('flow.advance.blockingRevRefused', lang);
+                failCli({
+                    code: 'BLOCKING_REVIEWS',
+                    message,
+                    detail: { stage: stageArg, to: 'done', reviews: blockingOpen.map((r) => r.id) },
+                    stderrLines: [message, t('flow.advance.blockingRevHint', lang)],
+                });
                 return;
             }
         }
@@ -919,14 +1075,21 @@ export function registerFlowCommand(program) {
                 archived = mgr.advanceStagePhase(stageArg, next, 'cli', explicitTier ? { reviewTier: explicitTier } : undefined);
             }
             catch (err) {
+                const stderrLines = [];
                 if (totalSteps > 1) {
                     const remaining = phasePath.slice(i).join(t('flow.advance.pathArrow', lang));
                     const doneTo = i > 0 ? phasePath[i - 1] : t('common.none', lang);
-                    console.error(t('flow.advance.partialFailTmpl', lang, { done: doneTo, failed: next, remaining }));
+                    stderrLines.push(t('flow.advance.partialFailTmpl', lang, { done: doneTo, failed: next, remaining }));
                 }
                 const msg = err instanceof Error ? err.message : String(err);
-                console.error(t('common.errorTmpl', lang, { msg }));
-                process.exit(1);
+                const message = t('common.errorTmpl', lang, { msg });
+                stderrLines.push(message);
+                // 多步循环中的意外异常归内部错误（D-95-11：原 exit 1 → exit 3，登记为分类补全）
+                failInternal(err, {
+                    message,
+                    stderrLines,
+                    detail: { stage: stageArg, failed: next, remaining: phasePath.slice(i) },
+                });
                 return;
             }
             archivedAny = archivedAny || archived;
@@ -965,11 +1128,16 @@ export function registerFlowCommand(program) {
                 const blockingOpen = assertNoBlockingOpenRev(mgr, stageArg, lang);
                 if (blockingOpen.length > 0) {
                     const remainingPath = phasePath.slice(i + 1);
-                    console.error(t('flow.advance.blockedByRevTmpl', lang, {
+                    const message = t('flow.advance.blockedByRevTmpl', lang, {
                         revs: blockingOpen.map((r) => r.id).join(', '),
                         remaining: remainingPath.length > 0 ? remainingPath.join(t('flow.advance.pathArrow', lang)) : t('common.none', lang),
-                    }));
-                    process.exit(1);
+                    });
+                    failCli({
+                        code: 'BLOCKING_REVIEWS',
+                        message,
+                        detail: { stage: stageArg, to: 'done', reviews: blockingOpen.map((r) => r.id) },
+                        stderrLines: [message],
+                    });
                     return;
                 }
             }
@@ -1102,14 +1270,14 @@ export function registerFlowCommand(program) {
             }
         }
         if (options.json) {
-            // 复用 op-001 口径：顶层对象 + schemaVersion:1
+            // 复用 op-001 口径：顶层对象 + schemaVersion:1；warning 恒在（非 empty 为 null）
             const ops = items.map((it) => ({
                 stage: it.stage,
                 opId: it.opId,
                 title: it.title,
                 state: it.state,
                 fill: it.fill,
-                ...(it.fill === 'empty' ? { warning: t('flow.ops.emptyWarningTmpl', lang, { opId: it.opId }) } : {}),
+                warning: it.fill === 'empty' ? t('flow.ops.emptyWarningTmpl', lang, { opId: it.opId }) : null,
             }));
             console.log(JSON.stringify({ schemaVersion: 1, ops }, null, 2));
             return;
@@ -1138,14 +1306,29 @@ export function registerFlowCommand(program) {
         .command('log')
         .description('显示最近操作日志')
         .option('--last <n>', '显示最近 n 条（默认 10）', '10')
+        .option('--json', t('help.flow.log.json', getCliLang(process.cwd())))
         .action((options) => {
         const lang = getCliLang(process.cwd());
         const mgr = createManager();
+        const n = Math.max(1, parseInt(options.last, 10) || 10);
+        // JSON 分支须为首行纯 JSON 单文档；空日志与未初始化同形（entries: []）
+        if (options.json) {
+            const entries = mgr.isLoaded() && mgr.getData() ? mgr.getData().log.slice(-n) : [];
+            emitJson(withSchemaVersion({
+                count: entries.length,
+                entries: entries.map((e) => ({
+                    time: e.time,
+                    agent: normalizeAgentName(e.agent),
+                    action: e.action,
+                    detail: e.detail,
+                })),
+            }));
+            return;
+        }
         if (!mgr.isLoaded()) {
             console.log(t('flow.log.noInit', lang));
             return;
         }
-        const n = Math.max(1, parseInt(options.last, 10) || 10);
         const data = mgr.getData();
         if (!data || data.log.length === 0) {
             console.log(t('flow.log.noLogs', lang));
@@ -1513,10 +1696,20 @@ export function registerFlowCommand(program) {
         .command('list')
         .description('列出所有（或指定阶段的）Checkpoint 快照')
         .argument('[stage]', '阶段 ID（可选），如 v5.3-stage-01')
-        .action((stage) => {
+        .option('--json', t('help.flow.checkpoint.list.json', getCliLang(process.cwd())))
+        .action((stage, options) => {
         const lang = getCliLang(process.cwd());
         const mgr = createManager();
         const snapshots = mgr.listCheckpoints(stage);
+        // JSON 分支：未初始化与空集合同形（checkpoints: []）
+        if (options.json) {
+            emitJson(withSchemaVersion({
+                stage: stage ?? null,
+                checkpoints: snapshots,
+                count: snapshots.length,
+            }));
+            return;
+        }
         if (snapshots.length === 0) {
             console.log(stage
                 ? t('flow.checkpoint.noSnapshotsStageTmpl', lang, { stage })
@@ -1600,18 +1793,19 @@ export function registerFlowCommand(program) {
         const projectPath = process.cwd();
         const lang = getCliLang(projectPath);
         const mgr = createManager();
-        // --json 失败出口统一：纯 JSON 单文档 + exit 1（不混人类文案、不走 stderr）
-        const failJson = (payload) => {
-            console.log(JSON.stringify({ schemaVersion: 1, ...payload }, null, 2));
-            process.exitCode = 1;
+        // --json 失败出口统一（legacy 形态）：纯 JSON 单文档、不混人类文案；
+        // `errorKind` 恒为末尾键，`error` 恒 string、既有键序零改动（REV-95-002 / D-95-09）
+        const failJson = (payload, errorKind = 'refusal', exitCode = 1) => {
+            console.log(JSON.stringify({ schemaVersion: 1, ...payload, errorKind }, null, 2));
+            process.exitCode = exitCode;
         };
         if (!mgr.isLoaded()) {
             if (options.json) {
                 failJson({ error: 'no-init' });
                 return;
             }
-            console.error(t('common.errorNoInit', lang));
-            process.exitCode = 1;
+            const message = t('common.errorNoInit', lang);
+            failCli({ code: 'NO_INIT', message, detail: null, stderrLines: [message] });
             return;
         }
         // 版本归一（REV-79-004）：去 v 再加 v；非法 → exit 1 零写盘
@@ -1621,8 +1815,8 @@ export function registerFlowCommand(program) {
                 failJson({ error: 'invalid-version', input: versionInput });
                 return;
             }
-            console.error(t('flow.archive.invalidVersionTmpl', lang, { input: versionInput }));
-            process.exitCode = 1;
+            const message = t('flow.archive.invalidVersionTmpl', lang, { input: versionInput });
+            failCli({ code: 'INVALID_ARGUMENT', message, detail: { input: versionInput }, stderrLines: [message] });
             return;
         }
         const data = mgr.getData();
@@ -1633,8 +1827,8 @@ export function registerFlowCommand(program) {
                 failJson({ error: 'version-not-active', version });
                 return;
             }
-            console.error(t('flow.archive.versionNotActiveTmpl', lang, { version }));
-            process.exitCode = 1;
+            const message = t('flow.archive.versionNotActiveTmpl', lang, { version });
+            failCli({ code: 'INVALID_ARGUMENT', message, detail: { version }, stderrLines: [message] });
             return;
         }
         // 判据门：全 done（candidate.allDone 空集守卫）+ 无 blocking open REV（全仓唯一谓词，REV-79-002）
@@ -1642,23 +1836,38 @@ export function registerFlowCommand(program) {
         const blockingOpen = listBlockingOpenRevsForVersion(data, version);
         if (!candidate.allDone || blockingOpen.length > 0) {
             if (options.json) {
-                failJson({ error: 'gate-rejected', version, notDone, blockingOpen: blockingOpen.map((r) => r.id) });
+                // 判据明细（D-97-03-04）：legacy 五键序保留，三新键插在 blockingOpen 后、errorKind 前
+                failJson({
+                    error: 'gate-rejected',
+                    version,
+                    notDone,
+                    blockingOpen: blockingOpen.map((r) => r.id),
+                    eligible: false,
+                    unfinishedStages: notDone.map((id) => ({ id, phase: data.stages[id]?.phase ?? null })),
+                    blockingReviews: blockingOpen.map((r) => ({ id: r.id, title: r.title, priority: r.priority })),
+                });
                 return;
             }
+            const stderrLines = [];
             if (notDone.length > 0) {
-                console.error(t('flow.archive.gateNotDoneTitleTmpl', lang, { version, n: String(notDone.length) }));
+                stderrLines.push(t('flow.archive.gateNotDoneTitleTmpl', lang, { version, n: String(notDone.length) }));
                 for (const id of notDone) {
-                    console.error(t('flow.archive.gateItemTmpl', lang, { item: id + ' [' + (data.stages[id]?.phase ?? '') + ']' }));
+                    stderrLines.push(t('flow.archive.gateItemTmpl', lang, { item: id + ' [' + (data.stages[id]?.phase ?? '') + ']' }));
                 }
             }
             if (blockingOpen.length > 0) {
-                console.error(t('flow.archive.gateBlockingRevTitleTmpl', lang, { version, n: String(blockingOpen.length) }));
+                stderrLines.push(t('flow.archive.gateBlockingRevTitleTmpl', lang, { version, n: String(blockingOpen.length) }));
                 for (const r of blockingOpen) {
-                    console.error(t('flow.archive.gateItemTmpl', lang, { item: r.id + ': ' + r.title + ' (priority=' + r.priority + ')' }));
+                    stderrLines.push(t('flow.archive.gateItemTmpl', lang, { item: r.id + ': ' + r.title + ' (priority=' + r.priority + ')' }));
                 }
             }
-            console.error(t('flow.archive.gateRejected', lang));
-            process.exitCode = 1;
+            stderrLines.push(t('flow.archive.gateRejected', lang));
+            failCli({
+                code: 'ARCHIVE_GATE_REJECTED',
+                message: stderrLines[stderrLines.length - 1],
+                detail: { version, notDone, blockingOpen: blockingOpen.map((r) => r.id) },
+                stderrLines,
+            });
             return;
         }
         // 切分（纯函数；禁命令层第二套解析/切分）
@@ -1678,7 +1887,11 @@ export function registerFlowCommand(program) {
             };
             const preview = applyArchivePipelineDisposition(previewData, version);
             if (options.json) {
-                console.log(JSON.stringify({ schemaVersion: 1, version, stages: counts.stages, reviews: counts.reviews, log: counts.log, dryRun: true }, null, 2));
+                // 成功 9 键（D-97-03-03）：dry-run 只读 counts，零写盘
+                console.log(JSON.stringify({
+                    schemaVersion: 1, version, stages: counts.stages, reviews: counts.reviews, log: counts.log,
+                    dryRun: true, eligible: true, unfinishedStages: [], blockingReviews: [],
+                }, null, 2));
                 return;
             }
             console.log(t('flow.archive.previewTmpl', lang, { version, stages: String(counts.stages), reviews: String(counts.reviews), log: String(counts.log) }));
@@ -1694,13 +1907,14 @@ export function registerFlowCommand(program) {
             writeArchiveFile(projectPath, file);
         }
         catch (err) {
-            // 写盘失败（REV-79-013）：内存未改动（移除/索引/审计均在其后），无需回滚；exit 1 零 flow.json 变更
+            // 写盘失败（REV-79-013）：内存未改动（移除/索引/审计均在其后），无需回滚；exit 3 零 flow.json 变更
+            // 分类补全（D-95-09）：写盘失败用户无法通过修正输入解决 → internal / exit 3
             if (options.json) {
-                failJson({ error: 'archive-write-failed', version });
+                failJson({ error: 'archive-write-failed', version }, 'internal', 3);
                 return;
             }
-            console.error(t('common.errorTmpl', lang, { msg: err instanceof Error ? err.message : String(err) }));
-            process.exitCode = 1;
+            const message = t('common.errorTmpl', lang, { msg: err instanceof Error ? err.message : String(err) });
+            failCli({ code: 'ARCHIVE_WRITE_FAILED', message, detail: { version }, stderrLines: [message] });
             return;
         }
         // ② 内存移除（stages / reviews / log 三段）
@@ -1727,7 +1941,11 @@ export function registerFlowCommand(program) {
             return;
         }
         if (options.json) {
-            console.log(JSON.stringify({ schemaVersion: 1, version, stages: counts.stages, reviews: counts.reviews, log: counts.log, dryRun: false }, null, 2));
+            // 成功 9 键（D-97-03-03）：保持在 mgr.save() 成功之后输出（顺序不变）
+            console.log(JSON.stringify({
+                schemaVersion: 1, version, stages: counts.stages, reviews: counts.reviews, log: counts.log,
+                dryRun: false, eligible: true, unfinishedStages: [], blockingReviews: [],
+            }, null, 2));
             return;
         }
         if (added) {
@@ -1794,30 +2012,33 @@ export function registerFlowCommand(program) {
         const version = normalizeArchiveVersion(versionInput);
         if (!version) {
             if (json) {
-                console.log(JSON.stringify({ schemaVersion: 1, error: 'invalid-version', input: versionInput, available }, null, 2));
+                // legacy 形态：error 恒 string、既有键序不变，errorKind 恒末尾
+                console.log(JSON.stringify({ schemaVersion: 1, error: 'invalid-version', input: versionInput, available, errorKind: 'refusal' }, null, 2));
                 process.exitCode = 1;
                 return;
             }
-            console.error(t('flow.archive.invalidVersionTmpl', lang, { input: versionInput }));
-            process.exitCode = 1;
+            const message = t('flow.archive.invalidVersionTmpl', lang, { input: versionInput });
+            failCli({ code: 'INVALID_ARGUMENT', message, detail: { input: versionInput }, stderrLines: [message] });
             return;
         }
         const file = readArchiveFile(projectPath, version);
         if (!file) {
             if (json) {
-                console.log(JSON.stringify({ schemaVersion: 1, error: 'not-found', version, available }, null, 2));
+                // legacy 形态：error 恒 string、既有键序不变，errorKind 恒末尾
+                console.log(JSON.stringify({ schemaVersion: 1, error: 'not-found', version, available, errorKind: 'refusal' }, null, 2));
                 process.exitCode = 1;
                 return;
             }
-            console.error(t('flow.archive.show.notFoundTmpl', lang, {
+            const message = t('flow.archive.show.notFoundTmpl', lang, {
                 version, versions: available.length > 0 ? available.join(', ') : t('common.none', lang),
-            }));
-            process.exitCode = 1;
+            });
+            failCli({ code: 'INVALID_ARGUMENT', message, detail: { version }, stderrLines: [message] });
             return;
         }
         // --json = 全量载荷（ArchiveFile 原文自带 schemaVersion:1，含 log / reviews）——显式请求才取全量（REV-79-003）
+        // G-1（stage-95 op-001）：命令层 withSchemaVersion 包装，保证 schemaVersion 恒为首键；既有键相对顺序不变
         if (json) {
-            console.log(JSON.stringify(file, null, 2));
+            console.log(JSON.stringify(withSchemaVersion(file), null, 2));
             return;
         }
         console.log(t('flow.archive.show.titleTmpl', lang, { version, at: typeof file.archived_at === 'string' ? file.archived_at : '' }));
@@ -1863,10 +2084,9 @@ export function registerFlowCommand(program) {
                 reconciled = mgr.reconcileStatusMd({ dryRun: options.dryRun });
             }
             catch (err) {
-                // 写盘失败 → 明确错误 + 非 0 退出
+                // 写盘失败 → 内部错误（D-95-11：原 exit 1 → exit 3，登记为分类补全）；非 JSON 文案逐字不变
                 const msg = err instanceof Error ? err.message : String(err);
-                console.error(t('common.errorTmpl', lang, { msg }));
-                process.exit(1);
+                failInternal(err, { stderrLines: [t('common.errorTmpl', lang, { msg })] });
                 return;
             }
         }
@@ -1879,11 +2099,8 @@ export function registerFlowCommand(program) {
                 ...archiveItems.map((i) => ({ name: i.section, status: i.status, detail: i.message })),
                 ...reqItems.map((i) => ({ name: i.section, status: i.status, detail: i.message })),
             ];
-            const payload = { schemaVersion: 1, ok: report.ok, items };
-            // 与 op-001 的 health --json 合并字段（--fix 时追加 reconciled）
-            if (reconciled) {
-                payload.reconciled = reconciled;
-            }
+            // D-95-02：reconciled 恒在（非 --fix 时 null），位置固定于 items 之后
+            const payload = { schemaVersion: 1, ok: report.ok, items, reconciled: reconciled ?? null };
             console.log(JSON.stringify(payload, null, 2));
             if (!report.ok) {
                 process.exit(1);
@@ -1947,14 +2164,42 @@ export function registerFlowCommand(program) {
     flow
         .command('recover')
         .description('跨会话上下文恢复：输出流水线状态、阻塞原因和待处理任务')
-        .action(() => {
+        .option('--json', t('help.flow.recover.json', getCliLang(process.cwd())))
+        .action((options) => {
         const lang = getCliLang(process.cwd());
         const mgr = createManager();
         if (!mgr.isLoaded()) {
+            // JSON 分支：未初始化 exit 0 + initialized:false + 空值（镜像人类 exit 0）
+            if (options.json) {
+                emitJson(withSchemaVersion({
+                    initialized: false,
+                    phase: null,
+                    currentOp: null,
+                    stageStatus: null,
+                    blockedBy: null,
+                    pendingTasks: [],
+                    stageStats: {},
+                }));
+                return;
+            }
             console.log(t('common.noInit', lang));
             return;
         }
         const recovery = mgr.recoverContext(lang);
+        const stageStats = mgr.getAllStageStats();
+        // JSON 分支（键序：initialized,phase,currentOp,stageStatus,blockedBy,pendingTasks,stageStats）
+        if (options.json) {
+            emitJson(withSchemaVersion({
+                initialized: true,
+                phase: recovery.phase,
+                currentOp: recovery.currentOp,
+                stageStatus: recovery.stageStatus,
+                blockedBy: recovery.blockedBy === '' ? null : recovery.blockedBy,
+                pendingTasks: recovery.pendingTasks,
+                stageStats,
+            }));
+            return;
+        }
         console.log('');
         console.log(t('flow.recover.title', lang));
         console.log('');
@@ -2171,9 +2416,10 @@ export function registerFlowCommand(program) {
             }
         }
         catch (err) {
-            // 并发写冲突：统一单点（i18n 文案 + 退出码 2）
+            // 并发写冲突：统一单点（i18n 文案 + 退出码 2）；JSON 模式置码返回 → 显式 return 防落入通用分支
             if (isFlowConcurrentError(err)) {
                 handleConcurrentConflict(err, lang);
+                return;
             }
             // 失败：统一错误模板 + 非 0 退出（T39）
             const msg = err instanceof Error ? err.message : String(err);
@@ -2254,6 +2500,18 @@ function findPhaseEnteredAtMs(mgr, stageArg, fromPhase, logLenBefore) {
 function createManager() {
     return new FlowManager(process.cwd());
 }
+/**
+ * `--stage` 非法 / 不存在错误的 stderr 两行（逐字保持既有文案与顺序）。
+ * @param lang 语言标识
+ * @param projectPath 项目根
+ * @param input 用户输入的阶段 ID
+ */
+function stageIdErrorLines(lang, projectPath, input) {
+    return [
+        t('common.stageIdInvalidTmpl', lang, { input }),
+        t('common.stageIdSuggestTmpl', lang, { suggest: suggestStageId(projectPath, input) }),
+    ];
+}
 /**
  * 断言不存在阻塞中的 open REV（REV 闭环兜底，B5-3 / REV-52-001）。
  * 命中 → 打印列出并返回命中的 REV 列表（调用方决定退出码与文案）；无命中 → 空数组。
@@ -2267,8 +2525,8 @@ function assertNoBlockingOpenRev(mgr, stage, lang) {
         return [];
     }
     // REV-007：补 `.` 分隔符（与 core flow-manager.ts 的 stageId + '.' 范式一致），避免 stageId 前缀重叠误拦
-    const stageReviews = mgr.getReviewItems().filter((r) => r.op === stage || r.op.startsWith(stage + '.'));
-    const blockingOpen = stageReviews.filter((r) => r.blocking !== false && r.status === 'open');
+    // 单点委托：阶段域 + blocking !== false + status === 'open' 判定归核心 listStageBlockingOpenReviews（禁第二份）
+    const blockingOpen = listStageBlockingOpenReviews(mgr.getReviewItems(), stage);
     if (blockingOpen.length > 0) {
         console.warn(t('flow.advance.revBlockedTitleTmpl', lang, { n: String(blockingOpen.length) }));
         for (const rev of blockingOpen) {
@@ -2313,9 +2571,21 @@ function collectOpStates(stage) {
     }
     return result;
 }
+/**
+ * 由 ops (opId→state) 派生汇总：total = 键数；byState 仅含观测到的状态（无零值键）。
+ * 键序 = 状态首次出现序；空 ops → { total: 0, byState: {} }。
+ */
+function summarizeOpStates(ops) {
+    const byState = {};
+    for (const state of Object.values(ops)) {
+        byState[state] = (byState[state] ?? 0) + 1;
+    }
+    return { total: Object.keys(ops).length, byState };
+}
 /**
  * 构建 `flow status --json` 的结构化输出（B1-1）。
  * 顶层对象 + schemaVersion:1；stages 为数组，ops 为 opId→state 映射；counts 为阶段计数。
+ * stage-96 op-002：stages[] 末位追加 5 个调度属性（既有 5 键键序/类型逐字不变）。
  */
 function buildStatusJson(mgr) {
     const data = mgr.getData();
@@ -2327,13 +2597,23 @@ function buildStatusJson(mgr) {
             counts: { total: 0, done: 0, active: 0 },
         };
     }
-    const stages = Object.entries(data.stages).map(([id, stage]) => ({
-        id,
-        phase: stage.phase,
-        status: stage.status,
-        deps: stage.deps ?? [],
-        ops: collectOpStates(stage),
-    }));
+    const stages = Object.entries(data.stages).map(([id, stage]) => {
+        const ops = collectOpStates(stage);
+        // 模式单点解析：逐阶段经 resolveStageWorkflowMode（同一 manager 快照；D-96-12 不缓存）
+        const workflowMode = mgr.resolveStageWorkflowMode(id).value;
+        return {
+            id,
+            phase: stage.phase,
+            status: stage.status,
+            deps: stage.deps ?? [],
+            ops,
+            workflowMode,
+            requirementId: stage.requirement_id ?? null,
+            reviewTier: MODE_DERIVED_TIER[workflowMode],
+            effectiveReviewTier: DEFAULT_EFFECTIVE_REVIEW_TIER,
+            opsSummary: summarizeOpStates(ops),
+        };
+    });
     const total = stages.length;
     const done = stages.filter((s) => s.phase === 'done').length;
     return {