@joekytc/dsh-swarm 0.1.0

package/lib/dispatcher/workspace-attach.js

@@ -0,0 +1,112 @@
+import { SessionId } from '@deepseek-ai/dsh-session';
+const ASK_TIMEOUT_MS = 120_000;
+function getWs(ctx) {
+    return ctx.get?.('workspaceRegistry');
+}
+function getUq(ctx) {
+    return ctx.get?.('userQuestions');
+}
+/** 询问用户注册工作区（超时护栏，与 requestRepoPermission 一致）。返回选定路径或 null。 */
+async function askWorkspace(uq, cwd, label) {
+    try {
+        const options = cwd
+            ? [{ label: '创建', description: '注册 ' + cwd + ' 为工作区并归组会话' }]
+            : [];
+        options.push({ label: '跳过', description: '保持 Ungrouped，不创建工作区' });
+        const ans = await Promise.race([
+            uq.ask({
+                questions: [{
+                        id: 'workspace-register',
+                        header: '工作区注册',
+                        question: cwd
+                            ? '会话工作目录 ' + cwd + '（' + label + '）未注册为 DSH 工作区。是否注册为工作区以归组角色会话？'
+                            : label + ' 未绑定工作区。请在 Other 中输入要注册为工作区的目录绝对路径，或选择跳过。',
+                        detail: '注册后角色/编排会话将与主 agent 同组展示；不注册则保持 Ungrouped。',
+                        options,
+                    }],
+            }),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('workspace-ask-timeout')), ASK_TIMEOUT_MS)),
+        ]);
+        const item = ans.answers?.[0];
+        if (item?.custom?.trim())
+            return item.custom.trim();
+        if (item?.selected?.includes('创建') && cwd)
+            return cwd;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 返回可用的会话工作目录路径。
+ * - cwd 已知：优先复用已注册工作区；未注册则询问用户（默认创建 @cwd）自动 create；询问失败/跳过仍返回 cwd（目录正确性优先，归组是 bonus）。
+ * - cwd 未知：必须经询问拿到路径并 create；无路径/无通道/无服务 → null（调用方 block 或待命）。
+ */
+export async function resolveOrCreateWorkspace(ctx, cwd, label) {
+    const ws = getWs(ctx);
+    if (cwd) {
+        if (ws?.resolveByPath) {
+            try {
+                if (await ws.resolveByPath(cwd))
+                    return cwd;
+            }
+            catch { /* 归组失败不阻断 */ }
+        }
+        if (ws?.create) {
+            const uq = getUq(ctx);
+            if (uq?.ask) {
+                const chosen = await askWorkspace(uq, cwd, label);
+                if (chosen) {
+                    try {
+                        await ws.create(chosen);
+                    }
+                    catch { /* 创建失败不阻断 */ }
+                    return chosen;
+                }
+            }
+        }
+        return cwd;
+    }
+    if (!ws?.create)
+        return null;
+    const uq = getUq(ctx);
+    if (!uq?.ask)
+        return null;
+    const chosen = await askWorkspace(uq, null, label);
+    if (!chosen)
+        return null;
+    try {
+        await ws.create(chosen);
+    }
+    catch {
+        return null;
+    }
+    return chosen;
+}
+/** 把已创建/恢复的会话归组到 cwd 对应工作区；未注册时询问用户（仅明确「创建」才 create）；全程失败静默（归组是 UX 增强，不阻断任务）。 */
+export async function attachSessionToWorkspace(ctx, sessionId, cwd, label) {
+    const ws = getWs(ctx);
+    if (!ws?.create || !ws?.resolveByPath)
+        return; // 无注册表 → 静默跳过（归组是 bonus）
+    try {
+        let entity = await ws.resolveByPath(cwd);
+        if (!entity) {
+            // 未注册：询问用户是否注册；跳过/无通道/超时 → 保持 Ungrouped（不创建）
+            const uq = getUq(ctx);
+            if (!uq?.ask)
+                return;
+            const chosen = await askWorkspace(uq, cwd, label);
+            if (!chosen)
+                return;
+            entity = await ws.create(chosen);
+        }
+        if (!entity?.attachSession)
+            return;
+        await entity.attachSession(SessionId(sessionId));
+        console.error('[dsh-swarm][debug] session attached workspace ' + sessionId + ' cwd=' + cwd + ' label=' + label);
+    }
+    catch (err) {
+        console.error('[dsh-swarm][debug] attach session failed ' + sessionId + ': ' + String(err));
+    }
+}

package/lib/domain/delivery-contract.d.ts

