@joekytc/dsh-swarm 0.1.2 → 0.3.0

package/lib/domain/kanban-service.js

@@ -6,7 +6,7 @@ import { validateReviewEvidence } from './review-evidence.js';
 import { resolveTaskParents, nonTerminalSemanticParents } from './task-parents.js';
 let seqCounter = 0;
 const nid = (p) => `${p}_${(++seqCounter).toString(36)}_${Date.now().toString(36)}`;
-/** 首句：trim 后按首个换行或「。？！ 」截断；超长兜底 40 字（T7 需求标题规范化）。 */
+/** 首句：trim 后按首个换行或「。？！ 」截断；超长兜底 40 字（需求标题规范化）。 */
 export function firstSentence(text) {
     const t = text.trim();
     const cut = t.search(/[\n。？！]/);
@@ -22,18 +22,23 @@ export function buildChainTitle(requirementName, _openspecRest, problem) {
 export class KanbanService {
     state;
     store;
-    // Q4：kb_url host 前缀硬校验基准（config.wikiVault.baseUrl）。null = 不校验前缀（兼容测试/旧调用）。
-    kbUrlBase;
+    // kb_url host 前缀硬校验基准（config.wikiVault.baseUrl）。null = 不校验前缀（兼容测试/旧调用）。
+    // 配置面板热生效：改为 getter，每次校验时取最新值——改 baseUrl 无需重建服务。
+    getKbUrlBase;
     emitQueue = Promise.resolve();
     listeners = new Set();
-    // D23：链完成验收核对钩子（dispatcher 注入：读主会话事件/产物归属核对 → auditWarning）
+    // 链完成验收核对钩子（dispatcher 注入：读主会话事件/产物归属核对 → auditWarning）
     onChainCompletedHook = null;
-    // Q3&5：W2/W3 完成互链登记钩子（dispatcher 注入：拿 page_path → 机械写三方互链，失败不阻塞完成）
+    // W2/W3 完成互链登记钩子（dispatcher 注入：拿 page_path → 机械写三方互链，失败不阻塞完成）
     onTaskCompletedHook = null;
-    constructor(store, kbUrlBase) {
+    // 实测闸钩子（装配层注入：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;
-        // P0-3：同步重投影，消除"构造后立即调用基于空状态"的竞态
+        this.getKbUrlBase = getKbUrlBase ?? null;
+        // 同步重投影，消除"构造后立即调用基于空状态"的竞态
         this.state = project(store.readAllSync());
     }
     async emit(ev) {
@@ -49,20 +54,24 @@ export class KanbanService {
         await pending;
         return emitted;
     }
-    /** D23：注入链完成核对钩子（由调度层设置；仅一个消费者）。 */
+    /** 注入链完成核对钩子（由调度层设置；仅一个消费者）。 */
     setOnChainCompleted(hook) {
         this.onChainCompletedHook = hook;
     }
-    /** Q3&5：注入任务完成互链登记钩子（由调度层设置；仅一个消费者）。 */
+    /** 注入任务完成互链登记钩子（由调度层设置；仅一个消费者）。 */
     setOnTaskCompleted(hook) {
         this.onTaskCompletedHook = hook;
     }
-    /** T22：订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
+    /** 注入实测闸钩子（由装配层设置；null=关闭实测闸，行为与旧版逐字节一致）。 */
+    setGateHook(hook) {
+        this.gateHook = hook;
+    }
+    /** 订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
     subscribe(listener) {
         this.listeners.add(listener);
         return () => { this.listeners.delete(listener); };
     }
-    /** T22：返回 seq >= 入参 的事件（与 EventStore.readSince 同为 inclusive 语义）。 */
+    /** 返回 seq >= 入参 的事件（与 EventStore.readSince 同为 inclusive 语义）。 */
     async eventsSince(seq) {
         return this.store.readSince(seq);
     }
@@ -127,6 +136,24 @@ 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() });
+    }
+    /** IM 投递失败留痕（仅 system 机械记账）：非状态转换注记事件，仅落盘供取证/GUI 观察。
+     *  投递是旁路通知，失败绝不 block 链（评审决议）；留痕满足「禁止静默 skip」红线。 */
+    async noteImDeliveryFailed(chainId, detail, actor) {
+        if (actor !== 'system')
+            throw new Error('permission denied: only system may note im delivery failure');
+        await this.chainOf(chainId);
+        return this.emit({ chainId, taskId: null, kind: 'chain/im-delivery-failed', payload: { detail }, author: actor, at: Date.now() });
+    }
     async createTask(input, actor) {
         if (!can('create-task', actor, null))
             throw new Error('permission denied');
@@ -135,7 +162,7 @@ export class KanbanService {
             throw new Error('title required');
         const chain = await this.chainOf(input.chainId);
         const explicitParents = input.parents && input.parents.length > 0;
-        // P0 硬拦（防御纵深）：调用方未显式指定 parents（V 建全新阶段卡）时，按语义依赖查上游非终态——
+        // 硬拦（防御纵深）：调用方未显式指定 parents（V 建全新阶段卡）时，按语义依赖查上游非终态——
         // 上游卡还卡着/未走完则拒绝建卡（防「P blocked 后仍建 PT」类事故）。显式 parents 的调用
         // （复审卡 parents=[rework.id]、createReworkTask）由调用方决定接链，不在此拦。
         if (!explicitParents) {
@@ -145,7 +172,7 @@ export class KanbanService {
                 throw new Error(`create-task rejected: 上游 ${b} 未终态，下游 ${input.assignee}/${input.mode} 卡不能创建`);
             }
         }
-        // 语义 parents 兜底：调用方（V 建卡）未显式指定 parents 时，按 R20 依赖自动接链上终态父任务，
+        // 语义 parents 兜底：调用方（V 建卡）未显式指定 parents 时，按语义依赖自动接链上终态父任务，
         // 保证「父交接注入」通道闭合（如 w2 接 P、dt 接 d）。兜底对已显式传 parents 的
         // 调用（复审卡 parents=[rework.id]、createReworkTask）不生效。
         const parents = input.parents && input.parents.length > 0
@@ -176,13 +203,13 @@ export class KanbanService {
             throw new Error('permission denied');
         if (!handoff.summary.trim())
             throw new Error('handoff summary required');
-        // C2：D(execute) 完成必须带 git 产物证据（changed_files + commit/push 至少其一）——
-        // 执行者语义硬校验；human 为信任锚（GUI 强制收尾）可豁免，但 C1 链完成门禁仍会拦截无证据链。
+        // D(execute) 完成必须带 git 产物证据（changed_files + commit/push 至少其一）——
+        // 执行者语义硬校验；human 为信任锚（GUI 强制收尾）可豁免，但链完成门禁仍会拦截无证据链。
         if (t.assignee === 'd' && t.mode === 'execute' && actor !== 'human' && !hasDeliveryEvidence(handoff)) {
             throw new Error('delivery evidence required: D(execute) complete must carry changed_files + (commit_hash|push)');
         }
         // TDD 声明闸（2026-08-26）：D(execute) 完成必须带 tdd 声明（test_files 非空 或 skipped.reason 非空），
-        // 否则抛错——防止 D 完全不声明测试；顺序真伪由 DT 评审闸兜底。human 信任锚可豁免（同 C2）。
+        // 否则抛错——防止 D 完全不声明测试；顺序真伪由 DT 评审闸兜底。human 信任锚可豁免（同上）。
         if (t.assignee === 'd' && t.mode === 'execute' && actor !== 'human' && !hasTddDeclaration(handoff)) {
             throw new Error('tdd declaration required: D(execute) complete must carry tdd = { test_files: [...] } or tdd = { skipped: { reason } }');
         }
@@ -203,7 +230,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,8 +238,20 @@ export class KanbanService {
         }
         // v2 断代：w:file 交付键随旧 w1 预取阶段移除，manifest 校验块同步删除
         // （validatePrefetchManifest 仍保留于 prefetch-manifest.ts，供清单 schema 校验复用）。
+        // 实测闸：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 机械写三方互链）。
+        // W2/W3 完成 → 调度层互链登记（拿 page_path 机械写三方互链）。
         // 仅 w:kb 触发（P/D/PT/DT 不涉 KB 页互链）；钩子内异常不阻断 completeTask（登记失败仅记 warning）。
         if (t.assignee === 'w' && t.mode === 'kb' && this.onTaskCompletedHook) {
             try {
@@ -222,11 +261,11 @@ export class KanbanService {
                 console.error('[dsh-swarm] task completion linkage hook failed: ' + String(error));
             }
         }
-        // P0-3 链完成机械规则：仅当「最后完成的执行任务是 W3（w/kb）且链上 D(execute) 已 done 且
+        // 链完成机械规则：仅当「最后完成的执行任务是 W3（w/kb）且链上 D(execute) 已 done 且
         // 交付物证据满足（changed_files + commit/push）」且无未终态任务时 → 链 completed（不靠 agent 自觉）。
         // 收紧判据：中间阶段（如 P done 后 W2 尚未创建）无未终态任务也不得误收链。
-        // C1：D(execute) 无产物证据 → 不判链完成（human 强制 complete 的 D 卡同样被拦截，防漂移被掩盖）。
-        // 'align' 为旧链路兼容（只读对齐/校验语义已废弃，R20 起新卡一律 'execute'）。
+        // D(execute) 无产物证据 → 不判链完成（human 强制 complete 的 D 卡同样被拦截，防漂移被掩盖）。
+        // 'align' 为旧链路兼容（只读对齐/校验语义已废弃，新卡一律 'execute'）。
         const terminal = ['done', 'archived'];
         const chain = this.state.chains.get(t.chainId);
         const chainTasks = [...this.state.tasks.values()].filter((x) => x.chainId === t.chainId);
@@ -239,7 +278,7 @@ export class KanbanService {
         const w3Done = !!lastTask && lastTask.assignee === 'w' && lastTask.mode === 'kb' && dDone && dEvidenceOk;
         if (chain && chain.status === 'executing' && openTasks.length === 0 && w3Done) {
             await this.emit({ chainId: t.chainId, taskId: null, kind: 'chain/completed', payload: {}, author: 'system', at: Date.now() });
-            // D23：链完成 → 调度层验收核对（主会话越权写产物 → chain/audit-warning）。
+            // 链完成 → 调度层验收核对（主会话越权写产物 → chain/audit-warning）。
             // 钩子内异常不阻断 completeTask 本身（核对失败仅记录，链路仍 completed）。
             if (this.onChainCompletedHook) {
                 try {
@@ -252,14 +291,14 @@ export class KanbanService {
         }
         return this.state.tasks.get(taskId);
     }
-    /** D23：链完成验收核对发警告（仅 system/dispatcher 可发）。Chain 状态保持 completed。 */
+    /** 链完成验收核对发警告（仅 system/dispatcher 可发）。Chain 状态保持 completed。 */
     async auditWarning(chainId, evidence, actor) {
         if (actor !== 'system')
             throw new Error('permission denied: only dispatcher may raise audit warnings');
         await this.chainOf(chainId);
         return this.emit({ chainId, taskId: null, kind: 'chain/audit-warning', payload: { evidence }, author: actor, at: Date.now() });
     }
-    /** D23：用户确认产物归属（仅 human，GUI confirm-audit action）。放行最终汇报。 */
+    /** 用户确认产物归属（仅 human，GUI confirm-audit action）。放行最终汇报。 */
     async confirmAudit(chainId, actor) {
         if (!can('audit-confirm', actor, null))
             throw new Error('permission denied');
@@ -269,7 +308,7 @@ export class KanbanService {
             throw new Error('no audit warning for chain: ' + chainId);
         return this.emit({ chainId, taskId: null, kind: 'chain/audit-confirmed', payload: {}, author: actor, at: Date.now() });
     }
-    /** T7：链标题改名（仅 human，GUI）。发 chain/title-updated 事件（非状态转换）。 */
+    /** 链标题改名（仅 human，GUI）。发 chain/title-updated 事件（非状态转换）。 */
     async updateChainTitle(chainId, title, actor) {
         if (!can('update-title', actor, null))
             throw new Error('permission denied');
@@ -362,7 +401,7 @@ export class KanbanService {
         await this.emit({ chainId: t.chainId, taskId, kind: 'task/archived', payload: {}, author: actor, at: Date.now() });
         return this.state.tasks.get(taskId);
     }
-    /** T10.5：仅 draft 规格卡可挂附件（V 挂清单附件（/openspec: 建链）/ human GUI 上传）。 */
+    /** 仅 draft 规格卡可挂附件（V 挂清单附件（/openspec: 建链）/ human GUI 上传）。 */
     async addSpecCardAttachment(cardId, attachment, actor) {
         const card = this.state.specCards.get(cardId);
         if (!card)
@@ -397,7 +436,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 +454,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;
@@ -419,7 +462,7 @@ export class KanbanService {
         return task;
     }
     async snapshot() {
-        // P0-3：重投影为权威（事件日志是唯一事实源；非法转换在此抛错）
+        // 重投影为权威（事件日志是唯一事实源；非法转换在此抛错）
         this.state = project(await this.store.readAll());
         return this.state;
     }

package/lib/domain/memory.js

@@ -65,7 +65,7 @@ export function buildRepoSlug(workspaceDir) {
     const base = workspaceDir.replace(/\/+$/, '').split('/').pop() ?? '';
     return buildChecklistSlug(base);
 }
-// ── Task 4：证据包 + 链解析 ──────────────────────────────────────────
+// ── 证据包 + 链解析 ──────────────────────────────────────────
 const truncate = (s, n) => (s.length > n ? s.slice(0, n) + '…' : s);
 /** 链上下文头：链标题 + 规格卡 problem 首行。 */
 function chainContext(state, chainId) {

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

@@ -0,0 +1,47 @@
+/** OCR 委派子命令类型：预览 / 规则 / 托管评审。 */
+export type OcrSub = 'preview' | 'rule' | 'managed';
+/** OCR 调用可选参数集合。 */
+export interface OcrArgsInput {
+    repo?: string;
+    from?: string;
+    to?: string;
+    commit?: string;
+    paths?: string[];
+}
+/** 构造 OCR CLI 参数：preview/rule 走 delegate，managed 走 review 并恒带 JSON 输出。 */
+export declare function buildOcrArgs(sub: OcrSub, a: OcrArgsInput): string[];
+/** 预览结果归一化结构。 */
+export interface PreviewResult {
+    mode: string;
+    files: {
+        path: string;
+        status: string;
+    }[];
+    excluded: {
+        path: string;
+        reason: string;
+    }[];
+    mergeBase: string | null;
+}
+/** 解析 delegate preview 的 JSON 输出，失败或结构异常时回退 unknown。 */
+export declare function parsePreviewJson(stdout: string): PreviewResult;
+/** 托管评审结果归一化结构。 */
+export interface ManagedResult {
+    status: string;
+    comments: {
+        path: string | null;
+        line: number | null;
+        severity: string | null;
+        message: string;
+    }[];
+}
+/** 解析 managed review 的 JSON 输出，失败时回退 unknown。 */
+export declare function parseManagedJson(stdout: string): ManagedResult;
+/** 建议切换托管评审的文件数阈值。 */
+export declare const SUGGEST_MANAGED_FILES = 50;
+/** 文件数严格超过阈值时建议托管评审。 */
+export declare function shouldSuggestManaged(fileCount: number): boolean;
+/** 生成独立评审页命名空间路径：projects/<slug>/reviews/<topic>-<ymd>/。 */
+export declare function reviewPagePath(repoSlug: string, topic: string, ymd: string): string;
+/** 判定路径是否为合法的独立评审页命名空间路径。 */
+export declare function isStandaloneReviewNamespacePath(pagePath: string): boolean;

package/lib/domain/ocr-review.js

@@ -0,0 +1,105 @@
+/** 构造 OCR CLI 参数：preview/rule 走 delegate，managed 走 review 并恒带 JSON 输出。 */
+export function buildOcrArgs(sub, a) {
+    if (sub === 'preview') {
+        const args = ['delegate', 'preview'];
+        if (a.from)
+            args.push('--from', a.from);
+        if (a.to)
+            args.push('--to', a.to);
+        if (a.repo)
+            args.push('--repo', a.repo);
+        return args;
+    }
+    if (sub === 'rule') {
+        return ['delegate', 'rule', ...(a.paths ?? [])];
+    }
+    const args = ['review'];
+    if (a.commit)
+        args.push('--commit', a.commit);
+    else if (a.from || a.to) {
+        if (a.from)
+            args.push('--from', a.from);
+        if (a.to)
+            args.push('--to', a.to);
+    }
+    args.push('--format', 'json');
+    return args;
+}
+/** 解析失败的兜底结果。 */
+const UNKNOWN_PREVIEW = { mode: 'unknown', files: [], excluded: [], mergeBase: null };
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** 元素字段别名读取（path/filePath）。 */
+function pathOf(el) {
+    return String(el.path ?? el.filePath ?? '');
+}
+function asArray(v) {
+    return Array.isArray(v) ? v.filter(isRecord) : [];
+}
+/** 解析 delegate preview 的 JSON 输出，失败或结构异常时回退 unknown。 */
+export function parsePreviewJson(stdout) {
+    let obj;
+    try {
+        obj = JSON.parse(stdout);
+    }
+    catch {
+        return UNKNOWN_PREVIEW;
+    }
+    if (!isRecord(obj))
+        return UNKNOWN_PREVIEW;
+    const mergeBase = obj.merge_base ?? obj.mergeBase;
+    return {
+        mode: String(obj.mode ?? 'unknown'),
+        files: asArray(obj.files).map((el) => ({ path: pathOf(el), status: String(el.status ?? '') })),
+        excluded: asArray(obj.excluded).map((el) => ({ path: pathOf(el), reason: String(el.reason ?? '') })),
+        mergeBase: mergeBase == null ? null : String(mergeBase),
+    };
+}
+/** 解析 managed review 的 JSON 输出，失败时回退 unknown。 */
+export function parseManagedJson(stdout) {
+    let obj;
+    try {
+        obj = JSON.parse(stdout);
+    }
+    catch {
+        return { status: 'unknown', comments: [] };
+    }
+    if (!isRecord(obj))
+        return { status: 'unknown', comments: [] };
+    const comments = asArray(obj.comments).map((el) => {
+        const rawLine = el.line ?? el.startLine;
+        const line = Number(rawLine);
+        const message = String(el.content ?? el.message ?? el.body ?? '');
+        return {
+            path: el.path == null && el.filePath == null ? null : pathOf(el),
+            line: Number.isNaN(line) ? null : line,
+            severity: el.severity == null && el.level == null ? null : String(el.severity ?? el.level),
+            message: message.slice(0, 2000),
+        };
+    });
+    return { status: String(obj.status ?? 'unknown'), comments };
+}
+/** 建议切换托管评审的文件数阈值。 */
+export const SUGGEST_MANAGED_FILES = 50;
+/** 文件数严格超过阈值时建议托管评审。 */
+export function shouldSuggestManaged(fileCount) {
+    return fileCount > SUGGEST_MANAGED_FILES;
+}
+/** 评审主题清洗：小写化，非字母数字连续折叠为 -，去首尾 -，空则回退 review。 */
+function sanitizeTopic(topic) {
+    const cleaned = topic.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return cleaned || 'review';
+}
+/** 生成独立评审页命名空间路径：projects/<slug>/reviews/<topic>-<ymd>/。 */
+export function reviewPagePath(repoSlug, topic, ymd) {
+    return `projects/${repoSlug}/reviews/${sanitizeTopic(topic)}-${ymd}/`;
+}
+/** 独立评审页命名空间路径匹配规则。 */
+const REVIEW_NS_RE = /^projects\/[a-z0-9-]+\/reviews\/[a-z0-9-]+-[0-9]{4}-[0-9]{2}-[0-9]{2}\//;
+/** 判定路径是否为合法的独立评审页命名空间路径。 */
+export function isStandaloneReviewNamespacePath(pagePath) {
+    if (!pagePath || pagePath.startsWith('/') || pagePath.includes('..'))
+        return false;
+    return REVIEW_NS_RE.test(pagePath);
+}

package/lib/domain/permissions.js

@@ -1,5 +1,5 @@
 export function can(action, actor, task, opts = {}) {
-    // P1-4：会话绑定——角色 agent 只能操作其被 spawn 绑定的任务（boundTaskId=AgentSessionRef.task_id）；
+    // 会话绑定——角色 agent 只能操作其被 spawn 绑定的任务（boundTaskId=AgentSessionRef.task_id）；
     // 旧 own（仅查 assignee）允许"链上任意同角色任务"，属跨任务越权，已废弃。
     const bound = opts.boundTaskId !== undefined && task !== null && opts.boundTaskId === task.id;
     switch (action) {
@@ -10,7 +10,7 @@ export function can(action, actor, task, opts = {}) {
             return actor === 'system';
         case 'complete':
             // 仅绑定该任务的 agent 会话（boundTaskId 匹配且角色=任务 assignee）、系统收尾，
-            // 或 human（GUI 强制收尾，T27：human 为信任锚，不算越权）；跨角色 bound 拒。
+            // 或 human（GUI 强制收尾，human 为信任锚，不算越权）；跨角色 bound 拒。
             return actor === 'system' || actor === 'human' || (bound && actor === task.assignee);
         case 'block':
             return actor === 'system' || actor === 'human' || bound;
@@ -25,13 +25,13 @@ export function can(action, actor, task, opts = {}) {
         case 'spec-approve':
             return actor === 'human';
         case 'spec-edit':
-            // P1-4：规格卡编辑仅 human（主会话前台）；P 对规格卡只读
+            // 规格卡编辑仅 human（主会话前台）；P 对规格卡只读
             return actor === 'human';
         case 'spec-attach':
             // 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 工具面
@@ -39,10 +39,10 @@ export function can(action, actor, task, opts = {}) {
         case 'prefetch':
             return actor === 'w';
         case 'audit-confirm':
-            // D23：仅人类在 GUI 确认产物归属；system/角色均不可
+            // 仅人类在 GUI 确认产物归属；system/角色均不可
             return actor === 'human';
         case 'update-title':
-            // T7：链/任务标题改名仅 human（GUI）；V/角色均不可（防角色伪造链/卡标题）
+            // 链/任务标题改名仅 human（GUI）；V/角色均不可（防角色伪造链/卡标题）
             return actor === 'human';
         case 'delete-chain':
             // 整链硬删除仅 human（GUI 二次确认）；V/角色/system 均不可

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);
@@ -26,7 +27,7 @@ export function applyTo(state, ev) {
             next.chains = new Map(state.chains).set(ev.chainId, { ...c, rootTaskId: String(ev.payload['rootTaskId'] ?? '') });
             break;
         }
-        // D23：audit 事件不改 Chain 状态，只写验收核对视图（auditWarnings）
+        // audit 事件不改 Chain 状态，只写验收核对视图（auditWarnings）
         case 'chain/audit-warning': {
             const c = state.chains.get(ev.chainId);
             if (!c)
@@ -58,7 +59,7 @@ export function applyTo(state, ev) {
             });
             break;
         }
-        // T7：链标题改名（非状态转换，只更新 title；快照重放可见）
+        // 链标题改名（非状态转换，只更新 title；快照重放可见）
         case 'chain/title-updated': {
             const c = state.chains.get(ev.chainId);
             if (!c)
@@ -66,7 +67,7 @@ export function applyTo(state, ev) {
             next.chains = new Map(state.chains).set(ev.chainId, { ...c, title: String(ev.payload['to'] ?? '') });
             break;
         }
-        // T7：任务标题改名（非状态转换，只更新 title）
+        // 任务标题改名（非状态转换，只更新 title）
         case 'task/renamed': {
             if (!ev.taskId)
                 throw new Error('projection: event without taskId');
@@ -80,7 +81,7 @@ export function applyTo(state, ev) {
             const p = ev.payload;
             if (!p.id || !p.assignee)
                 throw new Error('projection: malformed task/created');
-            // 归一化缺省字段，使最小 payload 的事件日志可回放（P0-3 回放为权威）
+            // 归一化缺省字段，使最小 payload 的事件日志可回放（回放为权威）
             const normalized = {
                 ...p,
                 status: p.status ?? 'todo',
@@ -112,11 +113,11 @@ export function applyTo(state, ev) {
             const updated = { ...t, status: transitionTask(t.status, ev.kind) };
             if (ev.kind === 'task/heartbeat')
                 updated.heartbeats = [...t.heartbeats, ev.at];
-            // RC4：infra 失败不计入 attempts（瞬时基础设施错误不烧重试预算）；任务质量失败正常 +1
+            // infra 失败不计入 attempts（瞬时基础设施错误不烧重试预算）；任务质量失败正常 +1
             if (ev.kind === 'task/failed' && !ev.payload['infra'])
                 updated.attempts = t.attempts + 1;
             if (ev.kind === 'task/unblocked')
-                updated.attempts = 0; // RC4：人工解除阻塞 → 重试预算重置
+                updated.attempts = 0; // 人工解除阻塞 → 重试预算重置
             if (ev.kind === 'task/completed') {
                 const p = ev.payload;
                 next.handoffs = new Map(state.handoffs).set(ev.taskId, p);