openfeel 1.1.7 → 1.2.1

package/dist/core/flow-archive/archive-ops.js

@@ -0,0 +1,184 @@
+/**
+ * 归档读写原语与索引管理 — 归档引擎的 IO 层
+ * 职责：归档文件路径单点 / 写盘（独立锁 flow-archive + 原子写）/ 读取（宽容） / 列举 / meta.archived_versions 管理（纯内存）
+ *       + pipeline 处置（纯内存）。
+ * 写盘与锁复用 src/core/fs/ 工具层（原子写模式 + 建议性文件锁模式）；
+ * 归档锁名 `flow-archive` 与 flow 锁**不嵌套**（裁定 P；核验 A19）。
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWriteFileSync } from '../fs/atomic-write.js';
+import { withFileLock, projectLockPath } from '../fs/file-lock.js';
+import { versionOfStageId } from './grouping.js';
+/** 归档写盘锁名（独立于 flow 锁；锁文件落 .openfeel/tmp/locks/flow-archive.lock） */
+const ARCHIVE_LOCK_NAME = 'flow-archive';
+/** 归档目录：{projectPath}/.openfeel/flow-archive（Q2 定稿：不纳入 WORKSPACE_DIRS，按需 mkdir 幂等创建） */
+export function getArchiveDir(projectPath) {
+    return join(projectPath, '.openfeel', 'flow-archive');
+}
+/**
+ * 归档文件路径：{archiveDir}/{version}.json（路径单点）。
+ *
+ * ⚠️ 仅接受**已校验**的版本字符串（经 `isValidArchiveVersion`，REV-78-011）：
+ * 本函数只做拼接、不做合法性/路径穿越校验；调用方须先走 `isValidArchiveVersion`
+ * 或使用上游已校验入口（`writeArchiveFile` / `readArchiveFile` / `listArchiveVersions`）。
+ */
+export function getArchiveFilePath(projectPath, version) {
+    return join(getArchiveDir(projectPath), `${version}.json`);
+}
+/**
+ * 版本字符串合法性（探针法复用 parseStageId，禁自写正则）：
+ * `${s}-stage-00` 可被 parseStageId 解析且版本段恒等 → 合法；空串/含路径分隔符/非版本形态 → 非法。
+ *
+ * 导出版（原私有版本校验函数重命名并导出），供命令层复用——REV-79-004。
+ */
+export function isValidArchiveVersion(s) {
+    if (s.length === 0) {
+        return false;
+    }
+    return versionOfStageId(`${s}-stage-00`) === s;
+}
+/**
+ * 版本号归一（输入前缀兼容）：trim → 去单个前导 `v`（如有）→ 补 `v` → 经 `isValidArchiveVersion` 校验。
+ * 归一方向恒为「去 v 再加 v」：引擎键恒带 `v`（与 `versionOfStageId` 输出同形态；REV-79-004）。
+ * **禁**复用 `normalizeVersion`（`src/core/plan/roadmap.ts:17`，方向相反：去 `v`）。
+ *
+ * 错误路径返回 null 的触发条件：空串 / 探针校验失败（非 vX.Y[.Z] 形态、含路径分隔符等）。
+ */
+export function normalizeArchiveVersion(input) {
+    const trimmed = input.trim();
+    // 去单个前导 v（如 `vv1.1.7` 去后剩 `v1.1.7`，仍带 v → 校验失败 → null，防双前缀）
+    const body = trimmed.startsWith('v') ? trimmed.slice(1) : trimmed;
+    const candidate = `v${body}`;
+    return isValidArchiveVersion(candidate) ? candidate : null;
+}
+/**
+ * 写归档文件（覆盖写 = 同版本幂等；backup:false，D8 定稿）。
+ * 独立锁 `flow-archive` 内原子写（同目录 temp + fsync + rename）；目录按需 mkdir（幂等）。
+ * @throws 版本字符串非法（路径穿越防御，D9）或写盘失败
+ */
+export function writeArchiveFile(projectPath, file) {
+    if (!isValidArchiveVersion(file.version)) {
+        // 破坏性写路径默认拒绝：非法版本（含路径分隔符/非版本形态）零写盘
+        throw new Error(`归档版本非法：${file.version}`);
+    }
+    const filePath = getArchiveFilePath(projectPath, file.version);
+    mkdirSync(getArchiveDir(projectPath), { recursive: true });
+    const lockPath = projectLockPath(projectPath, ARCHIVE_LOCK_NAME);
+    withFileLock(lockPath, () => {
+        atomicWriteFileSync(filePath, JSON.stringify(file, null, 2) + '\n', { backup: false });
+    });
+}
+/**
+ * 列举已归档版本（目录扫描 + 文件名合法校验）。
+ * 目录不存在 → []；仅收 `{version}.json` 且 version 通过 isValidArchiveVersion 者；返回字典序排序（非语义版本序）。
+ */
+export function listArchiveVersions(projectPath) {
+    const dir = getArchiveDir(projectPath);
+    if (!existsSync(dir)) {
+        return [];
+    }
+    return readdirSync(dir)
+        .filter((name) => name.endsWith('.json'))
+        .map((name) => name.slice(0, -'.json'.length))
+        .filter((stem) => isValidArchiveVersion(stem))
+        .sort();
+}
+/**
+ * 读取归档文件。
+ * 缺失 / 损坏（JSON 解析失败）/ 非法版本（路径穿越防御）/ 内容非对象 → null（不抛）；
+ * 未知键保留（不重建对象）；缺 counts → 按实际长度回填（读时计算，不写盘）。
+ */
+export function readArchiveFile(projectPath, version) {
+    if (!isValidArchiveVersion(version)) {
+        return null; // 读侧宽容：非法版本不抛，视同不可读
+    }
+    const filePath = getArchiveFilePath(projectPath, version);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        // 合法 JSON 但非对象（null / 数组 / 数字 / 字符串）→ 视同损坏（契约：缺失/损坏/非法 → null，REV-78-012）
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return null;
+        }
+        return withCountsFallback(parsed);
+    }
+    catch {
+        // 损坏（解析失败）：返回 null 不崩溃（读侧宽容；kb 读侧分类范式）
+        return null;
+    }
+}
+/** 读侧宽容：counts 三段齐全则原样返回；否则按实际长度回填（读时计算，不写盘） */
+function withCountsFallback(file) {
+    const counts = file.counts;
+    if (counts &&
+        typeof counts.stages === 'number' &&
+        typeof counts.reviews === 'number' &&
+        typeof counts.log === 'number') {
+        return file;
+    }
+    const stages = file.stages ?? {};
+    const reviews = file.reviews ?? [];
+    const log = file.log ?? [];
+    return {
+        ...file,
+        stages,
+        reviews,
+        log,
+        counts: {
+            stages: Object.keys(stages).length,
+            reviews: reviews.length,
+            log: log.length,
+        },
+    };
+}
+/**
+ * 读取已归档版本索引（快照副本，防外部改内存；缺失/非数组 → []）。
+ */
+export function getArchivedVersions(data) {
+    const list = data.meta?.archived_versions;
+    return Array.isArray(list) ? [...list] : [];
+}
+/**
+ * 追加已归档版本（幂等去重；**纯内存**，不写盘——持久化由命令层 save() 承担）。
+ * @returns 是否新增（false = 已存在，no-op 不追加）
+ */
+export function addArchivedVersion(data, version) {
+    if (!data.meta) {
+        // 防御：缺 meta 的存量/损坏数据（与 save() 的 ??= 兜底同字面量）
+        data.meta = { version: '1.0', project: '', updated: '', revision: 0 };
+    }
+    const existing = getArchivedVersions(data);
+    if (existing.includes(version)) {
+        return false; // 幂等：重复登记不追加
+    }
+    data.meta.archived_versions = [...existing, version];
+    return true;
+}
+/**
+ * 归档后 pipeline 处置（**纯内存**，不 IO；save 由调用方统一（裁定 P））。
+ *
+ * 前置条件：须在 stages 移除**之后**调用（phase 按归档后活跃集重算）。
+ * - `pipeline.current.stage` 属被归档版本 → 置空 `{ stage: '', op: '' }`（currentCleared = true）。
+ * - `pipeline.phase` 按活跃集重算：非空且全部 done → `'done'`，否则 `'active'`
+ *   （**空集 → active**，与 `flow-manager.ts:1495-1496` 空集守卫同效；REV-79-005）。
+ *
+ * @returns currentCleared = current 是否命中被归档版本；phase = 处置后的 pipeline.phase
+ */
+export function applyArchivePipelineDisposition(data, version) {
+    const current = data.pipeline?.current;
+    // 命中被归档版本 → 置空 current（stage 与 op 同清；versionOfStageId('') === null 故空串永不命中）
+    const currentCleared = !!current && versionOfStageId(current.stage) === version;
+    if (currentCleared && data.pipeline) {
+        data.pipeline.current = { stage: '', op: '' };
+    }
+    // 宏观 done 判定（空集守卫：无阶段视为非全 done → active）
+    const allDone = Object.keys(data.stages).length > 0
+        && Object.values(data.stages).every((s) => s.phase === 'done');
+    data.pipeline.phase = allDone ? 'done' : 'active';
+    return { currentCleared, phase: data.pipeline.phase };
+}
+//# sourceMappingURL=archive-ops.js.map

