@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/lib/tools/main-session-tools.js

@@ -1,4 +1,5 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 import { tmpdir } from 'node:os';
 import { KanbanProvider } from '../services/kanban-provider.js';
 import { buildKanbanTools } from './kanban-tools.js';
@@ -10,8 +11,11 @@ import { buildPlanningGuidance } from '../routes/planning-driver.js';
 import { attachSessionToWorkspace, resolveOrCreateWorkspace } from '../dispatcher/workspace-attach.js';
 import { PREFETCH_MANIFEST_SCHEMA } from '../domain/prefetch-manifest.js';
 import { WikiVaultClient } from '../wiki/wiki-vault-client.js';
+import { LocalWikiClient } from '../wiki/local-kb-client.js';
+import { ensureLocalKbRoot } from '../wiki/local-kb.js';
+import { LOCAL_CHECKLIST_PREFIX } from '../wiki/page-path.js';
 export const planningBySession = new Map();
-const KANBAN_HANDOFF_RULE = (routes) => `
+export const KANBAN_HANDOFF_RULE = (routes) => `
 ## 主 agent 铁律（看板工作流 v2）
 - 你是计划者：只做需求澄清（grill-me）与最终收尾汇报；绝不执行任务本身。
 - 最高护栏：只读仓库——禁止 git 操作、禁止 write/edit 任何仓库源码；只允许写 KB（planning_checklist_save）与临时目录兜底。
@@ -19,7 +23,25 @@ const KANBAN_HANDOFF_RULE = (routes) => `
 - ${routes.openspec} 后链路进入 executing，V 自动串行建卡 p→(pt)→w2→d→dt→w3；你不要自己执行。
 - 用 kanban_show / kanban_list / spec_card_view 观察进度，链完成后向用户汇报产物链接与轨迹入口。
 - 经验沉淀：链路完成后，用户可发 ${routes.learning}（或 ${routes.learning} <chainId>）沉淀本链经验；主 agent 消化机械证据包后调 planning_learning_save 入库。
+- 叙述铁律：回复中的链号/卡号（ch_/sc_/t_ 编号）只能逐字复制自工具结果；建链成败以工具结果字段为准，禁止编造或沿用旧对话里的编号。
 `;
+/** 防线③：/openspec: 成功后的逐链确定性叙述规则（2026-09-04 mtmgp81q：模型口播 ch_1_mtjrhkrf
+ *  与工具结果 ch_1_mtmgp81q 脱节）。逐字引用锚点 + firstCard 成败结论；整包缓存回放仍可能
+ *  绕过 prompt 层——最终防线是链级看门狗（防线①）。 */
+export function buildOpenspecNarrationRule(r) {
+    const firstCardLine = !r.firstCard
+        ? '- 首卡结果未采集（旧返回体）。汇报前先调 kanban_show 复核链状态，以 kanban_show 复核后再汇报，禁止臆断建卡成功。'
+        : 'pending' in r.firstCard
+            ? `- 首卡尚未创建（等待超时，看门狗接管）。回复必须写明「首卡尚未创建，看门狗接管」，禁止声称建卡成功。`
+            : `- 首卡已创建：taskId=${r.firstCard.taskId}（status=${r.firstCard.status}）。回复必须写明「首卡已创建」。`;
+    return [
+        '## 本次建链结果（回复必须逐字引用，禁止改写编号）',
+        `- chainId=${r.chainId}`,
+        `- specCardId=${r.specCardId}`,
+        firstCardLine,
+        '- 铁律：回复中的 ch_/sc_/t_ 编号只能逐字复制自本结果；禁止出现本结果之外的任何编号；禁止声称与本结果矛盾的建卡状态。',
+    ].join('\n');
+}
 // 清单获取只有两条路：内存（路由1）> KB 候选页（路由2，LLM 读页重建）。禁止编造其他原因
 // （"先重试 / 查服务进程是否重启"类诊断是噪声：内存丢失唯一成因是插件重启，重启后按两条路恢复即可）。
 const RECOVERY_KB_GUIDANCE = (routes, candidates) => `
@@ -28,7 +50,7 @@ const RECOVERY_KB_GUIDANCE = (routes, candidates) => `
 ${candidates.map((c) => '- ' + c).join('\n')}
 恢复步骤（严格顺序）：
 1. 读取候选页内容，对照当前需求判定哪一页是本次需求的需求澄清清单（页首行标题为「# 【需求】<需求名>」）；
-2. 消化该页内容，重建结构化 PlanningChecklist（spec 六段 + manifest + clarifications + doubts，requirementName 取页标题中【需求】后的名称）；
+2. 消化该页内容，重建结构化 PlanningChecklist（spec 六段 + manifest + clarifications + doubts + risks（风险点，若有），requirementName 取页标题中【需求】后的名称；恢复重建时 clarifications 允许登记单条无澄清说明，如 {"q": "本轮无澄清（恢复重建）", "a": "<来源页或原因>"}，其余场景 clarifications 禁止为空）；
 3. 调 planning_checklist_save(checklist, restoreRef=<该候选页路径>) 回存（覆盖原页，勿产生重复页）；
 4. 回存成功后提示用户重新发送 ${routes.openspec} 确认。
 禁止：跳过恢复直接建链建卡；猜测清单内容；把恢复失败归因于"重试/进程检查"之外的任何原因。
