@joekytc/dsh-swarm 0.2.0 → 0.3.1

package/lib/domain/im-message.js

@@ -0,0 +1,149 @@
+import { hasDeliveryEvidence } from './delivery-evidence.js';
+/** W3 收尾判据（镜像 kanban-service.completeTask 机械规则，但不含 dEvidenceOk 与链状态要求）：
+ *  完成卡为 w+kb、链上无未终态卡、它是最后完成的卡、且链上存在 done 的 D 卡（防 W2 中间态误投）。 */
+export function isFinalW3Completion(state, chainId, completedTaskId) {
+    const task = state.tasks.get(completedTaskId);
+    if (!task || task.chainId !== chainId || task.assignee !== 'w' || task.mode !== 'kb')
+        return false;
+    const chainTasks = [...state.tasks.values()].filter((t) => t.chainId === chainId);
+    if (chainTasks.some((t) => t.status !== 'done' && t.status !== 'archived'))
+        return false;
+    const completedEvents = state.events.filter((e) => e.chainId === chainId && e.kind === 'task/completed' && e.taskId);
+    if (completedEvents.at(-1)?.taskId !== completedTaskId)
+        return false;
+    return chainTasks.some((t) => (t.mode === 'execute' || t.mode === 'align') && t.status === 'done');
+}
+function fmtTime(ms) {
+    const d = new Date(ms);
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+function strMeta(handoff, key) {
+    const v = (handoff?.metadata ?? {})[key];
+    return typeof v === 'string' ? v.trim() : '';
+}
+/** 人工关注点：TDD 跳过声明、D 证据缺失（链完成门禁拦截）、审计警告状态。 */
+function completionAttention(state, chainId, dHandoff) {
+    const out = [];
+    const tdd = (dHandoff?.metadata ?? {})['tdd'];
+    const skipReason = tdd?.skipped && typeof tdd.skipped['reason'] === 'string' ? tdd.skipped['reason'].trim() : '';
+    if (skipReason)
+        out.push(`TDD 曾跳过：${skipReason}`);
+    if (!hasDeliveryEvidence(dHandoff))
+        out.push('D 卡缺 git 产物证据，链未自动收链，请人工核对');
+    const audit = state.auditWarnings.get(chainId);
+    if (audit && !audit.confirmedAt)
+        out.push(`审计警告待 GUI 确认（${audit.evidence.length} 条证据）`);
+    else if (audit?.confirmedAt)
+        out.push(`审计警告已于 ${fmtTime(audit.confirmedAt)} 确认`);
+    return out;
+}
+/** 成功汇报（markdown）。判据不满足（W2 中间态/非 w:kb/非收尾）返回 null。 */
+export function buildCompletionMessage(state, chainId, completedTaskId, now) {
+    if (!isFinalW3Completion(state, chainId, completedTaskId))
+        return null;
+    const chain = state.chains.get(chainId);
+    if (!chain)
+        return null;
+    const chainTasks = [...state.tasks.values()].filter((t) => t.chainId === chainId);
+    const wHandoff = state.handoffs.get(completedTaskId);
+    const dTask = chainTasks.find((t) => (t.mode === 'execute' || t.mode === 'align') && t.status === 'done');
+    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 lines = [];
+    lines.push(`**【DSH 需求完成】${chain.title}**`);
+    lines.push('');
+    lines.push(`**完成清单**（${fmtTime(now)}）`);
+    for (const t of chainTasks)
+        lines.push(`- ✅ ${t.title}`);
+    lines.push('');
+    lines.push('**产出**');
+    const kbUrl = strMeta(wHandoff, 'kb_url');
+    const pagePath = strMeta(wHandoff, 'page_path');
+    if (kbUrl)
+        lines.push(`- KB 文档：${kbUrl}`);
+    if (pagePath)
+        lines.push(`- KB 页：${pagePath}`);
+    lines.push(`- 产出物：${artifacts || '（无）'}`);
+    const attention = completionAttention(state, chainId, dHandoff);
+    if (attention.length > 0) {
+        lines.push('');
+        lines.push('**人工关注点**');
+        for (const a of attention)
+            lines.push(`- ${a}`);
+    }
+    return lines.join('\n');
+}
+/** 阻塞建议映射表（静态工程知识，禁止模型现场生成——评审决议）。 */
+const SUGGESTION_TABLE = [
+    {
+        pattern: /\[create-failed\]/,
+        lines: [
+            'V 连续多轮建卡失败：查 dispatcher.log 的 [wakeV] / [tick] error 行，确认编排会话报错原因',
+            '核对 roles.models.v 模型路由配置；历史案例：网关回复缓存回放（from-cache）会致零工具调用，可更换 provider/model 后重试',
+        ],
+    },
+    {
+        pattern: /\[stall-watchdog\]/,
+        lines: [
+            '链持续无进展且重唤醒耗尽：查 dispatcher.log [stall-watchdog] 行与 orchestration.json 的 phase/stallCount',
+            '检查最后一张卡会话（kbn-<taskId>）session.jsonl 是否空壳（仅 4 行骨架）——空壳需人工清理后删链重跑',
+        ],
+    },
+];
+export function suggestionsFor(reason) {
+    const out = [];
+    for (const row of SUGGESTION_TABLE) {
+        if (row.pattern.test(reason))
+            out.push(...row.lines);
+    }
+    if (out.length === 0) {
+        out.push('查 events.jsonl 最近事件定位阻塞前最后一个动作');
+        out.push('GUI 打开该链逐卡核对状态；人工恢复 = 删链重跑');
+    }
+    return out;
+}
+/** 链下全部 blocked 卡（title + 最近一次 task/blocked 原因）。 */
+export function latestBlockedTasks(events, tasks, chainId) {
+    const reasons = new Map();
+    for (const e of events) {
+        if (e.chainId !== chainId || e.kind !== 'task/blocked' || !e.taskId)
+            continue;
+        reasons.set(e.taskId, String(e.payload['reason'] ?? ''));
+    }
+    const out = [];
+    for (const t of tasks) {
+        if (t.chainId !== chainId || t.status !== 'blocked')
+            continue;
+        out.push({ id: t.id, title: t.title, reason: reasons.get(t.id) ?? '（原因见事件流）' });
+    }
+    return out;
+}
+/** 阻塞通知（markdown）。 */
+export function buildBlockMessage(state, chainId, chainReason, storageDir) {
+    const chain = state.chains.get(chainId);
+    const blocked = latestBlockedTasks(state.events, state.tasks.values(), chainId);
+    const lines = [];
+    lines.push(`**【DSH 需求阻塞】${chain?.title ?? chainId}**`);
+    lines.push('');
+    lines.push('**阻塞卡**');
+    if (blocked.length === 0)
+        lines.push('- 无（链级停滞，见阻塞原因）');
+    else
+        for (const b of blocked)
+            lines.push(`- ${b.title}：${b.reason}`);
+    lines.push('');
+    lines.push('**阻塞原因**');
+    lines.push(`> ${chainReason}`);
+    lines.push('');
+    lines.push('**排查建议**');
+    for (const s of suggestionsFor(chainReason))
+        lines.push(`- ${s}`);
+    lines.push('');
+    lines.push('**取证路径**');
+    lines.push(`- 事件：${storageDir}/events.jsonl`);
+    lines.push(`- 编排：${storageDir}/orchestration.json`);
+    lines.push(`- 调度：${storageDir}/dispatcher.log`);
+    return lines.join('\n');
+}

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

@@ -2,7 +2,7 @@ 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';
 export type KanbanListener = (event: KanbanEvent) => void;
-/** 首句：trim 后按首个换行或「。？！ 」截断；超长兜底 40 字（T7 需求标题规范化）。 */
+/** 首句：trim 后按首个换行或「。？！ 」截断；超长兜底 40 字（需求标题规范化）。 */
 export declare function firstSentence(text: string): string;
 /** 默认链标题：【需求】<一句话需求描述>。来源优先级 /plan: rest 首句 → checklist.problem 首句 → 未命名需求。 */
 export declare function buildChainTitle(requirementName: string | null, _openspecRest: string, problem: string): string;
@@ -18,18 +18,18 @@ export declare class KanbanService {
     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=关闭实测闸，行为与旧版逐字节一致）。 */
+    /** 注入实测闸钩子（由装配层设置；null=关闭实测闸，行为与旧版逐字节一致）。 */
     setGateHook(hook: ((task: Task, handoff: Handoff) => Promise<{
         ok: boolean;
         detail: string;
     } | null>) | null): void;
-    /** T22：订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
+    /** 订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
     subscribe(listener: KanbanListener): () => void;
-    /** T22：返回 seq >= 入参 的事件（与 EventStore.readSince 同为 inclusive 语义）。 */
+    /** 返回 seq >= 入参 的事件（与 EventStore.readSince 同为 inclusive 语义）。 */
     eventsSince(seq: number): Promise<KanbanEvent[]>;
     private publish;
     private chainOf;
@@ -45,6 +45,9 @@ export declare class KanbanService {
     /** 链级停滞终态（防线A，看门狗/V stall 超限专用机械记账）：executing → blocked。
      *  非 executing 调用即抛（fail-closed）；人工恢复=GUI 删链重跑（blocked 无出边）。 */
     blockChain(chainId: string, reason: string): Promise<void>;
+    /** IM 投递失败留痕（仅 system 机械记账）：非状态转换注记事件，仅落盘供取证/GUI 观察。
+     *  投递是旁路通知，失败绝不 block 链（评审决议）；留痕满足「禁止静默 skip」红线。 */
+    noteImDeliveryFailed(chainId: string, detail: string, actor: Actor): Promise<KanbanEvent>;
     createTask(input: {
         chainId: string;
         title: string;
@@ -58,11 +61,11 @@ export declare class KanbanService {
     completeTask(taskId: string, handoff: Handoff, actor: Actor, opts?: {
         boundTaskId?: string;
     }): Promise<Task>;
-    /** D23：链完成验收核对发警告（仅 system/dispatcher 可发）。Chain 状态保持 completed。 */
+    /** 链完成验收核对发警告（仅 system/dispatcher 可发）。Chain 状态保持 completed。 */
     auditWarning(chainId: string, evidence: AuditEvidence[], actor: Actor): Promise<KanbanEvent>;
-    /** D23：用户确认产物归属（仅 human，GUI confirm-audit action）。放行最终汇报。 */
+    /** 用户确认产物归属（仅 human，GUI confirm-audit action）。放行最终汇报。 */
     confirmAudit(chainId: string, actor: Actor): Promise<KanbanEvent>;
-    /** T7：链标题改名（仅 human，GUI）。发 chain/title-updated 事件（非状态转换）。 */
+    /** 链标题改名（仅 human，GUI）。发 chain/title-updated 事件（非状态转换）。 */
     updateChainTitle(chainId: string, title: string, actor: Actor): Promise<Chain>;
     /** 整链硬删除（含其下全部角色卡/规格卡事件；仅 human，GUI 二次确认）。物理 purge 事件行，不可恢复。 */
     deleteChain(chainId: string, actor: Actor): Promise<void>;
@@ -80,7 +83,7 @@ export declare class KanbanService {
     }): Promise<Task>;
     comment(taskId: string, body: string, actor: Actor): Promise<KanbanEvent>;
     archiveTask(taskId: string, actor: Actor): Promise<Task>;
-    /** T10.5：仅 draft 规格卡可挂附件（V 挂清单附件（/openspec: 建链）/ human GUI 上传）。 */
+    /** 仅 draft 规格卡可挂附件（V 挂清单附件（/openspec: 建链）/ human GUI 上传）。 */
     addSpecCardAttachment(cardId: string, attachment: SpecCardAttachment, actor: Actor): Promise<SpecCard>;
     /** 评审事件（交付质量链）：recordReview 记录评审卡结论并更新被评审任务 reviewStatus。
      *  actor 必须 system（V/角色不可伪造评审结论）；verdict=pass → review/passed，否则 review/failed。

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,23 +22,23 @@ export function buildChainTitle(requirementName, _openspecRest, problem) {
 export class KanbanService {
     state;
     store;
-    // Q4：kb_url host 前缀硬校验基准（config.wikiVault.baseUrl）。null = 不校验前缀（兼容测试/旧调用）。
-    // 配置面板热生效（Task 6）：改为 getter，每次校验时取最新值——改 baseUrl 无需重建服务。
+    // 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;
-    // P1：实测闸钩子（装配层注入：gate-policy 派生 + gate-runner 实测执行 + 分支核对）。
+    // 实测闸钩子（装配层注入：gate-policy 派生 + gate-runner 实测执行 + 分支核对）。
     // null=未启用（行为不变）；hook 返回 null=跳过（零感知，无 gate 事件）。
     // **无 actor 参数——human 无豁免**（2026-09-02 决议收紧）。
     gateHook = null;
     constructor(store, getKbUrlBase) {
         this.store = store;
         this.getKbUrlBase = getKbUrlBase ?? null;
-        // P0-3：同步重投影，消除"构造后立即调用基于空状态"的竞态
+        // 同步重投影，消除"构造后立即调用基于空状态"的竞态
         this.state = project(store.readAllSync());
     }
     async emit(ev) {
@@ -54,24 +54,24 @@ export class KanbanService {
         await pending;
         return emitted;
     }
-    /** D23：注入链完成核对钩子（由调度层设置；仅一个消费者）。 */
+    /** 注入链完成核对钩子（由调度层设置；仅一个消费者）。 */
     setOnChainCompleted(hook) {
         this.onChainCompletedHook = hook;
     }
-    /** Q3&5：注入任务完成互链登记钩子（由调度层设置；仅一个消费者）。 */
+    /** 注入任务完成互链登记钩子（由调度层设置；仅一个消费者）。 */
     setOnTaskCompleted(hook) {
         this.onTaskCompletedHook = hook;
     }
-    /** P1：注入实测闸钩子（由装配层设置；null=关闭实测闸，行为与旧版逐字节一致）。 */
+    /** 注入实测闸钩子（由装配层设置；null=关闭实测闸，行为与旧版逐字节一致）。 */
     setGateHook(hook) {
         this.gateHook = hook;
     }
-    /** T22：订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
+    /** 订阅持久化后的看板事件；返回解除订阅函数。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);
     }
@@ -146,6 +146,14 @@ export class KanbanService {
             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');
@@ -154,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) {
@@ -164,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
@@ -195,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 } }');
         }
@@ -230,7 +238,7 @@ export class KanbanService {
         }
         // v2 断代：w:file 交付键随旧 w1 预取阶段移除，manifest 校验块同步删除
         // （validatePrefetchManifest 仍保留于 prefetch-manifest.ts，供清单 schema 校验复用）。
-        // 实测闸（P1）：hook 由装配层注入（gate-policy 派生 + gate-runner 实测执行 + 分支核对），
+        // 实测闸：hook 由装配层注入（gate-policy 派生 + gate-runner 实测执行 + 分支核对），
         // hook 返回 null=跳过（未启用/非 D/旧卡/分支不一致）。**无 human 豁免**（2026-09-02 决议收紧）；
         // ok=false → gate-failed 事件 + 拒绝 complete（卡留 running，throw 经工具边界回 D 会话）。
         if (this.gateHook) {
@@ -243,7 +251,7 @@ export class KanbanService {
             }
         }
         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 {
@@ -253,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);
@@ -270,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 {
@@ -283,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');
@@ -300,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');
@@ -393,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)
@@ -454,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.d.ts

@@ -5,7 +5,11 @@ export interface LearningEntry {
     evidence: string;
     tags: string[];
 }
+/** 五类有效经验类别标签（0.3.1 判据）：tags 必含其一，防「为出经验而出」的假沉淀。 */
+export declare const LEARNING_CATEGORY_TAGS: readonly ["mistake", "reusable", "env-trap", "collab-contract", "efficiency"];
 export declare function validateLearning(raw: unknown): string[];
+/** A 类犯错教训机械信号累计（评审失败/任务阻塞/审计警告事件 + 返工卡）。brief 统计行与 save 硬闸共用同一口径。 */
+export declare function countLearningSignals(state: BoardState, chainId: string): number;
 export declare function formatLearningBody(entry: LearningEntry, created?: Date): string;
 export interface MemoryIndexEntry {
     kind: 'learning' | 'doc';
@@ -16,7 +20,8 @@ export declare function buildMemoryIndexBlock(entries: MemoryIndexEntry[]): stri
 export declare function weightedRank<T>(items: T[], scoreOf: (t: T) => number, timeOf: (t: T) => number): T[];
 export declare function buildRepoSlug(workspaceDir: string): string;
 export type { BoardState };
-/** 机械提取四类信号（事件流/投影，禁 LLM 猜测），渲染紧凑 markdown。 */
+/** 机械提取四类信号（事件流/投影，禁 LLM 猜测），渲染紧凑 markdown。
+ *  头部带信号统计（判据 A 准入：累计 ≥2 次才可沉淀犯错教训，模型不用自己数）。 */
 export declare function buildLearningBrief(state: BoardState, chainId: string): string;
 /** /learning rest → 链解析：空→最近链；精确 id→命中；子串匹配→单命中或候选列表（≤3）；无→null。 */
 export declare function resolveLearningChainId(state: BoardState, rest: string): {

package/lib/domain/memory.js

@@ -1,4 +1,6 @@
 import { buildChecklistSlug } from '../wiki/page-path.js';
+/** 五类有效经验类别标签（0.3.1 判据）：tags 必含其一，防「为出经验而出」的假沉淀。 */
+export const LEARNING_CATEGORY_TAGS = ['mistake', 'reusable', 'env-trap', 'collab-contract', 'efficiency'];
 export function validateLearning(raw) {
     const errors = [];
     if (typeof raw !== 'object' || raw === null)
@@ -14,8 +16,18 @@ export function validateLearning(raw) {
         errors.push('learning.tags must be an array of strings');
     if (Array.isArray(l['tags']) && l['tags'].some((v) => typeof v !== 'string'))
         errors.push('learning.tags must be an array of strings');
+    // 类别硬闸（报错文案即教学）：tags 必含五类之一；样式/文案/字段名等一次性平凡变更不构成经验
+    if (Array.isArray(l['tags']) && l['tags'].every((v) => typeof v !== 'string' || !LEARNING_CATEGORY_TAGS.includes(v))) {
+        errors.push('learning.tags 必须含类别标签之一：mistake(犯错教训:链上阻塞/返工/评审失败/审计警告累计≥2) / reusable(可复用模式:同类流程或行为重复≥2) / env-trap(环境陷阱:踩坑1次+报错diff等硬证据) / collab-contract(协作契约:用户偏好≥2次确认) / efficiency(效率模式:量化省力依据)；样式/文案/字段名等一次性平凡变更不构成经验，五类均不满足应回复「无新经验」');
+    }
     return errors;
 }
+/** A 类犯错教训机械信号累计（评审失败/任务阻塞/审计警告事件 + 返工卡）。brief 统计行与 save 硬闸共用同一口径。 */
+export function countLearningSignals(state, chainId) {
+    const chainEvents = state.events.filter((e) => e.chainId === chainId);
+    const reworks = [...state.tasks.values()].filter((t) => t.chainId === chainId && t.reworkOfTaskId !== null);
+    return chainEvents.filter((e) => e.kind === 'review/failed' || e.kind === 'task/blocked' || e.kind === 'chain/audit-warning').length + reworks.length;
+}
 export function formatLearningBody(entry, created = new Date()) {
     const date = created.toISOString().slice(0, 10);
     const lines = [
@@ -65,7 +77,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) {
@@ -76,12 +88,22 @@ function chainContext(state, chainId) {
     const problem = spec?.sections.problem ? spec.sections.problem.split('\n')[0].slice(0, 200) : '';
     return [chain.title, problem].filter(Boolean).join(' — ');
 }
-/** 机械提取四类信号（事件流/投影，禁 LLM 猜测），渲染紧凑 markdown。 */
+/** 机械提取四类信号（事件流/投影，禁 LLM 猜测），渲染紧凑 markdown。
+ *  头部带信号统计（判据 A 准入：累计 ≥2 次才可沉淀犯错教训，模型不用自己数）。 */
 export function buildLearningBrief(state, chainId) {
     const header = ['## 链上下文', chainContext(state, chainId), ''];
-    const sections = [];
     const chainEvents = state.events.filter((e) => e.chainId === chainId);
     const reviewFailed = chainEvents.filter((e) => e.kind === 'review/failed');
+    const blocked = chainEvents.filter((e) => e.kind === 'task/blocked');
+    const reworks = [...state.tasks.values()].filter((t) => t.chainId === chainId && t.reworkOfTaskId !== null);
+    const audit = chainEvents.filter((e) => e.kind === 'chain/audit-warning');
+    if (countLearningSignals(state, chainId) === 0) {
+        return [...header, '（无机械信号。A 类犯错教训判据不满足；B/D 需重复出现 ≥2 次，C 需报错/diff 等硬证据，E 需量化省力依据，均不满足则回复「无新经验」）'].join('\n');
+    }
+    const total = countLearningSignals(state, chainId);
+    const sections = [
+        ['### 信号统计（A 类准入：累计 ≥2 次）', `评审失败 ${reviewFailed.length} / 任务阻塞 ${blocked.length} / 返工卡 ${reworks.length} / 审计警告 ${audit.length}，累计 ${total} 次`].join('\n'),
+    ];
     if (reviewFailed.length > 0) {
         const lines = ['### 评审失败'];
         for (const e of reviewFailed.slice(-5)) {
@@ -91,7 +113,6 @@ export function buildLearningBrief(state, chainId) {
         }
         sections.push(lines.join('\n'));
     }
-    const blocked = chainEvents.filter((e) => e.kind === 'task/blocked');
     if (blocked.length > 0) {
         const lines = ['### 任务阻塞'];
         for (const e of blocked.slice(-5)) {
@@ -101,14 +122,12 @@ export function buildLearningBrief(state, chainId) {
         }
         sections.push(lines.join('\n'));
     }
-    const reworks = [...state.tasks.values()].filter((t) => t.chainId === chainId && t.reworkOfTaskId !== null);
     if (reworks.length > 0) {
         const lines = ['### 返工卡'];
         for (const t of reworks.slice(-5))
             lines.push(`- [返工×${t.reviewAttempt}] ${t.title}（原卡 ${t.reworkOfTaskId}）`);
         sections.push(lines.join('\n'));
     }
-    const audit = chainEvents.filter((e) => e.kind === 'chain/audit-warning');
     if (audit.length > 0) {
         const lines = ['### 审计警告'];
         for (const e of audit.slice(-5)) {
@@ -118,8 +137,6 @@ export function buildLearningBrief(state, chainId) {
         }
         sections.push(lines.join('\n'));
     }
-    if (sections.length === 0)
-        return [...header, '（无机械信号，可基于对话观察蒸馏）'].join('\n');
     return [...header, ...sections].join('\n');
 }
 /** /learning rest → 链解析：空→最近链；精确 id→命中；子串匹配→单命中或候选列表（≤3）；无→null。 */

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;