@joekytc/dsh-swarm 0.1.0

package/lib/domain/kanban-service.js

@@ -0,0 +1,430 @@
+import { project, applyTo } from './projection.js';
+import { can } from './permissions.js';
+import { hasDeliveryEvidence, hasTddDeclaration } from './delivery-evidence.js';
+import { missingDeliveryKeys } from './delivery-contract.js';
+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 需求标题规范化）。 */
+export function firstSentence(text) {
+    const t = text.trim();
+    const cut = t.search(/[\n。？！]/);
+    const s = cut === -1 ? t : t.slice(0, cut);
+    return s.trim().slice(0, 40);
+}
+/** 默认链标题：【需求】<一句话需求描述>。来源优先级 /plan: rest 首句 → checklist.problem 首句 → 未命名需求。 */
+export function buildChainTitle(requirementName, _openspecRest, problem) {
+    const src = (requirementName && requirementName.trim()) || problem.trim();
+    return `【需求】${src ? firstSentence(src) : '未命名需求'}`;
+}
+/** 看板领域门面：三界面（工具/CLI/UI）统一路由的唯一入口。 */
+export class KanbanService {
+    state;
+    store;
+    // Q4：kb_url host 前缀硬校验基准（config.wikiVault.baseUrl）。null = 不校验前缀（兼容测试/旧调用）。
+    kbUrlBase;
+    emitQueue = Promise.resolve();
+    listeners = new Set();
+    // D23：链完成验收核对钩子（dispatcher 注入：读主会话事件/产物归属核对 → auditWarning）
+    onChainCompletedHook = null;
+    // Q3&5：W2/W3 完成互链登记钩子（dispatcher 注入：拿 page_path → 机械写三方互链，失败不阻塞完成）
+    onTaskCompletedHook = null;
+    constructor(store, kbUrlBase) {
+        this.store = store;
+        this.kbUrlBase = kbUrlBase ?? null;
+        // P0-3：同步重投影，消除"构造后立即调用基于空状态"的竞态
+        this.state = project(store.readAllSync());
+    }
+    async emit(ev) {
+        let emitted;
+        const pending = this.emitQueue.then(async () => {
+            const candidate = applyTo(this.state, { ...ev, seq: -1 });
+            const full = await this.store.append(ev);
+            this.state = { ...candidate, events: [...candidate.events.slice(0, -1), full] };
+            emitted = full;
+            this.publish(full);
+        });
+        this.emitQueue = pending.catch(() => { });
+        await pending;
+        return emitted;
+    }
+    /** D23：注入链完成核对钩子（由调度层设置；仅一个消费者）。 */
+    setOnChainCompleted(hook) {
+        this.onChainCompletedHook = hook;
+    }
+    /** Q3&5：注入任务完成互链登记钩子（由调度层设置；仅一个消费者）。 */
+    setOnTaskCompleted(hook) {
+        this.onTaskCompletedHook = hook;
+    }
+    /** T22：订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /** T22：返回 seq >= 入参 的事件（与 EventStore.readSince 同为 inclusive 语义）。 */
+    async eventsSince(seq) {
+        return this.store.readSince(seq);
+    }
+    publish(event) {
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                console.error('[dsh-swarm] event listener failed', error);
+            }
+        }
+    }
+    async chainOf(chainId) {
+        const c = this.state.chains.get(chainId);
+        if (!c)
+            throw new Error('unknown chain: ' + chainId);
+        return c;
+    }
+    async taskOf(taskId) {
+        const t = this.state.tasks.get(taskId);
+        if (!t)
+            throw new Error('unknown task: ' + taskId);
+        return t;
+    }
+    async createChain(input, actor) {
+        if (!can('create-chain', actor, null))
+            throw new Error('permission denied');
+        // 工具边界硬拦：空标题链不得入库
+        if (!input.title || !input.title.trim())
+            throw new Error('title required');
+        const chain = { id: nid('ch'), title: input.title, status: 'planning', rootTaskId: null, specCardId: null, ownerSessionId: input.ownerSessionId, workspaceDir: input.workspaceDir ?? null, createdAt: Date.now() };
+        await this.emit({ chainId: chain.id, taskId: null, kind: 'chain/created', payload: { ...chain }, author: actor, at: Date.now() });
+        return chain;
+    }
+    async createSpecCard(chainId, sections, actor) {
+        if (!can('spec-edit', actor, null))
+            throw new Error('permission denied');
+        const card = { id: nid('sc'), chainId, status: 'draft', sections, attachments: [], rawDialogueRef: null, approvedAt: null, approvedBy: null };
+        await this.emit({ chainId, taskId: null, kind: 'spec-card/created', payload: { ...card }, author: actor, at: Date.now() });
+        return card;
+    }
+    async editSpecCard(cardId, sections, actor) {
+        if (!can('spec-edit', actor, null))
+            throw new Error('permission denied');
+        const card = this.state.specCards.get(cardId);
+        if (!card || card.status !== 'draft')
+            throw new Error('spec card not editable');
+        const updated = { ...card, sections };
+        await this.emit({ chainId: card.chainId, taskId: null, kind: 'spec-card/edited', payload: { ...updated }, author: actor, at: Date.now() });
+        return updated;
+    }
+    async approveSpecCard(cardId, actor) {
+        if (!can('spec-approve', actor, null))
+            throw new Error('permission denied');
+        const card = this.state.specCards.get(cardId);
+        if (!card)
+            throw new Error('unknown spec card: ' + cardId);
+        await this.emit({ chainId: card.chainId, taskId: null, kind: 'spec-card/approved', payload: { id: cardId }, author: actor, at: Date.now() });
+        const updated = this.state.specCards.get(cardId);
+        // 规格卡批准 → 链路进入 executing（语义正确的事件：chain/executing）
+        await this.emit({ chainId: card.chainId, taskId: null, kind: 'chain/executing', payload: {}, author: actor, at: Date.now() });
+        return updated;
+    }
+    async createTask(input, actor) {
+        if (!can('create-task', actor, null))
+            throw new Error('permission denied');
+        // 工具边界硬拦：provided must be legal——空标题卡不得入库（GUI 曾现空标题链/卡）
+        if (!input.title || !input.title.trim())
+            throw new Error('title required');
+        const chain = await this.chainOf(input.chainId);
+        const explicitParents = input.parents && input.parents.length > 0;
+        // P0 硬拦（防御纵深）：调用方未显式指定 parents（V 建全新阶段卡）时，按语义依赖查上游非终态——
+        // 上游卡还卡着/未走完则拒绝建卡（防「P blocked 后仍建 PT」类事故）。显式 parents 的调用
+        // （复审卡 parents=[rework.id]、createReworkTask）由调用方决定接链，不在此拦。
+        if (!explicitParents) {
+            const blockers = nonTerminalSemanticParents(this.state.tasks.values(), input.chainId, input.assignee, input.mode);
+            if (blockers.length > 0) {
+                const b = blockers.map((t) => `${t.assignee}/${t.mode}(${t.id}, ${t.status})`).join(', ');
+                throw new Error(`create-task rejected: 上游 ${b} 未终态，下游 ${input.assignee}/${input.mode} 卡不能创建`);
+            }
+        }
+        // 语义 parents 兜底：调用方（V 建卡）未显式指定 parents 时，按 R20 依赖自动接链上终态父任务，
+        // 保证「父交接注入」通道闭合（如 w2 接 P、dt 接 d）。兜底对已显式传 parents 的
+        // 调用（复审卡 parents=[rework.id]、createReworkTask）不生效。
+        const parents = input.parents && input.parents.length > 0
+            ? input.parents
+            : resolveTaskParents(this.state.tasks.values(), input.chainId, input.assignee, input.mode);
+        const task = { id: nid('t'), chainId: input.chainId, title: input.title, body: input.body ?? '', assignee: input.assignee, status: 'todo', mode: input.mode, priority: 1, parents, children: [], createdBy: actor === 'human' ? 'human' : 'v', attempts: 0, heartbeats: [], sessionId: '', reworkOfTaskId: null, resumeSessionId: null, reviewAttempt: input.reviewAttempt ?? 0, reviewStatus: 'not-required' };
+        task.sessionId = 'kbn-' + task.id; // 确定性会话 id：与角色会话 id 一致，供追踪定位与 resume
+        await this.emit({ chainId: input.chainId, taskId: task.id, kind: 'task/created', payload: { ...task }, author: actor, at: Date.now() });
+        if (chain.rootTaskId === null) {
+            await this.emit({ chainId: input.chainId, taskId: task.id, kind: 'chain/root-task-set', payload: { rootTaskId: task.id }, author: actor, at: Date.now() });
+        }
+        return task;
+    }
+    async claimTask(taskId, actor) {
+        if (!can('claim', actor, null))
+            throw new Error('permission denied');
+        const t = this.state.tasks.get(taskId);
+        if (!t)
+            throw new Error('unknown task: ' + taskId);
+        await this.emit({ chainId: t.chainId, taskId, kind: 'task/claimed', payload: {}, author: actor, at: Date.now() });
+        return this.state.tasks.get(taskId);
+    }
+    async completeTask(taskId, handoff, actor, opts = {}) {
+        const t = this.state.tasks.get(taskId);
+        if (!t)
+            throw new Error('unknown task: ' + taskId);
+        if (!can('complete', actor, t, opts))
+            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 链完成门禁仍会拦截无证据链。
+        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）。
+        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 } }');
+        }
+        // 评审证据闸：PT/DT 完成必须带机械校验合法的 review_evidence（缺证据拒绝 pass）。
+        // human 为信任锚（GUI 强制收尾）可豁免。
+        if ((t.assignee === 'pt' || t.assignee === 'dt') && actor !== 'human') {
+            const missing = validateReviewEvidence(t.assignee === 'pt' ? 'pt' : 'dt', handoff);
+            if (missing.length > 0) {
+                throw new Error('review evidence required: ' + missing.join(', '));
+            }
+        }
+        // 交付契约闸（上游对下游负责）：W/P 完成必须带其阶段交付物（W2-W3 kb_url+page_path /
+        // P artifacts_path + pt_decision）。缺失交付物 → 直接 kanban_block（running→blocked 标在缺交付的「当前角色」卡上），
+        // 而非仅报错留 running 等下游（如 D 读 W2 的 page_path）执行时才暴露断裂。blocked ≠ done，V 的
+        // resolveTaskParents 只取 done/archived 父卡，故 V 永远不会拿该父卡推进建下游卡；task/blocked 事件
+        // 同时唤醒 V 走其阻塞复核。与 D(execute)/PT/DT 证据闸不同：交付键是下游硬依赖的机械非空字符串，
+        // 无「human 信任锚强制收尾」豁免——human 强制收尾同样必须补齐交付键，否则 W/P 卡直接 blocked，
+        // 从源头杜绝 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);
+            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(', '));
+            }
+        }
+        // v2 断代：w:file 交付键随旧 w1 预取阶段移除，manifest 校验块同步删除
+        // （validatePrefetchManifest 仍保留于 prefetch-manifest.ts，供清单 schema 校验复用）。
+        await this.emit({ chainId: t.chainId, taskId, kind: 'task/completed', payload: { ...handoff }, author: actor, at: Date.now() });
+        // Q3&5：W2/W3 完成 → 调度层互链登记（拿 page_path 机械写三方互链）。
+        // 仅 w:kb 触发（P/D/PT/DT 不涉 KB 页互链）；钩子内异常不阻断 completeTask（登记失败仅记 warning）。
+        if (t.assignee === 'w' && t.mode === 'kb' && this.onTaskCompletedHook) {
+            try {
+                await this.onTaskCompletedHook(taskId);
+            }
+            catch (error) {
+                console.error('[dsh-swarm] task completion linkage hook failed: ' + String(error));
+            }
+        }
+        // P0-3 链完成机械规则：仅当「最后完成的执行任务是 W3（w/kb）且链上 D(execute) 已 done 且
+        // 交付物证据满足（changed_files + commit/push）」且无未终态任务时 → 链 completed（不靠 agent 自觉）。
+        // 收紧判据：中间阶段（如 P done 后 W2 尚未创建）无未终态任务也不得误收链。
+        // C1：D(execute) 无产物证据 → 不判链完成（human 强制 complete 的 D 卡同样被拦截，防漂移被掩盖）。
+        // 'align' 为旧链路兼容（只读对齐/校验语义已废弃，R20 起新卡一律 '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);
+        const openTasks = chainTasks.filter((x) => !terminal.includes(x.status));
+        const dTask = chainTasks.find((x) => (x.mode === 'execute' || x.mode === 'align') && x.status === 'done');
+        const dDone = !!dTask;
+        const dEvidenceOk = dTask ? (dTask.mode === 'align' ? true : hasDeliveryEvidence(this.state.handoffs.get(dTask.id))) : false;
+        const completedEvents = this.state.events.filter((e) => e.chainId === t.chainId && e.kind === 'task/completed' && e.taskId);
+        const lastTask = completedEvents.length ? this.state.tasks.get(completedEvents[completedEvents.length - 1].taskId) : undefined;
+        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）。
+            // 钩子内异常不阻断 completeTask 本身（核对失败仅记录，链路仍 completed）。
+            if (this.onChainCompletedHook) {
+                try {
+                    await this.onChainCompletedHook(t.chainId);
+                }
+                catch (error) {
+                    console.error('[dsh-swarm] chain completion audit hook failed: ' + String(error));
+                }
+            }
+        }
+        return this.state.tasks.get(taskId);
+    }
+    /** D23：链完成验收核对发警告（仅 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）。放行最终汇报。 */
+    async confirmAudit(chainId, actor) {
+        if (!can('audit-confirm', actor, null))
+            throw new Error('permission denied');
+        await this.chainOf(chainId);
+        const audit = this.state.auditWarnings.get(chainId);
+        if (!audit)
+            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 事件（非状态转换）。 */
+    async updateChainTitle(chainId, title, actor) {
+        if (!can('update-title', actor, null))
+            throw new Error('permission denied');
+        const chain = await this.chainOf(chainId);
+        const next = title.trim();
+        if (!next)
+            throw new Error('title required');
+        if (next.length > 60)
+            throw new Error('title too long');
+        await this.emit({ chainId, taskId: chain.rootTaskId, kind: 'chain/title-updated', payload: { from: chain.title, to: next }, author: actor, at: Date.now() });
+        return { ...chain, title: next };
+    }
+    /** 整链硬删除（含其下全部角色卡/规格卡事件；仅 human，GUI 二次确认）。物理 purge 事件行，不可恢复。 */
+    async deleteChain(chainId, actor) {
+        if (!can('delete-chain', actor, null))
+            throw new Error('permission denied');
+        await this.chainOf(chainId); // 不存在则 throw
+        if (!this.store.purge)
+            throw new Error('event store does not support purge');
+        await this.store.purge((ev) => ev.chainId === chainId);
+        this.state = project(this.store.readAllSync());
+    }
+    async renameTask(taskId, title, actor) {
+        if (!can('update-title', actor, null))
+            throw new Error('permission denied');
+        const task = await this.taskOf(taskId);
+        const next = title.trim();
+        if (!next)
+            throw new Error('title required');
+        if (next.length > 60)
+            throw new Error('title too long');
+        await this.emit({ chainId: task.chainId, taskId, kind: 'task/renamed', payload: { from: task.title, to: next }, author: actor, at: Date.now() });
+        return { ...task, title: next };
+    }
+    async blockTask(taskId, reason, actor, opts = {}) {
+        const t = this.state.tasks.get(taskId);
+        if (!t)
+            throw new Error('unknown task: ' + taskId);
+        if (!can('block', actor, t, opts))
+            throw new Error('permission denied');
+        if (!reason.trim())
+            throw new Error('block reason required');
+        await this.emit({ chainId: t.chainId, taskId, kind: 'task/blocked', payload: { reason }, author: actor, at: Date.now() });
+        return this.state.tasks.get(taskId);
+    }
+    async unblockTask(taskId, actor) {
+        const t = this.state.tasks.get(taskId);
+        if (!t)
+            throw new Error('unknown task: ' + taskId);
+        if (!can('unblock', actor, t))
+            throw new Error('permission denied');
+        await this.emit({ chainId: t.chainId, taskId, kind: 'task/unblocked', payload: {}, author: actor, at: Date.now() });
+        return this.state.tasks.get(taskId);
+    }
+    async heartbeat(taskId, actor, opts = {}) {
+        const t = this.state.tasks.get(taskId);
+        if (!t)
+            throw new Error('unknown task: ' + taskId);
+        if (!can('heartbeat', actor, t, opts))
+            throw new Error('permission denied');
+        await this.emit({ chainId: t.chainId, taskId, kind: 'task/heartbeat', payload: {}, author: actor, at: Date.now() });
+        return this.state.tasks.get(taskId);
+    }
+    /** 标记任务失败（runner 异常/心跳超时回收）；投影递增 attempts（infra 瞬时错误不计数）。重试由调度器重派。 */
+    async failTask(taskId, reason, actor, opts = {}) {
+        const t = this.state.tasks.get(taskId);
+        if (!t)
+            throw new Error('unknown task: ' + taskId);
+        if (actor !== 'system')
+            throw new Error('permission denied: only dispatcher may fail tasks');
+        if (!reason.trim())
+            throw new Error('fail reason required');
+        await this.emit({ chainId: t.chainId, taskId, kind: 'task/failed', payload: { reason, infra: opts.infra ?? false }, author: actor, at: Date.now() });
+        return this.state.tasks.get(taskId);
+    }
+    async comment(taskId, body, actor) {
+        const t = this.state.tasks.get(taskId);
+        if (!t)
+            throw new Error('unknown task: ' + taskId);
+        if (!can('comment', actor, t))
+            throw new Error('permission denied');
+        return this.emit({ chainId: t.chainId, taskId, kind: 'task/commented', payload: { body }, author: actor, at: Date.now() });
+    }
+    async archiveTask(taskId, actor) {
+        const t = this.state.tasks.get(taskId);
+        if (!t)
+            throw new Error('unknown task: ' + taskId);
+        if (!can('archive', actor, t))
+            throw new Error('permission denied');
+        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 上传）。 */
+    async addSpecCardAttachment(cardId, attachment, actor) {
+        const card = this.state.specCards.get(cardId);
+        if (!card)
+            throw new Error('unknown spec card: ' + cardId);
+        if (!can('spec-attach', actor, null))
+            throw new Error('permission denied');
+        if (card.status !== 'draft')
+            throw new Error('spec card not editable');
+        const updated = { ...card, attachments: [...card.attachments, attachment] };
+        await this.emit({ chainId: card.chainId, taskId: null, kind: 'spec-card/edited', payload: { ...updated }, author: actor, at: Date.now() });
+        return updated;
+    }
+    /** 评审事件（交付质量链）：recordReview 记录评审卡结论并更新被评审任务 reviewStatus。
+     *  actor 必须 system（V/角色不可伪造评审结论）；verdict=pass → review/passed，否则 review/failed。
+     *  投影（projection.ts）据事件更新 target.reviewStatus（passed/failed）。 */
+    async recordReview(reviewTaskId, targetTaskId, evidence, actor) {
+        if (actor !== 'system')
+            throw new Error('permission denied: only dispatcher may record review');
+        const t = this.state.tasks.get(targetTaskId);
+        if (!t)
+            throw new Error('unknown target task: ' + targetTaskId);
+        const kind = evidence.verdict === 'pass' ? 'review/passed' : 'review/failed';
+        return this.emit({ chainId: t.chainId, taskId: reviewTaskId, kind, payload: { reviewTaskId, targetTaskId, evidence }, author: actor, at: Date.now() });
+    }
+    /** 评审超限放弃：review/gave-up（含证据链信息）。仅 system。 */
+    async reviewGaveUp(reviewTaskId, targetTaskId, reason, actor) {
+        if (actor !== 'system')
+            throw new Error('permission denied: only dispatcher may give up review');
+        const t = this.state.tasks.get(targetTaskId);
+        if (!t)
+            throw new Error('unknown target task: ' + targetTaskId);
+        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 建返工卡。 */
+    async createReworkTask(input, actor) {
+        if (!can('create-rework-task', actor, null))
+            throw new Error('permission denied');
+        const source = this.state.tasks.get(input.sourceTaskId);
+        if (!source)
+            throw new Error('unknown source task: ' + input.sourceTaskId);
+        if (source.status !== 'done')
+            throw new Error('rework source must be done: ' + source.status);
+        const task = {
+            id: nid('t'), chainId: source.chainId, title: `[返工] ${source.title}`, body: source.body,
+            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,
+            reviewAttempt: source.reviewAttempt + 1, reviewStatus: 'pending',
+        };
+        task.sessionId = 'kbn-' + task.id;
+        await this.emit({ chainId: source.chainId, taskId: task.id, kind: 'task/created', payload: { ...task }, author: actor, at: Date.now() });
+        return task;
+    }
+    async snapshot() {
+        // P0-3：重投影为权威（事件日志是唯一事实源；非法转换在此抛错）
+        this.state = project(await this.store.readAll());
+        return this.state;
+    }
+    async listTasks(opts = {}) {
+        return [...this.state.tasks.values()].filter((t) => (opts.assignee === undefined || t.assignee === opts.assignee) &&
+            (opts.status === undefined || t.status === opts.status));
+    }
+}

package/lib/domain/permissions.d.ts

@@ -0,0 +1,7 @@
+import type { Role, Task } from './types.js';
+export type KanbanAction = 'create-task' | 'create-chain' | 'claim' | 'complete' | 'block' | 'unblock' | 'comment' | 'heartbeat' | 'archive' | 'spec-approve' | 'spec-edit' | 'spec-attach' | 'wiki-write' | 'wiki-read' | 'prefetch' | 'audit-confirm' | 'update-title' | 'delete-chain' | 'create-rework-task';
+export type Actor = Role | 'human' | 'system';
+export declare function can(action: KanbanAction, actor: Actor, task: Task | null, opts?: {
+    isOwnTask?: boolean;
+    boundTaskId?: string;
+}): boolean;

package/lib/domain/permissions.js

@@ -0,0 +1,54 @@
+export function can(action, actor, task, opts = {}) {
+    // P1-4：会话绑定——角色 agent 只能操作其被 spawn 绑定的任务（boundTaskId=AgentSessionRef.task_id）；
+    // 旧 own（仅查 assignee）允许"链上任意同角色任务"，属跨任务越权，已废弃。
+    const bound = opts.boundTaskId !== undefined && task !== null && opts.boundTaskId === task.id;
+    switch (action) {
+        case 'create-task':
+        case 'create-chain':
+            return actor === 'v' || actor === 'human';
+        case 'claim':
+            return actor === 'system';
+        case 'complete':
+            // 仅绑定该任务的 agent 会话（boundTaskId 匹配且角色=任务 assignee）、系统收尾，
+            // 或 human（GUI 强制收尾，T27：human 为信任锚，不算越权）；跨角色 bound 拒。
+            return actor === 'system' || actor === 'human' || (bound && actor === task.assignee);
+        case 'block':
+            return actor === 'system' || actor === 'human' || bound;
+        case 'heartbeat':
+            return bound;
+        case 'comment':
+            return true;
+        case 'unblock':
+            return actor === 'human';
+        case 'archive':
+            return actor === 'human' || actor === 'v';
+        case 'spec-approve':
+            return actor === 'human';
+        case 'spec-edit':
+            // P1-4：规格卡编辑仅 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 层再收窄路径）
+            return actor === 'w' || actor === 'dt';
+        case 'wiki-read':
+            // w/d 读 KB 正文；dt 需读 KB 校验（评审只读）；pt 无 wiki 工具面
+            return actor === 'w' || actor === 'd' || actor === 'dt';
+        case 'prefetch':
+            return actor === 'w';
+        case 'audit-confirm':
+            // D23：仅人类在 GUI 确认产物归属；system/角色均不可
+            return actor === 'human';
+        case 'update-title':
+            // T7：链/任务标题改名仅 human（GUI）；V/角色均不可（防角色伪造链/卡标题）
+            return actor === 'human';
+        case 'delete-chain':
+            // 整链硬删除仅 human（GUI 二次确认）；V/角色/system 均不可
+            return actor === 'human';
+        case 'create-rework-task':
+            // 评审失败返工卡创建：仅系统（V 建执行卡、system 建返工卡，防角色伪造返工链）
+            return actor === 'system';
+    }
+}

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

@@ -0,0 +1,22 @@
+import type { SpecCardSections } from './types.js';
+import { type PrefetchManifest } from './prefetch-manifest.js';
+export interface PlanningChecklist {
+    requirementName?: string;
+    spec: SpecCardSections;
+    manifest: PrefetchManifest;
+    clarifications: Array<{
+        q: string;
+        a: string;
+    }>;
+    doubts: Array<{
+        q: string;
+        resolved: boolean;
+        answer?: string;
+    }>;
+}
+/** 需求澄清清单 schema 硬校验：返回错误列表（空数组=合法）。清单缺段即拒绝保存（硬闸，主 agent 会话内修正）。 */
+export declare function validatePlanningChecklist(raw: unknown): string[];
+/** 需求澄清清单页标题：与任务卡 title 同源同逻辑（buildChainTitle），保证 KB 可检索。 */
+export declare function buildChecklistTitle(c: PlanningChecklist): string;
+/** 需求澄清清单落库 body：标题【需求】+ 各段可读 markdown（非裸 JSON）。KB 与临时目录两分支共用。 */
+export declare function formatChecklistBody(c: PlanningChecklist): string;

package/lib/domain/planning-checklist.js

@@ -0,0 +1,81 @@
+import { validatePrefetchManifest } from './prefetch-manifest.js';
+import { buildChainTitle } from './kanban-service.js';
+const STR_FIELDS = [
+    ['problem', 'problem'], ['solution', 'solution'], ['testing', 'testing'], ['out_of_scope', 'out_of_scope'],
+];
+const ARR_FIELDS = [['user_stories', 'user_stories'], ['impl_decisions', 'impl_decisions']];
+/** 需求澄清清单 schema 硬校验：返回错误列表（空数组=合法）。清单缺段即拒绝保存（硬闸，主 agent 会话内修正）。 */
+export function validatePlanningChecklist(raw) {
+    const errors = [];
+    if (typeof raw !== 'object' || raw === null)
+        return ['checklist must be an object'];
+    const c = raw;
+    // requirementName（可选）：存在则须为非空 string
+    if ('requirementName' in c && (typeof c['requirementName'] !== 'string' || !c['requirementName'].trim())) {
+        errors.push('checklist.requirementName must be a non-empty string when present');
+    }
+    // spec 六段
+    const spec = c['spec'];
+    if (typeof spec !== 'object' || spec === null) {
+        errors.push('checklist.spec required');
+    }
+    else {
+        for (const [label, key] of STR_FIELDS) {
+            if (typeof spec[key] !== 'string' || spec[key].trim().length === 0) {
+                errors.push(`checklist.spec.${label} must be a non-empty string (got: ${JSON.stringify(spec[key])})`);
+            }
+        }
+        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[]`);
+            }
+        }
+    }
+    // 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`);
+    }
+    return errors;
+}
+/** 需求澄清清单页标题：与任务卡 title 同源同逻辑（buildChainTitle），保证 KB 可检索。 */
+export function buildChecklistTitle(c) {
+    return buildChainTitle(c.requirementName ?? null, '', c.spec.problem);
+}
+/** 需求澄清清单落库 body：标题【需求】+ 各段可读 markdown（非裸 JSON）。KB 与临时目录两分支共用。 */
+export function formatChecklistBody(c) {
+    const { spec, manifest, clarifications, doubts } = c;
+    const lines = [`# ${buildChecklistTitle(c)}`, '## Spec', ''];
+    lines.push('### 问题描述 (problem)', spec.problem, '');
+    lines.push('### 解决方案 (solution)', spec.solution, '');
+    lines.push('### 用户故事 (user_stories)', ...spec.user_stories.map((u) => `- ${u}`), '');
+    lines.push('### 实现决策 (impl_decisions)', ...spec.impl_decisions.map((d) => `- ${d}`), '');
+    lines.push('### 测试计划 (testing)', spec.testing, '');
+    lines.push('### 范围外 (out_of_scope)', spec.out_of_scope, '');
+    lines.push('## Repo 事实 (manifest)', '');
+    const { repo, files } = manifest;
+    lines.push('- 本地路径: ' + repo.localPath);
+    if (repo.remoteUrl)
+        lines.push('- 远端仓库: ' + repo.remoteUrl);
+    if (repo.branch)
+        lines.push('- 当前分支: ' + repo.branch);
+    lines.push('- 未提交改动: ' + (repo.dirtyFiles.length ? repo.dirtyFiles.map((f) => `\`${f}\``).join(', ') : '无'));
+    lines.push('', '### 文件基线', '', '| 路径 | 期望 | 备注 |', '| --- | --- | --- |');
+    for (const f of files)
+        lines.push(`| ${f.path} | ${f.expected} | ${f.note ?? '-'} |`);
+    lines.push('', '## 澄清问答', '');
+    clarifications.forEach((qa, i) => {
+        lines.push(`### Q${i + 1}. ${qa.q}`, `- **A**: ${qa.a}`, '');
+    });
+    if (clarifications.length === 0)
+        lines.push('（无）', '');
+    lines.push('## 疑问点', '');
+    for (const d of doubts) {
+        lines.push(d.resolved ? `- [x] ${d.q}${d.answer ? ` — ${d.answer}` : ''}` : `- [ ] ${d.q}`);
+    }
+    if (doubts.length === 0)
+        lines.push('（无）');
+    return lines.join('\n').replace(/\n{3,}/g, '\n\n');
+}

package/lib/domain/prefetch-manifest.d.ts

@@ -0,0 +1,21 @@
+import type { ObjectJsonSchema } from '@deepseek-ai/dsh-tools';
+export interface PrefetchFileEntry {
+    path: string;
+    expected: 'exists' | 'absent' | 'content-hash';
+    note?: string;
+}
+export interface PrefetchManifest {
+    repo: {
+        localPath: string;
+        remoteUrl?: string;
+        branch?: string;
+        dirtyFiles: string[];
+    };
+    files: PrefetchFileEntry[];
+}
+/** prefetch 子代理结构化输出的 JSON Schema（经 ctx.subagents.start 的 outputSchema 传入，
+ *  由 spawn provider 在子代理侧强制校验；assertObjectJsonSchema 强制子集内：
+ *  type/properties/required/items/enum/additionalProperties）。与 validatePrefetchManifest 同源同语义。 */
+export declare const PREFETCH_MANIFEST_SCHEMA: ObjectJsonSchema;
+/** 需求澄清清单 manifest schema 校验（planning-checklist 复用本 schema）：返回错误列表（空数组 = 合法）。 */
+export declare function validatePrefetchManifest(raw: unknown): string[];