@@ -89,7 +111,7 @@ export function buildSpawnPrefetch(ctx) {
 /** v2 主会话工具面：/plan: 捕获规划上下文（零副作用）→ planning_checklist_save 回写 → /openspec: 用清单建链。
  *  工具面 = kanban_route + 只读 kanban 子集 + spec_card_view + planning 工具；
  *  无 spec_card_edit/approve、无 kanban_create/complete/block（主会话越权写由工具面裁剪 + prefetch 子代理只读护栏双保险）。 */
-export function registerMainSessionTools(ctx, config) {
+export function registerMainSessionTools(ctx, configProvider) {
     const registry = ctx.get('tools');
     if (!registry)
         return; // 测试裸 Context 无 tools 服务（P1-9 无 inject 依赖），跳过注册
@@ -97,9 +119,13 @@ export function registerMainSessionTools(ctx, config) {
     if (!provider)
         return;
     const service = provider.service;
-    // 生产 wiring（src/index.ts:44）仅保证 tools+kanban 可用，无 wiki 服务 → 用 config.wikiVault 自建
-    //（与 dispatcher 构造同源）；测试经 ctx.get('wiki') 注入 mock 客户端。
-    const wiki = ctx.get('wiki') ?? new WikiVaultClient(config.wikiVault);
+    // 生产 wiring（src/index.ts）仅保证 tools+kanban 可用，无 wiki 服务 → 经 configProvider 自建
+    //（与 dispatcher 构造同源，getEffective() 调用时热读取 baseUrl/pagePrefix）；测试经 ctx.get('wiki') 注入 mock 客户端。
+    // D3 双模式：local 模式走 LocalWikiClient 本地检索（不发 HTTP），remote 用配置的 WikiVaultClient。
+    const kbMode = configProvider.mode;
+    const wiki = kbMode === 'local'
+        ? new LocalWikiClient(ensureLocalKbRoot())
+        : (ctx.get('wiki') ?? new WikiVaultClient(() => configProvider.getEffective().wikiVault));
     const caller = () => ({ actor: 'human' });
     // 只读 kanban 子集（无 create/complete/block）
     const readOnly = new Set(['kanban_show', 'kanban_chain', 'kanban_list', 'kanban_comment']);
@@ -115,13 +141,15 @@ export function registerMainSessionTools(ctx, config) {
     }
     // planning 工具（清单落库 + 只读预取）——spawnPrefetch 由模块级 buildSpawnPrefetch 提供（可单测）
     for (const tool of buildPlanningTools({
-        service, wiki,
+        service, wiki: wiki, // local 模式为 LocalWikiClient（write/read/search 同面，D3 双模式客户端）
         getCaller: caller,
         spawnPrefetch: buildSpawnPrefetch(ctx),
         tempDir: () => `${tmpdir()}/dsh-swarm-checklists`, // KB 不可达时的临时兜底，放系统临时目录（不落插件源码/核心存储目录）
-        pagePrefix: config.wikiVault?.pagePrefix ?? 'projects/', // 生成的清单页路径保持在该客户端配置的命名空间内（避免 kb-rejected）
-        prefixRoutes: config.prefixRoutes,
-        memoryEnabled: config.memory?.enabled ?? true,
+        pagePrefix: configProvider.getEffective().wikiVault?.pagePrefix ?? 'projects/', // 生成的清单页路径保持在该客户端配置的命名空间内（避免 kb-rejected）
+        kbMode: configProvider.mode, // D3 双模式：local 时 checklist/learning 落本地库命名空间（wiki/queries/checklists/、wiki/synthesis/learnings/）
+        prefixRoutes: configProvider.getEffective().prefixRoutes,
+        memoryEnabled: configProvider.getEffective().memory?.enabled ?? true,
+        resolveWorkspaceDir: () => planningBySession.get('session_main')?.workspaceDir ?? null,
         ownerSessionId: 'session_main',
         onChecklistSaved({ ref, source, checklist }) {
             const cur = planningBySession.get('session_main') ?? { workspaceDir: null, sessionId: 'session_main', checklist: null, checklistRef: null, checklistSource: null, requirementName: null };
@@ -129,8 +157,8 @@ export function registerMainSessionTools(ctx, config) {
         },
     }))
         registry.register(tool);
-    // kanban_route：/plan: 捕获规划上下文；/openspec: 用清单建链
-    const { plan, openspec, learning } = config.prefixRoutes;
+    // kanban_route：/plan: 捕获规划上下文；/openspec: 用清单建链（前缀路由注册时快照，用于工具描述）
+    const { plan, openspec, learning } = configProvider.getEffective().prefixRoutes;
     registry.register(defineTool({
         name: 'kanban_route',
         description: `MUST be called when the human message starts with ${plan}, ${openspec}, or ${learning}. This is dsh-swarm planning, NOT the built-in /plan plan mode. ${plan} = zero side-effect + start grill-me (+ auto KB memory index); ${openspec} = create chain from saved checklist; ${learning} = distill experience from a chain (evidence pack + planning_learning_save).`,
@@ -140,17 +168,18 @@ export function registerMainSessionTools(ctx, config) {
             // M2(Q5)+归组：仅 /plan: 分支捕获主 agent 工作空间并可能询问注册——/openspec:/none 不触发，
             // 避免死代码副作用多弹一次 ask（/openspec: 实际用的是 planningBySession 已存的 workspaceDir）。
             // header.cwd 缺失或未注册时询问用户注册工作区；仍不可得保持 null（链任务随后 block 'workspace-unknown'）。
-            const plan = await handlePlanRoute(args.message, service, config.prefixRoutes, 'session_main');
+            const plan = await handlePlanRoute(args.message, service, configProvider.getEffective().prefixRoutes, 'session_main');
             if (plan.kind === 'plan') {
                 const headerCwd = exec?.agent?.session?.header?.cwd ?? null;
                 const workspaceDir = await resolveOrCreateWorkspace(ctx, headerCwd, '主 agent 会话');
                 planningBySession.set('session_main', { workspaceDir, sessionId: 'session_main', checklist: null, checklistRef: null, checklistSource: null, requirementName: plan.rest });
-                let guidance = buildPlanningGuidance(config.prefixRoutes) + KANBAN_HANDOFF_RULE(config.prefixRoutes);
-                if ((config.memory?.enabled ?? true) && workspaceDir) {
+                let guidance = buildPlanningGuidance(configProvider.getEffective().prefixRoutes) + KANBAN_HANDOFF_RULE(configProvider.getEffective().prefixRoutes);
+                if ((configProvider.getEffective().memory?.enabled ?? true) && workspaceDir) {
                     const idx = await recallMemoryIndex(wiki, {
                         requirementName: plan.rest || null,
                         workspaceDir,
-                        maxEntries: config.memory?.maxIndexEntries ?? 8,
+                        maxEntries: configProvider.getEffective().memory?.maxIndexEntries ?? 8,
+                        kbMode,
                     });
                     if (idx)
                         guidance += '\n' + idx;
@@ -158,7 +187,7 @@ export function registerMainSessionTools(ctx, config) {
                 return { kind: 'plan', guidance };
             }
             if (plan.kind === 'learning') {
-                const r = await handleLearningRoute(args.message, service, config.prefixRoutes, 'session_main');
+                const r = await handleLearningRoute(args.message, service, configProvider.getEffective().prefixRoutes, 'session_main');
                 if (r.error)
                     return { kind: 'learning', error: r.error, guidance: r.guidance };
                 return { kind: 'learning', chainId: r.chainId, brief: r.brief, guidance: r.guidance };
@@ -168,21 +197,59 @@ export function registerMainSessionTools(ctx, config) {
             // 路由1（内存）：planningBySession 命中 → 直接建链
             const pctx = planningBySession.get('session_main');
             if (pctx?.checklist && pctx.checklistRef) {
+                // 恢复补捕①：内存有清单但 workspaceDir=null（主 agent 重启后清单经 KB 恢复、异常态）→
+                // 从 exec.agent.session.header.cwd 捡回工作区，路由1 继续正常建链。已有值绝不重解析
+                // （不重复弹 ask，对齐下方 /plan: 分支注释顾虑）；解析 null（无 cwd/无通道/用户跳过）保持
+                // 现状 → 走 handleOpenspecRoute 的 workspace-unknown fail-fast（不吞错、不猜测路径）。
+                if (!pctx.workspaceDir) {
+                    const headerCwd = exec?.agent?.session?.header?.cwd ?? null;
+                    const workspaceDir = await resolveOrCreateWorkspace(ctx, headerCwd, '主 agent 会话（/openspec: 恢复）');
+                    if (workspaceDir) {
+                        pctx.workspaceDir = workspaceDir;
+                        planningBySession.set('session_main', pctx);
+                    }
+                }
+                // 闸2：清单落库的仓库与当前工作区不一致 → 硬拦不建链（KB 页路径带 repoSlug 维度的前提是链与工作区同源）
+                const localPath = pctx.checklist.manifest.repo.localPath;
+                if (pctx.workspaceDir && localPath !== pctx.workspaceDir) {
+                    return {
+                        kind: 'openspec', approved: false, reason: 'workspace-mismatch',
+                        error: `[workspace-mismatch] 清单 manifest.repo.localPath (${localPath}) 与当前工作区 (${pctx.workspaceDir}) 不一致。请在目标仓库工作区内重新执行 ${configProvider.getEffective().prefixRoutes.plan} 重新澄清落库后再 ${configProvider.getEffective().prefixRoutes.openspec}（不可跳过）。`,
+                    };
+                }
                 const input = { workspaceDir: pctx.workspaceDir, checklist: pctx.checklist, checklistRef: pctx.checklistRef, requirementName: pctx.requirementName };
-                const r = await handleOpenspecRoute(args.message, service, config.prefixRoutes, input, 'session_main');
-                return { kind: 'openspec', chainId: r.chainId, specCardId: r.specCardId, approved: true, guidance: KANBAN_HANDOFF_RULE(config.prefixRoutes) };
+                const r = await handleOpenspecRoute(args.message, service, configProvider.getEffective().prefixRoutes, input, 'session_main');
+                // 护栏拦截（如 workspace-unknown）：透传失败原因与恢复指引，不得伪装成建链成功
+                if (r.approved === false || !r.chainId || !r.specCardId) {
+                    return { kind: 'openspec', approved: false, reason: r.reason ?? 'unknown', guidance: r.guidance };
+                }
+                return {
+                    kind: 'openspec', chainId: r.chainId, specCardId: r.specCardId, approved: true, firstCard: r.firstCard,
+                    guidance: KANBAN_HANDOFF_RULE(configProvider.getEffective().prefixRoutes) + '\n\n' + buildOpenspecNarrationRule({ chainId: r.chainId, specCardId: r.specCardId, firstCard: r.firstCard }),
+                };
             }
             // 路由2（知识库）：内存丢失（插件重启）→ 搜 KB 候选清单页供 LLM 读页重建；搜不到/不可达 → 两条路皆空
+            // 恢复补捕②：无内存条目或工作区未捕获 → 从 header.cwd 捡回，写入 planningBySession（checklist 等
+            // 字段保持 cur 或空缺省），后续 planning_checklist_save 触发 onChecklistSaved 的 { ...cur } 展开自然
+            // 带上 workspaceDir。解析失败不阻塞恢复 guidance 返回（行为同现状，只是少捕一次）。
+            if (!planningBySession.get('session_main')?.workspaceDir) {
+                const headerCwd = exec?.agent?.session?.header?.cwd ?? null;
+                const workspaceDir = await resolveOrCreateWorkspace(ctx, headerCwd, '主 agent 会话（/openspec: 恢复）');
+                if (workspaceDir) {
+                    const cur = planningBySession.get('session_main') ?? { workspaceDir: null, sessionId: 'session_main', checklist: null, checklistRef: null, checklistSource: null, requirementName: null };
+                    planningBySession.set('session_main', { ...cur, workspaceDir });
+                }
+            }
             let candidates = [];
             try {
-                candidates = await searchChecklists(wiki, config.wikiVault?.pagePrefix ?? 'projects/');
+                candidates = await searchChecklists(wiki, kbMode === 'local' ? LOCAL_CHECKLIST_PREFIX : (configProvider.getEffective().wikiVault?.pagePrefix ?? 'projects/'));
             }
             catch { /* KB 不可达/搜索失败 → 候选为空，走两条路皆空分支 */ }
             return {
                 kind: 'openspec', approved: false, reason: 'no-checklist',
                 recovery: candidates.length > 0 ? 'kb' : 'none',
                 checklistCandidates: candidates,
-                guidance: candidates.length > 0 ? RECOVERY_KB_GUIDANCE(config.prefixRoutes, candidates) : RECOVERY_NONE_GUIDANCE(config.prefixRoutes),
+                guidance: candidates.length > 0 ? RECOVERY_KB_GUIDANCE(configProvider.getEffective().prefixRoutes, candidates) : RECOVERY_NONE_GUIDANCE(configProvider.getEffective().prefixRoutes),
             };
         },
     }));

package/lib/tools/planning-tools.d.ts

@@ -20,6 +20,8 @@ export interface PlanningToolDeps {
     spawnPrefetch?(prompt: string, workspaceDir: string, parentAgent?: Agent, signal?: AbortSignal): Promise<string>;
     tempDir(): string;
     pagePrefix?: string;
+    /** KB 双模式（D3）：local 时 checklist/learning 落本地库命名空间（wiki/queries/checklists/、wiki/synthesis/learnings/），缺省 remote。 */
+    kbMode?: 'remote' | 'local';
     ownerSessionId?: string;
     /** 斜杠命令前缀路由（决策12 单一事实源），用于 description 文案派生。 */
     prefixRoutes: PrefixRoutes;
@@ -32,6 +34,8 @@ export interface PlanningToolDeps {
     }): void;
     /** memory.enabled；false 时 planning_memory_recall 返回 disabled 提示（planning_learning_save 不受影响）。 */
     memoryEnabled?: boolean;
+    /** 闸1：/plan: 捕获的当前工作区（main-session-tools 注入）；非 null 且与清单 localPath 不一致 → 阻断落库。 */
+    resolveWorkspaceDir?: () => string | null;
 }
 /** 主 agent 规划期工具：需求澄清清单落库（KB 优先/临时目录兜底）+ 只读仓库预取（子代理）。 */
 export declare function buildPlanningTools(deps: PlanningToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/tools/planning-tools.js

@@ -1,19 +1,24 @@
 // src/tools/planning-tools.ts
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 import { validatePlanningChecklist, formatChecklistBody } from '../domain/planning-checklist.js';
 import { validatePrefetchManifest } from '../domain/prefetch-manifest.js';
-import { buildChecklistSlug, CHECKLIST_PAGE_PREFIX, assertAllowedWikiPagePath } from '../wiki/page-path.js';
+import { buildChecklistSlug, KB_PAGE_NAMESPACES_HINT, LOCAL_CHECKLIST_PREFIX, LOCAL_LEARNING_BASE, assertAllowedWikiPagePath, assertLocalKbPagePath } from '../wiki/page-path.js';
 import { validateLearning, formatLearningBody, buildRepoSlug } from '../domain/memory.js';
 const isWikiError = (e) => e instanceof Error && e.code === 'kb-unreachable';
 /** 主 agent 规划期工具：需求澄清清单落库（KB 优先/临时目录兜底）+ 只读仓库预取（子代理）。 */
 export function buildPlanningTools(deps) {
+    const local = deps.kbMode === 'local';
+    // checklist 前缀双模式（D3/D5）：remote → projects/<repoSlug>/checklists/（repoSlug 段在 pagePath 拼接，workspace 计划 T3）；
+    // local → wiki/queries/checklists/（local 时 LocalWikiClient.write 仅接受 wiki/** 相对路径，projects/ 会被 kb-rejected——I1 修复）
     const pagePrefix = deps.pagePrefix ?? 'projects/';
+    const checklistPrefix = local ? LOCAL_CHECKLIST_PREFIX : pagePrefix;
     const session = deps.ownerSessionId ?? 'session_main';
     return [
         defineTool({
             name: 'planning_checklist_save',
             description: 'Save the converged requirement-clarification checklist (structured schema) to KB, falling back to a temp dir if KB is unreachable. Returns ref/path + authoritative repo path. restoreRef (optional) = existing KB page path to overwrite in place (recovery path when in-memory context was lost); omit for first-time save (creates a new timestamped page).',
-            parameters: { checklist: { type: 'json', required: true, description: 'Structured PlanningChecklist: spec six sections + manifest(repo.files) + clarifications + doubts. checklist.requirementName (optional) = ' + deps.prefixRoutes.plan + ' rest first sentence, used for the checklist page title 【需求】, same source as the task-card title' }, restoreRef: { type: 'string', description: 'Optional KB page path to overwrite in place (recovery path); omit for new save' } },
+            parameters: { checklist: { type: 'json', required: true, description: 'Structured PlanningChecklist: {requirementName?, spec: {problem, solution, user_stories, impl_decisions, testing, out_of_scope}, manifest, clarifications, doubts: Array<{"q": string, "resolved": boolean, "answer"?: string}>, risks?}. spec.user_stories: array of plain strings — each element ONE sentence "As a <role>, I want <capability>, so that <benefit>"; NEVER objects/nested. spec.impl_decisions: array of plain strings — one decision per element; NEVER objects. clarifications: non-empty required — record every Q&A asked during this planning round; Array<{"q": string, "a": string}> with keys exactly "q"/"a" (NOT "question"/"answer"). risks (optional): Array<{"description": string, "source": string, "mitigation": string}> — register real risks/non-blocking concerns surfaced during clarification; omit or [] when none. checklist.requirementName (optional) = ' + deps.prefixRoutes.plan + ' rest first sentence, used for the checklist page title 【需求】, same source as the task-card title' }, restoreRef: { type: 'string', description: 'Optional KB page path to overwrite in place (recovery path); omit for new save' } },
             output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
             async execute(args) {
                 const caller = deps.getCaller();
@@ -23,9 +28,13 @@ export function buildPlanningTools(deps) {
                 if (errors.length > 0)
                     throw new Error('invalid planning checklist: ' + errors.join('; '));
                 const checklist = args.checklist;
+                const wsDir = deps.resolveWorkspaceDir?.() ?? null;
+                if (wsDir && checklist.manifest.repo.localPath !== wsDir) {
+                    throw new Error(`[workspace-mismatch] 清单 manifest.repo.localPath (${checklist.manifest.repo.localPath}) 与当前工作区 (${wsDir}) 不一致。请在目标仓库工作区内重新执行 ${deps.prefixRoutes.plan} 重新澄清落库（不可跳过）。`);
+                }
                 const body = formatChecklistBody(checklist);
                 // 恢复路径（内存丢失后重建）：传 restoreRef 则覆盖原页，不产生重复页
-                if (args.restoreRef && args.restoreRef.startsWith(pagePrefix)) {
+                if (args.restoreRef && args.restoreRef.startsWith(checklistPrefix)) {
                     try {
                         await deps.wiki.write(args.restoreRef, body);
                         deps.onChecklistSaved?.({ ref: args.restoreRef, source: 'kb', checklist });
@@ -37,7 +46,10 @@ export function buildPlanningTools(deps) {
                         // KB 不可达 → 落临时目录兜底（不覆盖原页），回调仍回填内存
                     }
                 }
-                const pagePath = `${CHECKLIST_PAGE_PREFIX}${buildChecklistSlug(checklist.requirementName ?? checklist.spec.problem)}-${Date.now().toString(36)}.md`;
+                const slug = buildChecklistSlug(checklist.requirementName ?? checklist.spec.problem);
+                const pagePath = local
+                    ? `${checklistPrefix}${slug}-${Date.now().toString(36)}.md`
+                    : `${pagePrefix}${buildRepoSlug(checklist.manifest.repo.localPath)}/checklists/${slug}-${Date.now().toString(36)}.md`;
                 try {
                     await deps.wiki.write(pagePath, body);
                     deps.onChecklistSaved?.({ ref: pagePath, source: 'kb', checklist });
@@ -86,7 +98,7 @@ export function buildPlanningTools(deps) {
         }),
         defineTool({
             name: 'planning_learning_save',
-            description: 'Save a distilled learning (experience) to the knowledge base. scope=chain → projects/<chainId>/learnings/ (requirement-level); scope=project → projects/<repoSlug>/learnings/ (repo-level, repoSlug derived from the chain workspaceDir). Returns ref. Soft-fails {ok:false,reason:"kb-unreachable"} when KB is unreachable (no temp fallback).',
+            description: 'Save a distilled learning (experience) to the knowledge base. Remote KB: scope=chain → projects/<repoSlug>/<chainId>/learnings/ (requirement-level); scope=project → projects/<repoSlug>/learnings/ (repo-level). repoSlug is derived from the chain workspaceDir; both scopes require chain.workspaceDir. Local KB: both scopes → wiki/synthesis/learnings/<chainId|repoSlug>/. Returns ref. Soft-fails {ok:false,reason:"kb-unreachable"} when KB is unreachable (no temp fallback).',
             parameters: {
                 learning: { type: 'json', required: true, description: 'LearningEntry: { title (≤80 chars), lesson, evidence (mechanical chain/task id — required), tags: string[] }' },
                 scope: { type: 'string', enum: ['chain', 'project'], required: true, description: '"chain" (requirement-level) | "project" (repo-level)' },
@@ -110,13 +122,23 @@ export function buildPlanningTools(deps) {
                     throw new Error('unknown chain: ' + args.chainId);
                 const entry = args.learning;
                 let prefix;
-                if (args.scope === 'chain') {
-                    prefix = `projects/${args.chainId}/learnings/`;
+                if (local) {
+                    // local（D5）：scope=chain 直接挂 chainId；scope=project 挂 repoSlug（需 workspaceDir）
+                    if (args.scope === 'chain') {
+                        prefix = `${LOCAL_LEARNING_BASE}${args.chainId}/`;
+                    }
+                    else {
+                        if (!chain.workspaceDir)
+                            throw new Error('scope=project requires chain.workspaceDir (target repo) — chain has none');
+                        prefix = `${LOCAL_LEARNING_BASE}${buildRepoSlug(chain.workspaceDir)}/`;
+                    }
                 }
                 else {
+                    // remote（workspace 计划 T3）：两 scope 均要求 chain.workspaceDir，统一挂 projects/<repoSlug>/
                     if (!chain.workspaceDir)
-                        throw new Error('scope=project requires chain.workspaceDir (target repo) — chain has none');
-                    prefix = `projects/${buildRepoSlug(chain.workspaceDir)}/learnings/`;
+                        throw new Error('learning save requires chain.workspaceDir (target repo) — chain has none');
+                    const wsRoot = `${pagePrefix}${buildRepoSlug(chain.workspaceDir)}/`;
+                    prefix = args.scope === 'chain' ? `${wsRoot}${args.chainId}/learnings/` : `${wsRoot}learnings/`;
                 }
                 const pagePath = `${prefix}${buildChecklistSlug(entry.title)}-${Date.now().toString(36)}.md`;
                 try {
@@ -132,9 +154,9 @@ export function buildPlanningTools(deps) {
         }),
         defineTool({
             name: 'planning_memory_recall',
-            description: 'Recall KB memory for planning. path mode: read a full page (whitelist: projects/checklists/, projects/learnings/, projects/<slug>/learnings/, projects/ch_*/learnings/, projects/ch_*/t_*.md, projects/ch_*/review/) truncated to 8000 chars. query mode: full-text search returning top 5 {path,title,score}. Returns {ok:false,reason:"kb-unreachable"} on KB failure; {ok:false,reason:"disabled"} when memory is disabled.',
+            description: 'Recall KB memory for planning. path mode: read a full page truncated to 8000 chars. path mode whitelist: remote = ' + KB_PAGE_NAMESPACES_HINT + '; local = any wiki/** relative path inside the local KB root. query mode: full-text search returning top 5 {path,title,score}. Returns {ok:false,reason:"kb-unreachable"} on KB failure; {ok:false,reason:"disabled"} when memory is disabled.',
             parameters: {
-                path: { type: 'string', description: 'KB page path to read in full (mutually exclusive with query)' },
+                path: { type: 'string', description: 'KB page path to read in full (mutually exclusive with query). remote mode: projects/ namespace path; local mode: wiki/** relative path inside the local KB root.' },
                 query: { type: 'string', description: 'Full-text query; returns top 5 result paths (mutually exclusive with path)' },
             },
             output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
@@ -149,7 +171,12 @@ export function buildPlanningTools(deps) {
                 if (hasPath === hasQuery)
                     throw new Error('provide exactly one of path|query');
                 if (hasPath) {
-                    assertAllowedWikiPagePath(args.path);
+                    // path 白名单按 KB 双模式分支（D3/D9）：remote → projects/** 命名空间；local → wiki/**（
+                    // Task 11 后 local 的 checklist/learning 全落 wiki/ 前缀，用 projects/ 白名单会把 local 读腿全拒）
+                    if (local)
+                        assertLocalKbPagePath(args.path);
+                    else
+                        assertAllowedWikiPagePath(args.path);
                     try {
                         const d = await deps.wiki.read(args.path);
                         const content = d.rawMd.length > 8000 ? d.rawMd.slice(0, 8000) + '…' : d.rawMd;

package/lib/tools/prefetch-tools.js

@@ -1,4 +1,5 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 import { can } from '../domain/permissions.js';
 function guard(action, caller) {
     if (!can(action, caller.actor, null))

package/lib/tools/spec-card-tools.js

@@ -1,4 +1,5 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 import { KanbanService } from '../domain/kanban-service.js';
 import { can } from '../domain/permissions.js';
 function guard(action, caller) {

package/lib/tools/wiki-tools.js

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 import { can } from '../domain/permissions.js';
-import { assertAllowedWikiPagePath } from '../wiki/page-path.js';
+import { assertAllowedWikiPagePath, KB_PAGE_NAMESPACES_HINT } from '../wiki/page-path.js';
 function guard(action, caller) {
     if (!can(action, caller.actor, null))
         throw new Error('permission denied: ' + action);
@@ -34,7 +35,7 @@ export function buildWikiTools(wiki, getCaller) {
         }),
         defineTool({
             name: 'wiki_write',
-            description: 'Write a wiki-vault page under the configured pagePrefix (W only).',
+            description: 'Write a wiki-vault page under projects/<repoSlug>/ namespaces (W only). pagePath must match: ' + KB_PAGE_NAMESPACES_HINT,
             parameters: {
                 pagePath: { type: 'string', required: true },
                 content: { type: 'string', required: true },
@@ -43,8 +44,8 @@ export function buildWikiTools(wiki, getCaller) {
             async execute(args) {
                 const caller = getCaller();
                 guard('wiki-write', caller);
-                // Q3&5：工具边界强校验——只允许 projects/checklists/、projects/ch_*/t_*.md、projects/ch_*/review/
-                // 三类命名空间（page-path.ts 白名单），杜绝 LLM 自造路径/拼错层级导致 kb_url 无法跳转。
+                // Q3&5：工具边界强校验——只允许 projects/<repoSlug>/ 白名单命名空间（KB_PAGE_NAMESPACES_HINT 五类，
+                // 见 page-path.ts），杜绝 LLM 自造路径/拼错层级导致 kb_url 无法跳转。
                 assertAllowedWikiPagePath(args.pagePath);
                 const out = await wiki.write(args.pagePath, args.content);
                 // Q4：工具直接拼完整 kb_url（host 用 config.wikiVault.baseUrl，杜绝 LLM 手写错域名）。

package/lib/wiki/kb-linkage.d.ts

@@ -1,9 +1,16 @@
-import type { WikiVaultClient } from './wiki-vault-client.js';
 import type { BoardState } from '../domain/types.js';
+/** kb-linkage 所需最小 wiki 面（WikiVaultClient / LocalWikiClient 均满足，D2 双模式客户端注入）。 */
+type KbWikiClient = {
+    read(pagePath: string): Promise<{
+        rawMd: string;
+    }>;
+    write(pagePath: string, content: string): Promise<unknown>;
+};
 /**
  * 机械互链登记：链上 w:kb 任务完成时调用。
  * - 清单页：追加/更新「关联文档」区块，列出链上全部已 done 的 W2/W3 页。
  * - 当前页：写回清单页链接（清单 ref 来自规格卡 kind:'kb' 附件）。
  * 幂等（containsLine / 区块就地替换）；任何 wiki 读/写失败均静默跳过，不抛错。
  */
-export declare function syncKbLinks(wiki: WikiVaultClient, state: BoardState, taskId: string): Promise<void>;
+export declare function syncKbLinks(wiki: KbWikiClient, state: BoardState, taskId: string): Promise<void>;
+export {};

package/lib/wiki/kb-linkage.js

@@ -49,9 +49,9 @@ export async function syncKbLinks(wiki, state, taskId) {
     if (!chain?.specCardId)
         return;
     const spec = state.specCards.get(chain.specCardId);
-    // 清单页 ref：kind:'kb' 附件；仅接受 projects/ 命名空间（临时目录兜底路径不是 KB 页，跳过）
+    // 清单页 ref：kind:'kb' 附件；接受 projects/（remote）或 wiki/（local）命名空间（临时目录兜底路径不是 KB 页，跳过）
     const checklistRef = spec?.attachments.find((a) => a.kind === 'kb')?.ref ?? null;
-    const checklistPath = checklistRef && checklistRef.startsWith('projects/') ? checklistRef : null;
+    const checklistPath = checklistRef && (checklistRef.startsWith('projects/') || checklistRef.startsWith('wiki/')) ? checklistRef : null;
     // 链上已 done 的 W2/W3 页（含当前任务所属页）
     const pages = [...state.tasks.values()]
         .filter((t) => t.chainId === task.chainId && t.assignee === 'w' && t.mode === 'kb' && t.status === 'done')
@@ -61,7 +61,7 @@ export async function syncKbLinks(wiki, state, taskId) {
             ? state.handoffs.get(t.id).metadata.page_path
             : null,
     }))
-        .filter((p) => p.pagePath !== null && p.pagePath.startsWith('projects/'));
+        .filter((p) => p.pagePath !== null && (p.pagePath.startsWith('projects/') || p.pagePath.startsWith('wiki/')));
     if (pages.length === 0)
         return;
     // 1) 清单页：登记全部 W2/W3 页链接

package/lib/wiki/local-kb-client.d.ts

@@ -0,0 +1,14 @@
+import { type WikiSearchResult } from './wiki-vault-client.js';
+export declare class LocalWikiClient {
+    readonly baseUrl = "";
+    readonly root: string;
+    constructor(root: string);
+    private abs;
+    write(pagePath: string, content: string): Promise<{
+        path: string;
+    }>;
+    read(pagePath: string): Promise<{
+        rawMd: string;
+    }>;
+    search(q: string): Promise<WikiSearchResult[]>;
+}

package/lib/wiki/local-kb-client.js

@@ -0,0 +1,101 @@
+// src/wiki/local-kb-client.ts
+// 本地 KB 客户端（llm-wiki 目录结构）：与 WikiVaultClient 同构的 search/read/write 面，
+// local 模式下替换注入（planning 工具 / kb-linkage / memory-recall 复用既有逻辑，零分支扩散）。
+// 排序原则 D12：相关性优先 7 : 新鲜度 3（0.7*scoreNorm + 0.3*mtimeNorm）。
+import { readdirSync, readFileSync, writeFileSync, mkdirSync, statSync, existsSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
+import { WikiError } from './wiki-vault-client.js';
+import { isInsideKbRoot } from './local-kb.js';
+import { assertLocalKbPagePath } from './page-path.js';
+export class LocalWikiClient {
+    baseUrl = '';
+    root;
+    constructor(root) { this.root = root; }
+    abs(pagePath) {
+        assertLocalKbPagePath(pagePath); // Task 1 白名单单一来源（wiki/**、拒 .. 与绝对路径），勿内联重复
+        const t = resolve(this.root, pagePath);
+        if (!isInsideKbRoot(this.root, t))
+            throw new WikiError('kb-rejected', undefined, `kb-rejected: path escapes local KB root: ${pagePath}`);
+        return t;
+    }
+    async write(pagePath, content) {
+        const t = this.abs(pagePath);
+        try {
+            mkdirSync(dirname(t), { recursive: true });
+            writeFileSync(t, content, 'utf8');
+        }
+        catch (err) {
+            // §9 降级链依赖：fs 失败归一 kb-unreachable（planning 工具按 code 判定 temp 兜底/软失败，审查 M5）
+            throw new WikiError('kb-unreachable', undefined, `kb-unreachable: local KB write failed: ${String(err)}`);
+        }
+        return { path: pagePath };
+    }
+    async read(pagePath) {
+        const t = this.abs(pagePath);
+        if (!existsSync(t))
+            throw new WikiError('kb-rejected', undefined, `kb-rejected: page not found: ${pagePath}`);
+        try {
+            return { rawMd: readFileSync(t, 'utf8') };
+        }
+        catch (err) {
+            throw new WikiError('kb-unreachable', undefined, `kb-unreachable: local KB read failed: ${String(err)}`);
+        }
+    }
+    async search(q) {
+        const needle = String(q ?? '').toLowerCase().trim();
+        if (!needle)
+            return [];
+        const hits = [];
+        const walk = (dir) => {
+            let entries = [];
+            try {
+                entries = readdirSync(dir);
+            }
+            catch {
+                return;
+            }
+            for (const e of entries) {
+                const p = join(dir, e);
+                const st = statSync(p);
+                if (st.isDirectory()) {
+                    walk(p);
+                    continue;
+                }
+                if (!e.endsWith('.md'))
+                    continue;
+                let text = '';
+                try {
+                    text = readFileSync(p, 'utf8');
+                }
+                catch {
+                    continue;
+                }
+                const lower = text.toLowerCase();
+                const n = lower.split(needle).length - 1;
+                if (n === 0)
+                    continue;
+                hits.push({
+                    path: p.slice(this.root.length + 1).split(sep).join('/'),
+                    title: text.split('\n')[0]?.replace(/^#\s*/, '').trim() || e,
+                    score: n,
+                    mtime: Math.floor(st.mtimeMs / 1000),
+                    hits: n,
+                });
+            }
+        };
+        walk(this.root);
+        if (hits.length === 0)
+            return [];
+        const maxHits = Math.max(...hits.map((h) => h.hits));
+        const times = hits.map((h) => h.mtime);
+        const minT = Math.min(...times);
+        const maxT = Math.max(...times);
+        const span = maxT - minT || 1;
+        return hits
+            .map((h) => ({
+            ...h,
+            score: Number((0.7 * (h.hits / maxHits) + 0.3 * ((h.mtime - minT) / span)).toFixed(4)),
+        }))
+            .sort((a, b) => b.score - a.score);
+    }
+}

package/lib/wiki/local-kb.d.ts

@@ -0,0 +1,6 @@
+export declare function localKbRoot(): string;
+/** 尽力创建库根（幂等）；失败由调用方告警 + block(kb-unreachable)（设计 §9）。 */
+export declare function ensureLocalKbRoot(root?: string): string;
+/** target 须为绝对路径且解析后落在 root 内（resolve 折叠重复斜杠；相对路径 fail-closed，
+ *  因为 bash/fs 里的相对目标语义属会话 cwd 而非库根，护栏不可猜测）。 */
+export declare function isInsideKbRoot(root: string, target: string): boolean;

package/lib/wiki/local-kb.js

@@ -0,0 +1,25 @@
+// src/wiki/local-kb.ts
+// 本地 KB（llm-wiki）库根工具（设计 D4：独立 <DSH_HOME>/storages/kanban/wiki/，隔离用户个人 ~/.llm-wiki-path）。
+import { homedir } from 'node:os';
+import { join, resolve, sep } from 'node:path';
+import { mkdirSync } from 'node:fs';
+export function localKbRoot() {
+    const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(dshHome, 'storages', 'kanban', 'wiki');
+}
+/** 尽力创建库根（幂等）；失败由调用方告警 + block(kb-unreachable)（设计 §9）。 */
+export function ensureLocalKbRoot(root = localKbRoot()) {
+    mkdirSync(root, { recursive: true });
+    return root;
+}
+/** target 须为绝对路径且解析后落在 root 内（resolve 折叠重复斜杠；相对路径 fail-closed，
+ *  因为 bash/fs 里的相对目标语义属会话 cwd 而非库根，护栏不可猜测）。 */
+export function isInsideKbRoot(root, target) {
+    if (!target)
+        return false;
+    // 相对路径 fail-closed：不与 root 拼接猜测（相对目标语义属会话 cwd）
+    if (resolve(target) !== target)
+        return false;
+    const r = resolve(root).replace(/\/+$/, '');
+    return resolve(target) === r || resolve(target).startsWith(r + sep);
+}

package/lib/wiki/memory-recall.d.ts

@@ -1,16 +1,24 @@
-import type { WikiVaultClient, WikiSearchResult } from './wiki-vault-client.js';
-export declare function recallLearningIndex(wiki: WikiVaultClient, opts: {
+import type { WikiSearchResult } from './wiki-vault-client.js';
+/** KB 客户端最小检索面（WikiVaultClient / LocalWikiClient 均满足）。 */
+type WikiSearchClient = {
+    search(q: string): Promise<WikiSearchResult[]>;
+};
+export declare function recallLearningIndex(wiki: WikiSearchClient, opts: {
     requirementName: string | null;
     workspaceDir: string | null;
+    kbMode?: 'remote' | 'local';
 }): Promise<WikiSearchResult[]>;
-export declare function recallDocIndex(wiki: WikiVaultClient, opts: {
+export declare function recallDocIndex(wiki: WikiSearchClient, opts: {
     requirementName: string | null;
     workspaceDir: string | null;
+    kbMode?: 'remote' | 'local';
 }): Promise<WikiSearchResult[]>;
-export declare function recallMemoryIndex(wiki: WikiVaultClient, opts: {
+export declare function recallMemoryIndex(wiki: WikiSearchClient, opts: {
     requirementName: string | null;
     workspaceDir: string | null;
     maxEntries: number;
+    kbMode?: 'remote' | 'local';
 }): Promise<string | null>;
-/** /openspec: 恢复路径复用：搜【需求】候选清单页（projects/ 前缀 top5）。 */
-export declare function searchChecklists(wiki: WikiVaultClient, pagePrefix?: string): Promise<string[]>;
+/** /openspec: 恢复路径复用：搜【需求】候选清单页（pagePrefix 前缀 top5；local 调用方传 wiki/queries/checklists/）。 */
+export declare function searchChecklists(wiki: WikiSearchClient, pagePrefix?: string): Promise<string[]>;
+export {};