@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/lib/domain/delivery-contract.js

@@ -1,4 +1,4 @@
-import { isAllowedWikiPagePath } from '../wiki/page-path.js';
+import { isAllowedWikiPagePath, isLocalKbPagePath, KB_PAGE_NAMESPACES_HINT } from '../wiki/page-path.js';
 /**
  * 上游交付契约（R20「上游对下游负责」宗旨）：每阶段任务完成交接 metadata 必须产出的键。
  * key = `${assignee}:${mode}`；仅列出「下游实际读取」的硬交付物——
@@ -40,24 +40,35 @@ export function missingDeliveryKeys(assignee, mode, handoff, kbUrlBase) {
     if (!handoff)
         return keys.slice();
     const m = handoff.metadata ?? {};
-    const base = kbUrlBase ? kbUrlBase.replace(/\/$/, '') : null;
+    // 推导修正（审查 C1）：kbUrlBase === undefined 才是宽松；'' 是 local strict
+    const hasBase = kbUrlBase !== undefined;
+    const base = hasBase ? kbUrlBase.replace(/\/$/, '') : null;
     const strict = base !== null;
     const missing = [];
     for (const k of keys) {
         if (k === 'pt_decision') {
             missing.push(...missingPtDecisionKeys(handoff));
+            continue;
+        }
+        const v = m[k];
+        if (strict && k === 'kb_url' && base === '') {
+            // local 模式（D5）：kb_url 必须显式空串（非缺失键）
+            if (typeof v !== 'string' || v.trim() !== '')
+                missing.push(`${k} (本地模式 kb_url 必须为空串)`);
+            continue;
+        }
+        if (typeof v !== 'string' || v.trim().length === 0) {
+            missing.push(k);
+        }
+        else if (strict && k === 'kb_url' && !v.startsWith(base)) {
+            missing.push(`${k} (host 前缀必须为 ${base})`);
+        }
+        else if (strict && k === 'page_path' && base === '') {
+            if (!isLocalKbPagePath(v))
+                missing.push(`${k} (本地模式必须为本地库 wiki/** 相对路径)`);
         }
-        else {
-            const v = m[k];
-            if (typeof v !== 'string' || v.trim().length === 0) {
-                missing.push(k);
-            }
-            else if (strict && k === 'kb_url' && !v.startsWith(base)) {
-                missing.push(`${k} (host 前缀必须为 ${base})`);
-            }
-            else if (strict && k === 'page_path' && !isAllowedWikiPagePath(v)) {
-                missing.push(`${k} (必须为 projects/checklists/、projects/learnings/、projects/<slug>/learnings/、projects/ch_*/learnings/、projects/ch_*/t_*.md 或 projects/ch_*/review/ 命名空间)`);
-            }
+        else if (strict && k === 'page_path' && !isAllowedWikiPagePath(v)) {
+            missing.push(`${k} (必须为 ${KB_PAGE_NAMESPACES_HINT} 命名空间)`);
         }
     }
     return missing;
@@ -65,14 +76,15 @@ export function missingDeliveryKeys(assignee, mode, handoff, kbUrlBase) {
 export function hasRequiredDelivery(assignee, mode, handoff) {
     return missingDeliveryKeys(assignee, mode, handoff).length === 0;
 }
-/** 对一组父任务 id 做交付契约校验，返回缺关键交付物的父卡清单（无缺失返回空数组）。 */
-export function missingParentDelivery(state, parentIds) {
+/** 对一组父任务 id 做交付契约校验，返回缺关键交付物的父卡清单（无缺失返回空数组）。
+ *  kbUrlBase 可选透传 missingDeliveryKeys（与 Task 4 的 C1 推导修正配套——local 模式传 '' 走 strict local 分支）。 */
+export function missingParentDelivery(state, parentIds, kbUrlBase) {
     const out = [];
     for (const pid of parentIds) {
         const pt = state.tasks.get(pid);
         if (!pt)
             continue;
-        const missing = missingDeliveryKeys(pt.assignee, pt.mode, state.handoffs.get(pid));
+        const missing = missingDeliveryKeys(pt.assignee, pt.mode, state.handoffs.get(pid), kbUrlBase);
         if (missing.length > 0)
             out.push({ taskId: pid, assignee: pt.assignee, mode: pt.mode, missing });
     }

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

@@ -0,0 +1,26 @@
+export interface GateCommand {
+    command: string;
+    cwd: string;
+    source: 'tdd';
+}
+export interface GatePlan {
+    commands: GateCommand[];
+    skipped: false;
+}
+export interface GateSkip {
+    commands: [];
+    skipped: true;
+    reason: string;
+}
+export declare function isGatePlan(x: GatePlan | GateSkip): x is GatePlan;
+export declare function branchMatches(current: string | null, declared: unknown): boolean;
+export declare function deriveGatePlan(input: {
+    assignee: string;
+    mode: string;
+    handoff: {
+        metadata?: Record<string, unknown>;
+    };
+    config: {
+        enabled: boolean;
+    };
+}): GatePlan | GateSkip;

package/lib/domain/gate-policy.js

@@ -0,0 +1,44 @@
+// 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）。 */
+import { isAbsolute } from 'node:path';
+export function isGatePlan(x) {
+    return x.skipped === false;
+}
+export function branchMatches(current, declared) {
+    return typeof declared === 'string' && declared.trim().length > 0 && current === declared;
+}
+/** 相对路径 + 不得含 .. 段（含 a/../b 形式，一并拒绝，从简从严）。
+ * 另限字符 allowlist [A-Za-z0-9._/-]：test_files 会被拼入 `bash -c` 执行（见 gate-runner），
+ * 白名单一并拒绝空白与 ; | & $ ` () 等元字符——既防 shell 注入（如 'x || true' 拼成
+ * `vitest run x || true`，未跑闸却 exit 0 通过），也防借空白等变体绕 runner 黑名单子串匹配
+ * （如 'a;git  push' 双空格躲过 includes('git push')）。 */
+const isSafeRelativeTestFile = (f) => /^[A-Za-z0-9._/-]+$/.test(f) && !isAbsolute(f) && !f.split(/[/\\]/).includes('..')
+    && !f.startsWith('-'); // 拒绝以 - 开头的条目：防 vitest CLI 旗标注入（如 --passWithNoTests 使 0 tests matched 也 exit 0，空跑绕闸）
+export function deriveGatePlan(input) {
+    const m = input.handoff.metadata ?? {};
+    if (!input.config.enabled)
+        return { commands: [], skipped: true, reason: 'gates disabled' };
+    if (!(input.assignee === 'd' && input.mode === 'execute'))
+        return { commands: [], skipped: true, 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)' };
+    const tdd = m['tdd'];
+    if (tdd?.skipped)
+        return { commands: [], skipped: true, reason: 'tdd skipped by declaration' };
+    if (!Array.isArray(tdd?.test_files) || tdd.test_files.length === 0)
+        return { commands: [], skipped: true, reason: 'no gate commands' };
+    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' };
+    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,
+    };
+}

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

