@joekytc/dsh-swarm 0.3.1 → 0.3.6

package/lib/config.d.ts

@@ -59,13 +59,17 @@ export interface KanbanConfig {
         forbidden: string[];
     };
     /** IM 主动投递（企微，2026-09-07 评审决议）：W3 收尾/链阻塞时经 dsh-im 投群。
-     *  enabled=false（默认）功能关闭；botId/targetId 留空=运行时自动发现（唯一 wecom bot + 唯一已保存群目标）。 */
+     *  enabled=false（默认）功能关闭；botId/targetId 留空=运行时自动发现（唯一 wecom bot + 唯一已保存群目标）。
+     *  多机器人接入时：botId 留空 → 按会话 preset 匹配机器人（探针读 dsh-im 侧 agentPreset）；
+     *  未命中 → fallbackBotId；仍未设默认 → 手动投递路径交互选择（auto 路径直接 fail-closed 列候选）。 */
     imDelivery: {
         enabled: boolean;
         botId: string;
         targetId: string;
         /** 私聊目标（自由投递 /sms -s）：留空=自动发现唯一 kind:'user' 已保存目标，仅且只有一个。 */
         dmTargetId: string;
+        /** 默认机器人（预设未命中的落点）：空=未设默认，多机器人下手动投递每次都要交互选择。 */
+        fallbackBotId: string;
     };
     /** 评审引擎双模：delegate=沿用各角色自有模型评审；managed=统一经 dsh「模型链」评审。
      *  managed.provider/model = dsh「模型链」llm-catalog 的 provider/model id，wire 时写成 ocr 自定义 provider（dsh-managed）；key 不落本配置。 */

package/lib/config.js

