@twinsearth/dsh-master 3.3.4 → 3.3.6

package/dist-host/channel/ws.js

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+/**
+ * 最小 RFC 6455 服务端实现（不引入 `ws` 依赖）。
+ *
+ * 只覆盖本通道需要的能力：
+ *   * 握手：`Sec-WebSocket-Accept` = base64(sha1(key + GUID))；
+ *   * 收帧：客户端帧必须带掩码（RFC 要求），支持 7/16/64 位长度、分片续帧、close/ping/pong；
+ *   * 发帧：服务端文本帧不加掩码，另发 ping/close。
+ *
+ * 不做：permessage-deflate、二进制 payload 处理（收到即忽略）、扩展协商。
+ */
+import crypto from 'node:crypto';
+export const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+export const WS_MAX_PAYLOAD = 256 * 1024;
+export const OPCODE = Object.freeze({ continuation: 0x0, text: 0x1, binary: 0x2, close: 0x8, ping: 0x9, pong: 0xa });
+/** 计算握手 accept 值（RFC 6455 §1.3）。 */
+export function acceptKey(clientKey) {
+    return crypto.createHash('sha1').update(String(clientKey) + WS_GUID).digest('base64');
+}
+/** 是否是合法的 WebSocket 升级请求；返回具名原因以便拒绝时说明。 */
+export function validateUpgradeRequest(req) {
+    const headers = req?.headers ?? {};
+    const upgrade = String(headers.upgrade ?? '').toLowerCase();
+    const connection = String(headers.connection ?? '').toLowerCase();
+    const key = String(headers['sec-websocket-key'] ?? '').trim();
+    const version = String(headers['sec-websocket-version'] ?? '').trim();
+    if (upgrade !== 'websocket')
+        return { ok: false, code: 'not-websocket-upgrade' };
+    if (!connection.split(',').map((part) => part.trim()).includes('upgrade'))
+        return { ok: false, code: 'missing-connection-upgrade' };
+    if (!key || Buffer.from(key, 'base64').length !== 16)
+        return { ok: false, code: 'invalid-websocket-key' };
+    if (version !== '13')
+        return { ok: false, code: 'unsupported-websocket-version', version };
+    return { ok: true, key, accept: acceptKey(key) };
+}
+/** 生成 101 响应文本。 */
+export function upgradeResponse(accept) {
+    return [
+        'HTTP/1.1 101 Switching Protocols',
+        'Upgrade: websocket',
+        'Connection: Upgrade',
+        `Sec-WebSocket-Accept: ${accept}`,
+        '', '',
+    ].join('\r\n');
+}
+/** 生成拒绝响应（带状态码与具名原因）。 */
+export function rejectionResponse(status, code, message) {
+    const body = JSON.stringify({ ok: false, code, message });
+    return [
+        `HTTP/1.1 ${status} ${status === 401 ? 'Unauthorized' : status === 400 ? 'Bad Request' : 'Forbidden'}`,
+        'Content-Type: application/json; charset=utf-8',
+        `Content-Length: ${Buffer.byteLength(body)}`,
+        'Connection: close',
+        '', body,
+    ].join('\r\n');
+}
+function encodeFrame(opcode, payloadBuffer) {
+    const length = payloadBuffer.length;
+    let header = null;
+    if (length < 126) {
+        header = Buffer.alloc(2);
+        header[1] = length;
+    }
+    else if (length < 65536) {
+        header = Buffer.alloc(4);
+        header[1] = 126;
+        header.writeUInt16BE(length, 2);
+    }
+    else {
+        header = Buffer.alloc(10);
+        header[1] = 127;
+        header.writeBigUInt64BE(BigInt(length), 2);
+    }
+    header[0] = 0x80 | opcode; // FIN + opcode
+    return Buffer.concat([header, payloadBuffer]);
+}
+export function encodeText(value) {
+    return encodeFrame(OPCODE.text, Buffer.from(String(value), 'utf8'));
+}
+export function encodeClose(code = 1000, reason = '') {
+    const reasonBuffer = Buffer.from(String(reason), 'utf8');
+    const payload = Buffer.alloc(2 + reasonBuffer.length);
+    payload.writeUInt16BE(Number(code) || 1000, 0);
+    reasonBuffer.copy(payload, 2);
+    return encodeFrame(OPCODE.close, payload);
+}
+export function encodePing() {
+    return encodeFrame(OPCODE.ping, Buffer.alloc(0));
+}
+export function encodePong(payload = Buffer.alloc(0)) {
+    return encodeFrame(OPCODE.pong, Buffer.from(payload));
+}
+/**
+ * 增量帧解析器。`push(buffer)` 返回本次解析出的完整消息与需要回应的控制帧。
+ * 超过 maxPayload 的帧返回 error 并停止后续解析（由调用方断开连接）。
+ */
+export function createFrameParser({ maxPayload = WS_MAX_PAYLOAD } = {}) {
+    let pending = Buffer.alloc(0);
+    let fragments = [];
+    let fragmentOpcode = null;
+    function takeMessage(opcode, payload) {
+        if (opcode === OPCODE.continuation) {
+            if (fragmentOpcode === null)
+                return { error: 'unexpected-continuation' };
+            fragments.push(payload);
+            return null;
+        }
+        fragments = [payload];
+        fragmentOpcode = opcode;
+        return null;
+    }
+    return {
+        push(chunk) {
+            pending = pending.length === 0 ? Buffer.from(chunk) : Buffer.concat([pending, chunk]);
+            const messages = [];
+            const controls = [];
+            const errors = [];
+            while (pending.length >= 2) {
+                const first = pending[0];
+                const second = pending[1];
+                const fin = (first & 0x80) !== 0;
+                const opcode = first & 0x0f;
+                const masked = (second & 0x80) !== 0;
+                let length = second & 0x7f;
+                let offset = 2;
+                if (length === 126) {
+                    if (pending.length < offset + 2)
+                        break;
+                    length = pending.readUInt16BE(offset);
+                    offset += 2;
+                }
+                else if (length === 127) {
+                    if (pending.length < offset + 8)
+                        break;
+                    const big = pending.readBigUInt64BE(offset);
+                    if (big > BigInt(maxPayload)) {
+                        errors.push('payload-too-large');
+                        return { messages, controls, errors };
+                    }
+                    length = Number(big);
+                    offset += 8;
+                }
+                if (length > maxPayload) {
+                    errors.push('payload-too-large');
+                    return { messages, controls, errors };
+                }
+                if (!masked) {
+                    errors.push('client-frame-must-be-masked');
+                    return { messages, controls, errors };
+                }
+                if (pending.length < offset + 4 + length)
+                    break;
+                const mask = pending.subarray(offset, offset + 4);
+                offset += 4;
+                const payload = Buffer.from(pending.subarray(offset, offset + length));
+                for (let index = 0; index < payload.length; index += 1)
+                    payload[index] ^= mask[index % 4];
+                pending = pending.subarray(offset + length);
+                if (opcode === OPCODE.ping) {
+                    controls.push({ type: 'ping', payload });
+                    continue;
+                }
+                if (opcode === OPCODE.pong) {
+                    controls.push({ type: 'pong', payload });
+                    continue;
+                }
+                if (opcode === OPCODE.close) {
+                    controls.push({ type: 'close', payload });
+                    fragmentOpcode = null;
+                    fragments = [];
+                    continue;
+                }
+                if (opcode === OPCODE.binary) {
+                    controls.push({ type: 'binary-ignored' });
+                    continue;
+                }
+                const result = takeMessage(opcode, payload);
+                if (result && result.error) {
+                    errors.push(result.error);
+                    return { messages, controls, errors };
+                }
+                if (fin) {
+                    const merged = Buffer.concat(fragments);
+                    const frameOpcode = fragmentOpcode;
+                    fragments = [];
+                    fragmentOpcode = null;
+                    if (frameOpcode === OPCODE.text)
+                        messages.push(merged.toString('utf8'));
+                    else
+                        controls.push({ type: 'binary-ignored' });
+                }
+            }
+            return { messages, controls, errors };
+        },
+    };
+}