@@ -0,0 +1,18 @@
+import type { BoardState, Handoff, Role, TaskMode } from './types.js';
+export declare function requiredDeliveryKeys(assignee: Role, mode: TaskMode): string[];
+/** v2：pt_decision 结构校验（needed 布尔必填；needed=true 时 reason 必填）。返回缺失键列表。 */
+export declare function missingPtDecisionKeys(handoff: Handoff | undefined): string[];
+/** 缺失的交付键（存在但为空的字符串/非字符串均视为缺失；pt_decision 走结构校验透传细粒度键）。
+ *  可选 kbUrlBase：提供时对 w:kb 的 kb_url 做 host 前缀硬校验（防 LLM 手写错域名）、对 page_path 做
+ *  命名空间格式校验（Q3&5：防 LLM 自造路径/拼错层级）——未提供则仅非空校验（兼容旧调用/测试）。 */
+export declare function missingDeliveryKeys(assignee: Role, mode: TaskMode, handoff: Handoff | undefined, kbUrlBase?: string): string[];
+export declare function hasRequiredDelivery(assignee: Role, mode: TaskMode, handoff: Handoff | undefined): boolean;
+/** 交付契约缺失的父卡项（供 V 建下游卡前的前置校验）。 */
+export interface MissingParentDelivery {
+    taskId: string;
+    assignee: Role;
+    mode: TaskMode;
+    missing: string[];
+}
+/** 对一组父任务 id 做交付契约校验，返回缺关键交付物的父卡清单（无缺失返回空数组）。 */
+export declare function missingParentDelivery(state: BoardState, parentIds: string[]): MissingParentDelivery[];

package/lib/domain/delivery-contract.js

@@ -0,0 +1,80 @@
+import { isAllowedWikiPagePath } from '../wiki/page-path.js';
+/**
+ * 上游交付契约（R20「上游对下游负责」宗旨）：每阶段任务完成交接 metadata 必须产出的键。
+ * key = `${assignee}:${mode}`；仅列出「下游实际读取」的硬交付物——
+ *   - w:kb（W2/W3）：kb_url + page_path = KB 同步页（下游 wiki_read 读原文 / 收尾）
+ *   - p:openspec（P）：artifacts_path = openspec 实施计划产物路径（W2 读取同步 KB）；
+ *     pt_decision = P 判定是否需要计划评审的硬键（v2：needed 布尔必填，needed=true 时 reason 必填）
+ * d:execute 的 git 产物证据由 hasDeliveryEvidence 单独判定；pt/dt 由 validateReviewEvidence 判定，
+ * 二者不重复登记。
+ * 未列出的 mode（w:external 可选、align 旧兼容等）无硬交付约束。
+ * v2 断代：w:file 交付键随旧 w1 预取阶段已删除。
+ */
+const REQUIRED_DELIVERY = {
+    'w:kb': ['kb_url', 'page_path'],
+    'p:openspec': ['artifacts_path', 'pt_decision'],
+};
+export function requiredDeliveryKeys(assignee, mode) {
+    return REQUIRED_DELIVERY[`${assignee}:${mode}`] ?? [];
+}
+/** v2：pt_decision 结构校验（needed 布尔必填；needed=true 时 reason 必填）。返回缺失键列表。 */
+export function missingPtDecisionKeys(handoff) {
+    const d = (handoff?.metadata ?? {})['pt_decision'];
+    if (typeof d !== 'object' || d === null)
+        return ['pt_decision'];
+    const o = d;
+    if (typeof o['needed'] !== 'boolean')
+        return ['pt_decision.needed'];
+    if (o['needed'] === true && (typeof o['reason'] !== 'string' || o['reason'].trim().length === 0)) {
+        return ['pt_decision.reason'];
+    }
+    return [];
+}
+/** 缺失的交付键（存在但为空的字符串/非字符串均视为缺失；pt_decision 走结构校验透传细粒度键）。
+ *  可选 kbUrlBase：提供时对 w:kb 的 kb_url 做 host 前缀硬校验（防 LLM 手写错域名）、对 page_path 做
+ *  命名空间格式校验（Q3&5：防 LLM 自造路径/拼错层级）——未提供则仅非空校验（兼容旧调用/测试）。 */
+export function missingDeliveryKeys(assignee, mode, handoff, kbUrlBase) {
+    const keys = requiredDeliveryKeys(assignee, mode);
+    if (keys.length === 0)
+        return [];
+    if (!handoff)
+        return keys.slice();
+    const m = handoff.metadata ?? {};
+    const base = kbUrlBase ? kbUrlBase.replace(/\/$/, '') : null;
+    const strict = base !== null;
+    const missing = [];
+    for (const k of keys) {
+        if (k === 'pt_decision') {
+            missing.push(...missingPtDecisionKeys(handoff));
+        }
+        else {
+            const v = m[k];
+            if (typeof v !== 'string' || v.trim().length === 0) {
+                missing.push(k);
+            }
+            else if (strict && k === 'kb_url' && !v.startsWith(base)) {
+                missing.push(`${k} (host 前缀必须为 ${base})`);
+            }
+            else if (strict && k === 'page_path' && !isAllowedWikiPagePath(v)) {
+                missing.push(`${k} (必须为 projects/checklists/、projects/ch_*/t_*.md 或 projects/ch_*/review/ 命名空间)`);
+            }
+        }
+    }
+    return missing;
+}
+export function hasRequiredDelivery(assignee, mode, handoff) {
+    return missingDeliveryKeys(assignee, mode, handoff).length === 0;
+}
+/** 对一组父任务 id 做交付契约校验，返回缺关键交付物的父卡清单（无缺失返回空数组）。 */
+export function missingParentDelivery(state, parentIds) {
+    const out = [];
+    for (const pid of parentIds) {
+        const pt = state.tasks.get(pid);
+        if (!pt)
+            continue;
+        const missing = missingDeliveryKeys(pt.assignee, pt.mode, state.handoffs.get(pid));
+        if (missing.length > 0)
+            out.push({ taskId: pid, assignee: pt.assignee, mode: pt.mode, missing });
+    }
+    return out;
+}

