@joekytc/dsh-swarm 0.3.6 → 0.3.8

package/lib/config.d.ts

@@ -58,6 +58,15 @@ export interface KanbanConfig {
         /** 命令黑名单子串（命中即拒执行）。纵深防御：派生命令由系统从 tdd 生成，正常不触黑名单。 */
         forbidden: string[];
     };
+    /** 评审证据三级核验（PR2）：L1 缺证标记 → L2 纸面核对（零执行）→ L3 重放（真执行 AI 命令，默认关——
+     *  开启即视为接受"非沙箱"风险；仅放行已知工具前缀，词边界匹配，npm run 仅固定脚本名）。 */
+    evidenceReplay: {
+        enabled: boolean;
+        /** 重放单条命令超时（ms），到点 SIGKILL。 */
+        timeoutMs: number;
+        /** 已知工具前缀白名单（词边界匹配命令开头；npm run 仅固定脚本名）。未命中 → 不执行转人工。 */
+        allowPrefixes: string[];
+    };
     /** IM 主动投递（企微，2026-09-07 评审决议）：W3 收尾/链阻塞时经 dsh-im 投群。
      *  enabled=false（默认）功能关闭；botId/targetId 留空=运行时自动发现（唯一 wecom bot + 唯一已保存群目标）。
      *  多机器人接入时：botId 留空 → 按会话 preset 匹配机器人（探针读 dsh-im 侧 agentPreset）；
@@ -80,5 +89,13 @@ export interface KanbanConfig {
             model: string;
         };
     };
+    /** wiki_write 会话级放行的 preset id 白名单（buildStandaloneDtGuard 非独立分支热读）。
+     *  默认：插件自有 'swarm'（蜂群 preset）/'kanban-w'（W preset）+ 宿主内置 'ptc'。
+     *  历史：'ptc' 原是为「dsh web「蜂群模式」标签会话的 header.agentPreset 实为宿主 PTC id」
+     *  打的补丁；2026-09-17 起 preset 判定统一走 session-preset.ts（引擎真相优先），此处
+     *  'ptc' 语义变为「显式放行普通 PTC 模式会话」（写面仍由 wiki_write 路径白名单硬约束）。
+     *  宿主 preset 体系演化/部署自定义模式 id 时改配置即可，无需改代码。
+     *  写面仍由 wiki_write 工具内 assertAllowedWikiPagePath 五类命名空间白名单硬约束。 */
+    wikiWritePresets: string[];
 }
 export declare const Config: Schema<KanbanConfig>;

package/lib/config.js

@@ -57,6 +57,16 @@ export const Config = Schema.object({
         timeoutMs: Schema.number().min(1000).default(600000),
         forbidden: Schema.array(Schema.string()).default(['rm -rf /', 'git push']),
     }).default({ enabled: true, timeoutMs: 600000, forbidden: ['rm -rf /', 'git push'] }),
+    evidenceReplay: Schema.object({
+        enabled: Schema.boolean().default(false),
+        timeoutMs: Schema.number().min(1000).default(600000),
+        allowPrefixes: Schema.array(Schema.string()).default([
+            'npx --no-install vitest', 'npm test', 'npm run build', 'npm run typecheck', 'tsc', 'eslint',
+        ]),
+    }).default({
+        enabled: false, timeoutMs: 600000,
+        allowPrefixes: ['npx --no-install vitest', 'npm test', 'npm run build', 'npm run typecheck', 'tsc', 'eslint'],
+    }),
     imDelivery: Schema.object({
         enabled: Schema.boolean().default(false),
         botId: Schema.string().default(''),
@@ -71,4 +81,5 @@ export const Config = Schema.object({
             model: Schema.string().default(''),
         }),
     }).default({ mode: 'delegate', managed: { provider: '', model: '' } }),
+    wikiWritePresets: Schema.array(Schema.string()).default(['swarm', 'kanban-w', 'ptc']),
 });

package/lib/dispatcher/agent-runner.js

@@ -10,6 +10,7 @@ import { toolName } from './session-events.js';
 import { attachSessionToWorkspace, resolveOrCreateWorkspace } from './workspace-attach.js';
 import { isPathInside, resolveTargetRepoDir } from './target-repo.js';
 import { injectGitCredentials, resolveGitPatFromCtx } from './git-credentials.js';
+import { slimParentMetadata } from './context-dedup.js';
 /** 目标仓库在会话工作空间外、已 claim+block 等待用户授权且尚未建会话的任务集合（key=taskId）。
  *  人工放行后再次调度会重新询问；已授权后从集合移除。仅进程内记忆，重启后从事件日志恢复（block 事件仍在）。 */
 const permissionBlockedTasks = new Set();