package/dist-host/dual/documents.js

@@ -105,3 +105,39 @@ export function renderClosureDocument(plan) {
         '#### 项目资料汇总', '', bullets(closure.artifacts), '',
     ].join('\n');
 }
+/** PM 的复核 + 复盘 + 总结（闭环第三步）。 */
+export function renderReviewDocument(review, { feedback = null, handoff = null } = {}) {
+    const checks = review.acceptanceChecks;
+    const failed = checks.filter((check) => check.met !== true);
+    const out = [
+        `# 复核与复盘 · ${review.id}`, '',
+        `- 结论：**${review.verdict === 'accepted' ? '通过' : '退回修改'}**`,
+        `- 关联计划：${review.planId}`,
+        `- 关联 PRD：${review.prdId ?? '未关联'}`,
+        `- 反馈 ID：${review.feedbackId}`, '',
+        '## 一、复核：验收逐条核对', '',
+        '| 验收标准 | 结果 | 证据 | 备注 |',
+        '|---|---|---|---|',
+        ...checks.map((check) => `| ${cell(check.criterion)} | ${check.met ? '通过' : '未通过'} | ${cell(check.evidence.join('；') || '—')} | ${cell(check.note || '—')} |`), '',
+        failed.length > 0 ? `**未通过项**：${failed.map((check) => check.criterion).join('；')}` : '**全部验收项通过。**', '',
+    ];
+    if (feedback) {
+        out.push('## 二、执行回执（PJM 自反馈）', '', feedback.summary, '');
+        out.push(`- 步骤：${feedback.metrics.done}/${feedback.metrics.steps}（${feedback.metrics.percent}%）`);
+        out.push(`- 估时/实际：${feedback.metrics.estimatedMinutes} / ${feedback.metrics.actualMinutes} 分钟`);
+        if (feedback.deviations.length)
+            out.push('- 偏差：', bullets(feedback.deviations));
+        if (feedback.openIssues.length)
+            out.push('- 遗留问题：', bullets(feedback.openIssues));
+        out.push('');
+    }
+    if (handoff) {
+        out.push('## 三、交接对照', '', `- 交接包：${handoff.id}（${handoff.status}）`, `- 验收标准数：${handoff.acceptance.length}`, '');
+    }
+    out.push('## 四、复盘', '');
+    out.push('### 保持（做对了什么）', '', bullets(review.retrospective.kept), '');
+    out.push('### 改进（哪里不顺）', '', bullets(review.retrospective.improve), '');
+    out.push('### 经验（下次怎么做）', '', bullets(review.retrospective.lessons), '');
+    out.push('## 五、总结', '', review.summary, '');
+    return out.join('\n').trim() + '\n';
+}