package/lib/domain/delivery-evidence.d.ts

@@ -0,0 +1,12 @@
+import type { Handoff } from './types.js';
+/**
+ * R20 D(execute) 交付物证据判定（C1/C2 共用）：
+ * 完成交接 metadata 必须带 changed_files（非空）+ (commit_hash | push) 至少其一，
+ * 才算具备"实际执行并产出 git 产物"的证据。无证据 → 不判链完成 / kanban_complete 拒绝。
+ *
+ * changed_files：string[] 或非空字符串（分支/README/代码变更清单）。
+ * commit_hash：提交哈希字符串；push：布尔或描述串（已推送）。
+ */
+export declare function hasDeliveryEvidence(handoff: Handoff | undefined): boolean;
+/** D(execute) 的 TDD 声明（2026-08-26）：tdd 必须存在且结构合法——test_files 与 skipped 二选一（XOR）。 */
+export declare function hasTddDeclaration(handoff: Handoff | undefined): boolean;

package/lib/domain/delivery-evidence.js

@@ -0,0 +1,41 @@
+/**
+ * R20 D(execute) 交付物证据判定（C1/C2 共用）：
+ * 完成交接 metadata 必须带 changed_files（非空）+ (commit_hash | push) 至少其一，
+ * 才算具备"实际执行并产出 git 产物"的证据。无证据 → 不判链完成 / kanban_complete 拒绝。
+ *
+ * changed_files：string[] 或非空字符串（分支/README/代码变更清单）。
+ * commit_hash：提交哈希字符串；push：布尔或描述串（已推送）。
+ */
+export function hasDeliveryEvidence(handoff) {
+    if (!handoff)
+        return false;
+    const m = handoff.metadata ?? {};
+    const changed = m['changed_files'];
+    const changedOk = Array.isArray(changed)
+        ? changed.length > 0
+        : typeof changed === 'string' && changed.trim().length > 0;
+    if (!changedOk)
+        return false;
+    const commit = m['commit_hash'];
+    const commitOk = typeof commit === 'string' && commit.trim().length > 0;
+    const push = m['push'];
+    const pushOk = push === true || (typeof push === 'string' && push.trim().length > 0);
+    return commitOk || pushOk;
+}
+/** D(execute) 的 TDD 声明（2026-08-26）：tdd 必须存在且结构合法——test_files 与 skipped 二选一（XOR）。 */
+export function hasTddDeclaration(handoff) {
+    if (!handoff)
+        return false;
+    const tdd = (handoff.metadata ?? {})['tdd'];
+    if (!tdd || typeof tdd !== 'object')
+        return false;
+    const hasSkipped = typeof tdd.skipped === 'object' && tdd.skipped !== null;
+    const hasFiles = Array.isArray(tdd.test_files) && tdd.test_files.length > 0;
+    if (hasSkipped === hasFiles)
+        return false; // 二选一（XOR）：同时存在或都缺 → 非法
+    if (hasSkipped) {
+        const skipped = tdd.skipped;
+        return typeof skipped['reason'] === 'string' && skipped['reason'].trim().length > 0;
+    }
+    return true;
+}