@@ -113,7 +114,7 @@ ${task.body}`);
             parts.push('## Parent task results');
             for (const h of parents) {
                 parts.push(`- summary: ${h.summary}`);
-                parts.push(`- metadata: ${JSON.stringify(h.metadata)}`);
+                parts.push(`- metadata: ${JSON.stringify(slimParentMetadata((h.metadata ?? {})))}`);
             }
         }
         // 0.1.0 delegation：D(execute) 目标模式条件注入——spec 卡/父交接命中
@@ -181,12 +182,7 @@ ${task.body}`);
                 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}）` : ''}`);
-                    }
-                }
+                // PR1 注入去重：未修复项明细不在此重复（完整清单已在 body「本轮修复清单」节，P0-3 单一信息源）
             }
             else {
                 parts.push('- 事件流未找到 review/failed 记录；请先核对任务体「本轮修复清单」节，再完成返工。');

package/lib/dispatcher/chain-auditor.d.ts

@@ -19,7 +19,12 @@ import type { AuditEvidence, Task } from '../domain/types.js';
  *    角色 agent 只写各自任务工作区（workspaces/<chainId>/<taskId>/），
  *    链工作区根下非任务 id 的条目 = 无主产物（疑似主 agent 越权写）→ 证据。
  */
-export interface ChainAuditorDeps {
+export interface ChainAuditorPresetDeps {
+    /** 会话 preset 读取（生产由 dispatcher 注入 session-preset.ts 的统一实现；缺省回落 header
+     *  ——创建事实，仅供测试/未接线场景保留既有行为）。 */
+    readPreset?(agent: unknown): string;
+}
+export interface ChainAuditorDeps extends ChainAuditorPresetDeps {
     kanban: KanbanService;
     workspacesRoot: string;
     /** 活 agent 注册表快照（dispatcher 注入 ctx.agents.list 的适配）；测试可伪造。 */
@@ -38,6 +43,7 @@ export declare class ChainAuditor {
     private readonly kanban;
     private readonly workspacesRoot;
     private readonly listLiveAgents;
+    private readonly readPreset;
     constructor(deps: ChainAuditorDeps);
     /** 执行核对，返回越权证据（空=通过，不阻塞汇报）。
      *  @param workspaceDir 本链发起工作区（Chain.workspaceDir）；提供时仅扫描工作区内的会话。 */

package/lib/dispatcher/chain-auditor.js

@@ -3,6 +3,7 @@ import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { eventType, toolArgs, toolName } from './session-events.js';
 import { isPathInside } from './target-repo.js';
+import { headerPresetOf } from './session-preset.js';
 /** 直接写工具（无条件视为写能力；只读工具如 read/glob/grep 不算）。 */
 const DIRECT_WRITE_TOOLS = new Set(['write', 'edit', 'rm', 'mv', 'cp', 'mkdir', 'mkfile']);
 /** run_code：写能力载体，需结合派发子调用判定。 */
@@ -138,10 +139,12 @@ export class ChainAuditor {
     kanban;
     workspacesRoot;
     listLiveAgents;
+    readPreset;
     constructor(deps) {
         this.kanban = deps.kanban;
         this.workspacesRoot = deps.workspacesRoot;
         this.listLiveAgents = deps.listLiveAgents ?? (() => []);
+        this.readPreset = deps.readPreset ?? headerPresetOf;
     }
     /** 执行核对，返回越权证据（空=通过，不阻塞汇报）。
      *  @param workspaceDir 本链发起工作区（Chain.workspaceDir）；提供时仅扫描工作区内的会话。 */
@@ -151,11 +154,11 @@ export class ChainAuditor {
         for (const agent of this.listLiveAgents()) {
             if (String(agent.id ?? '').startsWith('kbn-'))
                 continue; // 角色会话（P/W/D/V）跳过
-            // 0.1.0 delegation 豁免：header.agentPreset 以 kanban- 开头 → 角色会话
-            // 的子代理（childSessionMeta 记录所 join 的 preset id），产物归属 git 证据链，
+            // 0.1.0 delegation 豁免：preset 以 kanban- 开头 → 角色会话的子代理，产物归属 git 证据链，
             // 不按"主会话越权"判定；源2（无主产物核对）仍兜底其误写链工作区根。
-            const joinedPreset = agent.session?.header?.agentPreset;
-            if (typeof joinedPreset === 'string' && joinedPreset.startsWith('kanban-'))
+            // preset 经 readPreset 统一读面（子代理继承父组合，引擎真相同样成立）。
+            const joinedPreset = this.readPreset(agent);
+            if (joinedPreset.startsWith('kanban-'))
                 continue;
             // 作用域收窄——仅扫本链发起工作区内的会话；会话无 cwd（测试伪造）时保守保留扫描
             if (workspaceDir && agent.session?.header?.cwd && !isPathInside(agent.session.header.cwd, workspaceDir)) {

package/lib/dispatcher/context-dedup.d.ts

@@ -0,0 +1 @@
+export declare function slimParentMetadata(metadata: Record<string, unknown>): Record<string, unknown>;

package/lib/dispatcher/context-dedup.js

@@ -0,0 +1,24 @@
+// src/dispatcher/context-dedup.ts
+/** buildContext 父链 metadata 注入瘦身（PR1 注入去重，纯函数）：
+ * 1) review_evidence 整键剥离——issues 已由返工卡 body「本轮修复清单」单一信息源承载（P0-3）；
+ * 2) 超长数组截断 20 条 + 计数尾注（changed_files 等）；超长字符串截断 2000 字符。
+ * 防御性通用规则，不感知业务键语义；原 metadata 不修改。 */
+const MAX_ARRAY = 20;
+const MAX_STRING = 2000;
+export function slimParentMetadata(metadata) {
+    const out = {};
+    for (const [k, v] of Object.entries(metadata)) {
+        if (k === 'review_evidence')
+            continue;
+        if (Array.isArray(v)) {
+            out[k] = v.length > MAX_ARRAY ? [...v.slice(0, MAX_ARRAY), `…(+${v.length - MAX_ARRAY} more)`] : v;
+        }
+        else if (typeof v === 'string' && v.length > MAX_STRING) {
+            out[k] = v.slice(0, MAX_STRING) + '…(truncated)';
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}

package/lib/dispatcher/dispatcher.js

@@ -9,6 +9,7 @@ import { VOrchestrator } from './v-orchestrator.js';
 import { AgentRunner } from './agent-runner.js';
 import { Watchdog } from './watchdog.js';
 import { ChainAuditor } from './chain-auditor.js';
+import { sessionPresetOf } from './session-preset.js';
 import { mergeDAfterReview } from './merge-gate.js';
 import { buildSubagentTreeGuard, buildSwarmSessionGuard, buildStandaloneDtGuard, registerStandaloneReviewerTools } from '../roles/toolsets.js';
 import { syncKbLinks } from '../wiki/kb-linkage.js';
@@ -414,6 +415,9 @@ function startDispatcherInner(ctx, configProvider, storageDir, logFile, provider
         kanban,
         workspacesRoot: join(storageDir, 'workspaces'),
         listLiveAgents: () => (ctx.get('agents')?.list?.() ?? []),
+        // preset 判定统一走 session-preset.ts（引擎真相优先）：只读 header 会把
+        // 「蜂群模式」标签会话（header=宿主默认 ptc）误判成主会话越权。
+        readPreset: (agent) => sessionPresetOf(ctx, agent),
     });
     kanban.setOnChainCompleted(async (chainId) => {
         // 传入本链发起工作区（Chain.workspaceDir），审计仅扫描该工作区内的会话，排除其他项目主会话
@@ -455,21 +459,29 @@ function startDispatcherInner(ctx, configProvider, storageDir, logFile, provider
     // guard 内部仅对 kanban-dt 系会话收紧；DT 父会话自身仍由 agent-runner 的 agent.ctx
     // guard 双保险。dispose 时注销。
     const toolsSvc = ctx.get('tools');
-    const unguardSubagents = toolsSvc?.guard?.(buildSubagentTreeGuard());
+    // 三个 preset 判定 guard 共用统一读面（session-preset.ts）：引擎真相优先，避免
+    // 「蜂群模式」标签会话（header=宿主默认 ptc）绕过只读/评审硬闸。
+    const readPreset = (agent) => sessionPresetOf(ctx, agent);
+    const unguardSubagents = toolsSvc?.guard?.(buildSubagentTreeGuard({ readPreset }));
     if (unguardSubagents) {
         ctx.on('dispose', unguardSubagents);
     }
-    // 蜂群模式硬闸：header.agentPreset==='swarm' 时只读+git 反选拦截；
+    // 蜂群模式硬闸：会话 preset==='swarm'（统一读面，非 header）时只读+git 反选拦截；
     // 内部对其余会话恒放行。dispose 时注销（与 subagent guard 同款）。
-    const unguardSwarm = toolsSvc?.guard?.(buildSwarmSessionGuard());
+    const unguardSwarm = toolsSvc?.guard?.(buildSwarmSessionGuard({ readPreset }));
     if (unguardSwarm) {
         ctx.on('dispose', unguardSwarm);
     }
-    // 独立评审硬闸：header.agentPreset==='kanban-dt' 且未经角色组合（session id 非 kbn-
+    // 独立评审硬闸：会话 preset==='kanban-dt'（统一读面）且未经角色组合（session id 非 kbn-
     // 前缀）时收紧（看板写工具拒、bash/run_code 仅只读 git+clone/fetch、wiki_write 仅
-    // reviews 命名空间）；wiki_write 对非评审会话全局收紧（链上组合会话放行）。dispose
-    // 时注销（与 subagent/swarm guard 同款）。
-    const unguardStandalone = toolsSvc?.guard?.(buildStandaloneDtGuard());
+    // reviews 命名空间）；wiki_write 对非评审会话全局收紧（链上组合会话/swarm 主会话/
+    // W preset 会话放行）。dispose 时注销（与 subagent/swarm guard 同款）。
+    const unguardStandalone = toolsSvc?.guard?.(buildStandaloneDtGuard({
+        // wiki_write 放行白名单热读配置（applyOverride 后下次工具调用即生效）；
+        // config 缺字段回 [] fail-closed（默认值由 config.ts schema 保证存在）。
+        getWikiWritePresets: () => configProvider.getEffective().wikiWritePresets ?? [],
+        readPreset,
+    }));
     if (unguardStandalone) {
         ctx.on('dispose', unguardStandalone);
     }

package/lib/dispatcher/session-preset.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 会话 preset 读取 —— 全插件单一实现（守卫、交付投递、审计共用，禁止各写一份）。
+ *
+ * 四级官方链，逐级回退（鸭子类型，不引入 dsh-session / dsh-agent 依赖）：
+ *   ① `ctx.agentPresets.composedPreset(agent.ctx)` —— **引擎真相**：该 live agent 实际挂载的组合。
+ *      官方语义："Read from the live scope chain rather than from the session, so it answers for an
+ *      agent whose session has not recorded a preset yet"；子代理继承父组合，同样有答案。
+ *   ② `ctx.sessionProjections.stateOf(session,'agentPreset')` —— 会话日志口径（持久、可冷读，
+ *      镜像客户端所见）；`agent-presets` 在插件 apply 期一次注册该 key（源码 register 调用），
+ *      故 key 恒在，仅当会话对象缺失或投影服务未装时为空。
+ *   ③ `session.header.agentPreset` —— **创建事实**（官方 deep-frozen）。
+ *   ④ `agentPresets.defaultId` → 空串（调用方按「未知模式」处理，绝不能当默认模式猜）。
+ *
+ * 为什么不能只读 header（2026-09-17 实测 + 官方语义）：preset 只在会话**空白期（首轮之前）**可改，
+ * 改后 header 保持创建时的值不再回头，而 ①② 前进。dsh web 的「蜂群模式」标签会话即此形态——
+ * header 落宿主默认 'ptc'、实际运行 'swarm'。只读 header 会让所有按 preset 分流的判定整体错位
+ * （实测造成：多机器人投递误判未命中、蜂群只读硬闸被绕过）。
+ */
+/** preset 读取用的 agent 最小面（结构鸭子类型）。 */
+export interface PresetAgentLike {
+    ctx?: unknown;
+    session?: {
+        header?: {
+            agentPreset?: unknown;
+        };
+    };
+}
+/** preset 读取用的 ctx 最小面（只需 get）。 */
+export interface PresetCtxLike {
+    get?(name: string): unknown;
+}
+/** 创建事实（header.agentPreset）：仅用于「会话创建时是什么」这类语义，或作为末级回退。
+ *  需要「现在跑什么模式」一律用 {@link sessionPresetOf}。 */
+export declare function headerPresetOf(agent: unknown): string;
+/** 当前会话/agent 的 preset id（引擎真相 → 会话投影 → 创建 header → 默认 id → 空串）。 */
+export declare function sessionPresetOf(ctx: PresetCtxLike | null | undefined, agent: unknown): string;

package/lib/dispatcher/session-preset.js

@@ -0,0 +1,67 @@
+// src/dispatcher/session-preset.ts
+/**
+ * 会话 preset 读取 —— 全插件单一实现（守卫、交付投递、审计共用，禁止各写一份）。
+ *
+ * 四级官方链，逐级回退（鸭子类型，不引入 dsh-session / dsh-agent 依赖）：
+ *   ① `ctx.agentPresets.composedPreset(agent.ctx)` —— **引擎真相**：该 live agent 实际挂载的组合。
+ *      官方语义："Read from the live scope chain rather than from the session, so it answers for an
+ *      agent whose session has not recorded a preset yet"；子代理继承父组合，同样有答案。
+ *   ② `ctx.sessionProjections.stateOf(session,'agentPreset')` —— 会话日志口径（持久、可冷读，
+ *      镜像客户端所见）；`agent-presets` 在插件 apply 期一次注册该 key（源码 register 调用），
+ *      故 key 恒在，仅当会话对象缺失或投影服务未装时为空。
+ *   ③ `session.header.agentPreset` —— **创建事实**（官方 deep-frozen）。
+ *   ④ `agentPresets.defaultId` → 空串（调用方按「未知模式」处理，绝不能当默认模式猜）。
+ *
+ * 为什么不能只读 header（2026-09-17 实测 + 官方语义）：preset 只在会话**空白期（首轮之前）**可改，
+ * 改后 header 保持创建时的值不再回头，而 ①② 前进。dsh web 的「蜂群模式」标签会话即此形态——
+ * header 落宿主默认 'ptc'、实际运行 'swarm'。只读 header 会让所有按 preset 分流的判定整体错位
+ * （实测造成：多机器人投递误判未命中、蜂群只读硬闸被绕过）。
+ */
+function asPresetId(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/** 创建事实（header.agentPreset）：仅用于「会话创建时是什么」这类语义，或作为末级回退。
+ *  需要「现在跑什么模式」一律用 {@link sessionPresetOf}。 */
+export function headerPresetOf(agent) {
+    const a = agent;
+    return asPresetId(a?.session?.header?.agentPreset);
+}
+/** 当前会话/agent 的 preset id（引擎真相 → 会话投影 → 创建 header → 默认 id → 空串）。 */
+export function sessionPresetOf(ctx, agent) {
+    const get = typeof ctx?.get === 'function' ? ctx.get.bind(ctx) : undefined;
+    const presets = get?.('agentPresets');
+    const a = agent;
+    // ① 引擎真相：读取失败（作用域链异常）不阻断调用方，降级到会话口径。
+    if (a?.ctx !== undefined && typeof presets?.composedPreset === 'function') {
+        let composed;
+        try {
+            composed = presets.composedPreset(a.ctx);
+        }
+        catch {
+            composed = undefined;
+        }
+        const id = asPresetId(composed);
+        if (id)
+            return id;
+    }
+    // ② 会话日志口径。
+    const projections = get?.('sessionProjections');
+    if (a?.session !== undefined && typeof projections?.stateOf === 'function') {
+        let projected;
+        try {
+            projected = projections.stateOf(a.session, 'agentPreset');
+        }
+        catch {
+            projected = undefined;
+        }
+        const id = asPresetId(projected);
+        if (id)
+            return id;
+    }
+    // ③ 创建事实。
+    const fromHeader = headerPresetOf(a);
+    if (fromHeader)
+        return fromHeader;
+    // ④ 默认 id（读不到 → 空串 = 未知模式）。
+    return asPresetId(presets?.defaultId);
+}

package/lib/domain/evidence-check.d.ts

@@ -0,0 +1,17 @@
+/** 评审证据核验纯函数（PR2 三级递进的判定层，零 IO）。
+ * 四态：matches/differs/could-not-replay/not-provided（澄清表 #6，2026-09-17 精化：
+ * "严重缺证才重放"不可执行——缺证即无命令可重放，落 could-not-replay + 转人工）。
+ * schema 单点封装：owner 调整 evidence 形态只改 parseIssueEvidence。 */
+export type EvidenceState = 'matches' | 'differs' | 'could-not-replay' | 'not-provided';
+export interface IssueEvidence {
+    file: string;
+    command: string;
+    exit: number;
+}
+/** issue.evidence 结构校验（issue #2 原样 schema：{file, command, exit}）。非法 → null（按 not-provided 处理）。 */
+export declare function parseIssueEvidence(raw: unknown): IssueEvidence | null;
+/** 纸面核对（零执行）：存档文件首行 `[exit code: N]` vs 声明 exit（行尾锚定，防 `[exit code: 0]任意文本` 绕过）。
+ * unreadable（文件缺失/首行非规范格式）宁纵勿枉 → 转人工，不判 matches。 */
+export declare function paperCheck(content: string | null, claimedExit: number): 'matches' | 'mismatch' | 'unreadable';
+/** 命令准入：词边界前缀匹配（非子串）；`npm run` 仅放行白名单内固定脚本名；rest 禁 shell 元字符。 */
+export declare function isAllowedCommand(command: string, prefixes: string[]): boolean;

package/lib/domain/evidence-check.js

@@ -0,0 +1,44 @@
+// src/domain/evidence-check.ts
+/** 评审证据核验纯函数（PR2 三级递进的判定层，零 IO）。
+ * 四态：matches/differs/could-not-replay/not-provided（澄清表 #6，2026-09-17 精化：
+ * "严重缺证才重放"不可执行——缺证即无命令可重放，落 could-not-replay + 转人工）。
+ * schema 单点封装：owner 调整 evidence 形态只改 parseIssueEvidence。 */
+/** issue.evidence 结构校验（issue #2 原样 schema：{file, command, exit}）。非法 → null（按 not-provided 处理）。 */
+export function parseIssueEvidence(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const r = raw;
+    if (typeof r['file'] !== 'string' || !r['file'].trim())
+        return null;
+    if (typeof r['command'] !== 'string' || !r['command'].trim())
+        return null;
+    if (typeof r['exit'] !== 'number' || !Number.isFinite(r['exit']))
+        return null;
+    return { file: r['file'], command: r['command'], exit: r['exit'] };
+}
+/** 纸面核对（零执行）：存档文件首行 `[exit code: N]` vs 声明 exit（行尾锚定，防 `[exit code: 0]任意文本` 绕过）。
+ * unreadable（文件缺失/首行非规范格式）宁纵勿枉 → 转人工，不判 matches。 */
+export function paperCheck(content, claimedExit) {
+    if (content === null)
+        return 'unreadable';
+    const first = content.trimStart().split('\n')[0]?.trim() ?? '';
+    const m = /^\[exit code:\s*(-?\d+)\]$/.exec(first);
+    if (!m)
+        return 'unreadable';
+    return Number(m[1]) === claimedExit ? 'matches' : 'mismatch';
+}
+/** shell 元字符：rest 中出现任一即拒绝——整串命令会交给 `bash -c` 执行（gate-runner），
+ * 前缀白名单只保证"以安全工具开头"，元字符可拼接任意后续命令（`npm test && rm -rf`）。 */
+const SHELL_META = /[;|&`$()<>\n'"\\]/;
+/** 命令准入：词边界前缀匹配（非子串）；`npm run` 仅放行白名单内固定脚本名；rest 禁 shell 元字符。 */
+export function isAllowedCommand(command, prefixes) {
+    const trimmed = command.trim();
+    return prefixes.some((p) => {
+        if (!trimmed.startsWith(p))
+            return false;
+        const rest = trimmed.slice(p.length);
+        if (SHELL_META.test(rest))
+            return false; // 元字符 = 命令链/替换/重定向，一律拒绝
+        return rest === '' || rest.startsWith(' ') || rest.startsWith('\t'); // 词边界：拒绝 'npm testify'
+    });
+}

package/lib/domain/gate-policy.d.ts

@@ -3,16 +3,38 @@ export interface GateCommand {
     cwd: string;
     source: 'tdd';
 }
-export interface GatePlan {
+export type GateOutcome = {
+    kind: 'run';
     commands: GateCommand[];
-    skipped: false;
-}
-export interface GateSkip {
-    commands: [];
-    skipped: true;
+} | {
+    kind: 'bounce';
     reason: string;
-}
-export declare function isGatePlan(x: GatePlan | GateSkip): x is GatePlan;
+} | {
+    kind: 'alarm-skip';
+    reason: string;
+} | {
+    kind: 'silent-skip';
+    reason: string;
+};
+export type SkippedVerdict = {
+    action: 'allow-alarm';
+    reason: string;
+} | {
+    action: 'bounce';
+    reason: string;
+} | {
+    action: 'proceed';
+};
+/** ④ tdd.skipped 声明互证：diff 实况三分支（改声明 / tdd 先行 / 放行留痕）。
+ * 返回类型排除 proceed（proceed 仅为 test_files 对称核验的"放行"语义）。 */
+export declare function classifySkippedDeclaration(diffFiles: string[] | null): Exclude<SkippedVerdict, {
+    action: 'proceed';
+}>;
+/** 对称核验：声明 tdd.test_files 但 diff 零测试变更（拿旧测试交差）→ bounce。 */
+export declare function classifyTestFilesDeclaration(diffFiles: string[] | null): SkippedVerdict;
+/** 从 D 卡 body 解析 diff base（body 模板声明 `TARGET_BRANCH=<目标分支名>`，v-orchestrator d:76）。
+ * 与 test_files 同款防线：拒 git 旗标注入（`--output=/x` 可写任意路径文件）与路径逃逸。 */
+export declare function resolveDiffBase(body: string): string | null;
 export declare function branchMatches(current: string | null, declared: unknown): boolean;
 export declare function deriveGatePlan(input: {
     assignee: string;
@@ -23,4 +45,6 @@ export declare function deriveGatePlan(input: {
     config: {
         enabled: boolean;
     };
-}): GatePlan | GateSkip;
+    /** 装配层 git diff --name-only base...HEAD 结果；undefined/null=不可得（保守）。 */
+    diffFiles?: string[] | null;
+}): GateOutcome;

package/lib/domain/gate-policy.js

@@ -1,12 +1,50 @@
 // src/domain/gate-policy.ts
-/** kanban_complete 实测闸派生（纯函数，零 IO）：
- * 声明来源单层——tdd.test_files 自动派生 npx --no-install vitest run（runner=vitest 为 review-evidence 既有口径）。
- * cwd 一律 metadata.worktree_dir，缺失即 skip（旧卡向后兼容零感知）。
- * test_files 必须相对路径且规范化后无 .. 段（防绝对路径跑主仓库/越界逃逸——跑错代码即闸被绕过），违规整单 skip。
- * branchMatches 供装配层在 git 查询后做分支一致性比对（current=null 视为不匹配，调用方 skip）。 */
+/** kanban_complete 实测闸派生（纯函数，零 IO）。
+ * 2026-09-16 PR1 互证升级：声明与实际必须互证（GateOutcome 四态）——
+ *  - run：真跑（派生 npx --no-install vitest run，runner=vitest 为 review-evidence 既有口径）
+ *  - bounce：闸失败打回（同会话 throw 修复重交；3 次上限见 kanban-service MAX_GATE_BOUNCES）
+ *  - alarm-skip：警报放行（task/gate-skipped 留痕后照常 completed）
+ *  - silent-skip：不适用（旧 null 语义逐字节兼容：gates disabled / 非 d-execute / 旧卡无 worktree）
+ * diffFiles 由装配层以 `git diff --name-only <TARGET_BRANCH>...HEAD` 取得；null=不可得 → 保守放行（fail-visible 不 fail-closed）。 */
 import { isAbsolute } from 'node:path';
-export function isGatePlan(x) {
-    return x.skipped === false;
+import { isTestFile } from './tdd-classify.js';
+/** 文档/配置扩展白名单——对齐 D 卡 body 既有口径「纯文档/配置变更则带 tdd={skipped:{reason}}」（v-orchestrator d 模板）。 */
+const DOC_CONFIG_EXT = new Set(['md', 'txt', 'json', 'yml', 'yaml', 'toml']);
+function extOf(path) {
+    const m = /\.([A-Za-z0-9]+)$/.exec(path);
+    return m ? m[1].toLowerCase() : '';
+}
+function isDocOrConfig(path) {
+    return DOC_CONFIG_EXT.has(extOf(path));
+}
+/** ④ tdd.skipped 声明互证：diff 实况三分支（改声明 / tdd 先行 / 放行留痕）。
+ * 返回类型排除 proceed（proceed 仅为 test_files 对称核验的"放行"语义）。 */
+export function classifySkippedDeclaration(diffFiles) {
+    if (diffFiles === null)
+        return { action: 'allow-alarm', reason: 'tdd skipped by declaration (diff unavailable, 保守放行)' };
+    if (diffFiles.some(isTestFile)) {
+        return { action: 'bounce', reason: '声明 tdd.skipped 但本次变更包含测试文件：请改声明 tdd.test_files（闸门将实测）' };
+    }
+    const hasCodeChange = diffFiles.some((f) => !isTestFile(f) && !isDocOrConfig(f));
+    if (hasCodeChange) {
+        return { action: 'bounce', reason: 'tdd 先行：本次变更含代码文件，必须声明 tdd.test_files（纯文档/配置变更才允许 skipped）' };
+    }
+    return { action: 'allow-alarm', reason: 'tdd skipped by declaration: pure docs/config change' };
+}
+/** 对称核验：声明 tdd.test_files 但 diff 零测试变更（拿旧测试交差）→ bounce。 */
+export function classifyTestFilesDeclaration(diffFiles) {
+    if (diffFiles === null)
+        return { action: 'proceed' };
+    if (diffFiles.some(isTestFile))
+        return { action: 'proceed' };
+    return { action: 'bounce', reason: 'tdd 先行：本次变更未包含测试文件（新增或修改测试文件后重交）' };
+}
+/** 从 D 卡 body 解析 diff base（body 模板声明 `TARGET_BRANCH=<目标分支名>`，v-orchestrator d:76）。
+ * 与 test_files 同款防线：拒 git 旗标注入（`--output=/x` 可写任意路径文件）与路径逃逸。 */
+export function resolveDiffBase(body) {
+    const m = /TARGET_BRANCH[=:]\s*([^\s，,。；]+)/.exec(body ?? '');
+    const base = m ? m[1] : null;
+    return base && /^[A-Za-z0-9._/-]+$/.test(base) && !base.startsWith('-') ? base : null;
 }
 export function branchMatches(current, declared) {
     return typeof declared === 'string' && declared.trim().length > 0 && current === declared;
@@ -20,25 +58,28 @@ const isSafeRelativeTestFile = (f) => /^[A-Za-z0-9._/-]+$/.test(f) && !isAbsolut
     && !f.startsWith('-'); // 拒绝以 - 开头的条目：防 vitest CLI 旗标注入（如 --passWithNoTests 使 0 tests matched 也 exit 0，空跑绕闸）
 export function deriveGatePlan(input) {
     const m = input.handoff.metadata ?? {};
+    const diff = input.diffFiles ?? null;
     if (!input.config.enabled)
-        return { commands: [], skipped: true, reason: 'gates disabled' };
+        return { kind: 'silent-skip', reason: 'gates disabled' };
     if (!(input.assignee === 'd' && input.mode === 'execute'))
-        return { commands: [], skipped: true, reason: 'not d/execute' };
+        return { kind: 'silent-skip', reason: 'not d/execute' };
     const wt = m['worktree_dir'];
     if (typeof wt !== 'string' || !wt.trim())
-        return { commands: [], skipped: true, reason: 'worktree_dir missing (legacy card)' };
+        return { kind: 'silent-skip', reason: 'worktree_dir missing (legacy card)' };
     const tdd = m['tdd'];
-    if (tdd?.skipped)
-        return { commands: [], skipped: true, reason: 'tdd skipped by declaration' };
+    if (tdd?.skipped) {
+        const v = classifySkippedDeclaration(diff);
+        return v.action === 'allow-alarm' ? { kind: 'alarm-skip', reason: v.reason } : { kind: 'bounce', reason: v.reason };
+    }
     if (!Array.isArray(tdd?.test_files) || tdd.test_files.length === 0)
-        return { commands: [], skipped: true, reason: 'no gate commands' };
+        return { kind: 'bounce', reason: 'tdd 先行：交付代码变更必须声明 tdd.test_files（纯文档/配置变更才允许声明 skipped）' };
     const files = tdd.test_files.filter((f) => typeof f === 'string' && f.trim().length > 0);
     if (files.length === 0)
-        return { commands: [], skipped: true, reason: 'no gate commands' };
+        return { kind: 'bounce', reason: 'tdd 先行：tdd.test_files 为空（纯文档/配置变更才允许声明 skipped）' };
     if (!files.every(isSafeRelativeTestFile))
-        return { commands: [], skipped: true, reason: 'invalid test_files path (relative in-worktree required)' };
-    return {
-        commands: [{ command: `npx --no-install vitest run ${files.join(' ')}`, cwd: wt, source: 'tdd' }],
-        skipped: false,
-    };
+        return { kind: 'bounce', reason: 'invalid test_files path (relative in-worktree required)' };
+    const declared = classifyTestFilesDeclaration(diff);
+    if (declared.action === 'bounce')
+        return { kind: 'bounce', reason: declared.reason };
+    return { kind: 'run', commands: [{ command: `npx --no-install vitest run ${files.join(' ')}`, cwd: wt, source: 'tdd' }] };
 }

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

@@ -6,6 +6,29 @@ export type KanbanListener = (event: KanbanEvent) => void;
 export declare function firstSentence(text: string): string;
 /** 默认链标题：【需求】<一句话需求描述>。来源优先级 /plan: rest 首句 → checklist.problem 首句 → 未命名需求。 */
 export declare function buildChainTitle(requirementName: string | null, _openspecRest: string, problem: string): string;
+/** gate hook 三态裁决（PR1 互证）：null=不适用（总开关关/非 D/旧卡，静默零事件）；
+ * {skipped,reason}=警报放行（task/gate-skipped 留痕后照常 completed）；
+ * {ok,detail}=真跑或打回（ok=false → gate-failed + throw 同会话修复重交）。 */
+export type GateHookVerdict = {
+    ok: boolean;
+    detail: string;
+} | {
+    skipped: true;
+    reason: string;
+} | null;
+/** 同一任务实测闸打回上限（累计计数）：超过后 blockTask 转人工。
+ * gate fail 不走 failTask、attempts 不递增（仅会话死亡路径 +1），故按 gate-failed 事件数自建计数。 */
+export declare const MAX_GATE_BOUNCES = 3;
+/** 评审证据核验汇总（PR2，非阻塞）：仅 DT 卡 complete 时调用，结果只发事件留痕
+ * （differs/could-not-replay 不阻塞 complete、不改 verdict——转人工信号走事件流）。 */
+export type EvidenceCheckSummary = {
+    results: Array<{
+        title: string;
+        severity: string;
+        state: string;
+        detail: string;
+    }>;
+} | null;
 /** 看板领域门面：三界面（工具/CLI/UI）统一路由的唯一入口。 */
 export declare class KanbanService {
     private state;
@@ -16,6 +39,7 @@ export declare class KanbanService {
     private onChainCompletedHook;
     private onTaskCompletedHook;
     private gateHook;
+    private evidenceCheckHook;
     constructor(store: EventStore, getKbUrlBase?: () => string | undefined);
     private emit;
     /** 注入链完成核对钩子（由调度层设置；仅一个消费者）。 */
@@ -23,10 +47,9 @@ export declare class KanbanService {
     /** 注入任务完成互链登记钩子（由调度层设置；仅一个消费者）。 */
     setOnTaskCompleted(hook: (taskId: string) => void | Promise<void>): void;
     /** 注入实测闸钩子（由装配层设置；null=关闭实测闸，行为与旧版逐字节一致）。 */
-    setGateHook(hook: ((task: Task, handoff: Handoff) => Promise<{
-        ok: boolean;
-        detail: string;
-    } | null>) | null): void;
+    setGateHook(hook: ((task: Task, handoff: Handoff) => Promise<GateHookVerdict>) | null): void;
+    /** 注入评审证据核验钩子（PR2；null=关闭，行为与旧版一致）。 */
+    setEvidenceCheckHook(hook: ((task: Task, handoff: Handoff) => Promise<EvidenceCheckSummary>) | null): void;
     /** 订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
     subscribe(listener: KanbanListener): () => void;
     /** 返回 seq >= 入参 的事件（与 EventStore.readSince 同为 inclusive 语义）。 */