package/dist-host/dual/orchestrator.js

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+/**
+ * PM/PJM 编排策略（3.3.5）。
+ *
+ * 解决的问题：模型知道工具清单，但不知道“现在这一步该用哪个”。让它在 7 个工具里猜，
+ * 就会出现「PRD 还没写就交接」「还有未决问题就派发」这类错误。
+ *
+ * 这里把闭环状态机写成确定性函数：给定结构化状态，返回**唯一推荐动作**与理由。
+ * 模型仍然负责内容（写 PRD、拆 WBS、判定验收），编排不替它做判断，也不产生副作用。
+ *
+ * 约束：
+ *   * 纯函数，不读全局、不写数据；
+ *   * 每个 action 都必须对应真实存在的工具名（测试会校验，防止漂移）；
+ *   * 无法推进时返回 `blocked` + 具名原因，而不是编一个动作。
+ */
+export const PM_ACTIONS = Object.freeze([
+    'create_prd', 'create_assessment', 'clarify', 'handoff', 'review', 'done', 'blocked',
+]);
+export const PJM_ACTIONS = Object.freeze([
+    'take_handoff', 'return_to_pm', 'create_plan', 'dispatch', 'report', 'complete_feedback', 'close', 'done', 'blocked',
+]);
+/** action → 真实工具名（agent preset 里注册过；测试比对）。 */
+export const ACTION_TOOL = Object.freeze({
+    create_prd: 'pm_create_prd',
+    create_assessment: 'pm_create_assessment',
+    clarify: 'pm_create_prd',
+    handoff: 'pm_handoff_to_pjm',
+    review: 'pm_review_feedback',
+    take_handoff: 'pjm_take_handoff',
+    return_to_pm: 'pjm_take_handoff',
+    create_plan: 'pjm_create_plan',
+    dispatch: 'pjm_dispatch_step',
+    report: 'pjm_report',
+    complete_feedback: 'pjm_submit_feedback',
+    close: 'pjm_close_project',
+    done: null,
+    blocked: null,
+});
+/**
+ * PM 的下一步：PRD → 盘点 → 澄清 → 交接 → 复核。
+ * @param {{prd?: object|null, assessment?: object|null, handoff?: object|null, feedback?: object|null, review?: object|null}} state
+ */
+export function nextPmAction(state = {}) {
+    const prd = state.prd ?? null;
+    const assessment = state.assessment ?? null;
+    const handoff = state.handoff ?? null;
+    const feedback = state.feedback ?? null;
+    const review = state.review ?? null;
+    if (!prd) {
+        return { action: 'create_prd', tool: ACTION_TOOL.create_prd, reason: 'no-prd-yet', detail: '先写结构化 PRD（title + goal）' };
+    }
+    if (!assessment) {
+        return { action: 'create_assessment', tool: ACTION_TOOL.create_assessment, reason: 'no-assessment-yet', detail: '六类盘点必须先落库，completed 项要有证据' };
+    }
+    const openQuestions = Array.isArray(prd.openQuestions) ? prd.openQuestions.length : 0;
+    const conflicts = Array.isArray(assessment.conflicts) ? assessment.conflicts.length : 0;
+    if (openQuestions > 0 || conflicts > 0) {
+        return {
+            action: 'clarify',
+            tool: null,
+            reason: openQuestions > 0 ? 'open-questions-unresolved' : 'conflicts-unresolved',
+            detail: openQuestions > 0
+                ? `PRD 还有 ${openQuestions} 个未决问题，必须用 ask_user_question 一次问一个决策点`
+                : `盘点里有 ${conflicts} 个冲突，必须让用户重新判断（回复：新需求新方案）`,
+            blocking: true,
+        };
+    }
+    if (!handoff) {
+        return {
+            action: 'handoff',
+            tool: ACTION_TOOL.handoff,
+            reason: 'ready-to-handoff',
+            detail: '验收标准齐全且无未决项，打交接包给 PJM',
+            argsHint: { prdId: prd.id, assessmentId: assessment.id },
+        };
+    }
+    if (handoff.status === 'needs-clarification') {
+        return {
+            action: 'blocked',
+            tool: null,
+            reason: handoff.reason || 'handoff-not-ready',
+            detail: '交接包未就绪，先解决未决问题再重新交接',
+            blocking: true,
+        };
+    }
+    if (feedback && !review) {
+        return {
+            action: 'review',
+            tool: ACTION_TOOL.review,
+            reason: 'feedback-awaiting-review',
+            detail: 'PJM 已交反馈：逐条核对验收（met + 证据），写复盘与总结；结论必须与验收一致',
+            argsHint: { feedbackId: feedback.id },
+        };
+    }
+    if (review) {
+        return {
+            action: 'done',
+            tool: null,
+            reason: review.verdict === 'accepted' ? 'loop-accepted' : 'loop-changes-requested',
+            detail: review.verdict === 'accepted' ? '本轮闭环已通过' : 'PJM 需按复核意见重做',
+        };
+    }
+    return {
+        action: 'blocked',
+        tool: null,
+        reason: 'waiting-for-pjm',
+        detail: '等 PJM 接单并提交反馈；PM 不替它派发',
+        blocking: false,
+    };
+}
+/**
+ * PJM 的下一步：接单 → 计划 → 派发 → 反馈 → 结案。
+ * @param {{handoff?: object|null, plan?: object|null, feedback?: object|null}} state
+ */
+export function nextPjmAction(state = {}) {
+    const handoff = state.handoff ?? null;
+    const plan = state.plan ?? null;
+    const feedback = state.feedback ?? null;
+    if (handoff && handoff.status === 'needs-clarification') {
+        return {
+            action: 'return_to_pm',
+            tool: null,
+            reason: 'handoff-needs-clarification',
+            detail: '交接包未就绪：退回 PM 澄清，不得硬开工',
+            blocking: true,
+        };
+    }
+    if (handoff && handoff.status === 'ready' && !plan) {
+        return {
+            action: 'take_handoff',
+            tool: ACTION_TOOL.take_handoff,
+            reason: 'handoff-ready',
+            detail: '接单后再拆 WBS',
+            argsHint: { handoffId: handoff.id },
+        };
+    }
+    if (!plan) {
+        return {
+            action: 'create_plan',
+            tool: ACTION_TOOL.create_plan,
+            reason: 'no-plan-yet',
+            detail: '用 pjm_create_plan 写七类项目内容，步骤必须自己拆（交接包不含 WBS）',
+        };
+    }
+    const steps = Array.isArray(plan.steps) ? plan.steps : [];
+    const failed = steps.filter((step) => step.status === 'failed');
+    const running = steps.filter((step) => step.status === 'running' || step.status === 'dispatching');
+    const pending = steps.filter((step) => step.status === 'pending');
+    const blockedReport = Array.isArray(plan.reports) ? [...plan.reports].reverse().find((report) => report.status === 'blocked') : null;
+    if (blockedReport && (blockedReport.blocker || blockedReport.summary)) {
+        return {
+            action: 'report',
+            tool: ACTION_TOOL.report,
+            reason: 'blocked-reported',
+            detail: `最近一次节点报告为阻塞：${blockedReport.blocker || blockedReport.summary}；需要 PM/用户决策后才能继续`,
+            blocking: true,
+        };
+    }
+    if (failed.length > 0) {
+        return {
+            action: 'report',
+            tool: ACTION_TOOL.report,
+            reason: 'step-failed',
+            detail: `${failed.length} 个步骤失败：如实汇报失败原因，不得写成完成`,
+            argsHint: { planId: plan.id, status: 'blocked' },
+        };
+    }
+    if (running.length > 0) {
+        return {
+            action: 'report',
+            tool: ACTION_TOOL.report,
+            reason: 'step-running',
+            detail: '有步骤在隔离执行体中运行：等结果并汇报节点，不重复派发',
+            argsHint: { planId: plan.id, status: 'progress' },
+        };
+    }
+    if (pending.length > 0) {
+        const next = pending[0];
+        return {
+            action: 'dispatch',
+            tool: ACTION_TOOL.dispatch,
+            reason: 'step-pending',
+            detail: '派发下一个待办步骤（走 fangForker.spawn；不可用即 fail-closed）',
+            argsHint: { planId: plan.id, stepId: next.id },
+        };
+    }
+    if (feedback) {
+        if (plan.status === 'closed') {
+            return { action: 'done', tool: null, reason: 'project-closed', detail: '项目已结案，等 PM 复核结论' };
+        }
+        return {
+            action: 'close',
+            tool: ACTION_TOOL.close,
+            reason: 'all-steps-done',
+            detail: '全部步骤完成且已提交反馈：结案需要总结、评审报告、验收与资料清单',
+            argsHint: { planId: plan.id },
+        };
+    }
+    return {
+        action: 'complete_feedback',
+        tool: ACTION_TOOL.complete_feedback,
+        reason: 'all-steps-done-no-feedback',
+        detail: '全部步骤完成：提交交付、偏差、遗留问题与测试证据，交给 PM 复核',
+        argsHint: { planId: plan.id },
+    };
+}
+/** 给 UI/测试用的紧凑摘要。 */
+export function describeAction(result) {
+    if (!result || !result.action)
+        return 'blocked: unknown state';
+    return [result.action, result.reason, result.detail].filter(Boolean).join(' · ');
+}