package/lib/domain/event-store.d.ts

@@ -0,0 +1,20 @@
+import type { KanbanEvent } from './types.js';
+export interface EventStore {
+    append(ev: Omit<KanbanEvent, 'seq'>): Promise<KanbanEvent>;
+    readAll(): Promise<KanbanEvent[]>;
+    readAllSync(): KanbanEvent[];
+    readSince(seq: number): Promise<KanbanEvent[]>;
+    /** 物理移除匹配事件行并重排 seq（整链硬删除用；不可恢复）。 */
+    purge?(predicate: (ev: KanbanEvent) => boolean): Promise<number>;
+}
+/** JSONL 事件存储：追加即持久化；重启回放由 readAll 提供。 */
+export declare class FileEventStore implements EventStore {
+    private readonly file;
+    private seq;
+    constructor(dir: string);
+    append(ev: Omit<KanbanEvent, 'seq'>): Promise<KanbanEvent>;
+    readAll(): Promise<KanbanEvent[]>;
+    readAllSync(): KanbanEvent[];
+    readSince(seq: number): Promise<KanbanEvent[]>;
+    purge(predicate: (ev: KanbanEvent) => boolean): Promise<number>;
+}

package/lib/domain/event-store.js

@@ -0,0 +1,53 @@
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** JSONL 事件存储：追加即持久化；重启回放由 readAll 提供。 */
+export class FileEventStore {
+    file;
+    seq = 0;
+    constructor(dir) {
+        mkdirSync(dir, { recursive: true });
+        this.file = join(dir, 'events.jsonl');
+        try {
+            const lines = readFileSync(this.file, 'utf8').trim().split('\n').filter(Boolean);
+            if (lines.length > 0) {
+                this.seq = JSON.parse(lines[lines.length - 1]).seq + 1;
+            }
+        }
+        catch {
+            this.seq = 0; // 文件不存在或为空
+        }
+    }
+    async append(ev) {
+        // P1-8：seq 每次从文件尾行重读分配（跨进程安全，多 dsh 实例并发追加时 seq 唯一）；
+        // appendFileSync 单行 JSONL 追加在 POSIX 上原子（行 < 4KB，无锁无残留）。
+        const all = this.readAllSync();
+        const seq = all.length > 0 ? all[all.length - 1].seq + 1 : 0;
+        const full = { ...ev, seq };
+        const line = JSON.stringify(full) + '\n';
+        appendFileSync(this.file, line);
+        return full;
+    }
+    async readAll() {
+        return this.readAllSync();
+    }
+    readAllSync() {
+        try {
+            const text = readFileSync(this.file, 'utf8');
+            return text.split('\n').filter(Boolean).map((l) => JSON.parse(l));
+        }
+        catch {
+            return [];
+        }
+    }
+    async readSince(seq) {
+        const all = await this.readAll();
+        return all.filter((e) => e.seq >= seq);
+    }
+    async purge(predicate) {
+        const all = this.readAllSync();
+        const kept = all.filter((e) => !predicate(e)).map((e, i) => ({ ...e, seq: i }));
+        writeFileSync(this.file, kept.map((e) => JSON.stringify(e)).join('\n') + (kept.length > 0 ? '\n' : ''));
+        this.seq = kept.length;
+        return all.length - kept.length;
+    }
+}

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