package/dist/core/flow-archive/archive-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-ops.js","sourceRoot":"","sources":["../../../src/core/flow-archive/archive-ops.ts"],"names":[],"mappings":"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"}

package/dist/core/flow-archive/grouping.d.ts

@@ -0,0 +1,58 @@
+import type { FlowData, StageData, ReviewItem, LogEntry } from '../flow-manager.js';
+import type { ArchiveFile } from './archive-file.js';
+/** splitForArchive 返回：归档段（缺 schemaVersion/archived_at，由命令层装配） + 保留段 */
+export interface SplitResult {
+    /** 归档段：不含 schemaVersion / archived_at（由 stage-79 命令层装配后交 writeArchiveFile） */
+    archive: Omit<ArchiveFile, 'schemaVersion' | 'archived_at'>;
+    /** 保留段：留在 flow.json 的条目（不可归档归属者一律落此） */
+    remainder: {
+        stages: Record<string, StageData>;
+        reviews: ReviewItem[];
+        log: LogEntry[];
+    };
+}
+/** 可归档候选（供命令面判据门消费；blocking REV 判定归命令层，本函数只读纯判定） */
+export interface ArchivableCandidate {
+    /** 版本前缀（如 `v1.1.7`） */
+    version: string;
+    /** 该版本全部 stageId（保持 stages 键遍历顺序） */
+    stages: string[];
+    /** 该版本是否全部阶段 phase=done（空集守卫：length>0 && every(done)） */
+    allDone: boolean;
+}
+/**
+ * stageId → 版本前缀（如 `v1.1.7`）。
+ * 复用 parseStageId（唯一权威，禁自写正则）：fullStageId = `${version}-${stageDir}`，剥离 `-${stageDir}` 后缀即版本段。
+ * 短名 stageId 经 parseStageId 归一化为 `v1.0.0-*`（DEFAULT_STAGE_VERSION，既定语义）。
+ * 无法解析返回 null。
+ */
+export declare function versionOfStageId(stageId: string): string | null;
+/**
+ * stages 按版本前缀分组（版本 → stageId 列表）。
+ * 保持稳定顺序（按 stages 键遍历顺序）；无法解析的 stageId 跳过（不产生分组 → 永不归档）。
+ */
+export declare function groupStagesByVersion(stages: Record<string, StageData>): Map<string, string[]>;
+/**
+ * 可归档候选列表（只读纯函数）：版本 + 该版本 stageId 列表 + 是否全部 phase=done。
+ * allDone 采用空集守卫（length > 0 && every(done)，对齐 flow-manager.ts:1484-1486 范式——空集不判 done）。
+ * 不判 REV（blocking open REV 判定归命令层，裁定 O2）。
+ */
+export declare function listArchivableCandidates(data: FlowData): ArchivableCandidate[];
+/**
+ * 版本作用域内的「阻塞 open」审查条目（只读纯函数；返回新数组副本，push 不影响 data.reviews）。
+ *
+ * 谓词为**全仓唯一**口径（对齐 `flow-manager.ts:1456`/`:1570`；REV-79-002）：
+ * `r.blocking !== false && r.status === 'open'` —— blocking 缺省（undefined）= 阻塞。
+ * 版本作用域解析与 splitForArchive **同源**（复用本文件私有 versionOfReviewOp）。
+ */
+export declare function listBlockingOpenRevsForVersion(data: FlowData, version: string): ReviewItem[];
+/**
+ * 按版本切分 flow 数据（纯函数，不写盘）。
+ * - stages：该版本全部 stageId 条目整体搬入 archive；其余（含不可解析 stageId）保留 remainder。
+ * - reviews：`versionOfReviewOp(r.op) === version` 者搬入；其余保留（保序）。
+ * - log：`versionOfLogEntry(e) === version` 者搬入；其余保留（保序；无 stageName / 不可解析一律保留）。
+ * - 版本不存在 → archive 为空集（counts 全 0），不抛错。
+ * 返回集合中的对象为原数据浅引用（调用方不得修改）。
+ */
+export declare function splitForArchive(data: FlowData, version: string): SplitResult;
+//# sourceMappingURL=grouping.d.ts.map

