openfeel 1.1.7 → 1.2.1

package/dist/core/req/body-file.d.ts

@@ -0,0 +1,16 @@
+import type { RequirementData } from './types.js';
+/** 需求正文目录：{projectPath}/.openfeel/requirements（**不纳入 WORKSPACE_DIRS**，按需 mkdir 幂等创建——与归档目录同口径） */
+export declare function getRequirementsDir(projectPath: string): string;
+/** 正文**存储**相对路径（恒 POSIX 正斜杠，跨平台一致；禁 path.join——Windows 产反斜杠） */
+export declare function getRequirementBodyRelPath(id: string): string;
+/** 正文**文件系统**路径（单点；FS 访问用原生分隔符） */
+export declare function getRequirementBodyPath(projectPath: string, id: string): string;
+/**
+ * 机械铺需求正文骨架（人读副本）。
+ * - mkdir 幂等；atomicWriteFileSync（backup 缺省 false）
+ * - 目标文件已存在 → **no-op 不覆盖**（保留人工补充内容）
+ * - 恒将 req.body_path 设为本函数单点派生的 POSIX 相对路径（传入须为 addRequirement 返回的本体）
+ * @returns 目标文件的绝对路径
+ */
+export declare function writeRequirementBodySkeleton(projectPath: string, req: RequirementData): string;
+//# sourceMappingURL=body-file.d.ts.map

package/dist/core/req/body-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-file.d.ts","sourceRoot":"","sources":["../../../src/core/req/body-file.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,kGAAkG;AAClG,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,gEAAgE;AAChE,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,mCAAmC;AACnC,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE9E;AA8CD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,MAAM,CAQ9F"}

package/dist/core/req/body-file.js

@@ -0,0 +1,84 @@
+/**
+ * 需求正文文件原语 — 正文路径单点与骨架机械铺
+ *
+ * 职责：`.openfeel/requirements/REQ-NNN.md` 正文文件（人读副本）的路径派生与骨架写入。
+ * 正交声明：路径全由 `projectPath` 参数传入，零全局路径依赖；不依赖归档层 / 不引用工作流模式字段。
+ * 唯一 IO 点：骨架经 `atomicWriteFileSync` 落盘（目录按需 mkdir 幂等创建）。
+ */
+import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+import { atomicWriteFileSync } from '../fs/atomic-write.js';
+/** 需求正文目录：{projectPath}/.openfeel/requirements（**不纳入 WORKSPACE_DIRS**，按需 mkdir 幂等创建——与归档目录同口径） */
+export function getRequirementsDir(projectPath) {
+    return join(projectPath, '.openfeel', 'requirements');
+}
+/** 正文**存储**相对路径（恒 POSIX 正斜杠，跨平台一致；禁 path.join——Windows 产反斜杠） */
+export function getRequirementBodyRelPath(id) {
+    return `.openfeel/requirements/${id}.md`;
+}
+/** 正文**文件系统**路径（单点；FS 访问用原生分隔符） */
+export function getRequirementBodyPath(projectPath, id) {
+    return join(getRequirementsDir(projectPath), `${id}.md`);
+}
+/**
+ * 渲染需求正文骨架（裁定 6 模板逐字）。
+ * 状态取当前值（参数化：req add 恒 draft；req split 子需求初值 scheduled）；`target_version` 缺省渲染为 `（未指定）`。
+ */
+function renderRequirementBodySkeleton(req) {
+    const targetVersion = req.target_version !== undefined && req.target_version !== ''
+        ? req.target_version
+        : '（未指定）';
+    return [
+        `# ${req.id}：${req.title}`,
+        '',
+        '> 本文件为需求正文（人读副本，由 openfeel req 机械铺骨架）。**机读权威恒为 `.openfeel/flow.json` 的 `requirements` 条目**；两者不一致时以 flow.json 为准。下方状态为创建时快照，不追写实时状态。',
+        '',
+        '## 状态',
+        '',
+        `${req.status}（创建时快照；以 flow.json 为准）`,
+        '',
+        '## 摘要',
+        '',
+        '（待补充）',
+        '',
+        '## 目标与验收',
+        '',
+        '（待补充）',
+        '',
+        '## 预估版本',
+        '',
+        targetVersion,
+        '',
+        '## 父需求',
+        '',
+        req.parent_id ?? '（无）',
+        '',
+        '## 关联阶段',
+        '',
+        '（以 flow.json 的 `stages[*].requirement_id` 为准；此处可人工补充说明）',
+        '',
+        '## 变更记录',
+        '',
+        `- ${req.created_at} 创建（${req.id}，初始状态 ${req.status}）`,
+        '',
+    ].join('\n');
+}
+/**
+ * 机械铺需求正文骨架（人读副本）。
+ * - mkdir 幂等；atomicWriteFileSync（backup 缺省 false）
+ * - 目标文件已存在 → **no-op 不覆盖**（保留人工补充内容）
+ * - 恒将 req.body_path 设为本函数单点派生的 POSIX 相对路径（传入须为 addRequirement 返回的本体）
+ * @returns 目标文件的绝对路径
+ */
+export function writeRequirementBodySkeleton(projectPath, req) {
+    const dir = getRequirementsDir(projectPath);
+    mkdirSync(dir, { recursive: true }); // 幂等
+    const filePath = getRequirementBodyPath(projectPath, req.id);
+    req.body_path = getRequirementBodyRelPath(req.id); // 单点赋值（no-op 路径亦保证一致）
+    if (existsSync(filePath)) {
+        return filePath;
+    } // 已存在 → 不覆盖
+    atomicWriteFileSync(filePath, renderRequirementBodySkeleton(req));
+    return filePath;
+}
+//# sourceMappingURL=body-file.js.map