@@ -10,17 +10,23 @@ export declare function buildChainTitle(requirementName: string | null, _openspe
 export declare class KanbanService {
     private state;
     private readonly store;
-    private readonly kbUrlBase;
+    private readonly getKbUrlBase;
     private emitQueue;
     private readonly listeners;
     private onChainCompletedHook;
     private onTaskCompletedHook;
-    constructor(store: EventStore, kbUrlBase?: string);
+    private gateHook;
+    constructor(store: EventStore, getKbUrlBase?: () => string | undefined);
     private emit;
     /** D23：注入链完成核对钩子（由调度层设置；仅一个消费者）。 */
     setOnChainCompleted(hook: (chainId: string) => void | Promise<void>): void;
     /** Q3&5：注入任务完成互链登记钩子（由调度层设置；仅一个消费者）。 */
     setOnTaskCompleted(hook: (taskId: string) => void | Promise<void>): void;
+    /** P1：注入实测闸钩子（由装配层设置；null=关闭实测闸，行为与旧版逐字节一致）。 */
+    setGateHook(hook: ((task: Task, handoff: Handoff) => Promise<{
+        ok: boolean;
+        detail: string;
+    } | null>) | null): void;
     /** T22：订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
     subscribe(listener: KanbanListener): () => void;
     /** T22：返回 seq >= 入参 的事件（与 EventStore.readSince 同为 inclusive 语义）。 */
@@ -36,6 +42,9 @@ export declare class KanbanService {
     createSpecCard(chainId: string, sections: SpecCardSections, actor: Actor): Promise<SpecCard>;
     editSpecCard(cardId: string, sections: SpecCardSections, actor: Actor): Promise<SpecCard>;
     approveSpecCard(cardId: string, actor: Actor): Promise<SpecCard>;
+    /** 链级停滞终态（防线A，看门狗/V stall 超限专用机械记账）：executing → blocked。
+     *  非 executing 调用即抛（fail-closed）；人工恢复=GUI 删链重跑（blocked 无出边）。 */
+    blockChain(chainId: string, reason: string): Promise<void>;
     createTask(input: {
         chainId: string;
         title: string;
@@ -80,7 +89,11 @@ export declare class KanbanService {
     /** 评审超限放弃：review/gave-up（含证据链信息）。仅 system。 */
     reviewGaveUp(reviewTaskId: string, targetTaskId: string, reason: string, actor: Actor): Promise<KanbanEvent>;
     /** 评审失败返工卡创建（评审失败闭环）：原任务保持 done（不可变），新建返工卡继承 rework 字段。
-     *  仅 system（can('create-rework-task')=system）；V 建执行卡、system 建返工卡。 */
+     *  仅 system（can('create-rework-task')=system）；V 建执行卡、system 建返工卡。
+     *  语义（2026-09-07 修正）：返工=该卡自己的独立会话——resumeSessionId 不继承源卡会话（置 null），
+     *  首跑由 runTask create `kbn-<reworkId>`，卡自身失败重试再 resume 该会话；reworkOfTaskId 保留溯源。
+     *  旧实现继承 source.sessionId 造成三方错位：runTask 首跑不消费它（hasRunHistory=false→create 新会话）、
+     *  UI（BoardCard resumeSessionId??sessionId）却跳到源卡会话 → 「返工在后台跑但哪都找不到它」。 */
     createReworkTask(input: {
         sourceTaskId: string;
         reviewTaskId: string;

package/lib/domain/kanban-service.js

@@ -23,16 +23,21 @@ export class KanbanService {
     state;
     store;
     // Q4：kb_url host 前缀硬校验基准（config.wikiVault.baseUrl）。null = 不校验前缀（兼容测试/旧调用）。
-    kbUrlBase;
+    // 配置面板热生效（Task 6）：改为 getter，每次校验时取最新值——改 baseUrl 无需重建服务。
+    getKbUrlBase;
     emitQueue = Promise.resolve();
     listeners = new Set();
     // D23：链完成验收核对钩子（dispatcher 注入：读主会话事件/产物归属核对 → auditWarning）
     onChainCompletedHook = null;
     // Q3&5：W2/W3 完成互链登记钩子（dispatcher 注入：拿 page_path → 机械写三方互链，失败不阻塞完成）
     onTaskCompletedHook = null;
-    constructor(store, kbUrlBase) {
+    // P1：实测闸钩子（装配层注入：gate-policy 派生 + gate-runner 实测执行 + 分支核对）。
+    // null=未启用（行为不变）；hook 返回 null=跳过（零感知，无 gate 事件）。
+    // **无 actor 参数——human 无豁免**（2026-09-02 决议收紧）。
+    gateHook = null;
+    constructor(store, getKbUrlBase) {
         this.store = store;
-        this.kbUrlBase = kbUrlBase ?? null;
+        this.getKbUrlBase = getKbUrlBase ?? null;
         // P0-3：同步重投影，消除"构造后立即调用基于空状态"的竞态
         this.state = project(store.readAllSync());
     }
@@ -57,6 +62,10 @@ export class KanbanService {
     setOnTaskCompleted(hook) {
         this.onTaskCompletedHook = hook;
     }
+    /** P1：注入实测闸钩子（由装配层设置；null=关闭实测闸，行为与旧版逐字节一致）。 */
+    setGateHook(hook) {
+        this.gateHook = hook;
+    }
     /** T22：订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
     subscribe(listener) {
         this.listeners.add(listener);
@@ -127,6 +136,16 @@ export class KanbanService {
         await this.emit({ chainId: card.chainId, taskId: null, kind: 'chain/executing', payload: {}, author: actor, at: Date.now() });
         return updated;
     }
+    /** 链级停滞终态（防线A，看门狗/V stall 超限专用机械记账）：executing → blocked。
+     *  非 executing 调用即抛（fail-closed）；人工恢复=GUI 删链重跑（blocked 无出边）。 */
+    async blockChain(chainId, reason) {
+        const chain = this.state.chains.get(chainId);
+        if (!chain)
+            throw new Error('unknown chain: ' + chainId);
+        if (chain.status !== 'executing')
+            throw new Error('blockChain requires executing chain, got: ' + chain.status);
+        await this.emit({ chainId, taskId: null, kind: 'chain/blocked', payload: { reason }, author: 'system', at: Date.now() });
+    }
     async createTask(input, actor) {
         if (!can('create-task', actor, null))
             throw new Error('permission denied');
@@ -203,7 +222,7 @@ export class KanbanService {
         // 从源头杜绝 done-but-missing（上游未产出 page_path 就不会成为 done 父卡 → V 不会建 D 卡）。
         // v2：pt_decision 为 P 卡硬键（needed 布尔必填；needed=true 时 reason 必填），缺则 blocked。
         {
-            const missing = missingDeliveryKeys(t.assignee, t.mode, handoff, this.kbUrlBase ?? undefined);
+            const missing = missingDeliveryKeys(t.assignee, t.mode, handoff, this.getKbUrlBase?.() ?? undefined);
             if (missing.length > 0) {
                 await this.emit({ chainId: t.chainId, taskId, kind: 'task/blocked', payload: { reason: 'delivery required: ' + missing.join(', ') }, author: 'system', at: Date.now() });
                 throw new Error('delivery required: ' + missing.join(', '));
@@ -211,6 +230,18 @@ export class KanbanService {
         }
         // v2 断代：w:file 交付键随旧 w1 预取阶段移除，manifest 校验块同步删除
         // （validatePrefetchManifest 仍保留于 prefetch-manifest.ts，供清单 schema 校验复用）。
+        // 实测闸（P1）：hook 由装配层注入（gate-policy 派生 + gate-runner 实测执行 + 分支核对），
+        // hook 返回 null=跳过（未启用/非 D/旧卡/分支不一致）。**无 human 豁免**（2026-09-02 决议收紧）；
+        // ok=false → gate-failed 事件 + 拒绝 complete（卡留 running，throw 经工具边界回 D 会话）。
+        if (this.gateHook) {
+            const verdict = await this.gateHook(t, handoff);
+            if (verdict !== null) {
+                await this.emit({ chainId: t.chainId, taskId, kind: verdict.ok ? 'task/gate-passed' : 'task/gate-failed',
+                    payload: { detail: verdict.detail }, author: 'system', at: Date.now() });
+                if (!verdict.ok)
+                    throw new Error('gate failed: ' + verdict.detail);
+            }
+        }
         await this.emit({ chainId: t.chainId, taskId, kind: 'task/completed', payload: { ...handoff }, author: actor, at: Date.now() });
         // Q3&5：W2/W3 完成 → 调度层互链登记（拿 page_path 机械写三方互链）。
         // 仅 w:kb 触发（P/D/PT/DT 不涉 KB 页互链）；钩子内异常不阻断 completeTask（登记失败仅记 warning）。
@@ -397,7 +428,11 @@ export class KanbanService {
         return this.emit({ chainId: t.chainId, taskId: reviewTaskId, kind: 'review/gave-up', payload: { reviewTaskId, targetTaskId, reason }, author: actor, at: Date.now() });
     }
     /** 评审失败返工卡创建（评审失败闭环）：原任务保持 done（不可变），新建返工卡继承 rework 字段。
-     *  仅 system（can('create-rework-task')=system）；V 建执行卡、system 建返工卡。 */
+     *  仅 system（can('create-rework-task')=system）；V 建执行卡、system 建返工卡。
+     *  语义（2026-09-07 修正）：返工=该卡自己的独立会话——resumeSessionId 不继承源卡会话（置 null），
+     *  首跑由 runTask create `kbn-<reworkId>`，卡自身失败重试再 resume 该会话；reworkOfTaskId 保留溯源。
+     *  旧实现继承 source.sessionId 造成三方错位：runTask 首跑不消费它（hasRunHistory=false→create 新会话）、
+     *  UI（BoardCard resumeSessionId??sessionId）却跳到源卡会话 → 「返工在后台跑但哪都找不到它」。 */
     async createReworkTask(input, actor) {
         if (!can('create-rework-task', actor, null))
             throw new Error('permission denied');
@@ -411,7 +446,7 @@ export class KanbanService {
             assignee: source.assignee, status: 'todo', mode: source.mode, priority: 1,
             parents: [...source.parents], children: [], createdBy: 'auto', // system 自动创建（返工卡）
             attempts: 0, heartbeats: [],
-            sessionId: '', reworkOfTaskId: source.id, resumeSessionId: source.sessionId,
+            sessionId: '', reworkOfTaskId: source.id, resumeSessionId: null,
             reviewAttempt: source.reviewAttempt + 1, reviewStatus: 'pending',
         };
         task.sessionId = 'kbn-' + task.id;

package/lib/domain/permissions.js

@@ -31,7 +31,7 @@ export function can(action, actor, task, opts = {}) {
             // V 挂清单附件到规格卡（/openspec: 建链）；human 亦可（GUI 上传）
             return actor === 'v' || actor === 'human';
         case 'wiki-write':
-            // 交付质量链：w 写 KB 正文；dt 仅写 projects/<chain>/review/ 评审命名空间（ToolGuard 层再收窄路径）
+            // 交付质量链：w 写 KB 正文；dt 仅写 projects/<repoSlug>/<chain>/review/ 评审命名空间（ToolGuard 层再收窄路径）
             return actor === 'w' || actor === 'dt';
         case 'wiki-read':
             // w/d 读 KB 正文；dt 需读 KB 校验（评审只读）；pt 无 wiki 工具面

package/lib/domain/planning-checklist.d.ts

@@ -13,6 +13,11 @@ export interface PlanningChecklist {
         resolved: boolean;
         answer?: string;
     }>;
+    risks?: Array<{
+        description: string;
+        source: string;
+        mitigation: string;
+    }>;
 }
 /** 需求澄清清单 schema 硬校验：返回错误列表（空数组=合法）。清单缺段即拒绝保存（硬闸，主 agent 会话内修正）。 */
 export declare function validatePlanningChecklist(raw: unknown): string[];

package/lib/domain/planning-checklist.js

@@ -26,17 +26,80 @@ export function validatePlanningChecklist(raw) {
             }
         }
         for (const [label, key] of ARR_FIELDS) {
-            if (!Array.isArray(spec[key]) || spec[key].some((v) => typeof v !== 'string')) {
-                errors.push(`checklist.spec.${label} must be string[]`);
+            const arr = spec[key];
+            if (!Array.isArray(arr)) {
+                errors.push(`checklist.spec.${label} must be an array of plain strings (got: ${JSON.stringify(arr)})`);
+                continue;
+            }
+            // 校验器错误文案是模型的 prompt（2026-09-04 二次复发：对象数组只回裸文案，模型零回显无法自纠）——
+            // 必须带 got: 回显 + 拍平指引。判定逻辑不变：非数组或含非字符串元素即拒。
+            const badIdx = arr.findIndex((v) => typeof v !== 'string');
+            if (badIdx >= 0) {
+                errors.push(`checklist.spec.${label} must be an array of plain strings; element ${badIdx} is not a string (got: ${JSON.stringify(arr[badIdx])}). Flatten objects into one sentence per element, e.g. "As a <role>, I want <capability>, so that <benefit>" for ${label}`);
             }
         }
     }
     // manifest 复用 PrefetchManifest schema
     errors.push(...validatePrefetchManifest(c['manifest']).map((e) => 'checklist.' + e));
-    // 澄清问答/疑问点
-    for (const key of ['clarifications', 'doubts']) {
-        if (!Array.isArray(c[key]))
-            errors.push(`checklist.${key} must be an array`);
+    // 澄清问答/疑问点：数组 + 元素形状硬校验。渲染读 qa.q/qa.a——键名错会静默产出 undefined 页面
+    //（2026-09-04 事故：模型传 {question,answer} 过闸，落库 9 条全 undefined），故必须锁确切键名。
+    const clar = c['clarifications'];
+    if (!Array.isArray(clar)) {
+        errors.push('checklist.clarifications must be an array');
+    }
+    else {
+        // 硬闸非空（2026-09-04：[] 合法过闸 → KB 页渲染「（无）」→ 澄清问答静默丢失）。
+        // 恢复场景（restoreRef 旧页无澄清）走逃生口文案，不加代码分支。
+        if (clar.length === 0) {
+            errors.push('checklist.clarifications must be a non-empty array — record every clarification Q&A from this planning round. If this checklist genuinely had no clarification round (e.g. rebuilt from a legacy KB page via restoreRef), add one entry {"q": "本轮无澄清（恢复重建）", "a": "<来源页或原因>"}');
+        }
+        clar.forEach((el, i) => {
+            const o = el;
+            const ok = typeof o === 'object' && o !== null &&
+                typeof o['q'] === 'string' && o['q'].trim().length > 0 &&
+                typeof o['a'] === 'string' && o['a'].trim().length > 0;
+            if (!ok) {
+                const got = typeof o === 'object' && o !== null ? Object.keys(o).join(',') : JSON.stringify(el);
+                errors.push(`checklist.clarifications[${i}] must be {"q": string, "a": string} with both non-empty (got keys: ${got}) — use keys "q" and "a", not "question"/"answer"`);
+            }
+        });
+    }
+    const dbs = c['doubts'];
+    if (!Array.isArray(dbs)) {
+        errors.push('checklist.doubts must be an array');
+    }
+    else {
+        dbs.forEach((el, i) => {
+            const o = el;
+            const ok = typeof o === 'object' && o !== null &&
+                typeof o['q'] === 'string' && o['q'].trim().length > 0 &&
+                typeof o['resolved'] === 'boolean' &&
+                (o['answer'] === undefined || typeof o['answer'] === 'string');
+            if (!ok) {
+                const got = typeof o === 'object' && o !== null ? Object.keys(o).join(',') : JSON.stringify(el);
+                errors.push(`checklist.doubts[${i}] must be {"q": string, "resolved": boolean, "answer"?: string} (got keys: ${got}) — use keys "q", "resolved", "answer"`);
+            }
+        });
+    }
+    // 风险点（可选）：存在则硬校验三要素键名。渲染读 r.description/r.source/r.mitigation——键名错会静默产出 undefined 行
+    const risks = c['risks'];
+    if (risks !== undefined) {
+        if (!Array.isArray(risks)) {
+            errors.push('checklist.risks must be an array when present');
+        }
+        else {
+            risks.forEach((el, i) => {
+                const o = el;
+                const ok = typeof o === 'object' && o !== null &&
+                    typeof o['description'] === 'string' && o['description'].trim().length > 0 &&
+                    typeof o['source'] === 'string' && o['source'].trim().length > 0 &&
+                    typeof o['mitigation'] === 'string' && o['mitigation'].trim().length > 0;
+                if (!ok) {
+                    const got = typeof o === 'object' && o !== null ? Object.keys(o).join(',') : JSON.stringify(el);
+                    errors.push(`checklist.risks[${i}] must be {"description": string, "source": string, "mitigation": string} with all non-empty (got keys: ${got}) — use keys "description", "source", "mitigation"`);
+                }
+            });
+        }
     }
     return errors;
 }
@@ -47,6 +110,7 @@ export function buildChecklistTitle(c) {
 /** 需求澄清清单落库 body：标题【需求】+ 各段可读 markdown（非裸 JSON）。KB 与临时目录两分支共用。 */
 export function formatChecklistBody(c) {
     const { spec, manifest, clarifications, doubts } = c;
+    const risks = c.risks ?? [];
     const lines = [`# ${buildChecklistTitle(c)}`, '## Spec', ''];
     lines.push('### 问题描述 (problem)', spec.problem, '');
     lines.push('### 解决方案 (solution)', spec.solution, '');
@@ -71,6 +135,16 @@ export function formatChecklistBody(c) {
     });
     if (clarifications.length === 0)
         lines.push('（无）', '');
+    lines.push('## 风险点', '');
+    if (risks.length === 0) {
+        lines.push('（无）', '');
+    }
+    else {
+        for (const r of risks) {
+            lines.push(`- ${r.description}（来源: ${r.source}；缓解: ${r.mitigation}）`);
+        }
+        lines.push('');
+    }
     lines.push('## 疑问点', '');
     for (const d of doubts) {
         lines.push(d.resolved ? `- [x] ${d.q}${d.answer ? ` — ${d.answer}` : ''}` : `- [ ] ${d.q}`);

package/lib/domain/projection.js

@@ -12,7 +12,8 @@ export function applyTo(state, ev) {
         }
         case 'chain/executing':
         case 'chain/completed':
-        case 'chain/aborted': {
+        case 'chain/aborted':
+        case 'chain/blocked': {
             const c = state.chains.get(ev.chainId);
             if (!c)
                 throw new Error('projection: unknown chain ' + ev.chainId);

package/lib/domain/review-evidence.js

@@ -24,7 +24,7 @@ export function validateReviewEvidence(role, handoff) {
         // 计划结构字段：评审须给出被评审计划产物引用（如 artifacts_path/page 结构）——缺则视为证据不足
         const planRef = ev.reviewPage ?? (handoff.metadata ?? {})['artifacts_path'];
         if (!planRef)
-            missing.push('review_evidence.plan (artifacts_path/reviewPage)');
+            missing.push('metadata.artifacts_path (被评审计划的 openspec 目录绝对路径，继承被评审 P 卡) 或 review_evidence.reviewPage');
     }
     else {
         // DT：实证校验证据（fail 评审同样必须已实证——test 字段必须存在；仅 pass 要求 exit 0）

package/lib/domain/state-machine.js

@@ -10,7 +10,8 @@ const TASK_TRANSITIONS = {
 };
 const CHAIN_TRANSITIONS = {
     planning: { 'chain/executing': 'executing' },
-    executing: { 'chain/completed': 'completed', 'chain/aborted': 'aborted' },
+    executing: { 'chain/completed': 'completed', 'chain/aborted': 'aborted', 'chain/blocked': 'blocked' },
+    blocked: {},
     completed: {},
     aborted: {},
 };

package/lib/domain/types.d.ts

@@ -1,7 +1,7 @@
 export type Role = 'v' | 'p' | 'w' | 'd' | 'pt' | 'dt';
 export type TaskMode = 'file' | 'external' | 'kb' | 'openspec' | 'mattpocock' | 'align' | 'execute' | 'review-plan' | 'review-impl';
 export type TaskStatus = 'triage' | 'todo' | 'ready' | 'running' | 'blocked' | 'done' | 'failed' | 'archived';
-export type ChainStatus = 'planning' | 'executing' | 'completed' | 'aborted';
+export type ChainStatus = 'planning' | 'executing' | 'blocked' | 'completed' | 'aborted';
 export type SpecCardStatus = 'draft' | 'approved';
 /** 评审状态（交付质量链）：not-required 普通卡 / pending 等待评审 / passed 通过 / failed 失败待返工 / gave-up 超限放弃。 */
 export type ReviewStatus = 'not-required' | 'pending' | 'passed' | 'failed' | 'gave-up';
@@ -40,7 +40,7 @@ export interface ReviewEvidence {
         kbUrl: string;
     };
 }
-export type EventKind = 'chain/created' | 'chain/executing' | 'chain/completed' | 'chain/aborted' | 'chain/root-task-set' | 'chain/audit-warning' | 'chain/audit-confirmed' | 'chain/title-updated' | 'spec-card/created' | 'spec-card/edited' | 'spec-card/approved' | 'task/created' | 'task/claimed' | 'task/heartbeat' | 'task/commented' | 'task/completed' | 'task/blocked' | 'task/unblocked' | 'task/archived' | 'task/failed' | 'task/renamed' | 'review/passed' | 'review/failed' | 'review/gave-up';
+export type EventKind = 'chain/created' | 'chain/executing' | 'chain/completed' | 'chain/aborted' | 'chain/blocked' | 'chain/root-task-set' | 'chain/audit-warning' | 'chain/audit-confirmed' | 'chain/title-updated' | 'spec-card/created' | 'spec-card/edited' | 'spec-card/approved' | 'task/created' | 'task/claimed' | 'task/heartbeat' | 'task/commented' | 'task/completed' | 'task/blocked' | 'task/unblocked' | 'task/archived' | 'task/gate-passed' | 'task/gate-failed' | 'task/failed' | 'task/renamed' | 'review/passed' | 'review/failed' | 'review/gave-up';
 export interface SpecCardSections {
     problem: string;
     solution: string;

package/lib/index.js

@@ -1,28 +1,15 @@
+import { homedir } from 'node:os';
 import { KanbanProvider } from './services/kanban-provider.js';
 import { Config } from './config.js';
 import { registerMainSessionTools } from './tools/main-session-tools.js';
 import { installRolePresets } from './roles/preset-installer.js';
+import { installLlWikiSkill } from './roles/skill-installer.js';
 import { registerKanbanHttp } from './routes/kanban-http.js';
 import { startDispatcher } from './dispatcher/dispatcher.js';
+import { ConfigProvider } from './services/config-provider.js';
 export const name = 'dsh-swarm';
 export { Config };
 // P1-9：无 inject——KanbanProvider 只用文件系统（FileEventStore），不依赖 ctx.storage 等任何服务。
-/** 可选服务延迟装配：插件 apply 时各服务可能尚未提供（cordis 注入顺序），轮询 ctx.get 直至可用再接线。 */
-function wireWhenAvailable(ctx, name, fn, timeoutMs = 60000) {
-    if (ctx.get(name)) {
-        fn();
-        return () => { };
-    }
-    const timer = setInterval(() => {
-        if (ctx.get(name)) {
-            clearInterval(timer);
-            clearTimeout(to);
-            fn();
-        }
-    }, 500);
-    const to = setTimeout(() => clearInterval(timer), timeoutMs);
-    return () => { clearInterval(timer); clearTimeout(to); };
-}
 /** 等待多个服务同时可用后再接线（如 tools 先于 kanban 出现时，单服务轮询会过早执行）。 */
 function wireAllAvailable(ctx, names, fn, timeoutMs = 60000) {
     const ready = () => names.every((name) => Boolean(ctx.get(name)));
@@ -42,15 +29,26 @@ function wireAllAvailable(ctx, names, fn, timeoutMs = 60000) {
 }
 export function apply(ctx, config) {
     // cordis 4：Service 构造即注册（super(ctx,'kanban') 调 ctx.reflect.provide），无需手动 provide。
-    const provider = new KanbanProvider(ctx, config);
+    // Task 8：ConfigProvider 在 apply 中创建一次（override 存放于 storageDir，$DSH_HOME 占位符在此解析），
+    // 全链路（KanbanProvider/HTTP 桥/主会话工具/调度器）共享同一实例实现配置面板热生效。
+    const storageDir = config.storageDir.replace('$DSH_HOME', process.env.DSH_HOME ?? homedir());
+    const configProvider = new ConfigProvider(ctx, config, storageDir);
+    // Task 6：KanbanProvider 持 ConfigProvider 引用，kb_url base 经 getter 热读取（配置面板改后无需重建）。
+    const provider = new KanbanProvider(ctx, config, configProvider);
     // D22：把包内角色裁剪 preset 组合安装到 $DSH_HOME/.agent-presets/（真实 API 下唯一可发现的自定义根）。
     const installed = installRolePresets();
+    installLlWikiSkill(); // 尽力而为：失败仅告警不阻断（设计 §7）
     console.info('[dsh-swarm] role presets installed: ' + (installed.length ? installed.join(',') : 'none'));
+    // LLM 运行时延迟取用：registerKanbanHttp 内部消费（llm-catalog 枚举），接线时 llm 服务已就绪。
+    const llm = () => ctx.get('llm');
     // 可选服务接线均延迟到服务可用后：
-    // - Web GUI 数据桥（GET /kanban/board + POST /kanban/action，仅 webServer 存在时挂载）
-    wireWhenAvailable(ctx, 'webServer', () => registerKanbanHttp(ctx, provider, config));
+    // - Web GUI 数据桥（GET /kanban/board + POST /kanban/action + 配置读写 + llm-catalog，仅 webServer 存在时挂载）
+    //   llm 需在 webServer 就绪且 llm 就绪后取，wireAllAvailable 双服务轮询比单服务更稳。
+    wireAllAvailable(ctx, ['webServer', 'llm'], () => registerKanbanHttp(ctx, provider, configProvider, llm(), config));
     // - P1-3 主会话工具面（spec_card_view/edit/approve + kanban 只读子集 + 前缀路由工具）
-    wireAllAvailable(ctx, ['tools', 'kanban'], () => registerMainSessionTools(ctx, config));
+    //   Task 8：收 ConfigProvider，wiki 客户端与全部配置读点经 getEffective() 调用时热读取。
+    wireAllAvailable(ctx, ['tools', 'kanban'], () => registerMainSessionTools(ctx, configProvider));
     // - 调度层：事件唤醒 V（R20）+ 每任务 agent runner + 看门狗（仅 agents 可用时启动）
-    wireAllAvailable(ctx, ['agents', 'kanban'], () => startDispatcher(ctx, config));
+    // Task 7：startDispatcher 收 ConfigProvider（模型链/wiki 热生效）。
+    wireAllAvailable(ctx, ['agents', 'kanban'], () => startDispatcher(ctx, configProvider));
 }

package/lib/roles/clean-fs-tools.d.ts

@@ -0,0 +1,22 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** 需剥离的带毒参数（dsh-sandbox escalation 配对参数；写死避免依赖宿主内部导出）。 */
+export declare const ESCALATION_PARAM_KEYS: readonly ["sandbox_permissions", "justification"];
+/** 剥离 escalation 参数：净化后新对象返回；本就干净则原对象透传（零拷贝零改写）。 */
+export declare function stripEscalationArgs(args: unknown): unknown;
+/**
+ * 给 danger-full-access 会话 shadow 注册去毒版 write/edit/bash。
+ *
+ * 行为契约：
+ * - 干净版 = 宿主定义浅拷贝 + parameters 去掉两带毒字段（JSON 深拷贝后删除，注册表保证 lossless JSON）
+ *   + execute 换成「剥参 → 转发宿主原工具 execute」。写逻辑零自实现，行为 100% 官方。
+ * - 宿主 schema 本就无带毒参数（无沙箱后端的组合，escalationModes 为空）→ 无需 shadow，跳过
+ *   （最小触碰面：不去盖一个本来就干净的版本）。
+ * - 转发失败面（宿主定义不可达 / 缺 execute / 同层注册冲突）→ 该工具不挂 + console.error 显形，
+ *   宿主带毒版本保持可见（fail-safe：绝不注册一个自实现写文件的半成品）。
+ * - 幂等：setup 重入（live 会话修复路径 resumeOrReuse 会重跑 setup）先以品牌标记识别已挂
+ *   shadow → 跳过；同层冲突抛错也被捕获显形，不炸 setup（宿主版本继续可见，plan-guard 兜底网仍在）。
+ *
+ * @param agentCtx agent setup 收到的 scoped ctx（agentCtx.tools 即该 scope 的注册表）
+ * @param agent Agent 实例（= dsh-tools scope key，exec.agent 同源；get 的 scope 视角参数）
+ */
+export declare function installCleanFsTools(agentCtx: Context, agent: unknown): void;