package/dist/core/flow-archive/grouping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grouping.d.ts","sourceRoot":"","sources":["../../../src/core/flow-archive/grouping.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,eAAe,GAAG,aAAa,CAAC,CAAC;IAC5D,wCAAwC;IACxC,SAAS,EAAE;QACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAClC,OAAO,EAAE,UAAU,EAAE,CAAC;QACtB,GAAG,EAAE,QAAQ,EAAE,CAAC;KACjB,CAAC;CACH;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,yDAAyD;IACzD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU/D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAe7F;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,QAAQ,GAAG,mBAAmB,EAAE,CAO9E;AAiBD;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAI5F;AAeD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAiD5E"}

package/dist/core/flow-archive/grouping.js

@@ -0,0 +1,153 @@
+/**
+ * 版本分组与切分纯函数 — 归档引擎的解析核心
+ * 职责：stageId → 版本前缀（复用 parseStageId，禁自写正则）；
+ *      按版本分组；按版本切分 flow 数据（stages 全搬 / reviews 按 op 前缀 / log 按 detail.stageName）。
+ * 本文件全部为纯函数（只读输入，不写盘、不加锁、不读环境）。
+ */
+import { parseStageId } from '../plan/path.js';
+/**
+ * stageId → 版本前缀（如 `v1.1.7`）。
+ * 复用 parseStageId（唯一权威，禁自写正则）：fullStageId = `${version}-${stageDir}`，剥离 `-${stageDir}` 后缀即版本段。
+ * 短名 stageId 经 parseStageId 归一化为 `v1.0.0-*`（DEFAULT_STAGE_VERSION，既定语义）。
+ * 无法解析返回 null。
+ */
+export function versionOfStageId(stageId) {
+    const parsed = parseStageId(stageId);
+    if (!parsed) {
+        return null;
+    }
+    const suffix = `-${parsed.stageDir}`;
+    if (!parsed.fullStageId.endsWith(suffix)) {
+        return null;
+    }
+    return parsed.fullStageId.slice(0, -suffix.length);
+}
+/**
+ * stages 按版本前缀分组（版本 → stageId 列表）。
+ * 保持稳定顺序（按 stages 键遍历顺序）；无法解析的 stageId 跳过（不产生分组 → 永不归档）。
+ */
+export function groupStagesByVersion(stages) {
+    const groups = new Map();
+    for (const stageId of Object.keys(stages)) {
+        const version = versionOfStageId(stageId);
+        if (!version) {
+            continue; // 无法解析 → 不分组（保留在 flow.json）
+        }
+        const list = groups.get(version);
+        if (list) {
+            list.push(stageId);
+        }
+        else {
+            groups.set(version, [stageId]);
+        }
+    }
+    return groups;
+}
+/**
+ * 可归档候选列表（只读纯函数）：版本 + 该版本 stageId 列表 + 是否全部 phase=done。
+ * allDone 采用空集守卫（length > 0 && every(done)，对齐 flow-manager.ts:1484-1486 范式——空集不判 done）。
+ * 不判 REV（blocking open REV 判定归命令层，裁定 O2）。
+ */
+export function listArchivableCandidates(data) {
+    const result = [];
+    for (const [version, stageIds] of groupStagesByVersion(data.stages)) {
+        const allDone = stageIds.length > 0 && stageIds.every((id) => data.stages[id]?.phase === 'done');
+        result.push({ version, stages: stageIds, allDone });
+    }
+    return result;
+}
+/**
+ * reviews 条目 → 版本前缀。
+ * `op` 形如 `<stageId>.op-NNN` 或 `<stageId>`：点号锚定正则 `/^(.+)\.(op-\d+)$/` 剥离 opId 段
+ * （stageId 自身可含点号，禁 split('.')；见 archive/merge.ts:57-67 既有范式）；stageId 段经 versionOfStageId。
+ * 无法归属返回 null（→ 保留在 flow.json）。
+ */
+function versionOfReviewOp(op) {
+    if (typeof op !== 'string' || op.length === 0) {
+        return null;
+    }
+    const anchor = op.match(/^(.+)\.(op-\d+)$/);
+    const stageId = anchor ? anchor[1] : op;
+    return versionOfStageId(stageId);
+}
+/**
+ * 版本作用域内的「阻塞 open」审查条目（只读纯函数；返回新数组副本，push 不影响 data.reviews）。
+ *
+ * 谓词为**全仓唯一**口径（对齐 `flow-manager.ts:1456`/`:1570`；REV-79-002）：
+ * `r.blocking !== false && r.status === 'open'` —— blocking 缺省（undefined）= 阻塞。
+ * 版本作用域解析与 splitForArchive **同源**（复用本文件私有 versionOfReviewOp）。
+ */
+export function listBlockingOpenRevsForVersion(data, version) {
+    return (data.reviews ?? []).filter((r) => versionOfReviewOp(r.op) === version && r.blocking !== false && r.status === 'open');
+}
+/**
+ * log 条目 → 版本前缀。
+ * 唯一读 `detail.stageName`（裁定 T）；缺失 / 非字符串 / 不可解析 → null（保留在 flow.json）。
+ * 注意：`detail.stageId` / `detail.stage` 等其它键一律不看（保守裁定，见 D3）。
+ */
+function versionOfLogEntry(entry) {
+    const stageName = entry?.detail?.['stageName'];
+    if (typeof stageName !== 'string') {
+        return null;
+    }
+    return versionOfStageId(stageName);
+}
+/**
+ * 按版本切分 flow 数据（纯函数，不写盘）。
+ * - stages：该版本全部 stageId 条目整体搬入 archive；其余（含不可解析 stageId）保留 remainder。
+ * - reviews：`versionOfReviewOp(r.op) === version` 者搬入；其余保留（保序）。
+ * - log：`versionOfLogEntry(e) === version` 者搬入；其余保留（保序；无 stageName / 不可解析一律保留）。
+ * - 版本不存在 → archive 为空集（counts 全 0），不抛错。
+ * 返回集合中的对象为原数据浅引用（调用方不得修改）。
+ */
+export function splitForArchive(data, version) {
+    const archiveStages = {};
+    const remainderStages = {};
+    for (const [stageId, stage] of Object.entries(data.stages)) {
+        if (versionOfStageId(stageId) === version) {
+            archiveStages[stageId] = stage;
+        }
+        else {
+            remainderStages[stageId] = stage;
+        }
+    }
+    const archiveReviews = [];
+    const remainderReviews = [];
+    for (const review of data.reviews ?? []) {
+        if (versionOfReviewOp(review.op) === version) {
+            archiveReviews.push(review);
+        }
+        else {
+            remainderReviews.push(review);
+        }
+    }
+    const archiveLog = [];
+    const remainderLog = [];
+    for (const entry of data.log ?? []) {
+        if (versionOfLogEntry(entry) === version) {
+            archiveLog.push(entry);
+        }
+        else {
+            remainderLog.push(entry);
+        }
+    }
+    return {
+        archive: {
+            version,
+            stages: archiveStages,
+            reviews: archiveReviews,
+            log: archiveLog,
+            counts: {
+                stages: Object.keys(archiveStages).length,
+                reviews: archiveReviews.length,
+                log: archiveLog.length,
+            },
+        },
+        remainder: {
+            stages: remainderStages,
+            reviews: remainderReviews,
+            log: remainderLog,
+        },
+    };
+}
+//# sourceMappingURL=grouping.js.map