@@ -0,0 +1,94 @@
+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 需求标题规范化）。 */
+export declare function firstSentence(text: string): string;
+/** 默认链标题：【需求】<一句话需求描述>。来源优先级 /plan: rest 首句 → checklist.problem 首句 → 未命名需求。 */
+export declare function buildChainTitle(requirementName: string | null, _openspecRest: string, problem: string): string;
+/** 看板领域门面：三界面（工具/CLI/UI）统一路由的唯一入口。 */
+export declare class KanbanService {
+    private state;
+    private readonly store;
+    private readonly kbUrlBase;
+    private emitQueue;
+    private readonly listeners;
+    private onChainCompletedHook;
+    private onTaskCompletedHook;
+    constructor(store: EventStore, kbUrlBase?: string);
+    private emit;
+    /** D23：注入链完成核对钩子（由调度层设置；仅一个消费者）。 */
+    setOnChainCompleted(hook: (chainId: string) => void | Promise<void>): void;
+    /** Q3&5：注入任务完成互链登记钩子（由调度层设置；仅一个消费者）。 */
+    setOnTaskCompleted(hook: (taskId: string) => void | Promise<void>): void;
+    /** T22：订阅持久化后的看板事件；返回解除订阅函数。listener 异常不影响已落盘状态。 */
+    subscribe(listener: KanbanListener): () => void;
+    /** T22：返回 seq >= 入参 的事件（与 EventStore.readSince 同为 inclusive 语义）。 */
+    eventsSince(seq: number): Promise<KanbanEvent[]>;
+    private publish;
+    private chainOf;
+    private taskOf;
+    createChain(input: {
+        title: string;
+        ownerSessionId: string;
+        workspaceDir?: string | null;
+    }, actor: Actor): Promise<Chain>;
+    createSpecCard(chainId: string, sections: SpecCardSections, actor: Actor): Promise<SpecCard>;
+    editSpecCard(cardId: string, sections: SpecCardSections, actor: Actor): Promise<SpecCard>;
+    approveSpecCard(cardId: string, actor: Actor): Promise<SpecCard>;
+    createTask(input: {
+        chainId: string;
+        title: string;
+        body?: string;
+        assignee: Role;
+        mode: TaskMode;
+        parents?: string[];
+        reviewAttempt?: number;
+    }, actor: Actor): Promise<Task>;
+    claimTask(taskId: string, actor: Actor): Promise<Task>;
+    completeTask(taskId: string, handoff: Handoff, actor: Actor, opts?: {
+        boundTaskId?: string;
+    }): Promise<Task>;
+    /** D23：链完成验收核对发警告（仅 system/dispatcher 可发）。Chain 状态保持 completed。 */
+    auditWarning(chainId: string, evidence: AuditEvidence[], actor: Actor): Promise<KanbanEvent>;
+    /** D23：用户确认产物归属（仅 human，GUI confirm-audit action）。放行最终汇报。 */
+    confirmAudit(chainId: string, actor: Actor): Promise<KanbanEvent>;
+    /** T7：链标题改名（仅 human，GUI）。发 chain/title-updated 事件（非状态转换）。 */
+    updateChainTitle(chainId: string, title: string, actor: Actor): Promise<Chain>;
+    /** 整链硬删除（含其下全部角色卡/规格卡事件；仅 human，GUI 二次确认）。物理 purge 事件行，不可恢复。 */
+    deleteChain(chainId: string, actor: Actor): Promise<void>;
+    renameTask(taskId: string, title: string, actor: Actor): Promise<Task>;
+    blockTask(taskId: string, reason: string, actor: Actor, opts?: {
+        boundTaskId?: string;
+    }): Promise<Task>;
+    unblockTask(taskId: string, actor: Actor): Promise<Task>;
+    heartbeat(taskId: string, actor: Actor, opts?: {
+        boundTaskId?: string;
+    }): Promise<Task>;
+    /** 标记任务失败（runner 异常/心跳超时回收）；投影递增 attempts（infra 瞬时错误不计数）。重试由调度器重派。 */
+    failTask(taskId: string, reason: string, actor: Actor, opts?: {
+        infra?: boolean;
+    }): 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 上传）。 */
+    addSpecCardAttachment(cardId: string, attachment: SpecCardAttachment, actor: Actor): Promise<SpecCard>;
+    /** 评审事件（交付质量链）：recordReview 记录评审卡结论并更新被评审任务 reviewStatus。
+     *  actor 必须 system（V/角色不可伪造评审结论）；verdict=pass → review/passed，否则 review/failed。
+     *  投影（projection.ts）据事件更新 target.reviewStatus（passed/failed）。 */
+    recordReview(reviewTaskId: string, targetTaskId: string, evidence: ReviewEvidence, actor: Actor): Promise<KanbanEvent>;
+    /** 评审超限放弃：review/gave-up（含证据链信息）。仅 system。 */
+    reviewGaveUp(reviewTaskId: string, targetTaskId: string, reason: string, actor: Actor): Promise<KanbanEvent>;
+    /** 评审失败返工卡创建（评审失败闭环）：原任务保持 done（不可变），新建返工卡继承 rework 字段。
+     *  仅 system（can('create-rework-task')=system）；V 建执行卡、system 建返工卡。 */
+    createReworkTask(input: {
+        sourceTaskId: string;
+        reviewTaskId: string;
+        reason: string;
+    }, actor: Actor): Promise<Task>;
+    snapshot(): Promise<BoardState>;
+    listTasks(opts?: {
+        assignee?: Role;
+        status?: Task['status'];
+    }): Promise<Task[]>;
+}