@@ -62,7 +62,8 @@ export const Config = Schema.object({
         botId: Schema.string().default(''),
         targetId: Schema.string().default(''),
         dmTargetId: Schema.string().default(''),
-    }).default({ enabled: false, botId: '', targetId: '', dmTargetId: '' }),
+        fallbackBotId: Schema.string().default(''),
+    }).default({ enabled: false, botId: '', targetId: '', dmTargetId: '', fallbackBotId: '' }),
     reviewEngine: Schema.object({
         mode: Schema.union(['delegate', 'managed']).default('delegate'),
         managed: Schema.object({

package/lib/dispatcher/agent-runner.js

@@ -155,25 +155,41 @@ ${task.body}`);
             }
         }
         // 返工场景（task.reworkOfTaskId 非空且 reviewStatus='pending'）：
-        // 注入 review/failed 的 issues 清单与建议方向（评审卡 verdict=fail 后的返工卡上下文）
+        // 注入上一轮评审的对账状态 + 未修复项速览。完整修复清单由返工卡 body「本轮修复清单」节承载
+        //（单一信息源，2026-09-15 P0-3）——避免同一份 issues 在上下文里重复两遍。
         if (task.reworkOfTaskId && task.reviewStatus === 'pending') {
+            // 2026-09-15 P0-1 修正：review/failed 的 targetTaskId 恒为 root（原卡），而 reworkOfTaskId 指向
+            // 上一张返工卡 —— 必须沿 reworkOfTaskId 链回溯到 root 再匹配。旧实现第 2 张返工卡起永不命中，
+            // 注入 "no review/failed evidence found"，P 盲修（ch_1_mu235xfz 不收敛的直接机制 L1）。
+            let rootId = task.reworkOfTaskId;
+            const seenIds = new Set([rootId]);
+            for (;;) {
+                const up = state.tasks.get(rootId);
+                if (!up?.reworkOfTaskId || seenIds.has(up.reworkOfTaskId))
+                    break;
+                rootId = up.reworkOfTaskId;
+                seenIds.add(rootId);
+            }
             const reviewFailed = [...state.events]
                 .reverse()
-                .find((e) => e.kind === 'review/failed' && e.payload['targetTaskId'] === task.reworkOfTaskId);
+                .find((e) => e.kind === 'review/failed' && e.payload['targetTaskId'] === rootId);
             parts.push('## Review guidance (rework task)');
-            parts.push('- 上游任务: ' + task.reworkOfTaskId);
+            parts.push('- 上游任务: ' + task.reworkOfTaskId + (rootId !== task.reworkOfTaskId ? `（root: ${rootId}）` : ''));
             if (reviewFailed) {
                 const evidence = reviewFailed.payload['evidence'];
                 const issues = evidence?.issues ?? [];
-                parts.push('- review issues:');
-                for (const issue of issues) {
-                    parts.push(`  - [${issue.severity}] ${issue.title}${issue.resolved ? ' (resolved)' : ''}`);
+                const unresolved = issues.filter((i) => i.resolved !== true);
+                parts.push(`- 上一轮评审 ${issues.length} 条 issue：未修复 ${unresolved.length} 条、已修复 ${issues.length - unresolved.length} 条。`);
+                parts.push('- 完整修复清单（含定位、问题原文与建议改法）见任务体「本轮修复清单」节：逐条处理未修复项，只做定点修复，禁止无关联全文重写与任务编号重排。');
+                if (unresolved.length > 0) {
+                    parts.push('- 未修复项速览:');
+                    for (const i of unresolved) {
+                        parts.push(`  - [${i.severity}]${i.legacy ? '[遗留]' : '[新问题]'} ${i.title}${i.location ? `（${i.location}）` : ''}`);
+                    }
                 }
-                if (issues.length === 0)
-                    parts.push('  - (no issues recorded in review evidence)');
             }
             else {
-                parts.push('- no review/failed evidence found; re-verify the upstream deliverable before completing');
+                parts.push('- 事件流未找到 review/failed 记录；请先核对任务体「本轮修复清单」节，再完成返工。');
             }
         }
         return parts.join('\n\n');

package/lib/dispatcher/event-waker.js

@@ -8,7 +8,10 @@ export class EventWaker {
     async onEvent(ev) {
         // V 仅在规格卡批准后（spec-card/approved）或任务完成/阻塞（驱动阶段推进）时唤醒；
         // chain/created 不再唤醒 V（V 不再处理旧 w1 预取阶段，等 /openspec: 建卡 + 批准后再行动）。
-        const wakeable = (ev.kind === 'task/completed' || ev.kind === 'task/blocked' || ev.kind === 'spec-card/approved');
+        // 2026-09-15 恢复能力：人工恢复（chain/reopened）与评审豁免（review/waived）同样唤醒 V，
+        // 重入编排按最后一条 review 事件判定推进（否则恢复动作后无人推进 = 恢复形同虚设）。
+        const wakeable = (ev.kind === 'task/completed' || ev.kind === 'task/blocked' || ev.kind === 'spec-card/approved'
+            || ev.kind === 'chain/reopened' || ev.kind === 'review/waived');
         if (!wakeable)
             return;
         if (this.inFlight.has(ev.chainId))

package/lib/dispatcher/v-orchestrator.d.ts

@@ -11,6 +11,8 @@ export interface ChainOrchestration {
     sessionId: string | null;
     waitingOn: string | null;
     stallCount?: number;
+    /** 已消费的人工恢复事件 seq（chain/reopened）：恢复后重置 stallCount 一次（2026-09-15，防反复清零）。 */
+    reopenConsumedSeq?: number;
 }
 export declare const R20_PHASE_ORDER: VPhase[];
 /** 每 phase 的期望建卡（pt 由 P 交付 pt_decision.needed=true 触发；dt 固定）。 */

package/lib/dispatcher/v-orchestrator.js

@@ -24,8 +24,11 @@ export const PHASE_INSTRUCTIONS = {
         '## P 阶段任务体要求（计划者，非执行者）',
         'body 写入规划指令：读规格卡（含 file-prefetch/kb 附件=需求澄清清单）→ 产出 openspec 实施计划。仓库事实不足时先只读自查仓库代码实证（fs/search/grep 均可），再产出计划。',
         '产物路径（OpenSpec 规范）：写入目标仓库 `openspec/changes/<change_name>/` 下 proposal.md / design.md / tasks.md（change_name 依规格自拟 kebab-case，如 autoNote-tab）；complete 时 metadata.artifacts_path = 该目录绝对路径。',
-        'tasks.md 拆分粒度（结构准备度，与 PT 同一判据）：每个任务条目必须有单一、可独立核对的完成判据；禁止一条任务/一条测试用例混 N≥2 个互不依赖的可观察结果——按可独立验证的行为逐条拆分。',
+        'tasks.md 拆分粒度（结构准备度，与 PT 同一判据）：每个任务条目必须有单一、可独立核对的完成判据；禁止一条任务/一条测试用例混 N≥2 个互不依赖的可观察结果——按可独立验证的行为逐条拆分。完成判据必须是实施完成后的单一终态；不写执行层阶段态判据（RED/GREEN/REFACTOR、"先失败再通过"属 D 阶段执行协议，见 D 阶段模板）。',
         'proposal.md 必须含「上游协议遵循说明」节：逐条列规格卡/澄清清单声明的工程协议引用（可定位出处：路径/明确协议名）+ 计划如何遵守；未声明任何协议则该节写「无」。禁止引用规格卡之外的协议标准。',
+        '需求对齐（颗粒度）：澄清清单/规格卡的任务项、任务点、注意点 ↔ 计划任务逐条双向映射——不遗漏；超纲任务须能溯源到澄清回答。',
+        '逻辑交互一致性：计划内部不得自相矛盾、依赖顺序可执行；impl_decisions 多方案必须在计划内收敛为唯一路径，不留未定分支。',
+        '返工轮约束（2026-09-15）：任务体含「本轮修复清单」节时，沿用既有任务编号、只做清单内条目的定点修复；禁止重排编号与清单无关的全文重写/扩写。',
         '铁律：P 是计划者，绝不执行任何 git/worktree/commit/push、不改源码/README、不跑构建部署——执行是 D 的职责；只读自查仅限读仓库，写边界仅限 openspec/changes/ 目录（会话工具级硬护栏强制，其余一律只读）。',
         'complete 时 metadata 必须带 schema 合法的 pt_decision = { needed: boolean, reason?: string }（needed=true 时 reason 必填）。按下列复杂度清单判定（逐条勾选，禁止"感觉"）：',
         '  needed=true（需 PT 计划评审），满足任一条：① 跨 ≥2 模块/目录，或改动公共接口/共享类型/配置文件；② 破坏性变更（对外 API、数据格式、迁移、兼容性）；③ impl_decisions 含 ≥2 个互斥方案需仲裁；④ tasks ≥8 条，或含新增/重写核心模块；⑤ 涉安全/权限/并发/数据迁移等高风险面；⑥ OpenSpec change 中 specs/ 模块的 spec.md 文件数 ≥3。',
@@ -34,9 +37,10 @@ export const PHASE_INSTRUCTIONS = {
     ].join('\n'),
     pt: [
         '## PT 阶段任务体要求（计划评审，只读）',
-        'body 写入计划评审指令：P 已判定需要计划评审（理由见上）。只读评审 P 的计划产物，按五要素核对：需求对齐（澄清清单条目↔任务双向映射，不遗漏不超纲）/完整性/逻辑交互一致性/结构准备度（每任务条目单一、可独立核对的完成判据；混 N≥2 个互不依赖的可观察结果=混行为须拆分）/工程协议一致性（只对账 proposal「上游协议遵循说明」节，未声明协议不得自行引入）。输出 verdict+issues 入交接 metadata.review_evidence。',
+        'body 写入计划评审指令：P 已判定需要计划评审（理由见上）。只读评审 P 的计划产物，按五要素核对：需求对齐（澄清清单/规格卡条目↔任务双向映射，不遗漏不超纲）/完整性/逻辑交互一致性/结构准备度（每任务条目单一、可独立核对的完成判据；混 N≥2 个互不依赖的可观察结果=混行为须拆分；看计划文本自身，不要求执行层字样）/工程协议一致性（只对账 proposal「上游协议遵循说明」节，未声明协议不得自行引入；TDD/RED-GREEN 属 D 阶段内置协议，不在对账范围）。输出 verdict+issues 入交接 metadata.review_evidence。',
+        '评审源正相关（2026-09-15）：评审源 = 规格卡功能面 + 计划文本；环境/工具/凭证/权限/接口来源等需求外事项不得作为阻断性判据（有价值者置非阻塞建议，由执行环节验证）。',
         'issues 四要素缺一无效：location（哪条任务/哪节）+ 依据（上游声明引用或计划内部矛盾点）+ 问题 + 可执行建议；pass 时 issues 只放非阻塞建议。',
-        '返工复审：body 含「上一轮评审未通过 issues」节时必须先逐条三态对账（已修复/未修复/部分修复），未修复旧 issue 原样沿用，再提新问题。',
+        '返工复审：body 含「上一轮评审未通过 issues」节时必须先逐条三态对账（已修复/未修复/部分修复），未修复旧 issue 原样沿用，再提新问题。对账条目必须写 legacy=true、本轮新问题 legacy=false/省略——收敛闸据此判定：旧账未清继续返工；旧账清零后仅未解决 critical 可继续 fail，其余降级为下游「评审遗留建议」。不要在旧账已修复的同一轮用更细的新维度继续 fail（不在五要素内的细化不算阻断）。',
         '评审闸硬要求（必须写入 body）：complete 时 handoff metadata 顶层必须带 artifacts_path=<被评审计划的 openspec 目录绝对路径，直接继承被评审 P 卡 handoff 里的 artifacts_path 值>，或在 review_evidence 里给 reviewPage；review_evidence 形状不变（{ verdict, issues, ...reviewPage 可选 }）——两者都缺时评审闸拒绝 pass。',
         '铁律：PT 是只读评审角色，绝不修改任何产物/源码；不调用 kanban_create、不执行代码。',
     ].join('\n'),
@@ -108,7 +112,11 @@ function extractPtPassSuggestions(state, chainId) {
         .filter(({ rt }) => !!rt && rt.chainId === chainId && rt.assignee === 'pt' && rt.mode === 'review-plan')
         .at(-1);
     const ev = passed?.e.payload['evidence'];
-    return Array.isArray(ev?.issues) ? ev.issues : [];
+    if (!Array.isArray(ev?.issues))
+        return [];
+    // 收敛闸降级通过：issues 含已对账（resolved=true）条目 → 只把未解决项传给下游；
+    // 真 pass 保持全量（pass 时 issues 即非阻塞建议留档）。
+    return ev.downgraded ? ev.issues.filter((i) => i.resolved !== true) : ev.issues;
 }
 /** 仅评审卡：archived 且从未处理过 verdict = 作废（void）。human 归档评审卡即作废，编排器视其不存在。
  *  非评审卡（p/d/w…）一律返回 false——避免误判"该阶段无卡"而重复建卡。 */
@@ -220,6 +228,14 @@ export class VOrchestrator {
         const specCard = chain.specCardId ? state.specCards.get(chain.specCardId) : null;
         if (chain.status === 'completed' || chain.status === 'aborted' || chain.status === 'blocked')
             return;
+        // 2026-09-15 恢复能力：人工恢复（chain/reopened）后重置 V 内建 stall 计数——每个恢复事件只消费一次
+        //（不可每轮无条件清零，否则 stall 计数失效、[create-failed] 永不触发）。给足重试额度，避免因历史
+        // stallCount 残留立即再撞上限（LRN-20260902-002：事件永不再来=永久停滞）。
+        const lastReopen = [...state.events].reverse().find((e) => e.kind === 'chain/reopened' && e.chainId === chainId);
+        if (lastReopen && lastReopen.seq > (orch.reopenConsumedSeq ?? -1)) {
+            orch.stallCount = 0;
+            orch.reopenConsumedSeq = lastReopen.seq;
+        }
         // 阻塞复核 pass（全量阻塞恢复）：链上有 status=blocked 且尚无 [blocked-review] 复核评论的任务
         // → 向 V 发一轮阻塞复核（本轮 V 唯一动作），V 用 kanban_comment 以 [blocked-review] 开头逐一
         // 评论给方向后待命；无此类任务则正常推进。扩展为所有 blocked（含 kb-insufficient 等），
@@ -488,10 +504,16 @@ export class VOrchestrator {
         const evidence = (handoff?.metadata?.['review_evidence']);
         if (!evidence)
             return 'gave-up'; // 无证据（异常路径；完成闸已拦）
-        // 幂等：该评审卡已有 review 事件（重启恢复）→ 按 passed 判定推进，否则保持
-        const hasReviewEvent = (kind) => state.events.some((e) => e.taskId === reviewTask.id && e.kind === kind);
-        if (hasReviewEvent('review/passed') || hasReviewEvent('review/failed') || hasReviewEvent('review/gave-up')) {
-            return hasReviewEvent('review/passed') ? 'advanced' : 'rework';
+        // 幂等：该评审卡已有 review 终态事件（重启恢复 / 人工恢复后重入）→ 按**最后一条** review 事件判定：
+        // passed / waived → 推进；failed / gave-up → 保持（等返工链或人工裁决）。
+        // 2026-09-15 修正（ch_1_mu235xfz 死结第二节）：旧实现用布尔 OR，gave-up 恒落 'rework' →
+        // 人工豁免/恢复后重入仍走不出去（该分支在 getVAgent 之前，纯空转零事件）。
+        const lastReview = [...state.events]
+            .reverse()
+            .find((e) => e.taskId === reviewTask.id
+            && (e.kind === 'review/passed' || e.kind === 'review/failed' || e.kind === 'review/gave-up' || e.kind === 'review/waived'));
+        if (lastReview) {
+            return lastReview.kind === 'review/passed' || lastReview.kind === 'review/waived' ? 'advanced' : 'rework';
         }
         // 被评审任务：复审卡经 reworkOfTaskId/parents 指向 rework 任务；首次评审回退到阶段源任务（done）
         const srcAssignee = role === 'pt' ? 'p' : 'd';
@@ -516,6 +538,28 @@ export class VOrchestrator {
         }
         // fail
         await this.kanban.recordReview(reviewTask.id, root.id, evidence, 'system');
+        // 收敛闸（2026-09-15 Q7/Q10，治本）：旧账清零后，仅未解决的 critical 允许继续返工；其余降级为
+        // 下游「评审遗留建议」并按通过处理 —— 保证必然收敛。ch_1_mu235xfz 教训：4 轮对账 12 条全清仍 fail
+        //（"计划自述类"新问题可在返工文本上无限再生），唯一出口是 gave-up 熔断。
+        const unresolved = evidence.issues.filter((i) => i.resolved !== true);
+        const legacyUnresolved = unresolved.filter((i) => i.legacy === true); // 漏标=false=视为新问题（方向安全）
+        // 生效范围（2026-09-15 修正）：仅 PT 计划评审 + 复审轮（reviewAttempt ≥ 1）。
+        // 首轮评审保持原语义（high 阻断，给计划 1 轮返工机会，符合"小需求 1 轮返工通过"预期）；
+        // DT 评审依据机械实证（test/build/lint/diff），severity 门槛会误放行真问题 → 不适用。
+        const isPtReworkRound = role === 'pt' && (currentTarget.reviewAttempt ?? 0) >= 1;
+        if (isPtReworkRound && legacyUnresolved.length === 0 && !unresolved.some((i) => i.severity === 'critical')) {
+            await this.kanban.comment(reviewTask.id, [
+                `[review-final] 收敛闸：旧账已清零（0 条未修复遗留），本轮 ${unresolved.length} 条新问题无 critical → 降级为下游「评审遗留建议」，本轮评审按通过处理。`,
+                '## 降级条目（原文）',
+                formatIssues(unresolved) || '  -（无）',
+            ].join('\n'), 'system');
+            await this.kanban.recordReview(reviewTask.id, root.id, {
+                ...evidence,
+                verdict: 'pass',
+                downgraded: { from: 'fail', reason: '旧账清零且无未解决 critical（收敛闸）' },
+            }, 'system');
+            return 'advanced';
+        }
         const maxR = this.configProvider.getEffective().dispatcher?.maxReworksPerRole?.[role] ?? 3;
         if ((currentTarget.reviewAttempt ?? 0) >= maxR) {
             await this.kanban.reviewGaveUp(reviewTask.id, root.id, 'exceeded max reworks (' + maxR + ')', 'system');
@@ -544,7 +588,12 @@ export class VOrchestrator {
             formatIssues(evidence.issues) || '  -（无）',
             '对账规则：每条旧 issue 给出三态结论——已修复（resolved=true）/未修复（resolved=false，detail 原样沿用）/部分修复（resolved=false，detail 注明剩余部分）；未修复旧 issue 必须原样保留在 issues 中，禁止跳过对账只提新问题。',
         ].join('\n');
-        const rework = await this.kanban.createReworkTask({ sourceTaskId: currentTarget.id, reviewTaskId: reviewTask.id, reason: 'review failed' }, 'system');
+        const rework = await this.kanban.createReworkTask({
+            sourceTaskId: currentTarget.id,
+            reviewTaskId: reviewTask.id,
+            reason: 'review failed',
+            issues: evidence.issues, // 2026-09-15 P0-3：issues 全文随卡传递（返工卡 body「本轮修复清单」节）
+        }, 'system');
         await this.kanban.createTask({
             chainId,
             title: role === 'pt' ? '计划复审' : '实现复审',

package/lib/domain/config-override.d.ts

@@ -21,6 +21,9 @@ export interface EditableOverride {
             model?: string;
         };
     };
+    imDelivery?: {
+        fallbackBotId?: string;
+    };
 }
 export interface EditableModelSnapshot {
     provider: string;
@@ -42,6 +45,9 @@ export interface EditableSnapshot {
             model: string;
         };
     };
+    imDelivery: {
+        fallbackBotId: string;
+    };
 }
 export type ConfigSource = 'override' | 'inherited';
 export type SourceMap = Record<string, ConfigSource>;

package/lib/domain/config-override.js

@@ -1,4 +1,6 @@
 export const ROLES = ['v', 'p', 'w', 'd', 'pt', 'dt'];
+/** botId 形态（与 dsh-im 的 id 校验同口径）：非空时只允许 id 安全字符。 */
+const BOT_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
 const MODEL_FIELDS = ['provider', 'model', 'reasoningEffort'];
 export function mergeConfig(baseline, override) {
     const wiki = { ...baseline.wikiVault };
@@ -33,7 +35,10 @@ export function mergeConfig(baseline, override) {
         if (cur.provider && cur.model)
             models[role] = cur;
     }
-    return { ...baseline, wikiVault: wiki, roles: { ...baseline.roles, models }, reviewEngine };
+    const imDelivery = { ...baseline.imDelivery };
+    if (override?.imDelivery?.fallbackBotId !== undefined)
+        imDelivery.fallbackBotId = override.imDelivery.fallbackBotId;
+    return { ...baseline, wikiVault: wiki, roles: { ...baseline.roles, models }, reviewEngine, imDelivery };
 }
 export function computeSources(override) {
     const src = {};
@@ -50,6 +55,7 @@ export function computeSources(override) {
     src['reviewEngine.mode'] = override?.reviewEngine?.mode !== undefined ? 'override' : 'inherited';
     src['reviewEngine.managed.provider'] = override?.reviewEngine?.managed?.provider !== undefined ? 'override' : 'inherited';
     src['reviewEngine.managed.model'] = override?.reviewEngine?.managed?.model !== undefined ? 'override' : 'inherited';
+    src['imDelivery.fallbackBotId'] = override?.imDelivery?.fallbackBotId !== undefined ? 'override' : 'inherited';
     return src;
 }
 export function projectEditable(effective) {
@@ -66,6 +72,7 @@ export function projectEditable(effective) {
             mode: effective.reviewEngine?.mode ?? 'delegate',
             managed: { provider: effective.reviewEngine?.managed?.provider ?? '', model: effective.reviewEngine?.managed?.model ?? '' },
         },
+        imDelivery: { fallbackBotId: effective.imDelivery?.fallbackBotId ?? '' },
     };
 }
 export function validateConfig(snapshot) {
@@ -89,6 +96,10 @@ export function validateConfig(snapshot) {
         if (!m.model?.trim())
             errs.push(`roles.models.${role}.model`);
     }
+    // 默认机器人：留空=未设默认（合法，语义为「未命中就交互」）；非空必须形如 dsh-im 的 botId。
+    const fb = (snapshot.imDelivery?.fallbackBotId ?? '').trim();
+    if (fb && !BOT_ID_RE.test(fb))
+        errs.push('imDelivery.fallbackBotId');
     return errs;
 }
 export function diffOverride(baseline, snapshot) {
@@ -134,5 +145,9 @@ export function diffOverride(baseline, snapshot) {
         re.managed = reManaged;
     if (Object.keys(re).length)
         out.reviewEngine = re;
+    const bFb = (baseline.imDelivery?.fallbackBotId ?? '').trim();
+    const sFb = (snapshot.imDelivery?.fallbackBotId ?? '').trim();
+    if (sFb !== bFb)
+        out.imDelivery = { fallbackBotId: sFb };
     return out;
 }

package/lib/domain/im-message.d.ts

@@ -2,7 +2,25 @@ import type { BoardState, KanbanEvent, Task } from './types.js';
 /** W3 收尾判据（镜像 kanban-service.completeTask 机械规则，但不含 dEvidenceOk 与链状态要求）：
  *  完成卡为 w+kb、链上无未终态卡、它是最后完成的卡、且链上存在 done 的 D 卡（防 W2 中间态误投）。 */
 export declare function isFinalW3Completion(state: BoardState, chainId: string, completedTaskId: string): boolean;
-/** 成功汇报（markdown）。判据不满足（W2 中间态/非 w:kb/非收尾）返回 null。 */
+/** 交付汇报结构化字段（W agent 收尾时写入 W3 交接 metadata.report；内容有出处=任务卡，渲染器只定骨架）。 */
+export interface ChainReportFields {
+    requirement: string;
+    status: string;
+    branch: string;
+    /** 功能清单：openspec/changes/<id>/tasks.md 勾选态逐条映射（done=已勾）。 */
+    tasks: Array<{
+        text: string;
+        done: boolean;
+    }>;
+    acceptance: string;
+    verification: string;
+    leftovers: string[];
+    todos: string[];
+}
+/** 校验并归一 metadata.report：任一必需字段缺失/形状不符 → null（渲染回退机械格式，绝不渲染半残骨架）。 */
+export declare function parseChainReport(raw: unknown): ChainReportFields | null;
+/** 成功汇报（markdown）。判据不满足（W2 中间态/非 w:kb/非收尾）返回 null。
+ *  W3 交接带合法 metadata.report → 交付汇报骨架；否则回退机械格式（旧链兼容）。 */
 export declare function buildCompletionMessage(state: BoardState, chainId: string, completedTaskId: string, now: number): string | null;
 export declare function suggestionsFor(reason: string): string[];
 /** 链下全部 blocked 卡（title + 最近一次 task/blocked 原因）。 */
@@ -11,5 +29,6 @@ export declare function latestBlockedTasks(events: KanbanEvent[], tasks: Iterabl
     title: string;
     reason: string;
 }>;
-/** 阻塞通知（markdown）。 */
+/** 阻塞通知（markdown）。阻塞是系统性事件（看门狗/stall/人工），时刻 LLM 大多不在环：
+ *  保持机械渲染（事实 + 静态建议，防编造），仅做视觉对齐（标题/链 id/已完成进度）。 */
 export declare function buildBlockMessage(state: BoardState, chainId: string, chainReason: string, storageDir: string): string;

package/lib/domain/im-message.js

@@ -22,6 +22,46 @@ function strMeta(handoff, key) {
     const v = (handoff?.metadata ?? {})[key];
     return typeof v === 'string' ? v.trim() : '';
 }
+function reportText(v) {
+    return typeof v === 'string' ? v.trim() : '';
+}
+function reportLines(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const item of v) {
+        const s = reportText(item);
+        if (s)
+            out.push(s);
+    }
+    return out;
+}
+/** 校验并归一 metadata.report：任一必需字段缺失/形状不符 → null（渲染回退机械格式，绝不渲染半残骨架）。 */
+export function parseChainReport(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const r = raw;
+    const requirement = reportText(r['requirement']);
+    const status = reportText(r['status']);
+    const branch = reportText(r['branch']);
+    const acceptance = reportText(r['acceptance']);
+    const verification = reportText(r['verification']);
+    if (!requirement || !status || !branch || !acceptance || !verification)
+        return null;
+    if (!Array.isArray(r['tasks']) || r['tasks'].length === 0)
+        return null;
+    const tasks = [];
+    for (const entry of r['tasks']) {
+        if (typeof entry !== 'object' || entry === null)
+            return null;
+        const text = reportText(entry['text']);
+        const done = entry['done'];
+        if (!text || typeof done !== 'boolean')
+            return null;
+        tasks.push({ text, done });
+    }
+    return { requirement, status, branch, tasks, acceptance, verification, leftovers: reportLines(r['leftovers']), todos: reportLines(r['todos']) };
+}
 /** 人工关注点：TDD 跳过声明、D 证据缺失（链完成门禁拦截）、审计警告状态。 */
 function completionAttention(state, chainId, dHandoff) {
     const out = [];
@@ -38,7 +78,37 @@ function completionAttention(state, chainId, dHandoff) {
         out.push(`审计警告已于 ${fmtTime(audit.confirmedAt)} 确认`);
     return out;
 }
-/** 成功汇报（markdown）。判据不满足（W2 中间态/非 w:kb/非收尾）返回 null。 */
+/** 交付汇报骨架（内容来自 W3 metadata.report，系统只定字段与顺序）。
+ *  待办 = report.todos + 机械关注点（TDD 跳过/证据缺失/审计警告不因 W 遗忘而消失）；遗留为空则整节省略。 */
+function renderDeliveryReport(chain, chainId, report, wHandoff, attention) {
+    const lines = [];
+    lines.push(`**【交付汇报】${chain.title}（${chainId}）**`);
+    lines.push(`需求：${report.requirement}`);
+    lines.push(`状态：${report.status}`);
+    lines.push(`分支：${report.branch}`);
+    lines.push('功能清单：');
+    for (const t of report.tasks)
+        lines.push(`- ${t.done ? '✅' : '❌'} ${t.text}`);
+    lines.push(`验收：${report.acceptance}`);
+    lines.push(`验证：${report.verification}`);
+    if (report.leftovers.length > 0) {
+        lines.push('遗留（非阻塞）：');
+        for (const l of report.leftovers)
+            lines.push(`- ${l}`);
+    }
+    const todos = [...report.todos, ...attention];
+    if (todos.length > 0) {
+        lines.push('待办：');
+        for (const t of todos)
+            lines.push(`- ${t}`);
+    }
+    const kbUrl = strMeta(wHandoff, 'kb_url');
+    if (kbUrl)
+        lines.push(`KB：${kbUrl}`);
+    return lines.join('\n');
+}
+/** 成功汇报（markdown）。判据不满足（W2 中间态/非 w:kb/非收尾）返回 null。
+ *  W3 交接带合法 metadata.report → 交付汇报骨架；否则回退机械格式（旧链兼容）。 */
 export function buildCompletionMessage(state, chainId, completedTaskId, now) {
     if (!isFinalW3Completion(state, chainId, completedTaskId))
         return null;
@@ -51,6 +121,10 @@ export function buildCompletionMessage(state, chainId, completedTaskId, now) {
     const dHandoff = state.handoffs.get(dTask.id);
     const pTask = [...chainTasks].reverse().find((t) => t.assignee === 'p' && t.status === 'done');
     const artifacts = strMeta(pTask ? state.handoffs.get(pTask.id) : undefined, 'artifacts_path');
+    const attention = completionAttention(state, chainId, dHandoff);
+    const report = parseChainReport((wHandoff?.metadata ?? {})['report']);
+    if (report)
+        return renderDeliveryReport(chain, chainId, report, wHandoff, attention);
     const lines = [];
     lines.push(`**【DSH 需求完成】${chain.title}**`);
     lines.push('');
@@ -66,7 +140,6 @@ export function buildCompletionMessage(state, chainId, completedTaskId, now) {
     if (pagePath)
         lines.push(`- KB 页：${pagePath}`);
     lines.push(`- 产出物：${artifacts || '（无）'}`);
-    const attention = completionAttention(state, chainId, dHandoff);
     if (attention.length > 0) {
         lines.push('');
         lines.push('**人工关注点**');
@@ -120,12 +193,15 @@ export function latestBlockedTasks(events, tasks, chainId) {
     }
     return out;
 }
-/** 阻塞通知（markdown）。 */
+/** 阻塞通知（markdown）。阻塞是系统性事件（看门狗/stall/人工），时刻 LLM 大多不在环：
+ *  保持机械渲染（事实 + 静态建议，防编造），仅做视觉对齐（标题/链 id/已完成进度）。 */
 export function buildBlockMessage(state, chainId, chainReason, storageDir) {
     const chain = state.chains.get(chainId);
     const blocked = latestBlockedTasks(state.events, state.tasks.values(), chainId);
+    const chainTasks = [...state.tasks.values()].filter((t) => t.chainId === chainId);
+    const doneCount = chainTasks.filter((t) => t.status === 'done' || t.status === 'archived').length;
     const lines = [];
-    lines.push(`**【DSH 需求阻塞】${chain?.title ?? chainId}**`);
+    lines.push(`**【交付阻塞】${chain?.title ?? chainId}（${chainId}）**`);
     lines.push('');
     lines.push('**阻塞卡**');
     if (blocked.length === 0)
@@ -136,6 +212,10 @@ export function buildBlockMessage(state, chainId, chainReason, storageDir) {
     lines.push('');
     lines.push('**阻塞原因**');
     lines.push(`> ${chainReason}`);
+    if (chainTasks.length > 0) {
+        lines.push('');
+        lines.push(`**已完成**：${doneCount}/${chainTasks.length} 卡`);
+    }
     lines.push('');
     lines.push('**排查建议**');
     for (const s of suggestionsFor(chainReason))

package/lib/domain/kanban-service.d.ts

@@ -1,6 +1,6 @@
 import type { EventStore } from './event-store.js';
 import { type Actor } from './permissions.js';
-import type { AuditEvidence, BoardState, Chain, Handoff, KanbanEvent, SpecCard, SpecCardAttachment, SpecCardSections, Task, TaskMode, Role, ReviewEvidence } from './types.js';
+import type { AuditEvidence, BoardState, Chain, Handoff, KanbanEvent, SpecCard, SpecCardAttachment, SpecCardSections, Task, TaskMode, Role, ReviewEvidence, ReviewIssue } from './types.js';
 export type KanbanListener = (event: KanbanEvent) => void;
 /** 首句：trim 后按首个换行或「。？！ 」截断；超长兜底 40 字（需求标题规范化）。 */
 export declare function firstSentence(text: string): string;
@@ -91,6 +91,12 @@ export declare class KanbanService {
     recordReview(reviewTaskId: string, targetTaskId: string, evidence: ReviewEvidence, actor: Actor): Promise<KanbanEvent>;
     /** 评审超限放弃：review/gave-up（含证据链信息）。仅 system。 */
     reviewGaveUp(reviewTaskId: string, targetTaskId: string, reason: string, actor: Actor): Promise<KanbanEvent>;
+    /** 人工恢复被 blocked 的链（2026-09-15 恢复能力）：仅 human；fail-closed 只接受 blocked。
+     *  发 chain/reopened（状态机 blocked → executing），并向链末锚点卡写 [recovery] 审计评论（禁止静默恢复）。 */
+    reopenChain(chainId: string, reason: string, actor: Actor): Promise<KanbanEvent>;
+    /** 人工评审豁免（2026-09-15 恢复能力）：仅 human；要求目标 reviewStatus ∈ {failed, gave-up}（防误豁免 passed/pending）。
+     *  发 review/waived（投影更新 target.reviewStatus='waived'），并向目标卡写 [recovery] 审计评论。 */
+    waiveReview(reviewTaskId: string, targetTaskId: string, reason: string, actor: Actor): Promise<KanbanEvent>;
     /** 评审失败返工卡创建（评审失败闭环）：原任务保持 done（不可变），新建返工卡继承 rework 字段。
      *  仅 system（can('create-rework-task')=system）；V 建执行卡、system 建返工卡。
      *  语义（2026-09-07 修正）：返工=该卡自己的独立会话——resumeSessionId 不继承源卡会话（置 null），
@@ -101,6 +107,7 @@ export declare class KanbanService {
         sourceTaskId: string;
         reviewTaskId: string;
         reason: string;
+        issues?: ReviewIssue[];
     }, actor: Actor): Promise<Task>;
     snapshot(): Promise<BoardState>;
     listTasks(opts?: {

package/lib/domain/kanban-service.js

@@ -18,6 +18,39 @@ export function buildChainTitle(requirementName, _openspecRest, problem) {
     const src = (requirementName && requirementName.trim()) || problem.trim();
     return `【需求】${src ? firstSentence(src) : '未命名需求'}`;
 }
+/** 返工卡「本轮修复清单」节（2026-09-15 P0-3）：系统确定性注入上一轮评审 issues 全文——
+ *  旧实现 body 逐字拷贝源卡，返工方看不到要修什么 → 全文重写 → 判据面再生（ch_1_mu235xfz 根因 L1/L4）。 */
+function reworkChecklistSection(issues) {
+    if (!issues || issues.length === 0)
+        return '';
+    const unresolved = issues.filter((i) => i.resolved !== true);
+    const resolved = issues.filter((i) => i.resolved === true);
+    const lines = [
+        '',
+        '',
+        '## 本轮修复清单（系统确定性注入：上一轮评审未通过项）',
+        `上一轮评审共 ${issues.length} 条：未修复 ${unresolved.length} 条、已修复 ${resolved.length} 条。`,
+        '本卡为返工轮：只做定点修复，禁止无关联的全文重写与任务编号重排（2026-09-15 收敛决议）。',
+    ];
+    if (unresolved.length > 0) {
+        lines.push('### 未修复（本轮必须处理）');
+        for (const i of unresolved) {
+            lines.push(`- [${i.severity}] ${i.title}`);
+            if (i.location)
+                lines.push(`  - 定位: ${i.location}`);
+            if (i.detail)
+                lines.push(`  - 问题: ${i.detail}`);
+            if (i.fix)
+                lines.push(`  - 建议改法: ${i.fix}`);
+        }
+    }
+    if (resolved.length > 0) {
+        lines.push('### 已修复（不需再改，保持现状）');
+        for (const i of resolved)
+            lines.push(`- [${i.severity}] ${i.title}`);
+    }
+    return lines.join('\n');
+}
 /** 看板领域门面：三界面（工具/CLI/UI）统一路由的唯一入口。 */
 export class KanbanService {
     state;
@@ -435,6 +468,39 @@ export class KanbanService {
             throw new Error('unknown target task: ' + targetTaskId);
         return this.emit({ chainId: t.chainId, taskId: reviewTaskId, kind: 'review/gave-up', payload: { reviewTaskId, targetTaskId, reason }, author: actor, at: Date.now() });
     }
+    /** 人工恢复被 blocked 的链（2026-09-15 恢复能力）：仅 human；fail-closed 只接受 blocked。
+     *  发 chain/reopened（状态机 blocked → executing），并向链末锚点卡写 [recovery] 审计评论（禁止静默恢复）。 */
+    async reopenChain(chainId, reason, actor) {
+        if (!can('reopen-chain', actor, null))
+            throw new Error('permission denied: only human may reopen chain');
+        const chain = await this.chainOf(chainId);
+        if (chain.status !== 'blocked')
+            throw new Error('reopenChain requires blocked chain, got: ' + chain.status);
+        if (!reason || !reason.trim())
+            throw new Error('reason required');
+        const ev = await this.emit({ chainId, taskId: null, kind: 'chain/reopened', payload: { reason }, author: actor, at: Date.now() });
+        const anchor = [...this.state.tasks.values()].filter((t) => t.chainId === chainId).at(-1);
+        if (anchor)
+            await this.comment(anchor.id, `[recovery] 人工恢复：链 ${chainId} 由 blocked 恢复为 executing（reason: ${reason}）`, actor);
+        return ev;
+    }
+    /** 人工评审豁免（2026-09-15 恢复能力）：仅 human；要求目标 reviewStatus ∈ {failed, gave-up}（防误豁免 passed/pending）。
+     *  发 review/waived（投影更新 target.reviewStatus='waived'），并向目标卡写 [recovery] 审计评论。 */
+    async waiveReview(reviewTaskId, targetTaskId, reason, actor) {
+        if (!can('waive-review', actor, null))
+            throw new Error('permission denied: only human may waive review');
+        const t = this.state.tasks.get(targetTaskId);
+        if (!t)
+            throw new Error('unknown target task: ' + targetTaskId);
+        if (t.reviewStatus !== 'failed' && t.reviewStatus !== 'gave-up') {
+            throw new Error('waiveReview requires target reviewStatus failed|gave-up, got: ' + t.reviewStatus);
+        }
+        if (!reason || !reason.trim())
+            throw new Error('reason required');
+        const ev = await this.emit({ chainId: t.chainId, taskId: reviewTaskId, kind: 'review/waived', payload: { reviewTaskId, targetTaskId, reason }, author: actor, at: Date.now() });
+        await this.comment(targetTaskId, `[recovery] 评审豁免：${reviewTaskId} → ${targetTaskId} 由人工豁免（reason: ${reason}）`, actor);
+        return ev;
+    }
     /** 评审失败返工卡创建（评审失败闭环）：原任务保持 done（不可变），新建返工卡继承 rework 字段。
      *  仅 system（can('create-rework-task')=system）；V 建执行卡、system 建返工卡。
      *  语义（2026-09-07 修正）：返工=该卡自己的独立会话——resumeSessionId 不继承源卡会话（置 null），
@@ -450,7 +516,7 @@ export class KanbanService {
         if (source.status !== 'done')
             throw new Error('rework source must be done: ' + source.status);
         const task = {
-            id: nid('t'), chainId: source.chainId, title: `[返工] ${source.title}`, body: source.body,
+            id: nid('t'), chainId: source.chainId, title: `[返工] ${source.title}`, body: source.body + reworkChecklistSection(input.issues),
             assignee: source.assignee, status: 'todo', mode: source.mode, priority: 1,
             parents: [...source.parents], children: [], createdBy: 'auto', // system 自动创建（返工卡）
             attempts: 0, heartbeats: [],

package/lib/domain/ocr-review.d.ts

@@ -7,8 +7,12 @@ export interface OcrArgsInput {
     to?: string;
     commit?: string;
     paths?: string[];
+    /** 业务上下文，托管评审时提升评审质量（仅 managed 分支透传）。 */
+    background?: string;
 }
-/** 构造 OCR CLI 参数：preview/rule 走 delegate，managed 走 review 并恒带 JSON 输出。 */
+/** 构造 OCR CLI 参数：preview/rule 走 delegate，managed 走 review。
+ * preview 默认输出 text，必须显式 --format json 才能拿到可解析输出；
+ * managed 恒带 --audience agent（agent 场景标准参数，抑制 progress 输出）。 */
 export declare function buildOcrArgs(sub: OcrSub, a: OcrArgsInput): string[];
 /** 预览结果归一化结构。 */
 export interface PreviewResult {
@@ -23,7 +27,7 @@ export interface PreviewResult {
     }[];
     mergeBase: string | null;
 }
-/** 解析 delegate preview 的 JSON 输出，失败或结构异常时回退 unknown。 */
+/** 解析 delegate preview 的 JSON 输出（官方字段 reviewable_files/excluded_files/exclude_reason），失败或结构异常时回退 unknown。 */
 export declare function parsePreviewJson(stdout: string): PreviewResult;
 /** 托管评审结果归一化结构。 */
 export interface ManagedResult {