package/dist/core/req/body-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-file.js","sourceRoot":"","sources":["../../../src/core/req/body-file.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG5D,kGAAkG;AAClG,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,OAAO,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;AACxD,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,yBAAyB,CAAC,EAAU;IAClD,OAAO,0BAA0B,EAAE,KAAK,CAAC;AAC3C,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,sBAAsB,CAAC,WAAmB,EAAE,EAAU;IACpE,OAAO,IAAI,CAAC,kBAAkB,CAAC,WAAW,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,SAAS,6BAA6B,CAAC,GAAoB;IACzD,MAAM,aAAa,GAAG,GAAG,CAAC,cAAc,KAAK,SAAS,IAAI,GAAG,CAAC,cAAc,KAAK,EAAE;QACjF,CAAC,CAAC,GAAG,CAAC,cAAc;QACpB,CAAC,CAAC,OAAO,CAAC;IACZ,OAAO;QACL,KAAK,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,KAAK,EAAE;QAC1B,EAAE;QACF,qIAAqI;QACrI,EAAE;QACF,OAAO;QACP,EAAE;QACF,GAAG,GAAG,CAAC,MAAM,wBAAwB;QACrC,EAAE;QACF,OAAO;QACP,EAAE;QACF,OAAO;QACP,EAAE;QACF,UAAU;QACV,EAAE;QACF,OAAO;QACP,EAAE;QACF,SAAS;QACT,EAAE;QACF,aAAa;QACb,EAAE;QACF,QAAQ;QACR,EAAE;QACF,GAAG,CAAC,SAAS,IAAI,KAAK;QACtB,EAAE;QACF,SAAS;QACT,EAAE;QACF,yDAAyD;QACzD,EAAE;QACF,SAAS;QACT,EAAE;QACF,KAAK,GAAG,CAAC,UAAU,OAAO,GAAG,CAAC,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG;QACtD,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B,CAAC,WAAmB,EAAE,GAAoB;IACpF,MAAM,GAAG,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC;IAC5C,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAuB,KAAK;IAChE,MAAM,QAAQ,GAAG,sBAAsB,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7D,GAAG,CAAC,SAAS,GAAG,yBAAyB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAS,sBAAsB;IACjF,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAAC,OAAO,QAAQ,CAAC;IAAC,CAAC,CAAa,YAAY;IACvE,mBAAmB,CAAC,QAAQ,EAAE,6BAA6B,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/core/req/requirement-ops.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 需求原语 — 需求层纯内存操作的单一入口
+ *
+ * 职责：需求读取（读侧宽容 + 浅副本）、ID 分配、写路径原语（add / claim / release / update / advance / link）
+ *       与共用谓词（终态判定 / 全部关联阶段 done）。全部为**纯内存**操作 + 审计内嵌（`data.log`），
+ *       零独立写盘点——落盘恒走调用方（命令层）的 `FlowManager` 落盘方法。
+ * 边界声明：不依赖归档层；模式属性（workflow_mode?）为调度属性——本层只做「值域校验 + 载体制门」，
+ *   解析 / 下发单点在 FlowManager；不参与聚合判定。
+ */
+import type { FlowData } from '../flow-manager.js';
+import { type WorkflowMode } from '../config.js';
+import { type RequirementData, type RequirementPriority, type RequirementStatus } from './types.js';
+/** 需求原语错误码（冻结；命令层据此映射 exit 非 0 零写盘） */
+export type RequirementErrorCode = 'not_found' | 'stage_not_found' | 'already_claimed' | 'already_linked' | 'invalid_status' | 'invalid_field' | 'general_mode_conflict';
+/** 写路径原语结果（ok=false 时携错误码；命令层映射 exit 非 0 零写盘） */
+export type RequirementOpResult = {
+    ok: true;
+    changed: boolean;
+} | {
+    ok: false;
+    code: RequirementErrorCode;
+};
+/** 拆分原语结果（成功携子需求**本体**列表；失败携错误码——**业务分流范式**，REV-87-002 定稿） */
+export type RequirementSplitResult = {
+    ok: true;
+    children: RequirementData[];
+} | {
+    ok: false;
+    code: RequirementErrorCode;
+};
+/** 全量需求（读侧宽容：缺失/非数组 → []；数组 + 元素浅副本，防外部直改内存） */
+export declare function getRequirements(data: FlowData): RequirementData[];
+/** 按 id 查询（未命中 null；返回浅副本） */
+export declare function getRequirement(data: FlowData, id: string): RequirementData | null;
+/** 过滤查询（status 精确 / target_version 精确 / owner 精确；多条件 AND；API 面命名统一 target_version——REV-81-012） */
+export declare function listRequirements(data: FlowData, filter?: {
+    status?: RequirementStatus;
+    target_version?: string;
+    owner?: string;
+}): RequirementData[];
+/** 下一个需求 ID：现存 id 数字部分 max+1（不回收；异常 id 跳过不崩） */
+export declare function nextRequirementId(data: FlowData): string;
+/** 终态判定（done/cancelled/rejected；claim / link 门共用） */
+export declare function isTerminalRequirementStatus(status: RequirementStatus): boolean;
+/** 裁定 4：全部关联阶段 done（零关联 → false，空集守卫） */
+export declare function allLinkedStagesDone(data: FlowData, requirementId: string): boolean;
+/**
+ * 完成门判据（BUG-002 单点收口；裁定 4 扩展为两路——stage-93）：
+ *   路 1（不变）：非 general 需求 → allLinkedStagesDone（有阶段且全 done；零关联恒 false）；
+ *   路 2（新增）：general 需求 → 载体制对偶完成路径（显式完成直接放行；general 恒零关联，
+ *     由双向载体制门保证——updateRequirement / linkRequirement）。
+ * 判据来源 = 需求自身 workflow_mode 字段直判（与载体制门同源；禁解析级联——解析链仅作用于阶段侧调度）。
+ * 防御：general 且有链接 = 载体制门不可达的数据损坏态 → 从严回落路 1（不因模式字段获得额外豁免）。
+ */
+export declare function canCompleteRequirement(data: FlowData, req: RequirementData): boolean;
+/**
+ * 新建需求（恒 `status: 'draft'`；读侧宽容写路径；返回**本体**供调用方继续设 body_path）。
+ * 非法入参（空 title / 非法 priority / 空 target_version）属构造期契约违反 → 抛错（唯一抛错原语，REV-81-015）。
+ * REV-81-018 登记：add 构造期抛错 / update 运行期错误码为接受差异（与命令层分流矩阵同口径，REV-82-002）；stage-81 冻结面不统一。
+ */
+export declare function addRequirement(data: FlowData, input: {
+    title: string;
+    target_version?: string;
+    priority?: RequirementPriority;
+    workflow_mode?: WorkflowMode;
+}): RequirementData;
+/**
+ * 拆分需求为若干子需求（T1 / Q4 定稿；纯内存 + 单条审计，落盘恒由调用方 save()）。
+ * 门（顺序固定；任一失败 → **零变更零审计**）：
+ *   ① children 非数组 / 空 → invalid_field（argument-shape）
+ *   ② 父不存在 → not_found
+ *   ③ 父终态 → invalid_status（与 claim / link 同款终态门）
+ *   ④ 逐子项标题校验（trim 后空串）→ invalid_field
+ *      —— **校验内容**对齐 add 构造期口径，**错误范式**为运行期错误码（REV-87-002 定稿：
+ *      split 不复用 add 的抛错路径，自持校验循环，与 update 同族——命令层 failCode 分流零适配）。
+ * 构造（校验全通过后单趟完成，循环内零可失败语句）：
+ *   - 顺序分配 ID：第 N 子 = 当前 max + N（经 staged 容器复用 nextRequirementId **单源派生**——不新写解析）；
+ *   - parent_id = 父 ID；status = SPLIT_CHILD_STATUS；created_at / updated_at 同批；
+ *   - **一次性并入** data.requirements（半成品不可达——全成或零变更）；
+ *   - 审计恰一条 requirement_split（detail {parentId, children: [ids]}——对齐 requirement_* 族命名）；
+ *   - 父需求**零副作用**（状态不变 / 不刷 updated_at / 不写父侧字段——父流转由 feel 显式执行）。
+ * 环检测：不写——子 ID 恒为新建 max+1、方向恒 `child → parent`，结构上无环。
+ * 返回子需求**本体**列表（供调用方逐条铺正文，对齐 addRequirement 返回本体先例；禁浅副本路径）。
+ */
+export declare function splitRequirement(data: FlowData, parentId: string, children: Array<{
+    title: string;
+}>): RequirementSplitResult;
+/** 认领需求（占用校验；同 owner 幂等；终态拒绝；他人占用零变更零审计） */
+export declare function claimRequirement(data: FlowData, id: string, owner: string): RequirementOpResult;
+/** 释放认领（裁定 5：无占用者 = no-op 成功——不刷 updated_at / 不写审计；不设状态门） */
+export declare function releaseRequirement(data: FlowData, id: string): RequirementOpResult;
+/**
+ * 当前状态的合法目标列表（只读纯函数；领域外状态 → []）。
+ * 命令层「列合法目标」的唯一来源——禁第二份流转表（REV-82-003）；返回副本，防调用方直改内部表。
+ */
+export declare function getAllowedNextStatuses(status: RequirementStatus): RequirementStatus[];
+/**
+ * 更新需求（patch 白名单；全部维度先校验后落地——校验失败整 patch 零变更）。
+ * 恒 raw find 改 `data.requirements` 本体（禁经 getRequirement 的浅副本——副本陷阱，REV-81-011）。
+ */
+export declare function updateRequirement(data: FlowData, id: string, patch: {
+    status?: RequirementStatus;
+    title?: string;
+    target_version?: string;
+    priority?: RequirementPriority;
+    workflow_mode?: WorkflowMode;
+}): RequirementOpResult;
+/** 显式人工推进（裁定 M）；语义与 update({status}) 完全一致（同表同门同审计，零第二套） */
+export declare function advanceRequirement(data: FlowData, id: string, to: RequirementStatus): RequirementOpResult;
+/**
+ * 阶段关联需求（stage 侧写点；`null` = 解绑）。
+ * 终态需求拒绝关联、他人已关联阶段拒绝重绑（须先解绑）；
+ * 不刷新 requirement.updated_at（关联写点落在 stage 记录，需求对象零变更）。
+ */
+export declare function linkRequirement(data: FlowData, stageId: string, requirementId: string | null): RequirementOpResult;
+//# sourceMappingURL=requirement-ops.d.ts.map