package/dist/core/flow-archive/grouping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grouping.js","sourceRoot":"","sources":["../../../src/core/flow-archive/grouping.ts"],"names":[],"mappings":"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"}

package/dist/core/flow-manager.d.ts

@@ -1,6 +1,7 @@
-import { type PipelinePhase, type MetaPhase, type StageStats } from './pipeline-schema.js';
+import { type PipelinePhase, type MetaPhase, type StageStats, type ReviewTier } from './pipeline-schema.js';
 export { type PipelinePhase, type MetaPhase, type StageStats } from './pipeline-schema.js';
 import { type WorkflowMode } from './config.js';
+import type { RequirementData } from './req/types.js';
 /** 操作执行状态（B4/A1：新增 draft = 已创建未发布） */
 export type OpState = 'pending' | 'executing' | 'done' | 'failed' | 'draft';
 /** 检查点结构 */
@@ -23,6 +24,10 @@ export interface Op {
     attempts: number;
     max_attempts: number;
     checkpoints: Checkpoints;
+    /** 最近一次 attempt 记录时间（ISO；可选——存量 op 缺省，读侧宽容不注入） */
+    attempted_at?: string;
+    /** 进入 done / failed 终态时间（ISO；可选——读侧宽容不注入） */
+    completed_at?: string;
 }
 /** 审查条目 */
 export interface ReviewItem {
@@ -64,7 +69,9 @@ export interface StageData {
     /** 阶段耗时统计（可选，运行时填充） */
     stats?: StageStats;
     /** 工作流模式（可选冗余，不参与级联；读取权威恒为 status.md/级联，裁定 G） */
-    workflow_mode?: 'full' | 'fast';
+    workflow_mode?: WorkflowMode;
+    /** 关联需求 ID（单值可空；存量缺省 ≡ null，不迁移——裁定 D/L） */
+    requirement_id?: string | null;
 }
 /** Flow 完整数据结构 */
 export interface FlowData {
@@ -73,6 +80,8 @@ export interface FlowData {
         project: string;
         updated: string;
         revision?: number;
+        /** 已归档版本前缀索引（轻量索引，裁定 Q；缺失视为 []，由 getArchivedVersions 承担——REV-78-015 移除 load 读侧补齐） */
+        archived_versions?: string[];
     };
     pipeline: {
         phase: MetaPhase;
@@ -84,6 +93,8 @@ export interface FlowData {
     };
     stages: Record<string, StageData>;
     reviews: ReviewItem[];
+    /** 需求条目（顶层可选；读侧宽容——getRequirements 派生 ?? []，**不** load 补齐，REV-81-003） */
+    requirements?: RequirementData[];
     log: LogEntry[];
 }
 /** flow.json 乐观并发冲突：磁盘 revision 与本次加载时不一致（存在并发写入） */
@@ -123,7 +134,7 @@ export interface CascadeConfig {
     effective: Record<string, string>;
 }
 /** 配置生效来源枚举（`config effective` 出口，P9） */
-export type ConfigSource = 'status.md' | 'config.yaml' | 'profile.yaml' | 'builtin';
+export type ConfigSource = 'status.md' | 'config.yaml' | 'profile.yaml' | 'builtin' | 'requirement';
 /** verbose 模式下的状态变更记录 */
 export interface RecentChange {
     time: string;
@@ -269,6 +280,13 @@ export interface PhasePathResult {
 }
 /** findPhasePath BFS 深度上限（B5-1；超出按拒绝处理） */
 export declare const PHASE_PATH_MAX_DEPTH = 8;
+/**
+ * 工作流模式 → 派生的审查档位（**单源常量**；stage-92 D-92-3）。
+ * 仅用于「展示 / 提示」（`flow phases` 档位分节行与 `--json.reviewTier`）；**不参与推进语义**
+ * （`flow advance` 的有效档位 = 显式声明 ?? full，缺省恒零裁剪 ⟹ 既有流程零回归）。
+ * general（无流水线）恒全量语义，不特判。
+ */
+export declare const MODE_DERIVED_TIER: Record<WorkflowMode, ReviewTier>;
 export declare class FlowManager {
     private projectPath;
     private data;
@@ -456,14 +474,28 @@ export declare class FlowManager {
         stage: string;
         op: string;
     };
+    /**
+     * T4：跨会话恢复判定。从 log 尾部回扫（本次条目尚未写入）取该 stage 最近一条
+     * advance_stage_phase / reset_stage_phase 条目（要求 detail.to === exitedPhase）；
+     * 任一侧不可信 / 缺失 → 返回 null（调用方省略 resumed 字段，不臆断；proc: 级不参与跨会话判定）。
+     * @param log 审计日志（本次条目尚未 append）
+     * @param stageKey 阶段键（完整 stageId）
+     * @param exitedPhase 本次转换退出的 phase（= 上一次转换进入的 phase）
+     * @param currentId 本次会话标识（含来源前缀）
+     * @returns true = 异会话恢复；false = 同会话；null = 不可判定（省略字段）
+     */
+    private computeResumed;
     /**
      * 推进指定阶段到目标流水线阶段（新 API）
      * @param stageName 阶段名（如 stage-01）
      * @param phase 目标流水线阶段（PipelinePhase）
      * @param triggeredBy 触发者标识（如 'cli' / 'Feel'），默认 'flow-manager'
+     * @param opts.reviewTier 本次调用的审查档位（**仅显式声明时写审计键** `review_tier`；缺省不写 ⟹ 既有条目逐字不变）
      * @returns 是否触发 done 归档（true = 本次推进将阶段变为 done 且之前非 done，需在 save 后执行归档 commit）
      */
-    advanceStagePhase(stageName: string, phase: PipelinePhase, triggeredBy?: string): boolean;
+    advanceStagePhase(stageName: string, phase: PipelinePhase, triggeredBy?: string, opts?: {
+        reviewTier?: ReviewTier;
+    }): boolean;
     /**
      * 复位指定阶段的 phase（允许越过正向转移表回退/前进）。
      * 约束：
@@ -543,6 +575,7 @@ export declare class FlowManager {
      * 无 '|' 的简单 key 保持单条件原行为（精确相等）。
      * @param fromPhase 当前源 phase
      * @param mode 工作流模式（**必传**；由调用点经 resolveStageWorkflowMode 从 stage 派生——禁止默认 mode）
+     * @param tier 审查档位（可选，缺省 'full' = 零裁剪 ⟹ 既有调用逐字零回归）
      * @returns 去重后的可达目标 phase 列表
      */
     private getValidTargets;
@@ -556,26 +589,49 @@ export declare class FlowManager {
      * 获取当前阶段的所有可达下一阶段（基于 transitions 表，支持组合条件）
      * 供 flow wizard 交互模式使用
      * @param stageName 可选阶段名，提供时使用该阶段 phase 进行查找；否则使用 current.stage 的 phase
+     * @param tier 审查档位（可选，缺省 'full' = 零裁剪）
      */
-    getAvailablePhases(stageName?: string): PipelinePhase[];
+    getAvailablePhases(stageName?: string, tier?: ReviewTier): PipelinePhase[];
     /**
      * 在运行时 transitions 上求 stageName 当前 phase → to 的**唯一**可达路径（B5-1）。
      * BFS（深度上限 PHASE_PATH_MAX_DEPTH）；最短深度上存在多条路径 → ambiguous（拒绝，不猜测）。
      * 纯只读：不写盘、不改内存。
      * @param stageName 阶段 ID
      * @param to 目标 phase
+     * @param tier 审查档位（可选，缺省 'full' = 零裁剪；显式声明时按裁剪表求路径）
      * @returns 路径与原因（no-path/ambiguous/depth-exceeded 供命令层报错；already-at-target 按 no-op）
      */
-    findPhasePath(stageName: string, to: string): PhasePathResult;
+    findPhasePath(stageName: string, to: string, tier?: ReviewTier): PhasePathResult;
     /**
      * 获取运行时生效的 phase 列表（供 flow phases 自描述）。
      * 数据源 = this.pipelineConfig（构造时经 loadPipelineConfig 加载 .openfeel/pipeline.yaml）；
      * 缺省/解析失败时回退内置默认配置。返回副本，避免调用方修改内部状态。
      */
     getPipelinePhases(): string[];
+    /**
+     * ═══ 审查档位裁剪（stage-92 D-92-2 / D-92-3；**唯一调用点** = resolveTransitionsForMode）═══
+     * 纯函数：不改入参（不污染 FAST_TRANSITIONS 常量 / pipelineConfig），恒返回新对象 + 新数组。
+     * 算法：
+     * ① `tier === 'full'` → 深拷贝原样返回（零裁剪 ⟹ 既有调用逐字零回归）；
+     * ② 各 key 的 targets 过滤被裁剪相位（目标侧裁剪 = 跳过该审查关）；
+     * ③ **边收缩回退**——若某 key 过滤后 targets 为空且原 targets 非空，则并入「被删目标的 targets」
+     *    （再过滤被裁剪项与自身）后去重。该回退保证 fast 基表裁 `plan_review` 后 `plan_pending` 非空集
+     *    （`['plan_review']` → 收缩 `plan_review` 的 targets → `plan_pending → ['plan_passed']`）。
+     * **裁剪只作用于入边 / 目标侧**：被裁剪相位保留出边（阶段已处于被裁剪关时可向该档位下游推进）；
+     * 「**进入**被裁剪关」仍被目标侧过滤裁掉。
+     * 边界（登记）：含被裁剪相位的**组合 key**（如 `'scheme_review|x'`）按 ② 过滤 targets（不再整键删除）；
+     * 内置 full/fast 表与本仓运行时表均无此类键（唯一组合键 `'review_passed|test_passed'` 不含被裁剪相位）。
+     * @param table 模式基表（由 resolveTransitionsForMode 按既有三分支解析所得）
+     * @param tier 审查档位
+     * @returns 裁剪后的新表
+     */
+    private pruneTransitionsByTier;
     /**
      * 按模式解析运行时转移表（唯一取表法则；校验/推进/路径 与 展示 同经本函数 ⇒ 单一信源）。
      * full → 运行时 pipelineConfig.transitions（pipeline.yaml 覆盖线）；fast → fast_transitions ?? 内置快线表。
+     * general → 空表（无流水线；模式语义本身，非「缺省回落」）。
+     * 审查档位为**第二参延伸**（stage-92 D-92-3）：末尾统一经 pruneTransitionsByTier 裁剪；
+     * 缺省 tier='full' = 零裁剪 ⟹ 与原逻辑等价（唯一取表点不变，禁第二份层序 / 取表）。
      * 说明：pipelineConfig 构造期恒已加载（constructor 无条件调用），`?? 内置` 保留既有访问器回退语义。
      */
     private resolveTransitionsForMode;
@@ -583,8 +639,9 @@ export declare class FlowManager {
      * 获取运行时生效的 phase 转移表（key 可含 '|' 组合条件）。
      * 缺省/解析失败时回退内置默认配置。返回浅拷贝。
      * **无参 = full**（零回归既有消费点）；fast 供 stage-75 `flow phases` 模式分节消费。
+     * @param tier 审查档位（可选，缺省 'full' = 零裁剪）
      */
-    getPipelineTransitions(mode?: WorkflowMode): Record<string, string[]>;
+    getPipelineTransitions(mode?: WorkflowMode, tier?: ReviewTier): Record<string, string[]>;
     /**
      * 获取内置默认 phase 转移表（不受项目 pipeline.yaml 影响）。
      * 供 `flow phases` 做「运行时 vs 默认」差异报告（T19）。
@@ -631,11 +688,11 @@ export declare class FlowManager {
     /**
      * 解析指定阶段的工作流模式（裁定 E：「stage → mode」表选择解析入口；stage-75 `flow mode` 契约）。
      * 带 stage 形参独立解析（REV-74-001）：该阶段 status.md（findStatusPath(stageId)）
-     *   > config.yaml defaults > profile.yaml（**有意不承载**，实际不产出）> builtin（DEFAULT_CONFIG.workflow_mode = fast）。
+     *   > 需求级（关联需求携带的 workflow_mode）> config.yaml defaults > profile.yaml（**有意不承载**，实际不产出）> builtin（DEFAULT_CONFIG.workflow_mode = fast）。
      * 语义边界：`config effective` / `flow status --verbose` = **当前阶段域**（无参）；
      *   本方法显式 stageId = **任意阶段域**（flow mode --stage / 表选择）。
      * @param stageId 目标阶段 ID（缺省 = pipeline.current.stage；无该阶段 status.md → 自然回落下一层）
-     * @returns { value, source }，source ∈ status.md | config.yaml | profile.yaml | builtin
+     * @returns { value, source }，source ∈ status.md | requirement | config.yaml | profile.yaml | builtin
      */
     resolveStageWorkflowMode(stageId?: string): {
         value: WorkflowMode;
@@ -896,6 +953,7 @@ export declare class FlowManager {
      * 当 pipeline.yaml 不存在或解析失败时使用。
      * @param mode 工作流模式；**无参 = full**（内置 full 表逐字等于历史现状，零回归既有消费点）；
      *             'fast' 返回快线表（FAST_TRANSITIONS 常量引用）。phases / checkpoint_mapping / phase_corrections 两模式共用。
+     *             'general' 返回空转移表（无流水线；phases 仍 15 项）。
      */
     private getDefaultPipelineConfig;
 }