openfeel 1.1.1 → 1.1.3

package/dist/core/flow-manager.js

@@ -10,15 +10,17 @@
  * - 新增 repair() 方法，自动检测并修复 flow.json 常见问题
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, unlinkSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { execSync } from 'node:child_process';
+import { resolve, dirname, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { parse as parseYaml } from 'yaml';
 import { PipelineConfigSchema, PipelinePhaseSchema, PIPELINE_PHASES, MetaPhaseSchema, META_PHASES, transitionKeyMatches, } from './pipeline-schema.js';
 import { PublicLogger, formatDate } from './public-logger.js';
 import { t, getCliLang } from './i18n.js';
-import { findStageStatusPath } from './plan/path.js';
+import { findStageStatusPath, findStageDirConflict, parseStageId, normalizeStageId } from './plan/path.js';
 import { atomicWriteFileSync } from './fs/atomic-write.js';
 import { withFileLock, projectLockPath } from './fs/file-lock.js';
+import { DEFAULT_CONFIG, ConfigDefaultsSchema } from './config.js';
+import { getGlobalProfilePath } from './global-paths.js';
 /** flow.json 乐观并发冲突：磁盘 revision 与本次加载时不一致（存在并发写入） */
 export class FlowConcurrentModificationError extends Error {
     /** 本次实例加载时的 revision */
@@ -37,6 +39,21 @@ export function isFlowConcurrentError(err) {
     return err instanceof FlowConcurrentModificationError
         || (typeof err === 'object' && err !== null && err.name === 'FlowConcurrentModificationError');
 }
+/** 阶段目录冲突：两个不同 stageId 映射同一 (series, stageDir)（cli/BUG-002） */
+export class StageDirConflictError extends Error {
+    /** 本次冲突检测的 stageId */
+    stage;
+    /** 已存在、占用同一目录的其它 stageId */
+    other;
+    constructor(stage, other) {
+        super(`阶段目录冲突：'${stage}' 与 '${other}' 映射同一 (series, stageDir)，请改用其它 stage-NN`);
+        this.name = 'StageDirConflictError';
+        this.stage = stage;
+        this.other = other;
+    }
+}
+/** `openfeel config effective` 的四个受管键（与 DEFAULT_CONFIG 一致） */
+const EFFECTIVE_CONFIG_KEYS = ['execution_mode', 'auto_advance', 'test_enabled', 'merge_mode'];
 // ── 默认值 ──
 /** 创建默认的 Checkpoints */
 function defaultCheckpoints() {
@@ -72,6 +89,80 @@ function extractRevision(data) {
     const rev = data?.meta?.revision;
     return typeof rev === 'number' && Number.isInteger(rev) ? rev : 0;
 }
+/**
+ * 对账 flow.json 的 op 键与 ops/ 目录文件（N1-2 单一实现，repair/health 共用）。
+ *
+ * 判定规则（R1）：op 模板文件同时匹配 `op-NNN.md`（新命名）与 `op-NNN_*.md`（历史命名），
+ * 两种命名都算「文件存在」，避免把历史命名误判为键孤儿。
+ * 无法解析 stageId 的阶段（非标准键）跳过对账。
+ *
+ * @param projectPath 项目根路径
+ * @param stages flow.json 的 stages 映射
+ * @returns keyOrphans（有注册键无文件）/ fileOrphans（有文件无注册键）
+ */
+function reconcileOrphans(projectPath, stages) {
+    const keyOrphans = [];
+    const fileOrphans = [];
+    for (const [stageId, stage] of Object.entries(stages ?? {})) {
+        // 非标准 stageId 无法定位 ops/ 目录，跳过（不误报）
+        const parsed = parseStageId(stageId);
+        if (!parsed) {
+            continue;
+        }
+        const keys = Object.keys(stage?.ops ?? {});
+        const opsDir = resolve(projectPath, '.openfeel', 'plan', parsed.series, parsed.stageDir, 'ops');
+        const fileIds = new Set();
+        if (existsSync(opsDir)) {
+            let entries = [];
+            try {
+                entries = readdirSync(opsDir);
+            }
+            catch {
+                entries = [];
+            }
+            for (const name of entries) {
+                const m = name.match(/^(op-\d+)/);
+                if (m) {
+                    fileIds.add(m[1]);
+                }
+            }
+        }
+        // 键孤儿：有注册键但 ops/ 无对应文件
+        for (const key of keys) {
+            if (!fileIds.has(key)) {
+                keyOrphans.push({ stage: stageId, opId: key });
+            }
+        }
+        // 文件孤儿：有文件但无注册键
+        for (const fileId of fileIds) {
+            if (!keys.includes(fileId)) {
+                fileOrphans.push({ stage: stageId, opId: fileId });
+            }
+        }
+    }
+    return { keyOrphans, fileOrphans };
+}
+/**
+ * 对账 flow.json 的 op 键与 ops/ 目录文件（N1-2 公开入口）。
+ * @param projectPath 项目根路径
+ * @returns keyOrphans（有键无文件）/ fileOrphans（有文件无键）；flow.json 缺失/损坏时返回空
+ */
+export function findOrphanOps(projectPath) {
+    const fp = resolve(projectPath, '.openfeel', 'flow.json');
+    if (!existsSync(fp)) {
+        return { keyOrphans: [], fileOrphans: [] };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(fp, 'utf-8'));
+        return reconcileOrphans(projectPath, parsed.stages ?? {});
+    }
+    catch {
+        // flow.json 不可解析时不做对账（不阻塞主流程）
+        return { keyOrphans: [], fileOrphans: [] };
+    }
+}
+/** findPhasePath BFS 深度上限（B5-1；超出按拒绝处理） */
+export const PHASE_PATH_MAX_DEPTH = 8;
 // ── 核心类 ──
 export class FlowManager {
     projectPath;
@@ -107,6 +198,13 @@ export class FlowManager {
             // 从 stages 的键名恢复 op 的 id 字段（运行时便利字段，磁盘不存储）
             if (this.data && this.data.stages) {
                 for (const [, stage] of Object.entries(this.data.stages)) {
+                    // T2 一处收口：存量/外部损坏数据缺 ops/deps 时补齐，避免下游 Object.entries(undefined) 崩溃
+                    if (!stage.ops) {
+                        stage.ops = {};
+                    }
+                    if (!stage.deps) {
+                        stage.deps = [];
+                    }
                     // 类型守卫：仅当 ops 为普通对象时才遍历（跳过 null/undefined/数组）
                     if (stage.ops && typeof stage.ops === 'object' && !Array.isArray(stage.ops)) {
                         for (const [opKey, op] of Object.entries(stage.ops)) {
@@ -126,6 +224,8 @@ export class FlowManager {
         if (!this.data) {
             return;
         }
+        // 存量 flow.json 可能缺 meta（REV-41 REV-008）：就地补齐，避免 save() 抛 TypeError（??= 仅补整体缺失，不覆盖既有字段）
+        this.data.meta ??= { version: '1.0', project: '', updated: '', revision: 0 };
         this.data.meta.updated = new Date().toISOString();
         // 创建清理后的副本：去除 op 中的 id 字段（id 由 stages.{stageId}.ops 的键名决定）
         const serializable = JSON.parse(JSON.stringify(this.data));
@@ -224,8 +324,11 @@ export class FlowManager {
             if (!existsSync(dir)) {
                 return [];
             }
+            // REV-009：短名归一化（快照文件名前缀为全名）；`||` 兜底兼容历史上以短名存的快照
+            const key = stageId ? (normalizeStageId(stageId) ?? stageId) : undefined;
             return readdirSync(dir)
-                .filter((f) => f.endsWith('.json') && (!stageId || f.startsWith(stageId + '-')))
+                .filter((f) => f.endsWith('.json')
+                && (!key || f.startsWith(key + '-') || (stageId !== undefined && stageId !== key && f.startsWith(stageId + '-'))))
                 .sort();
         }
         catch {
@@ -269,7 +372,7 @@ export class FlowManager {
                 atomicWriteFileSync(this.filePath, restoredContent, { backup: true });
             });
             if (conflict) {
-                console.warn('[WARN] flow.json 已被其它进程修改，拒绝从快照恢复（请重新加载后重试）');
+                console.warn(t('flow.manager.snapshotRestoreRefused', getCliLang(this.projectPath)));
                 return false;
             }
             this.load();
@@ -344,12 +447,20 @@ export class FlowManager {
         if (dotIdx === -1) {
             return null;
         }
-        const stageId = opId.substring(0, dotIdx);
+        const rawStageId = opId.substring(0, dotIdx);
         const opLocalId = opId.substring(dotIdx + 1);
         // 排除空字符串情况
-        if (!stageId || !opLocalId) {
+        if (!rawStageId || !opLocalId) {
             return null;
         }
+        // REV-007：出口归一化（短名前缀 → 全名），一处收口覆盖 getOp/advancePhase/recordAttempt/hasTransition。
+        // 仅归一化 stageId 段，opLocalId 保持原值（不影响 pipeline.current.op 写入值）；无法解析回退原值。
+        // 双键回退（与 setStageDeps/removeStage/removeScheme 同范式）：归一化键优先；
+        // 归一化键不存在而原始键存在时回退原始键（兼容以短名注册的阶段，N-1），避免误判「阶段不存在」。
+        const normalized = normalizeStageId(rawStageId) ?? rawStageId;
+        const stageId = this.data?.stages[normalized]
+            ? normalized
+            : (this.data?.stages[rawStageId] ? rawStageId : normalized);
         return { stageId, opLocalId };
     }
     /** 根据 opId 查找 Op 对象 */
@@ -408,6 +519,32 @@ export class FlowManager {
         }
         return this.data.reviews.filter((r) => r.op === opId);
     }
+    /**
+     * 读取 op 模板文件内容（兼容 `op-NNN.md` 与历史 `op-NNN_{title}.md` 两种命名）。
+     * B3-1 填充度检测与 healthCheck 空模板检查共用。
+     * @returns 文件内容；未找到/不可读返回 null
+     */
+    readOpTemplate(stageId, opId) {
+        const parsed = parseStageId(stageId);
+        if (!parsed) {
+            return null;
+        }
+        const opsDir = resolve(this.projectPath, '.openfeel', 'plan', parsed.series, parsed.stageDir, 'ops');
+        if (!existsSync(opsDir)) {
+            return null;
+        }
+        try {
+            const name = readdirSync(opsDir).find((f) => f === `${opId}.md` || f.startsWith(`${opId}_`));
+            if (!name) {
+                return null;
+            }
+            return readFileSync(resolve(opsDir, name), 'utf-8');
+        }
+        catch {
+            // 目录/文件不可读视为未找到（不误判）
+            return null;
+        }
+    }
     /** 获取指定 op 的重试次数 */
     getRetryCount(opId) {
         const op = this.getOp(opId);
@@ -421,9 +558,9 @@ export class FlowManager {
         const stagesCount = Object.keys(this.data.stages).length;
         let opsCount = 0;
         for (const stage of Object.values(this.data.stages)) {
-            // 类型守卫：仅统计普通对象 ops（跳过 null/undefined/数组）
+            // 类型守卫：仅统计普通对象 ops（跳过 null/undefined/数组）；draft 不计入完成度统计（A1 窄兼容第 2 条）
             if (stage.ops && typeof stage.ops === 'object' && !Array.isArray(stage.ops)) {
-                opsCount += Object.keys(stage.ops).length;
+                opsCount += Object.values(stage.ops).filter((o) => o.state !== 'draft').length;
             }
         }
         const openReviews = this.data.reviews.filter((r) => r.status === 'open').length;
@@ -460,9 +597,9 @@ export class FlowManager {
         }
         let opsCount = 0;
         for (const stage of Object.values(this.data.stages)) {
-            // 类型守卫：仅统计普通对象 ops（跳过 null/undefined/数组）
+            // 类型守卫：仅统计普通对象 ops（跳过 null/undefined/数组）；draft 不计入完成度统计（A1 窄兼容第 2 条）
             if (stage.ops && typeof stage.ops === 'object' && !Array.isArray(stage.ops)) {
-                opsCount += Object.keys(stage.ops).length;
+                opsCount += Object.values(stage.ops).filter((o) => o.state !== 'draft').length;
             }
         }
         return {
@@ -487,7 +624,12 @@ export class FlowManager {
             return;
         }
         if (this.data.stages[stageName]) {
-            return; // 已注册，跳过
+            return; // 已注册，跳过（幂等，保持既有行为）
+        }
+        // 冲突检测：不同 stageId 映射同一 (series, stageDir) 时拒绝写入（结构化错误，命令层按类型分流 i18n）
+        const conflict = findStageDirConflict(this.projectPath, stageName);
+        if (conflict) {
+            throw new StageDirConflictError(stageName, conflict);
         }
         this.data.stages[stageName] = {
             name: stageName,
@@ -496,6 +638,10 @@ export class FlowManager {
             deps,
             ops: {},
         };
+        // 审计日志（P7）：仅在实际新增时写入；同 stageId 幂等跳过时不写（保持「仅记录实际动作」）。
+        // 双轨说明（REV-42-002）：add_stage = 注册层（flow stage add / stage create，agent=flow-manager）；
+        // register_stage = 完整层（plan stage add，建目录 + overview/status + 注册，agent=cli）。入口不同，非重复。
+        this.appendLog({ time: '', agent: 'cli', action: 'register_stage', detail: { stageName, deps } });
     }
     // ═══ 阶段耗时统计 ═══
     /**
@@ -732,6 +878,31 @@ export class FlowManager {
         return { phase, currentOp, stageStatus, blockedBy, pendingTasks };
     }
     // ═══ 推进 ═══
+    /**
+     * 同步 pipeline.current 到指定阶段中首个 pending / executing 的 op。
+     * 单一 owner：被 advanceStagePhase 与 recordAttempt 共用，禁止各自实现。
+     * @param stageName 目标阶段 ID（如 'v1.1.2-stage-50'）
+     * @returns 同步后的 current 快照（便于调用方复用，不写盘）
+     */
+    syncCurrentOp(stageName) {
+        // 防御：阶段不存在时不改动 pipeline.current，直接返回当前快照
+        const stage = this.data?.stages[stageName];
+        if (!stage) {
+            return {
+                stage: this.data?.pipeline.current.stage ?? '',
+                op: this.data?.pipeline.current.op ?? '',
+            };
+        }
+        // 取首个 pending / executing 的 op
+        const pendingOpEntry = Object.entries(stage.ops ?? {}).find(([, op]) => op.state === 'pending' || op.state === 'executing');
+        // 命中 → 指向该 op；未命中（ops 全 done / 为空）→ 置空 op，绝不保留旧 op（T1 缺陷修复点）
+        const synced = { stage: stageName, op: pendingOpEntry ? pendingOpEntry[0] : '' };
+        if (this.data) {
+            // 不触碰 pipeline.phase / pipeline.retry，也不做 IO（由调用方 save()）
+            this.data.pipeline.current = synced;
+        }
+        return synced;
+    }
     /**
      * 推进指定阶段到目标流水线阶段（新 API）
      * @param stageName 阶段名（如 stage-01）
@@ -745,7 +916,11 @@ export class FlowManager {
         }
         const actualTrigger = triggeredBy ?? 'flow-manager';
         // 校验 stageName 存在
-        const stage = this.data.stages[stageName];
+        // REV-005：归一化 stageId（短名 → 全名）；此后函数体内一律使用 key（防半归一化）
+        // 双键回退：兼容以短名建键的存量 / 测试数据（归一化键不存在时回退原始键）
+        const normalized = normalizeStageId(stageName) ?? stageName;
+        const key = this.data.stages[normalized] ? normalized : stageName;
+        const stage = this.data.stages[key];
         if (!stage) {
             throw new Error(`阶段 '${stageName}' 不存在`);
         }
@@ -755,7 +930,7 @@ export class FlowManager {
         if (!phaseResult.success) {
             const corrected = this.fuzzyCorrectPhase(phase);
             if (corrected) {
-                console.warn(`[WARN] advanceStagePhase: Phase '${phase}' 自动修正为 '${corrected}'`);
+                console.warn(t('flow.manager.phaseAutoCorrectTmpl', getCliLang(this.projectPath), { phase: String(phase), corrected }));
                 targetPhase = corrected;
             }
             else {
@@ -767,7 +942,7 @@ export class FlowManager {
         }
         // REV 闭环：blocking REV > 0 时拒绝推进到 done（--force 仅降级警告）
         if (targetPhase === 'done') {
-            const stageReviews = this.data.reviews.filter((r) => r.op.startsWith(stageName + '.') || r.op === stageName);
+            const stageReviews = this.data.reviews.filter((r) => r.op.startsWith(key + '.') || r.op === key);
             const blockingOpen = stageReviews.filter((r) => r.blocking !== false && r.status === 'open');
             if (blockingOpen.length > 0) {
                 const revList = blockingOpen
@@ -779,9 +954,9 @@ export class FlowManager {
         // 保存旧 phase 用于日志
         const fromPhase = stage.phase;
         // 更新 stage phase
-        this.data.stages[stageName].phase = targetPhase;
+        this.data.stages[key].phase = targetPhase;
         // Checkpoint 自动快照：phase 推进成功后保存 flow.json 快照到 .openfeel/checkpoints/（失败不阻塞推进）
-        this.saveCheckpoint(stageName, targetPhase);
+        this.saveCheckpoint(key, targetPhase);
         // 日志强制落档骨架：关键 phase 节点自动创建骨架文件
         const SKELETON_PHASES = [
             'exec_running',
@@ -790,36 +965,40 @@ export class FlowManager {
             'archiving',
         ];
         if (SKELETON_PHASES.includes(targetPhase)) {
-            this.createLogSkeleton(stageName, targetPhase);
-        }
-        // 同步更新 pipeline.current：从该 stage 的 ops 中找到第一个 pending/executing 的 op
-        const pendingOpEntry = Object.entries(stage.ops).find(([, op]) => op.state === 'pending' || op.state === 'executing');
-        this.data.pipeline.current = {
-            stage: stageName,
-            op: pendingOpEntry ? pendingOpEntry[0] : this.data.pipeline.current.op,
-        };
-        // 同步更新 pipeline.phase 为 'active'
-        this.data.pipeline.phase = 'active';
+            this.createLogSkeleton(key, targetPhase);
+        }
+        // 同步更新 pipeline.current：单一 owner syncCurrentOp（未命中置空 op，修复跨阶段悬空 T1）
+        this.syncCurrentOp(key);
+        // 同步更新 pipeline.phase：所有 stage 均 done 时置 'done'，否则 'active'（P3 全量 done 判定）
+        // 说明（T6）：pipeline.phase 无条件覆写，手工 `paused` 属**软状态** —— 阶段推进即视为恢复，
+        // 覆写为 active/done 属预期语义。如需硬暂停，请勿推进阶段（保持 paused 且不调用 advance）。
+        // 空集守卫：无 stage 时 [].every(...) 为 true（vacuous truth），须排除以免误置 done。
+        const allDone = Object.keys(this.data.stages).length > 0
+            && Object.values(this.data.stages).every((s) => s.phase === 'done');
+        this.data.pipeline.phase = (allDone ? 'done' : 'active');
         // 追加日志（使用实际触发者名，而非硬编码 'flow-manager'）
         this.appendLog({
             time: '',
             agent: actualTrigger,
             action: 'advance_stage_phase',
-            detail: { stageName, from: fromPhase, to: targetPhase },
+            detail: { stageName: key, from: fromPhase, to: targetPhase },
         });
         // REV-003: advance_stage_phase 改为 endStage 时批量聚合，取消逐条写入
         // this.publicLogger.logPhaseChange({...});
         // 同步 stage status（调用已有 mapPhaseToStageStatus）
         const prevStatus = stage.status;
-        const newStatus = mapPhaseToStageStatus(targetPhase, prevStatus);
+        // test_enabled 由 buildCascadeConfig（config.yaml/status.md/profile 级联，无反向依赖）取真实值，
+        // 使 mapPhaseToStageStatus 的 testEnabled 分支可达（T9）
+        const testEnabled = this.buildCascadeConfig().effective['test_enabled'] !== 'false';
+        const newStatus = mapPhaseToStageStatus(targetPhase, prevStatus, testEnabled);
         stage.status = newStatus;
         // 自动记录阶段计时：首次状态变更时启动
         if (!stage.stats || !stage.stats.start_time) {
-            this.startStage(stageName);
+            this.startStage(key);
         }
         // 阶段完成时自动结束计时
         if (targetPhase === 'done' && prevStatus !== 'done') {
-            this.endStage(stageName);
+            this.endStage(key);
             // 归档 git commit 移出本方法：必须在 flow.json save 之后执行（否则 commit 不含本次 phase 变更）。
             // 返回 true 由命令层在 save 后调用 autoCommitOnDone。
             return true;
@@ -838,7 +1017,9 @@ export class FlowManager {
         try {
             const msg = `chore: 阶段归档 ${stageName}`;
             // cwd 指向项目根，确保 git 在 flow.json 所在仓库执行而非进程工作目录
-            execSync(`git add -A && git commit -m "${msg}"`, { stdio: 'pipe', cwd: this.projectPath });
+            // 使用 execFileSync 数组参数（无 shell 解析），避免 stageName 注入 shell（T16）
+            execFileSync('git', ['add', '-A'], { stdio: 'pipe', cwd: this.projectPath });
+            execFileSync('git', ['commit', '-m', msg], { stdio: 'pipe', cwd: this.projectPath });
             console.log(t('flow.advance.gitCommitOkTmpl', lang, { stage: stageName }));
         }
         catch {
@@ -858,6 +1039,11 @@ export class FlowManager {
         if (this.data.stages[stageId]) {
             throw new Error(`Stage '${stageId}' already exists`);
         }
+        // 冲突检测：不同 stageId 映射同一 (series, stageDir) 时拒绝写入（结构化错误，命令层按类型分流 i18n）
+        const conflict = findStageDirConflict(this.projectPath, stageId);
+        if (conflict) {
+            throw new StageDirConflictError(stageId, conflict);
+        }
         this.data.stages[stageId] = {
             name: stageId,
             phase: initialPhase,
@@ -876,6 +1062,138 @@ export class FlowManager {
             detail: { stageId, phase: initialPhase },
         });
     }
+    /**
+     * 检查阶段是否可安全移除（只读，不写盘）。
+     *
+     * 判定顺序：ops 非空 → 当前活跃阶段 → 被其它阶段 deps 引用。
+     * force=true 时越过三项校验（ok 恒 true，阶段不存在除外），但 opCount/isCurrent/referencing 仍如实返回。
+     *
+     * deps 匹配：精确相等，或 dep/target 经 parseStageId 解析后 (series, stageDir) 相同（兼容短名）。
+     * 存量 stage 可能缺 deps 字段（StageData.deps 虽为必填，历史数据未必），以 Array.isArray 守卫。
+     *
+     * @param stageId 目标阶段 ID
+     * @param options.force 是否越权检查
+     * @returns 可移除性检查结果
+     */
+    checkRemovable(stageId, options = {}) {
+        if (!this.data) {
+            return { ok: false, reason: '流水线数据未加载', opCount: 0, isCurrent: false, referencing: [] };
+        }
+        // REV-007：入口归一化（短名 → 全名）+ 双键回退（归一化键优先，短名键不被误改）
+        const key = normalizeStageId(stageId) ?? stageId;
+        const raw = this.data.stages[stageId];
+        const stageKey = this.data.stages[key] ? key : (raw ? stageId : key);
+        const stage = this.data.stages[stageKey];
+        if (!stage) {
+            return { ok: false, reason: `阶段不存在：'${stageKey}'`, opCount: 0, isCurrent: false, referencing: [] };
+        }
+        const opCount = stage.ops && typeof stage.ops === 'object' && !Array.isArray(stage.ops)
+            ? Object.keys(stage.ops).length
+            : 0;
+        const isCurrent = this.data.pipeline.current.stage === stageKey;
+        // 引用者扫描：其余 stages 的 deps 命中该阶段者（REV-004）
+        const target = parseStageId(stageKey);
+        const referencing = [];
+        for (const [otherId, otherStage] of Object.entries(this.data.stages)) {
+            if (otherId === stageKey) {
+                continue;
+            }
+            // 存量 stage 可能缺 deps 字段，以 Array.isArray 守卫
+            const deps = Array.isArray(otherStage.deps) ? otherStage.deps : [];
+            const hit = deps.some((dep) => {
+                if (dep === stageKey) {
+                    return true;
+                }
+                const parsed = parseStageId(dep);
+                return !!parsed && !!target && parsed.series === target.series && parsed.stageDir === target.stageDir;
+            });
+            if (hit) {
+                referencing.push(otherId);
+            }
+        }
+        if (!options.force) {
+            // 错误路径：ops 非空（存在未归档操作方案）
+            if (opCount > 0) {
+                return { ok: false, reason: `阶段 '${stageKey}' 仍有 ${opCount} 个未归档的 op；如需强制移除此阶段，请加 --force`, opCount, isCurrent, referencing };
+            }
+            // 错误路径：当前活跃阶段
+            if (isCurrent) {
+                return { ok: false, reason: `阶段 '${stageKey}' 是当前活跃阶段；如需强制移除，请加 --force（将自动回退 current）`, opCount, isCurrent, referencing };
+            }
+            // 错误路径：被其它阶段 deps 引用（REV-004）
+            if (referencing.length > 0) {
+                return { ok: false, reason: `阶段 '${stageKey}' 被其它阶段依赖：${referencing.join(', ')}；如需强制移除（将产生悬空依赖），请加 --force`, opCount, isCurrent, referencing };
+            }
+        }
+        return { ok: true, opCount, isCurrent, referencing };
+    }
+    /**
+     * 移除流水线阶段（仅注销 flow.json 注册；**不删除目录**）。
+     *
+     * 安全校验复用 checkRemovable：ops 非空 / 当前活跃阶段 / 被其它阶段 deps 引用，默认拒绝，--force 越过。
+     * --force 移除时**不清理**引用者 deps 中的悬空项（deps 为声明式引用；保留原样 + 日志 referencing/snapshot 使失真可审计）。
+     * 移除后 current 兜底：若 current 指向被删阶段，按 stages 插入序回退首个非 done；无则清空 current。
+     * 目录删除由调用方在 `save()` 成功后执行（REV-41 REV-009 事务顺序：避免 save 失败但目录已删的中间态）。
+     *
+     * @param stageId 目标阶段 ID
+     * @param options.force 越过安全校验；options.purge 计算待删 plan 目录（不在此处删除）
+     * @returns purgeTarget：`--purge` 时待删除的 plan 目录绝对路径；否则 undefined
+     */
+    removeStage(stageId, options = {}) {
+        if (!this.data) {
+            return {};
+        }
+        // REV-007：入口归一化（短名 → 全名）+ 双键回退（归一化键优先，短名键不被误改），以 stageKey 贯穿
+        const key = normalizeStageId(stageId) ?? stageId;
+        const raw = this.data.stages[stageId];
+        const stageKey = this.data.stages[key] ? key : (raw ? stageId : key);
+        const check = this.checkRemovable(stageKey, { force: options.force });
+        if (!check.ok) {
+            // 错误路径：安全校验未通过 → 保留既有文案（用户输入原样）
+            throw new Error(check.reason ?? `无法移除阶段 '${stageId}'`);
+        }
+        // 阶段快照（REV-006）：误删后可从审计日志重建
+        const stage = this.data.stages[stageKey];
+        const snapshot = {
+            phase: stage.phase,
+            status: stage.status,
+            deps: Array.isArray(stage.deps) ? [...stage.deps] : [],
+            opKeys: Object.keys(stage.ops ?? {}),
+        };
+        // ── 注销 flow.json 注册 ──
+        delete this.data.stages[stageKey];
+        // ── current 兜底：不悬空 ──
+        if (this.data.pipeline.current.stage === stageKey) {
+            const remaining = Object.keys(this.data.stages);
+            const fallback = remaining.find((k) => this.data.stages[k].phase !== 'done');
+            if (fallback) {
+                const pendingOp = Object.entries(this.data.stages[fallback].ops ?? {}).find(([, op]) => op.state === 'pending' || op.state === 'executing');
+                this.data.pipeline.current = { stage: fallback, op: pendingOp ? pendingOp[0] : '' };
+            }
+            else {
+                this.data.pipeline.current = { stage: '', op: '' };
+            }
+        }
+        // ── --purge：仅计算待删目录，不在此处删除（须 save() 成功后再删，REV-009 事务顺序） ──
+        let purgeTarget;
+        if (options.purge) {
+            const parsed = parseStageId(stageKey);
+            if (parsed) {
+                const dir = resolve(this.projectPath, '.openfeel', 'plan', parsed.series, parsed.stageDir);
+                if (existsSync(dir)) {
+                    purgeTarget = dir;
+                }
+            }
+        }
+        // ── 审计日志（含引用者与阶段快照，REV-004 / REV-006；purgeTarget 记录删除意图） ──
+        this.appendLog({
+            time: '',
+            agent: 'cli',
+            action: 'remove_stage',
+            detail: { stageId: stageKey, purgeTarget: purgeTarget ?? null, referencing: check.referencing, snapshot },
+        });
+        return { purgeTarget };
+    }
     /**
      * 推进流水线阶段（旧 API）
      * @param opId 操作 ID（格式 "stage-xx.op-xxx"）
@@ -885,7 +1203,7 @@ export class FlowManager {
      * @deprecated 请使用 advanceStagePhase(stageName, phase) 替代。内部保留 op 级逻辑后委托给 advanceStagePhase。
      */
     advancePhase(opId, to, stageId, force) {
-        console.warn('[DEPRECATED] advancePhase() 已弃用，请使用 advanceStagePhase(stageName, phase) 替代');
+        console.warn(t('flow.manager.advancePhaseDeprecated', getCliLang(this.projectPath)));
         // ── 1. 校验目标 phase ──
         let targetPhase;
         const phaseResult = PipelinePhaseSchema.safeParse(to);
@@ -893,7 +1211,7 @@ export class FlowManager {
             if (force) {
                 const corrected = this.fuzzyCorrectPhase(to);
                 if (corrected) {
-                    console.warn(`[WARN] Phase '${to}' 自动修正为 '${corrected}'`);
+                    console.warn(t('flow.manager.phaseAutoCorrectShortTmpl', getCliLang(this.projectPath), { to: String(to), corrected }));
                     targetPhase = corrected;
                 }
                 else {
@@ -916,7 +1234,7 @@ export class FlowManager {
         // ── 2. 解析 stageId ──
         const resolvedStageId = stageId || (opId ? this.parseOpId(opId)?.stageId : this.data.pipeline.current.stage);
         if (!resolvedStageId) {
-            console.warn('[DEPRECATED] advancePhase: 无法解析 stageId，跳过');
+            console.warn(t('flow.manager.advancePhaseNoStageId', getCliLang(this.projectPath)));
             return;
         }
         // ── 3. Op 级工作（检查点更新、重试计数） ──
@@ -1010,6 +1328,91 @@ export class FlowManager {
             return [];
         return this.getValidTargets(currentPhase);
     }
+    /**
+     * 在运行时 transitions 上求 stageName 当前 phase → to 的**唯一**可达路径（B5-1）。
+     * BFS（深度上限 PHASE_PATH_MAX_DEPTH）；最短深度上存在多条路径 → ambiguous（拒绝，不猜测）。
+     * 纯只读：不写盘、不改内存。
+     * @param stageName 阶段 ID
+     * @param to 目标 phase
+     * @returns 路径与原因（no-path/ambiguous/depth-exceeded 供命令层报错；already-at-target 按 no-op）
+     */
+    findPhasePath(stageName, to) {
+        // REV-005：归一化 stageId（短名 → 全名），与 setStageDeps / plan scheme * 同范式
+        // 双键回退：兼容以短名建键的存量 / 测试数据（归一化键不存在时回退原始键）
+        const normalized = normalizeStageId(stageName) ?? stageName;
+        const key = this.data?.stages[normalized] ? normalized : stageName;
+        const start = this.data?.stages[key]?.phase;
+        if (!start) {
+            return { path: [], reason: 'no-path' };
+        }
+        if (start === to) {
+            return { path: [], reason: 'already-at-target' };
+        }
+        // BFS 逐层扩展；visitedDepth 记录各 phase 首次到达的最小深度（剪枝，避免重复/环）
+        const visitedDepth = new Map();
+        visitedDepth.set(start, 0);
+        let layer = [{ phase: start, path: [] }];
+        while (layer.length > 0) {
+            const hits = [];
+            const nextLayer = [];
+            for (const node of layer) {
+                // 深度已达上限 → 不再扩展（超限在下方统一判定）
+                if (node.path.length >= PHASE_PATH_MAX_DEPTH) {
+                    continue;
+                }
+                for (const target of this.getValidTargets(node.phase)) {
+                    const path = [...node.path, target];
+                    if (target === to) {
+                        hits.push(path);
+                        continue;
+                    }
+                    const prevDepth = visitedDepth.get(target);
+                    if (prevDepth !== undefined && prevDepth <= path.length) {
+                        continue; // 已在更浅/等深访问过 → 剪枝
+                    }
+                    visitedDepth.set(target, path.length);
+                    nextLayer.push({ phase: target, path });
+                }
+            }
+            if (hits.length > 1) {
+                return { path: [], reason: 'ambiguous' }; // 最短深度多条等价路径 → 拒绝
+            }
+            if (hits.length === 1) {
+                return { path: hits[0], reason: 'ok' };
+            }
+            // 本层已到深度上限但未命中 → 拒绝（depth-exceeded）
+            if (layer[0]?.path.length !== undefined && layer[0].path.length + 1 > PHASE_PATH_MAX_DEPTH) {
+                return { path: [], reason: 'depth-exceeded' };
+            }
+            layer = nextLayer;
+        }
+        return { path: [], reason: 'no-path' };
+    }
+    /**
+     * 获取运行时生效的 phase 列表（供 flow phases 自描述）。
+     * 数据源 = this.pipelineConfig（构造时经 loadPipelineConfig 加载 .openfeel/pipeline.yaml）；
+     * 缺省/解析失败时回退内置默认配置。返回副本，避免调用方修改内部状态。
+     */
+    getPipelinePhases() {
+        const phases = this.pipelineConfig?.phases ?? this.getDefaultPipelineConfig().phases;
+        return [...phases];
+    }
+    /**
+     * 获取运行时生效的 phase 转移表（key 可含 '|' 组合条件）。
+     * 缺省/解析失败时回退内置默认配置。返回浅拷贝。
+     */
+    getPipelineTransitions() {
+        const transitions = this.pipelineConfig?.transitions ?? this.getDefaultPipelineConfig().transitions;
+        return Object.fromEntries(Object.entries(transitions).map(([k, v]) => [k, [...v]]));
+    }
+    /**
+     * 获取内置默认 phase 转移表（不受项目 pipeline.yaml 影响）。
+     * 供 `flow phases` 做「运行时 vs 默认」差异报告（T19）。
+     * @returns 默认 transitions 的深拷贝
+     */
+    getDefaultTransitions() {
+        return Object.fromEntries(Object.entries(this.getDefaultPipelineConfig().transitions).map(([k, v]) => [k, [...v]]));
+    }
     /**
      * 解析当前阶段 phase：优先使用传入的 stageName，其次 current.stage，最后 fallback
      */
@@ -1019,7 +1422,11 @@ export class FlowManager {
         const targetStageName = stageName || this.data.pipeline.current.stage;
         if (!targetStageName)
             return null;
-        const stage = this.data.stages[targetStageName];
+        // REV-005：归一化 stageId（短名 → 全名）；current.stage 本身为全名时归一化为恒等
+        // 双键回退：兼容以短名建键的存量 / 测试数据
+        const normalized = normalizeStageId(targetStageName) ?? targetStageName;
+        const key = this.data.stages[normalized] ? normalized : targetStageName;
+        const stage = this.data.stages[key];
         return stage?.phase ?? null;
     }
     /**
@@ -1095,12 +1502,31 @@ export class FlowManager {
         const downstreamPhases = this.buildDownstreamPhases();
         return { basic, cascade, recentChanges, downstreamPhases };
     }
-    /** 构建配置级联信息 */
+    /**
+     * 构建配置级联信息（优先级：profileDefaults < configDefaults < statusOverrides）
+     * 全局画像仅作最低优先级兜底（P2），且只取 preferences.auto_advance 单值，
+     * 不对 preferences 做整体替换（与 config.yaml defaults 键集重叠的仅 auto_advance）。
+     */
     buildCascadeConfig() {
+        const profileDefaults = {};
         const configDefaults = {};
         const statusOverrides = {};
-        const effective = {};
-        // 读取 config.yaml defaults
+        // 最低优先级：全局画像 ~/.config/openfeel/profile.yaml 的 preferences.auto_advance（P2 兜底）
+        // BUG-003（stage-47）：仅当画像文件真实存在且原始 YAML **显式声明**该键时兜底；否则落 builtin。
+        const profilePath = getGlobalProfilePath();
+        if (existsSync(profilePath)) {
+            try {
+                const raw = parseYaml(readFileSync(profilePath, 'utf-8'));
+                const explicit = raw?.preferences?.auto_advance;
+                if (explicit === 'enabled' || explicit === 'disabled') {
+                    profileDefaults['auto_advance'] = explicit;
+                }
+            }
+            catch {
+                // 解析失败 → 不填 → 落 builtin（更贴近「无有效画像」）
+            }
+        }
+        // 中优先级：项目 .openfeel/config.yaml 的 defaults 块
         const configPath = resolve(this.projectPath, '.openfeel', 'config.yaml');
         if (existsSync(configPath)) {
             try {
@@ -1108,9 +1534,23 @@ export class FlowManager {
                 const config = parseYaml(raw);
                 if (config && typeof config === 'object' && config.defaults) {
                     const defaults = config.defaults;
+                    const lang = getCliLang(this.projectPath);
                     for (const [key, value] of Object.entries(defaults)) {
-                        configDefaults[key] = String(value);
-                        effective[key] = String(value);
+                        // 逐键用 ConfigDefaultsSchema 校验（T29）：非法值跳过并告警，保持「有效配置」语义可用
+                        const fieldSchema = ConfigDefaultsSchema.shape[key];
+                        if (!fieldSchema) {
+                            // 非受管扩展键：保持原行为纳入
+                            configDefaults[key] = String(value);
+                            continue;
+                        }
+                        const parsed = fieldSchema.safeParse(value);
+                        if (parsed.success) {
+                            configDefaults[key] = String(value);
+                        }
+                        else {
+                            const reason = parsed.error?.issues[0]?.message ?? 'invalid';
+                            console.warn(t('config.effective.invalidValueSkipped', lang, { key, reason }));
+                        }
                     }
                 }
             }
@@ -1118,7 +1558,7 @@ export class FlowManager {
                 // 解析失败则用空值
             }
         }
-        // 读取当前 stage 的 status.md（如果存在）
+        // 最高优先级：当前 stage 的 status.md（如果存在）
         if (this.data && this.data.pipeline.current.stage) {
             const stageId = this.data.pipeline.current.stage;
             const statusPath = this.findStatusPath(stageId);
@@ -1130,11 +1570,9 @@ export class FlowManager {
                     const autoMatch = content.match(/\*\*自动推进\*\*[：:]\s*(disabled|enabled)/);
                     if (execMatch) {
                         statusOverrides['execution_mode'] = execMatch[1];
-                        effective['execution_mode'] = execMatch[1];
                     }
                     if (autoMatch) {
                         statusOverrides['auto_advance'] = autoMatch[1];
-                        effective['auto_advance'] = autoMatch[1];
                     }
                 }
                 catch {
@@ -1142,7 +1580,35 @@ export class FlowManager {
                 }
             }
         }
-        return { configDefaults, statusOverrides, effective };
+        // 级联合并（后写覆盖前写）：全局画像兜底 < 项目 config < status.md 覆盖
+        const effective = { ...profileDefaults, ...configDefaults, ...statusOverrides };
+        return { profileDefaults, configDefaults, statusOverrides, effective };
+    }
+    /**
+     * 解析四个受管配置键的「有效值 + 生效来源」（`openfeel config effective`，P9）。
+     * 复用 buildCascadeConfig（单一权威，避免第二套解析），优先级：
+     * status.md > config.yaml > profile.yaml > builtin。
+     * @returns key → { value, source }
+     */
+    resolveEffectiveConfig() {
+        const cascade = this.buildCascadeConfig();
+        const result = {};
+        for (const key of EFFECTIVE_CONFIG_KEYS) {
+            if (cascade.statusOverrides[key] !== undefined) {
+                result[key] = { value: cascade.statusOverrides[key], source: 'status.md' };
+            }
+            else if (cascade.configDefaults[key] !== undefined) {
+                result[key] = { value: cascade.configDefaults[key], source: 'config.yaml' };
+            }
+            else if (cascade.profileDefaults[key] !== undefined) {
+                result[key] = { value: cascade.profileDefaults[key], source: 'profile.yaml' };
+            }
+            else {
+                // 三层皆无 → 框架内置默认
+                result[key] = { value: String(DEFAULT_CONFIG[key]), source: 'builtin' };
+            }
+        }
+        return result;
     }
     /** 查找 status.md 的路径（三级回退：plan/{series}/ 精确 → plan 递归 → stages 兜底） */
     findStatusPath(stageId) {
@@ -1254,9 +1720,25 @@ export class FlowManager {
         if (!op) {
             return { shouldRetry: false, shouldReplan: false };
         }
+        // B4-5（A1 第 5 条）/ REV-52-002：draft op 拒绝记录执行结果（双层守卫之**核心层兜底**）。
+        // 命令层已先行守卫；此处保证 API 调用方亦被拦截。返回既有结构，不抛错（不改返回契约）。
+        if (op.state === 'draft') {
+            this.appendLog({
+                time: '',
+                agent: 'openfeel-executor',
+                action: 'attempt_refused_draft',
+                detail: { opId },
+            });
+            return { shouldRetry: false, shouldReplan: false };
+        }
         op.attempts += 1;
+        // current.op 生命周期单一 owner：state 变更后同步（T1，禁双实现）
+        const stageIdOfOp = this.parseOpId(opId)?.stageId;
         if (result === 'pass') {
             op.state = 'done';
+            if (stageIdOfOp) {
+                this.syncCurrentOp(stageIdOfOp);
+            }
             this.data.pipeline.retry = 0;
             this.appendLog({
                 time: '',
@@ -1275,6 +1757,9 @@ export class FlowManager {
         // result === 'fail'
         if (op.attempts < op.max_attempts) {
             op.state = 'pending'; // 回到 pending 等待重试
+            if (stageIdOfOp) {
+                this.syncCurrentOp(stageIdOfOp);
+            }
             this.data.pipeline.retry += 1;
             this.appendLog({
                 time: '',
@@ -1338,6 +1823,89 @@ export class FlowManager {
         review.status = 'resolved';
         return true;
     }
+    /**
+     * 更新审查条目的可编辑字段（N2-2）：仅覆盖 patch 中提供的键。
+     * 留审计日志 `review_update`，并 save()。
+     * @param revId 审查条目 ID
+     * @param patch 待覆盖字段（priority/title/blocking）
+     * @returns 是否命中条目
+     */
+    updateReview(revId, patch) {
+        if (!this.data) {
+            return false;
+        }
+        const review = this.data.reviews.find((r) => r.id === revId);
+        if (!review) {
+            return false;
+        }
+        if (patch.priority !== undefined) {
+            review.priority = patch.priority;
+        }
+        if (patch.title !== undefined) {
+            review.title = patch.title;
+        }
+        if (patch.blocking !== undefined) {
+            review.blocking = patch.blocking;
+        }
+        this.appendLog({
+            time: '',
+            agent: 'openfeel-reviewer',
+            action: 'review_update',
+            detail: { revId, patch: patch },
+        });
+        this.save();
+        return true;
+    }
+    /**
+     * 删除审查条目（N2-2）：留审计日志 `review_remove`，并 save()。
+     * @param revId 审查条目 ID
+     * @returns 是否命中并删除
+     */
+    removeReview(revId) {
+        if (!this.data) {
+            return false;
+        }
+        const idx = this.data.reviews.findIndex((r) => r.id === revId);
+        if (idx === -1) {
+            return false;
+        }
+        const removed = this.data.reviews[idx];
+        this.data.reviews.splice(idx, 1);
+        this.appendLog({
+            time: '',
+            agent: 'openfeel-reviewer',
+            action: 'review_remove',
+            detail: { revId, title: removed.title },
+        });
+        this.save();
+        return true;
+    }
+    /**
+     * 覆盖写入某阶段的 deps 列表（N2-1）。
+     * 悬空依赖的强制校验在命令层（核心层不静默，仅写入 + 审计日志 + save）。
+     * @param stageName 阶段 ID（简写或全称，经 normalizeStageId 归一）
+     * @param deps 依赖阶段 ID 列表
+     * @throws Error 阶段不存在时抛出（调用方决定退出码）
+     */
+    setStageDeps(stageName, deps) {
+        if (!this.data) {
+            throw new Error('flow.json 未加载');
+        }
+        const normalized = normalizeStageId(stageName) ?? stageName;
+        const stage = this.data.stages[normalized] ?? this.data.stages[stageName];
+        if (!stage) {
+            throw new Error(`阶段 '${stageName}' 不存在`);
+        }
+        const next = [...deps];
+        stage.deps = next;
+        this.appendLog({
+            time: '',
+            agent: 'cli',
+            action: 'stage_deps_set',
+            detail: { stage: normalized, deps: next },
+        });
+        this.save();
+    }
     /**
      * 添加自动修复审查条目
      * 当 openfeel-reviewer 认为问题可直接修复时调用，REV 条目状态直接设为 resolved，
@@ -1354,15 +1922,18 @@ export class FlowManager {
             console.error(`错误：opId 格式不正确 "${opId}"，应为 stage-xx.op-xxx`);
             return;
         }
-        const stageId = opId.substring(0, opId.lastIndexOf('.'));
-        const stage = this.data.stages[stageId];
+        const rawStageId = opId.substring(0, opId.lastIndexOf('.'));
+        // REV-009：短名前缀归一化 + 双键回退（与 parseOpId / setStageDeps 同范式）
+        const stageId = normalizeStageId(rawStageId) ?? rawStageId;
+        const stage = this.data.stages[stageId] ?? this.data.stages[rawStageId];
         if (!stage) {
-            console.error(`错误：opId "${opId}" 中的 stage "${stageId}" 不存在`);
+            // 诊断文案显示用户输入的原始 stage 名（便于定位）
+            console.error(`错误：opId "${opId}" 中的 stage "${rawStageId}" 不存在`);
             return;
         }
         // 前置条件：仅允许从 review_failed 状态调用，检查对应 stage 的 phase
         if (stage.phase !== 'review_failed') {
-            console.warn(`[WARN] addAutoFixReview 仅允许从 review_failed 状态调用，当前 stage ${stageId} phase 为 ${stage.phase}`);
+            console.warn(t('flow.manager.autoFixPhaseGuardTmpl', getCliLang(this.projectPath), { stage: stageId, phase: String(stage.phase) }));
             return;
         }
         // 标记为自动修复
@@ -1477,6 +2048,10 @@ export class FlowManager {
         else {
             // 遍历每个 stage，校验其 phase 字段为合法 PipelinePhase
             for (const [stageId, stage] of Object.entries(this.data.stages)) {
+                // T2：normalize 已补 ops 则不报；仅对无法识别的结构（非普通对象）报错
+                if (typeof stage.ops !== 'object' || stage.ops === null || Array.isArray(stage.ops)) {
+                    errors.push(`stages.${stageId}.ops 缺失或不是有效对象`);
+                }
                 if (!stage.phase) {
                     warnings.push(`stages.${stageId}.phase 缺失，设为默认 'plan_pending'`);
                     stage.phase = 'plan_pending';
@@ -1548,11 +2123,10 @@ export class FlowManager {
         if (containsMatches.length === 1) {
             return containsMatches[0];
         }
-        // 后缀匹配: 查找 normalized 是否为某合法值的后缀
-        for (const phase of PIPELINE_PHASES) {
-            if (phase.endsWith('_' + normalized) || phase.endsWith(normalized)) {
-                return phase;
-            }
+        // 后缀匹配（唯一命中时采用；多重命中返回 null，与 prefix/contains 分支语义对齐，T4）
+        const suffixMatches = PIPELINE_PHASES.filter((p) => p.endsWith('_' + normalized) || p.endsWith(normalized));
+        if (suffixMatches.length === 1) {
+            return suffixMatches[0];
         }
         // 常见拼写修正（硬编码扩展）
         const extraCorrections = {
@@ -1601,7 +2175,7 @@ export class FlowManager {
      * @param dryRun true 时仅检测不修复
      * @returns 修复结果（修改列表 + 是否从 .bak 恢复）
      */
-    repair(dryRun = false) {
+    repair(dryRun = false, options = {}) {
         const changes = [];
         let recovered = false;
         // 尝试加载 flow.json
@@ -1797,6 +2371,32 @@ export class FlowManager {
             changes.push('已补全缺失的 log');
             modified = true;
         }
+        // ── N1-2：op 键 ↔ ops/ 目录对账（A2：默认只报告，不删任何条目）──
+        const orphans = reconcileOrphans(this.projectPath, flowData.stages);
+        // --prune-orphans：仅清理 keyOrphans（flow.json 孤儿键）；fileOrphans 永不自动删除
+        if (options.pruneOrphans && !dryRun && orphans.keyOrphans.length > 0) {
+            for (const orphan of orphans.keyOrphans) {
+                const targetStage = flowData.stages?.[orphan.stage];
+                if (targetStage && targetStage.ops && orphan.opId in targetStage.ops) {
+                    delete targetStage.ops[orphan.opId];
+                }
+            }
+            // 审计日志写入 flowData（repair 以 flowData 序列化落盘，而非 this.data）
+            if (!Array.isArray(flowData.log)) {
+                flowData.log = [];
+            }
+            flowData.log.push({
+                time: new Date().toISOString(),
+                agent: 'cli',
+                action: 'prune_orphan_ops',
+                detail: {
+                    count: orphans.keyOrphans.length,
+                    ops: orphans.keyOrphans.map((o) => `${o.stage}.${o.opId}`),
+                },
+            });
+            changes.push(`已清理 ${orphans.keyOrphans.length} 个键孤儿（文件未删除）`);
+            modified = true;
+        }
         // 写入修复后的数据（recovered 场景下磁盘文件仍损坏，即使无字段修改也必须写回恢复内容）
         if ((modified || recovered) && !dryRun) {
             // （乐观并发修订）恢复/修复亦视为一次写入：先在源对象上递增 revision，
@@ -1833,34 +2433,43 @@ export class FlowManager {
             this.load();
         }
         // changes 在无问题时保持空数组，CLI 层通过 changes.length === 0 判断"没问题"
-        return { fixed: modified || recovered, changes, recovered };
+        return { fixed: modified || recovered, changes, recovered, orphans };
     }
     /**
      * 自动修复指定阶段的 phase/status 不一致
      * - status=done 但 phase≠done → 同步 phase 为 done
      * - phase=done 但 status≠done → 同步 status 为 done
      * @param stageName 阶段名（如 stage-01）
+     * @param options.dryRun 为 true 时仅计算并返回等价结果，不修改内存（供 --dry-run 预览用）
      * @returns 修复结果（是否修复 + 详情）
      */
-    autoRepairInconsistency(stageName) {
+    autoRepairInconsistency(stageName, options = {}) {
         if (!this.data) {
             return { fixed: false, detail: 'flow.json 未加载' };
         }
-        const stage = this.data.stages[stageName];
+        // REV-005：归一化 stageId（短名 → 全名），否则短名调用会静默返回「不存在」
+        // 双键回退：兼容以短名建键的存量 / 测试数据
+        const normalized = normalizeStageId(stageName) ?? stageName;
+        const key = this.data.stages[normalized] ? normalized : stageName;
+        const stage = this.data.stages[key];
         if (!stage) {
             return { fixed: false, detail: `阶段 '${stageName}' 不存在` };
         }
-        // 修复: status=done 但 phase≠done 时，同步 phase 为 done
+        // 修复: status=done 但 phase≠done → 同步 phase 为 done（dryRun 时仅报告，不写内存）
         if (stage.status === 'done' && stage.phase !== 'done') {
-            const oldPhase = stage.phase;
-            stage.phase = 'done';
-            return { fixed: true, detail: `phase ${oldPhase} → done (与 status 同步)` };
+            const detail = `phase ${stage.phase} → done (与 status 同步)`;
+            if (!options.dryRun) {
+                stage.phase = 'done';
+            }
+            return { fixed: true, detail };
         }
-        // 修复: phase=done 但 status≠done 时，同步 status
+        // 修复: phase=done 但 status≠done → 同步 status（dryRun 时仅报告）
         if (stage.phase === 'done' && stage.status !== 'done') {
-            const oldStatus = stage.status;
-            stage.status = 'done';
-            return { fixed: true, detail: `status ${oldStatus} → done (与 phase 同步)` };
+            const detail = `status ${stage.status} → done (与 phase 同步)`;
+            if (!options.dryRun) {
+                stage.status = 'done';
+            }
+            return { fixed: true, detail };
         }
         return { fixed: false, detail: '未检测到不一致' };
     }
@@ -2000,9 +2609,190 @@ export class FlowManager {
         if (!quick) {
             this.checkDepsYaml(items);
         }
+        // ── 7. 悬空依赖检测 ──
+        if (!quick) {
+            this.checkDanglingDeps(items);
+        }
+        // ── 8. 孤儿 op 检测（N1-3）──
+        if (!quick) {
+            this.checkOrphanOps(items);
+        }
+        // ── 9. 空模板检测（B3/B4-4；显式跳过 draft）──
+        if (!quick) {
+            this.checkEmptyTemplates(items);
+        }
         const ok = items.every((i) => i.status !== 'fail');
         return { items, ok };
     }
+    /**
+     * 结构化健康报告访问器（B1-3：供 `flow health --json` 消费）。
+     * 复用 healthCheck() 结果，仅做字段别名映射（section→name / message→detail），不改判定。
+     * @param quick 是否快速模式（仅检查关键项）
+     * @returns { ok, items: [{ name, status, detail }] }
+     */
+    getHealthReport(quick = false) {
+        const result = this.healthCheck(quick);
+        return {
+            ok: result.ok,
+            items: result.items.map((i) => ({ name: i.section, status: i.status, detail: i.message })),
+        };
+    }
+    /**
+     * 以 flow.json 为权威，对账并回写各阶段 status.md 的「状态」字段（B2-1 / A2）。
+     * 仅处理「状态」字段；**绝不**触碰执行模式/自动推进/当前任务/状态记录表（独立字段）。
+     * 与 `commands/stage.ts:setStatusField` 同语义（定向替换，其余字节不变）；后续可下沉合并。
+     * @param options.dryRun true 时只计算差异、不写盘
+     * @returns 差异清单（含 dry-run 预览结果）；已一致项不入清单（保证幂等 applied=0）
+     */
+    reconcileStatusMd(options) {
+        const out = [];
+        if (!this.data) {
+            return out;
+        }
+        const testEnabled = this.buildCascadeConfig().effective['test_enabled'] !== 'false';
+        for (const [stageId, stage] of Object.entries(this.data.stages)) {
+            // 跳过 draft（未发布不参与对账，与 op-005 窄兼容一致）
+            if (stage.phase === 'draft') {
+                continue;
+            }
+            const authoritative = mapPhaseToStageStatus(stage.phase, stage.status, testEnabled);
+            const statusPath = this.findStatusPath(stageId);
+            if (!statusPath || !existsSync(statusPath)) {
+                // status.md 缺失 → 安全跳过，不新建文件/字段
+                out.push({ stage: stageId, from: '', to: authoritative, result: 'skipped-not-found' });
+                continue;
+            }
+            const current = readStatusFieldValue(readFileSync(statusPath, 'utf-8'), '状态');
+            if (current === null) {
+                // 字段缺失 → 记为 skipped-not-found（不新建字段，避免扩大写入面）
+                out.push({ stage: stageId, from: '', to: authoritative, result: 'skipped-not-found' });
+                continue;
+            }
+            if (current === authoritative) {
+                // 已一致 → 不入清单（无差异，零写入）
+                continue;
+            }
+            if (options?.dryRun) {
+                out.push({ stage: stageId, from: current, to: authoritative, result: 'planned' });
+                continue;
+            }
+            // 定向替换「状态」字段行（其余字节不变），并留审计日志
+            this.writeStatusField(statusPath, '状态', authoritative);
+            this.appendLog({
+                time: '',
+                agent: 'openfeel-executor',
+                action: 'status_reconcile',
+                detail: { stage: stageId, from: current, to: authoritative },
+            });
+            out.push({ stage: stageId, from: current, to: authoritative, result: 'applied' });
+        }
+        return out;
+    }
+    /**
+     * status.md「状态」字段定向写（原子写 + 按阶段目录加锁）。
+     * 仅替换首个匹配的 `- **{key}**：{value}` 行的值，其余内容逐字节保留。
+     * 与 `commands/stage.ts:setStatusField` 同语义。
+     */
+    writeStatusField(statusPath, key, newValue) {
+        const stageDir = basename(dirname(statusPath));
+        const lockPath = projectLockPath(this.projectPath, `status-${stageDir}`);
+        return withFileLock(lockPath, () => {
+            const content = readFileSync(statusPath, 'utf-8');
+            const fieldRegex = new RegExp(`^(-\\s*(?:\\*\\*)?${escapeRegex(key)}(?:\\*\\*)?[：:]\\s*)(.*)$`, 'gm');
+            const updated = content.replace(fieldRegex, `$1${newValue}`);
+            if (updated === content) {
+                return false; // 未命中字段
+            }
+            atomicWriteFileSync(statusPath, updated);
+            return true;
+        });
+    }
+    /**
+     * 7. 悬空依赖检测：stages[].deps 是否均指向已注册阶段（B2 存量防御）
+     * 仅作数据卫生告警（warn），不阻断；强制校验点在命令层 `commands/plan.ts`
+     * @param items 健康检查结果收集数组
+     */
+    checkDanglingDeps(items) {
+        if (!this.data) {
+            return;
+        }
+        const known = new Set(Object.keys(this.data.stages).map((k) => normalizeStageId(k) ?? k));
+        const dangling = [];
+        // 逐阶段比对 deps 是否可归一化命中已注册阶段
+        for (const [stageId, stage] of Object.entries(this.data.stages)) {
+            const deps = Array.isArray(stage.deps) ? stage.deps : [];
+            for (const d of deps) {
+                if (!known.has(normalizeStageId(d) ?? d)) {
+                    dangling.push(`${stageId} → ${d}`);
+                }
+            }
+        }
+        if (dangling.length > 0) {
+            items.push({
+                section: '悬空依赖',
+                status: 'warn',
+                message: `检出 ${dangling.length} 条悬空依赖：${dangling.slice(0, 5).join('; ')}${dangling.length > 5 ? ' …' : ''}`,
+            });
+            return;
+        }
+        items.push({ section: '悬空依赖', status: 'pass', message: '未检测到悬空依赖' });
+    }
+    /**
+     * 8. 孤儿 op 检测：flow.json 的 op 键与 ops/ 目录文件是否一致（N1-3）
+     * 仅作数据卫生告警（warn），不阻断；退出码不受影响（仅 fail 决定）。
+     * 无孤儿时不产生条目（保持输出精简）。
+     * @param items 健康检查结果收集数组
+     */
+    checkOrphanOps(items) {
+        const { keyOrphans, fileOrphans } = findOrphanOps(this.projectPath);
+        if (keyOrphans.length === 0 && fileOrphans.length === 0) {
+            return;
+        }
+        const base = t('flow.health.orphanOpsDetail', 'zh-CN', {
+            n: String(keyOrphans.length),
+            m: String(fileOrphans.length),
+        });
+        // keyOrphans 详情列出前 5 条 + 总数
+        const sample = keyOrphans.slice(0, 5).map((o) => `${o.stage}.${o.opId}`).join('; ');
+        const message = sample
+            ? `${base} [${sample}${keyOrphans.length > 5 ? ' …' : ''}]`
+            : base;
+        items.push({ section: t('flow.health.orphanOps'), status: 'warn', message });
+    }
+    /**
+     * 9. 空模板检测：op 模板仍含 `- [ ] 待补充` 时告警（B3/B4）。
+     * 窄兼容（A1 第 1 条）：**显式跳过 `draft`** op（draft 本就允许空模板）。
+     * 仅作数据卫生告警（warn），不阻断。
+     * @param items 健康检查结果收集数组
+     */
+    checkEmptyTemplates(items) {
+        if (!this.data) {
+            return;
+        }
+        const empties = [];
+        for (const [stageId, stage] of Object.entries(this.data.stages)) {
+            const opsMap = stage.ops && typeof stage.ops === 'object' && !Array.isArray(stage.ops) ? stage.ops : {};
+            for (const [opId, op] of Object.entries(opsMap)) {
+                if (op.state === 'draft') {
+                    continue; // 窄兼容：draft 允许空模板
+                }
+                const content = this.readOpTemplate(stageId, opId);
+                if (content !== null && isTemplateEmpty(content)) {
+                    empties.push(`${stageId}.${opId}`);
+                }
+            }
+        }
+        if (empties.length > 0) {
+            items.push({
+                section: t('flow.health.emptyTemplate', 'zh-CN'),
+                status: 'warn',
+                message: t('flow.health.emptyTemplateDetail', 'zh-CN', {
+                    n: String(empties.length),
+                    items: empties.slice(0, 5).join(', ') + (empties.length > 5 ? ' …' : ''),
+                }),
+            });
+        }
+    }
     /** 1. 检查 flow.json 合法性 */
     checkFlowJson(items) {
         const fp = resolve(this.projectPath, '.openfeel', 'flow.json');
@@ -2124,7 +2914,8 @@ export class FlowManager {
         for (const [stageId, stage] of Object.entries(this.data.stages)) {
             // 所有 REV 已 closed 但 stage 仍为 review_failed
             if (stage.status === 'review_failed') {
-                const stageReviews = this.data.reviews.filter((r) => r.op.startsWith(stageId));
+                // 锚定 stageId + '.'（对齐 :1064），避免前缀重叠（如 stage-1 与 stage-10）误报 zombie（T14）
+                const stageReviews = this.data.reviews.filter((r) => r.op.startsWith(stageId + '.') || r.op === stageId);
                 const allClosed = stageReviews.length > 0 && stageReviews.every((r) => r.status === 'closed');
                 if (allClosed) {
                     items.push({ section: '僵尸状态', status: 'warn', message: `${stageId}: 所有 REV 已 closed 但 stage 仍为 review_failed` });
@@ -2374,7 +3165,8 @@ export class FlowManager {
                 exec: 'exec',
                 review: 'review',
                 test: 'test',
-                archive: 'archive',
+                archiving: 'archiving', // 主用：使 archiving 阶段更新 checkpoint（T12）
+                archive: 'archive', // 历史键，兼容自定义 pipeline 中 phase 名为 archive 的场景
             },
             phase_corrections: {
                 completed: 'done',
@@ -2413,6 +3205,54 @@ export function normalizeAgentName(name) {
     }
     return LEGACY_AGENT_NAME_MAP[key] ?? key;
 }
+/**
+ * 转义正则元字符（供 status.md 字段名匹配使用）。
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * 读取 status.md 中 `- **{key}**：{value}` 字段值（首个匹配）。
+ * @param content status.md 全文
+ * @param key 字段名（如「状态」）
+ * @returns 字段值；未命中返回 null
+ */
+function readStatusFieldValue(content, key) {
+    const fieldRegex = new RegExp(`^-\\s*(?:\\*\\*)?${escapeRegex(key)}(?:\\*\\*)?[：:]\\s*(.*)$`, 'm');
+    const m = content.match(fieldRegex);
+    return m ? m[1] : null;
+}
+/**
+ * 空模板标记（**单一来源**）：B3 填充度检测、B4 publish 校验、healthCheck 空模板检查共用。
+ * 见 op-005 验收 12（无第二套判定）。
+ */
+export const EMPTY_TEMPLATE_MARKER = '- [ ] 待补充';
+/**
+ * 空模板标记的**整行锚定**正则（单一来源）：
+ * 行首可含缩进（[ \t]*）、`-` 与 `[ ]` 之间允许空白、行尾允许空白并容忍 CRLF；
+ * 仅当标记**独占一行**（含缩进）时判为未填充——避免正文**行内引用**该字面导致误报（cli/BUG-005，stage-54 E1）。
+ * **已知边界**：代码围栏（```）内的独占行仍判为 empty（不引入围栏解析，见 stage-54 A1）。
+ */
+const EMPTY_TEMPLATE_LINE_RE = /(?:^|\n)[ \t]*-\s*\[\s*\]\s*待补充[ \t]*(?=\r?\n|$)/;
+/** 模板是否仍含空模板标记（未填充；**整行锚定**，非子串） */
+export function isTemplateEmpty(content) {
+    return EMPTY_TEMPLATE_LINE_RE.test(content);
+}
+/**
+ * 判定 op 模板填充度（B3-1）。
+ * - empty：仍含空模板标记 `- [ ] 待补充`（**整行锚定**，行内引用不误报）
+ * - partial：已删除该标记但存在其它未勾选 `- [ ]`（行首 `[ \t]*` 锚定，口径与 empty 统一）
+ * - filled：无未完成标记
+ */
+export function detectFillState(content) {
+    if (isTemplateEmpty(content)) {
+        return 'empty';
+    }
+    if (/(?:^|\n)[ \t]*-\s*\[\s*\]/.test(content)) {
+        return 'partial';
+    }
+    return 'filled';
+}
 /**
  * 将 PipelinePhase 映射为 stage 状态
  * @param phase 流水线阶段