package/dist/core/req/requirement-ops.d.ts.map

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

package/dist/core/req/requirement-ops.js

@@ -0,0 +1,395 @@
+import { WORKFLOW_MODES } from '../config.js'; // 值域单源（运行时值导入，禁就地三值字面量）
+import { REQ_ID_PATTERN, REQ_PRIORITIES, REQ_STATUSES, } from './types.js';
+/** 追加需求审计日志（纯内存；save 由调用方承担） */
+function appendRequirementLog(data, action, detail) {
+    data.log.push({ time: new Date().toISOString(), agent: 'cli', action, detail });
+}
+// ═══ 读取与分配（读侧宽容 + 浅副本，裁定 2/8）═══
+/** 全量需求（读侧宽容：缺失/非数组 → []；数组 + 元素浅副本，防外部直改内存） */
+export function getRequirements(data) {
+    const list = data.requirements;
+    return Array.isArray(list) ? list.map((r) => ({ ...r })) : [];
+}
+/** 按 id 查询（未命中 null；返回浅副本） */
+export function getRequirement(data, id) {
+    const found = (Array.isArray(data.requirements) ? data.requirements : []).find((r) => r?.id === id);
+    return found ? { ...found } : null;
+}
+/** 过滤查询（status 精确 / target_version 精确 / owner 精确；多条件 AND；API 面命名统一 target_version——REV-81-012） */
+export function listRequirements(data, filter) {
+    let result = getRequirements(data);
+    if (filter?.status !== undefined) {
+        result = result.filter((r) => r.status === filter.status);
+    }
+    if (filter?.target_version !== undefined) {
+        result = result.filter((r) => r.target_version === filter.target_version);
+    }
+    if (filter?.owner !== undefined) {
+        result = result.filter((r) => r.owner === filter.owner);
+    }
+    return result;
+}
+/** 下一个需求 ID：现存 id 数字部分 max+1（不回收；异常 id 跳过不崩） */
+export function nextRequirementId(data) {
+    let max = 0;
+    for (const r of getRequirements(data)) {
+        const m = REQ_ID_PATTERN.exec(typeof r?.id === 'string' ? r.id : '');
+        if (!m) {
+            continue;
+        } // 异常 id 跳过（不崩）
+        const n = Number.parseInt(m[1], 10);
+        if (Number.isFinite(n) && n > max) {
+            max = n;
+        }
+    }
+    return `REQ-${String(max + 1).padStart(3, '0')}`;
+}
+/** 终态判定（done/cancelled/rejected；claim / link 门共用） */
+export function isTerminalRequirementStatus(status) {
+    return status === 'done' || status === 'cancelled' || status === 'rejected';
+}
+/** 裁定 4：全部关联阶段 done（零关联 → false，空集守卫） */
+export function allLinkedStagesDone(data, requirementId) {
+    const linked = Object.values(data.stages ?? {}).filter((s) => (s.requirement_id ?? null) === requirementId);
+    return linked.length > 0 && linked.every((s) => s.phase === 'done');
+}
+/**
+ * 完成门判据（BUG-002 单点收口；裁定 4 扩展为两路——stage-93）：
+ *   路 1（不变）：非 general 需求 → allLinkedStagesDone（有阶段且全 done；零关联恒 false）；
+ *   路 2（新增）：general 需求 → 载体制对偶完成路径（显式完成直接放行；general 恒零关联，
+ *     由双向载体制门保证——updateRequirement / linkRequirement）。
+ * 判据来源 = 需求自身 workflow_mode 字段直判（与载体制门同源；禁解析级联——解析链仅作用于阶段侧调度）。
+ * 防御：general 且有链接 = 载体制门不可达的数据损坏态 → 从严回落路 1（不因模式字段获得额外豁免）。
+ */
+export function canCompleteRequirement(data, req) {
+    if (req.workflow_mode === 'general') {
+        const hasLinked = Object.values(data.stages ?? {}).some((s) => (s.requirement_id ?? null) === req.id);
+        if (!hasLinked) {
+            return true;
+        }
+    }
+    return allLinkedStagesDone(data, req.id);
+}
+// ═══ 写路径原语 ═══
+/**
+ * 新建需求（恒 `status: 'draft'`；读侧宽容写路径；返回**本体**供调用方继续设 body_path）。
+ * 非法入参（空 title / 非法 priority / 空 target_version）属构造期契约违反 → 抛错（唯一抛错原语，REV-81-015）。
+ * REV-81-018 登记：add 构造期抛错 / update 运行期错误码为接受差异（与命令层分流矩阵同口径，REV-82-002）；stage-81 冻结面不统一。
+ */
+export function addRequirement(data, input) {
+    const title = typeof input?.title === 'string' ? input.title.trim() : '';
+    if (title === '') {
+        throw new Error('需求标题不能为空');
+    } // 非法入参：编程错误抛错（非业务冲突）
+    if (input.priority !== undefined && !REQ_PRIORITIES.includes(input.priority)) {
+        throw new Error(`需求优先级非法：${String(input.priority)}`); // 值域单点 = REQ_PRIORITIES
+    }
+    if (input.workflow_mode !== undefined && !WORKFLOW_MODES.includes(input.workflow_mode)) {
+        throw new Error(`需求工作流模式非法：${String(input.workflow_mode)}`); // 值域单点 = WORKFLOW_MODES
+    }
+    // 命名统一（REV-81-012）：API 面恒 target_version（与存储字段同名，零映射层）
+    if (input.target_version !== undefined && String(input.target_version).trim() === '') {
+        throw new Error('预估版本不能为空串');
+    }
+    // 非数组（损坏数据）视同空集重建——与其余原语「非数组 ≡ 空集」宽容口径统一（req/BUG-001 = REV-81-019 单点收口）；改自 ??=（??= 不替换非数组真值 → push 抛 TypeError）
+    data.requirements = Array.isArray(data.requirements) ? data.requirements : [];
+    const now = new Date().toISOString();
+    const req = {
+        id: nextRequirementId(data), // 须在 push 之前分配
+        title,
+        status: 'draft', // 新建即 draft（REV-81-005）
+        created_at: now,
+        updated_at: now,
+    };
+    if (input.target_version !== undefined) {
+        req.target_version = String(input.target_version).trim();
+    }
+    if (input.priority !== undefined) {
+        req.priority = input.priority;
+    }
+    if (input.workflow_mode !== undefined) {
+        req.workflow_mode = input.workflow_mode;
+    }
+    data.requirements.push(req);
+    appendRequirementLog(data, 'requirement_add', { id: req.id, title: req.title });
+    return req; // 本体（调用方继续设 body_path）
+}
+/** 子需求初值状态：拆分即发布（Q11 定稿——子需求直接入 `req next` 候选池，达成「并行接取就绪」） */
+const SPLIT_CHILD_STATUS = 'scheduled';
+/**
+ * 拆分需求为若干子需求（T1 / Q4 定稿；纯内存 + 单条审计，落盘恒由调用方 save()）。
+ * 门（顺序固定；任一失败 → **零变更零审计**）：
+ *   ① children 非数组 / 空 → invalid_field（argument-shape）
+ *   ② 父不存在 → not_found
+ *   ③ 父终态 → invalid_status（与 claim / link 同款终态门）
+ *   ④ 逐子项标题校验（trim 后空串）→ invalid_field
+ *      —— **校验内容**对齐 add 构造期口径，**错误范式**为运行期错误码（REV-87-002 定稿：
+ *      split 不复用 add 的抛错路径，自持校验循环，与 update 同族——命令层 failCode 分流零适配）。
+ * 构造（校验全通过后单趟完成，循环内零可失败语句）：
+ *   - 顺序分配 ID：第 N 子 = 当前 max + N（经 staged 容器复用 nextRequirementId **单源派生**——不新写解析）；
+ *   - parent_id = 父 ID；status = SPLIT_CHILD_STATUS；created_at / updated_at 同批；
+ *   - **一次性并入** data.requirements（半成品不可达——全成或零变更）；
+ *   - 审计恰一条 requirement_split（detail {parentId, children: [ids]}——对齐 requirement_* 族命名）；
+ *   - 父需求**零副作用**（状态不变 / 不刷 updated_at / 不写父侧字段——父流转由 feel 显式执行）。
+ * 环检测：不写——子 ID 恒为新建 max+1、方向恒 `child → parent`，结构上无环。
+ * 返回子需求**本体**列表（供调用方逐条铺正文，对齐 addRequirement 返回本体先例；禁浅副本路径）。
+ */
+export function splitRequirement(data, parentId, children) {
+    if (!Array.isArray(children) || children.length === 0) {
+        return { ok: false, code: 'invalid_field' };
+    }
+    const parent = (Array.isArray(data.requirements) ? data.requirements : []).find((r) => r?.id === parentId);
+    if (!parent) {
+        return { ok: false, code: 'not_found' };
+    }
+    if (isTerminalRequirementStatus(parent.status)) {
+        return { ok: false, code: 'invalid_status' };
+    }
+    const titles = [];
+    for (const c of children) {
+        const title = typeof c?.title === 'string' ? c.title.trim() : '';
+        if (title === '') {
+            return { ok: false, code: 'invalid_field' };
+        }
+        titles.push(title);
+    }
+    // staged 容器承载「当前 max」：复用 nextRequirementId 单源派生 → 顺序分配且不重解析
+    const list = Array.isArray(data.requirements) ? [...data.requirements] : [];
+    const staged = { ...data, requirements: list };
+    const now = new Date().toISOString();
+    const created = [];
+    for (const title of titles) {
+        const child = {
+            id: nextRequirementId(staged),
+            title,
+            status: SPLIT_CHILD_STATUS,
+            parent_id: parentId,
+            created_at: now,
+            updated_at: now,
+        };
+        list.push(child);
+        created.push(child);
+    }
+    data.requirements = list;
+    appendRequirementLog(data, 'requirement_split', { parentId, children: created.map((c) => c.id) });
+    return { ok: true, children: created };
+}
+/** 认领需求（占用校验；同 owner 幂等；终态拒绝；他人占用零变更零审计） */
+export function claimRequirement(data, id, owner) {
+    const name = typeof owner === 'string' ? owner.trim() : '';
+    if (name === '') {
+        return { ok: false, code: 'invalid_field' };
+    }
+    const req = (Array.isArray(data.requirements) ? data.requirements : []).find((r) => r?.id === id);
+    if (!req) {
+        return { ok: false, code: 'not_found' };
+    }
+    if (isTerminalRequirementStatus(req.status)) {
+        return { ok: false, code: 'invalid_status' };
+    }
+    if (req.owner && req.owner !== name) {
+        return { ok: false, code: 'already_claimed' };
+    } // 数据零变更
+    if (req.owner === name) {
+        return { ok: true, changed: false };
+    } // 同 owner 幂等
+    req.owner = name;
+    req.claimed_at = new Date().toISOString();
+    req.updated_at = req.claimed_at;
+    appendRequirementLog(data, 'requirement_claim', { id, owner: name });
+    return { ok: true, changed: true };
+}
+/** 释放认领（裁定 5：无占用者 = no-op 成功——不刷 updated_at / 不写审计；不设状态门） */
+export function releaseRequirement(data, id) {
+    const req = (Array.isArray(data.requirements) ? data.requirements : []).find((r) => r?.id === id);
+    if (!req) {
+        return { ok: false, code: 'not_found' };
+    }
+    if (!req.owner) {
+        return { ok: true, changed: false };
+    } // 无占用者：no-op 成功（不刷 updated_at / 不写审计）
+    const prevOwner = req.owner;
+    delete req.owner;
+    delete req.claimed_at;
+    req.updated_at = new Date().toISOString();
+    appendRequirementLog(data, 'requirement_release', { id, owner: prevOwner });
+    return { ok: true, changed: true };
+}
+/** 显式流转表（裁定 3；终态不再流转）——状态流转单点 */
+const ALLOWED_TRANSITIONS = {
+    draft: ['scheduled', 'blocked', 'cancelled', 'rejected'],
+    scheduled: ['in_progress', 'blocked', 'cancelled', 'rejected'],
+    in_progress: ['done', 'blocked', 'cancelled', 'rejected'],
+    blocked: ['scheduled', 'in_progress', 'cancelled', 'rejected'],
+    done: [], cancelled: [], rejected: [],
+};
+/**
+ * 当前状态的合法目标列表（只读纯函数；领域外状态 → []）。
+ * 命令层「列合法目标」的唯一来源——禁第二份流转表（REV-82-003）；返回副本，防调用方直改内部表。
+ */
+export function getAllowedNextStatuses(status) {
+    return [...(ALLOWED_TRANSITIONS[status] ?? [])];
+}
+/** 状态变更应用（唯一实现）：返回 false = invalid_status（含 done 门不满足） */
+function applyStatusChange(data, req, to) {
+    if (!REQ_STATUSES.includes(to)) {
+        return false;
+    }
+    if (to === req.status) {
+        return false;
+    } // 同值由调用方按幂等 no-op 处理
+    // 域外 status（存量脏数据 / 人工篡改）→ 查表得 undefined，守卫后与「表外组合」同语义，不抛 TypeError（REV-81-016）
+    const allowed = ALLOWED_TRANSITIONS[req.status];
+    if (!allowed || !allowed.includes(to)) {
+        return false;
+    }
+    // 裁定 4 扩展（stage-93）：completion 判据单点（canCompleteRequirement），不再直呼路 1
+    if (to === 'done' && !canCompleteRequirement(data, req)) {
+        return false;
+    }
+    const from = req.status;
+    req.status = to;
+    req.updated_at = new Date().toISOString(); // 状态维度刷新（单次赋值纪律，REV-81-013）
+    appendRequirementLog(data, 'requirement_status', { id: req.id, from, to });
+    return true;
+}
+/** 字段白名单（= RequirementData 可变字段名子集） */
+const PATCH_WHITELIST = ['status', 'title', 'target_version', 'priority', 'workflow_mode'];
+/**
+ * 更新需求（patch 白名单；全部维度先校验后落地——校验失败整 patch 零变更）。
+ * 恒 raw find 改 `data.requirements` 本体（禁经 getRequirement 的浅副本——副本陷阱，REV-81-011）。
+ */
+export function updateRequirement(data, id, patch) {
+    // ① 内联 raw find（与 claim / release 同款）
+    const req = (Array.isArray(data.requirements) ? data.requirements : []).find((r) => r?.id === id);
+    if (!req) {
+        return { ok: false, code: 'not_found' };
+    }
+    const p = patch ?? {};
+    const keys = Object.entries(p).filter(([, v]) => v !== undefined).map(([k]) => k);
+    // ② 白名单外键（值非 undefined 才计）
+    for (const k of keys) {
+        if (!PATCH_WHITELIST.includes(k)) {
+            return { ok: false, code: 'invalid_field' };
+        }
+    }
+    // ③ 全空 patch（或全 undefined 值）
+    if (keys.length === 0) {
+        return { ok: true, changed: false };
+    }
+    // ④ 值校验（全部维度先校验，失败即整 patch 零变更）
+    // REV-81-018 登记：add 构造期抛错 / update 运行期错误码为接受差异（与命令层分流矩阵同口径，REV-82-002）；stage-81 冻结面不统一。
+    if (p.title !== undefined && String(p.title).trim() === '') {
+        return { ok: false, code: 'invalid_field' };
+    }
+    if (p.target_version !== undefined && (typeof p.target_version !== 'string' || p.target_version.trim() === '')) {
+        return { ok: false, code: 'invalid_field' };
+    }
+    if (p.priority !== undefined && !REQ_PRIORITIES.includes(p.priority)) {
+        return { ok: false, code: 'invalid_field' };
+    }
+    if (p.status !== undefined && !REQ_STATUSES.includes(p.status)) {
+        return { ok: false, code: 'invalid_status' };
+    }
+    if (p.workflow_mode !== undefined && !WORKFLOW_MODES.includes(p.workflow_mode)) {
+        return { ok: false, code: 'invalid_field' }; // 值域单点 = WORKFLOW_MODES
+    }
+    // 载体制门（D-90-4）：general 仅限**无关联阶段**的需求（有链接阶段 → 拒绝；零变更零审计）
+    if (p.workflow_mode === 'general') {
+        const hasLinked = Object.values(data.stages ?? {}).some((s) => (s.requirement_id ?? null) === id);
+        if (hasLinked) {
+            return { ok: false, code: 'general_mode_conflict' };
+        }
+    }
+    // ⑥ 状态维度（= 当前则无变更；≠ 走单点 applyStatusChange）
+    let statusChanged = false;
+    if (p.status !== undefined && p.status !== req.status) {
+        if (!applyStatusChange(data, req, p.status)) {
+            return { ok: false, code: 'invalid_status' };
+        }
+        statusChanged = true;
+    }
+    // ⑦ 字段维度（逐字段比较后对 raw 本体赋值；仅实际不同才赋值）
+    const changedFields = [];
+    if (p.title !== undefined) {
+        const v = String(p.title).trim();
+        if (req.title !== v) {
+            req.title = v;
+            changedFields.push('title');
+        }
+    }
+    if (p.target_version !== undefined) {
+        const v = String(p.target_version).trim();
+        if (req.target_version !== v) {
+            req.target_version = v;
+            changedFields.push('target_version');
+        }
+    }
+    if (p.priority !== undefined) {
+        if (req.priority !== p.priority) {
+            req.priority = p.priority;
+            changedFields.push('priority');
+        }
+    }
+    if (p.workflow_mode !== undefined) {
+        if (req.workflow_mode !== p.workflow_mode) {
+            req.workflow_mode = p.workflow_mode;
+            changedFields.push('workflow_mode');
+        }
+    }
+    // ⑧ updated_at 单次赋值纪律（REV-81-013）：字段维度实际变更且状态维度未变时刷新一次；
+    //    状态维度已由 applyStatusChange 刷新，两维度并存时不重复赋值
+    if (changedFields.length > 0) {
+        if (!statusChanged) {
+            req.updated_at = new Date().toISOString();
+        }
+        appendRequirementLog(data, 'requirement_update', { id, fields: changedFields });
+    }
+    // ⑩
+    return { ok: true, changed: statusChanged || changedFields.length > 0 };
+}
+/** 显式人工推进（裁定 M）；语义与 update({status}) 完全一致（同表同门同审计，零第二套） */
+export function advanceRequirement(data, id, to) {
+    return updateRequirement(data, id, { status: to });
+}
+/**
+ * 阶段关联需求（stage 侧写点；`null` = 解绑）。
+ * 终态需求拒绝关联、他人已关联阶段拒绝重绑（须先解绑）；
+ * 不刷新 requirement.updated_at（关联写点落在 stage 记录，需求对象零变更）。
+ */
+export function linkRequirement(data, stageId, requirementId) {
+    const stage = data.stages?.[stageId];
+    if (!stage) {
+        return { ok: false, code: 'stage_not_found' };
+    } // ① 阶段不存在
+    if (requirementId !== null) {
+        const req = (Array.isArray(data.requirements) ? data.requirements : []).find((r) => r?.id === requirementId);
+        if (!req) {
+            return { ok: false, code: 'not_found' };
+        } // 需求不存在
+        if (isTerminalRequirementStatus(req.status)) {
+            return { ok: false, code: 'invalid_status' };
+        } // 终态拒绝
+        // 载体制门（D-90-4）：general（无流水线）需求不接受阶段关联
+        if (req.workflow_mode === 'general') {
+            return { ok: false, code: 'general_mode_conflict' };
+        }
+        if ((stage.requirement_id ?? null) === requirementId) {
+            return { ok: true, changed: false };
+        } // 同值幂等
+        if (stage.requirement_id != null) {
+            return { ok: false, code: 'already_linked' };
+        } // 跨需求重绑
+        stage.requirement_id = requirementId;
+        appendRequirementLog(data, 'requirement_link', { stage: stageId, requirementId });
+        return { ok: true, changed: true };
+    }
+    // ③ null = 解绑（显式 null，对齐「可空」裁定 D）
+    if (stage.requirement_id == null) {
+        return { ok: true, changed: false };
+    }
+    stage.requirement_id = null;
+    appendRequirementLog(data, 'requirement_link', { stage: stageId, requirementId: null });
+    return { ok: true, changed: true };
+}
+//# sourceMappingURL=requirement-ops.js.map