package/dist-host/dual/schema.js

@@ -212,3 +212,156 @@ export function closePlan(plan, input = {}, now = Date.now()) {
     };
     return { ok: true, plan, closure: plan.closure, progress };
 }
+// ── 闭环：PM 交接 → PJM 执行/反馈 → PM 复核/复盘/总结 ──────────────────────────
+export const HANDOFF_STATUS = Object.freeze(['needs-clarification', 'ready', 'accepted', 'withdrawn']);
+export const REVIEW_VERDICTS = Object.freeze(['accepted', 'changes-requested']);
+/**
+ * PM → PJM 交接包。`ready` 是硬门禁：
+ *   * 没有验收标准 → 不 ready（PJM 无法判定“做没做成”）；
+ *   * 还有未决问题/冲突 → 不 ready（PJM 不得替用户决定需求）。
+ */
+export function normalizeHandoff(prd, assessment, input = {}, { id, now = Date.now() } = {}) {
+    if (!prd)
+        return error('prd-not-found', 'PRD not found', { id: String(input.prdId ?? '') });
+    const acceptance = [...(list(input.acceptance).length ? list(input.acceptance) : prd.acceptance)];
+    const openQuestions = [...prd.openQuestions, ...list(input.openQuestions)];
+    const conflicts = Array.isArray(assessment?.conflicts) ? assessment.conflicts.map((item) => text(item.question)).filter(Boolean) : [];
+    const ready = acceptance.length > 0 && openQuestions.length === 0 && conflicts.length === 0;
+    const reason = ready
+        ? null
+        : acceptance.length === 0
+            ? 'acceptance-required'
+            : openQuestions.length > 0
+                ? `open-questions-unresolved:${openQuestions.length}`
+                : `conflicts-unresolved:${conflicts.length}`;
+    return {
+        ok: true,
+        handoff: ({
+            id: String(id),
+            prdId: prd.id,
+            assessmentId: String(input.assessmentId ?? '') || null,
+            title: text(input.title, prd.title),
+            priority: prd.priority,
+            acceptance: Object.freeze(acceptance),
+            constraints: prd.constraints,
+            openQuestions: Object.freeze(openQuestions),
+            conflicts: Object.freeze(conflicts),
+            status: ready ? 'ready' : 'needs-clarification',
+            reason,
+            planId: null,
+            preparedAt: now,
+            acceptedAt: null,
+        }),
+    };
+}
+/** PJM 接单：只有 ready 的交接包可以被接走，否则退回 PM 澄清。 */
+export function acceptHandoff(handoff, input = {}, now = Date.now()) {
+    if (!handoff)
+        return error('handoff-not-found', 'Handoff not found');
+    if (handoff.status === 'accepted')
+        return error('handoff-already-accepted', 'Handoff already accepted', { planId: handoff.planId });
+    if (handoff.status !== 'ready') {
+        return error('handoff-not-ready', 'Handoff is not ready; PM must resolve open questions or add acceptance criteria', {
+            status: handoff.status, reason: handoff.reason,
+        });
+    }
+    handoff.status = 'accepted';
+    handoff.acceptedAt = now;
+    handoff.planId = String(input.planId ?? '') || null;
+    return { ok: true, handoff };
+}
+/**
+ * PJM → PM 自反馈：必须在计划全部步骤完成后提交；只写实测结果，不写结论性评价。
+ */
+export function normalizeFeedback(plan, prd, input = {}, { id, now = Date.now() } = {}) {
+    if (!plan)
+        return error('plan-not-found', 'Plan not found', { id: String(input.planId ?? '') });
+    const progress = planProgress(plan);
+    if (!progress.canClose)
+        return error('plan-not-ready', 'feedback requires every step to be done', { progress });
+    const summary = text(input.summary);
+    if (!summary)
+        return error('summary-required', 'feedback summary is required');
+    const delivered = plan.steps
+        .filter((step) => step.status === 'done')
+        .map((step) => Object.freeze({
+        stepId: step.id,
+        title: step.title,
+        owner: step.owner,
+        summary: step.summary,
+        evidence: Object.freeze([...(step.evidence ?? [])]),
+        actualMinutes: step.actualMinutes ?? null,
+    }));
+    return {
+        ok: true,
+        feedback: ({
+            id: String(id),
+            planId: plan.id,
+            prdId: plan.prdId ?? prd?.id ?? null,
+            handoffId: String(input.handoffId ?? '') || null,
+            status: plan.closure?.status === 'closed' ? 'closed' : 'reported',
+            summary,
+            delivered: Object.freeze(delivered),
+            deviations: Object.freeze(list(input.deviations)),
+            openIssues: Object.freeze(list(input.openIssues)),
+            tests: Object.freeze(list(input.tests ?? plan.quality?.tests)),
+            metrics: Object.freeze({
+                steps: progress.total,
+                done: progress.done,
+                estimatedMinutes: progress.estimatedMinutes,
+                actualMinutes: progress.actualMinutes,
+                percent: progress.percent,
+            }),
+            createdAt: now,
+        }),
+    };
+}
+/**
+ * PM 复核：逐条验收标准必须给出 met 布尔与证据；结论必须与验收结果一致，
+ * 不允许「有未达标却判 accepted」或「全达标却判 changes-requested」。
+ */
+export function normalizeReview(feedback, input = {}, { id, now = Date.now() } = {}) {
+    if (!feedback)
+        return error('feedback-not-found', 'Feedback not found', { id: String(input.feedbackId ?? '') });
+    const checks = [];
+    for (const [index, raw] of records(input.acceptanceChecks).entries()) {
+        const criterion = text(raw.criterion);
+        if (!criterion)
+            return error(`acceptanceChecks[${index}].criterion-required`, `acceptanceChecks[${index}].criterion is required`);
+        if (typeof raw.met !== 'boolean')
+            return error(`acceptanceChecks[${index}].met-required`, `acceptanceChecks[${index}].met must be boolean`);
+        checks.push(Object.freeze({ criterion, met: raw.met, evidence: Object.freeze(list(raw.evidence)), note: text(raw.note) }));
+    }
+    if (checks.length === 0)
+        return error('acceptance-checks-required', 'at least one acceptance check is required');
+    const allMet = checks.every((check) => check.met === true);
+    const verdict = REVIEW_VERDICTS.includes(text(input.verdict)) ? text(input.verdict) : (allMet ? 'accepted' : 'changes-requested');
+    if (verdict === 'accepted' && !allMet) {
+        return error('verdict-inconsistent', 'cannot accept while an acceptance check is not met', { failed: checks.filter((check) => !check.met).map((check) => check.criterion) });
+    }
+    if (verdict === 'changes-requested' && allMet) {
+        return error('verdict-inconsistent', 'all checks are met; use accepted or explain with a new check');
+    }
+    const summary = text(input.summary);
+    if (!summary)
+        return error('summary-required', 'review summary is required');
+    const retrospective = input.retrospective && typeof input.retrospective === 'object' ? input.retrospective : {};
+    return {
+        ok: true,
+        review: ({
+            id: String(id),
+            feedbackId: feedback.id,
+            planId: feedback.planId,
+            prdId: feedback.prdId ?? null,
+            verdict,
+            acceptanceChecks: Object.freeze(checks),
+            retrospective: Object.freeze({
+                kept: Object.freeze(list(retrospective.kept ?? input.kept)),
+                improve: Object.freeze(list(retrospective.improve ?? input.improve)),
+                lessons: Object.freeze(list(retrospective.lessons ?? input.lessons)),
+            }),
+            summary,
+            createdAt: now,
+        }),
+    };
+}