@joekytc/dsh-swarm 0.1.0

package/lib/domain/prefetch-manifest.js

@@ -0,0 +1,73 @@
+/** prefetch 子代理结构化输出的 JSON Schema（经 ctx.subagents.start 的 outputSchema 传入，
+ *  由 spawn provider 在子代理侧强制校验；assertObjectJsonSchema 强制子集内：
+ *  type/properties/required/items/enum/additionalProperties）。与 validatePrefetchManifest 同源同语义。 */
+export const PREFETCH_MANIFEST_SCHEMA = {
+    type: 'object',
+    properties: {
+        repo: {
+            type: 'object',
+            properties: {
+                localPath: { type: 'string' },
+                remoteUrl: { type: 'string' },
+                branch: { type: 'string' },
+                dirtyFiles: { type: 'array', items: { type: 'string' } },
+            },
+            required: ['localPath', 'dirtyFiles'],
+        },
+        files: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    expected: { type: 'string', enum: ['exists', 'absent', 'content-hash'] },
+                    note: { type: 'string' },
+                },
+                required: ['path', 'expected'],
+            },
+        },
+    },
+    required: ['repo', 'files'],
+};
+const EXPECTED_VALUES = new Set(['exists', 'absent', 'content-hash']);
+/** 需求澄清清单 manifest schema 校验（planning-checklist 复用本 schema）：返回错误列表（空数组 = 合法）。 */
+export function validatePrefetchManifest(raw) {
+    const errors = [];
+    if (typeof raw !== 'object' || raw === null)
+        return ['manifest must be an object'];
+    const m = raw;
+    const repo = m['repo'];
+    if (typeof repo !== 'object' || repo === null) {
+        errors.push('manifest.repo required');
+    }
+    else {
+        const r = repo;
+        if (typeof r['localPath'] !== 'string' || r['localPath'].trim().length === 0) {
+            errors.push(`manifest.repo.localPath required (got: ${JSON.stringify(r['localPath'])})`);
+        }
+        if (!Array.isArray(r['dirtyFiles']))
+            errors.push('manifest.repo.dirtyFiles must be an array');
+    }
+    if (!Array.isArray(m['files'])) {
+        errors.push('manifest.files must be an array');
+    }
+    else {
+        for (const f of m['files']) {
+            if (typeof f !== 'object' || f === null) {
+                errors.push('manifest.files entry must be an object');
+                continue;
+            }
+            const e = f;
+            if (typeof e['path'] !== 'string' || e['path'].trim().length === 0) {
+                errors.push(`manifest.files[].path (got: ${JSON.stringify(e['path'])})`);
+            }
+            if (typeof e['expected'] !== 'string' || !EXPECTED_VALUES.has(e['expected'])) {
+                errors.push(`manifest.files[].expected (got: ${JSON.stringify(e['expected'])})`);
+            }
+            if (e['expected'] === 'content-hash' && (typeof e['note'] !== 'string' || e['note'].trim().length === 0)) {
+                errors.push(`manifest.files[].note required for content-hash (got: ${JSON.stringify(e['note'])})`);
+            }
+        }
+    }
+    return errors;
+}

package/lib/domain/projection.d.ts

@@ -0,0 +1,3 @@
+import type { BoardState, KanbanEvent } from './types.js';
+export declare function applyTo(state: BoardState, ev: KanbanEvent): BoardState;
+export declare function project(events: KanbanEvent[]): BoardState;

package/lib/domain/projection.js

@@ -0,0 +1,165 @@
+import { transitionChain, transitionSpecCard, transitionTask } from './state-machine.js';
+function empty() {
+    return { chains: new Map(), tasks: new Map(), specCards: new Map(), handoffs: new Map(), auditWarnings: new Map(), events: [] };
+}
+export function applyTo(state, ev) {
+    const next = { ...state, events: [...state.events, ev] };
+    switch (ev.kind) {
+        case 'chain/created': {
+            const p = ev.payload;
+            next.chains = new Map(state.chains).set(p.id, { ...p, status: 'planning', workspaceDir: p.workspaceDir ?? null });
+            break;
+        }
+        case 'chain/executing':
+        case 'chain/completed':
+        case 'chain/aborted': {
+            const c = state.chains.get(ev.chainId);
+            if (!c)
+                throw new Error('projection: unknown chain ' + ev.chainId);
+            next.chains = new Map(state.chains).set(ev.chainId, { ...c, status: transitionChain(c.status, ev.kind) });
+            break;
+        }
+        case 'chain/root-task-set': {
+            const c = state.chains.get(ev.chainId);
+            if (!c)
+                throw new Error('projection: unknown chain ' + ev.chainId);
+            next.chains = new Map(state.chains).set(ev.chainId, { ...c, rootTaskId: String(ev.payload['rootTaskId'] ?? '') });
+            break;
+        }
+        // D23：audit 事件不改 Chain 状态，只写验收核对视图（auditWarnings）
+        case 'chain/audit-warning': {
+            const c = state.chains.get(ev.chainId);
+            if (!c)
+                throw new Error('projection: unknown chain ' + ev.chainId);
+            const evidence = (ev.payload['evidence'] ?? []);
+            const audit = {
+                evidence,
+                warnedAt: ev.at,
+                warnedSeq: ev.seq,
+                confirmedAt: null,
+                confirmedBy: null,
+                confirmedSeq: null,
+            };
+            next.auditWarnings = new Map(state.auditWarnings).set(ev.chainId, audit);
+            break;
+        }
+        case 'chain/audit-confirmed': {
+            const c = state.chains.get(ev.chainId);
+            if (!c)
+                throw new Error('projection: unknown chain ' + ev.chainId);
+            const existing = state.auditWarnings.get(ev.chainId);
+            if (!existing)
+                throw new Error('projection: audit-confirmed without audit-warning: ' + ev.chainId);
+            next.auditWarnings = new Map(state.auditWarnings).set(ev.chainId, {
+                ...existing,
+                confirmedAt: ev.at,
+                confirmedBy: ev.author,
+                confirmedSeq: ev.seq,
+            });
+            break;
+        }
+        // T7：链标题改名（非状态转换，只更新 title；快照重放可见）
+        case 'chain/title-updated': {
+            const c = state.chains.get(ev.chainId);
+            if (!c)
+                throw new Error('projection: unknown chain ' + ev.chainId);
+            next.chains = new Map(state.chains).set(ev.chainId, { ...c, title: String(ev.payload['to'] ?? '') });
+            break;
+        }
+        // T7：任务标题改名（非状态转换，只更新 title）
+        case 'task/renamed': {
+            if (!ev.taskId)
+                throw new Error('projection: event without taskId');
+            const t = state.tasks.get(ev.taskId);
+            if (!t)
+                throw new Error('projection: unknown task ' + ev.taskId);
+            next.tasks = new Map(state.tasks).set(ev.taskId, { ...t, title: String(ev.payload['to'] ?? '') });
+            break;
+        }
+        case 'task/created': {
+            const p = ev.payload;
+            if (!p.id || !p.assignee)
+                throw new Error('projection: malformed task/created');
+            // 归一化缺省字段，使最小 payload 的事件日志可回放（P0-3 回放为权威）
+            const normalized = {
+                ...p,
+                status: p.status ?? 'todo',
+                parents: p.parents ?? [],
+                children: p.children ?? [],
+                attempts: p.attempts ?? 0,
+                heartbeats: p.heartbeats ?? [],
+                sessionId: p.sessionId ?? 'kbn-' + p.id,
+                reworkOfTaskId: p.reworkOfTaskId ?? null,
+                resumeSessionId: p.resumeSessionId ?? null,
+                reviewAttempt: p.reviewAttempt ?? 0,
+                reviewStatus: p.reviewStatus ?? 'not-required',
+            };
+            next.tasks = new Map(state.tasks).set(p.id, normalized);
+            break;
+        }
+        case 'task/claimed':
+        case 'task/heartbeat':
+        case 'task/completed':
+        case 'task/blocked':
+        case 'task/unblocked':
+        case 'task/failed':
+        case 'task/archived': {
+            if (!ev.taskId)
+                throw new Error('projection: event without taskId');
+            const t = state.tasks.get(ev.taskId);
+            if (!t)
+                throw new Error('projection: unknown task ' + ev.taskId);
+            const updated = { ...t, status: transitionTask(t.status, ev.kind) };
+            if (ev.kind === 'task/heartbeat')
+                updated.heartbeats = [...t.heartbeats, ev.at];
+            // RC4：infra 失败不计入 attempts（瞬时基础设施错误不烧重试预算）；任务质量失败正常 +1
+            if (ev.kind === 'task/failed' && !ev.payload['infra'])
+                updated.attempts = t.attempts + 1;
+            if (ev.kind === 'task/unblocked')
+                updated.attempts = 0; // RC4：人工解除阻塞 → 重试预算重置
+            if (ev.kind === 'task/completed') {
+                const p = ev.payload;
+                next.handoffs = new Map(state.handoffs).set(ev.taskId, p);
+            }
+            next.tasks = new Map(state.tasks).set(ev.taskId, updated);
+            break;
+        }
+        // 评审事件（交付质量链）：非状态转换——按 payload.targetTaskId 更新被评审任务 reviewStatus
+        case 'review/passed':
+        case 'review/failed':
+        case 'review/gave-up': {
+            const targetId = String(ev.payload['targetTaskId'] ?? '');
+            const t = state.tasks.get(targetId);
+            if (!t)
+                throw new Error('projection: unknown review target ' + targetId);
+            const status = ev.kind === 'review/passed' ? 'passed' : ev.kind === 'review/failed' ? 'failed' : 'gave-up';
+            next.tasks = new Map(state.tasks).set(targetId, { ...t, reviewStatus: status });
+            break;
+        }
+        case 'spec-card/created':
+        case 'spec-card/edited': {
+            const p = ev.payload;
+            next.specCards = new Map(state.specCards).set(p.id, p);
+            // 规格卡创建时把链路的 specCardId 一并接线（事件溯源派生，无需额外事件）
+            if (ev.kind === 'spec-card/created') {
+                const c = state.chains.get(p.chainId);
+                if (c && !c.specCardId) {
+                    next.chains = new Map(state.chains).set(p.chainId, { ...c, specCardId: p.id });
+                }
+            }
+            break;
+        }
+        case 'spec-card/approved': {
+            const id = String(ev.payload['id'] ?? '');
+            const s = state.specCards.get(id);
+            if (!s)
+                throw new Error('projection: unknown spec card ' + id);
+            next.specCards = new Map(state.specCards).set(id, { ...s, status: transitionSpecCard(s.status, ev.kind), approvedAt: ev.at, approvedBy: ev.author });
+            break;
+        }
+    }
+    return next;
+}
+export function project(events) {
+    return events.reduce(applyTo, empty());
+}

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

@@ -0,0 +1,13 @@
+import type { Handoff } from './types.js';
+/**
+ * 评审证据机械校验（交付质量链 PT/DT 共用）：
+ * PT/DT 完成交接 metadata.review_evidence 必须满足角色所需的证据结构，
+ * 缺证据拒绝 pass（评审卡 complete 被拒 / orchestrator 不推进）。
+ *
+ * - PT（计划评审）：必需 verdict + issues + 计划结构字段（对齐需求/完整性/逻辑交互一致性的产物引用）。
+ * - DT（实现评审）：必需 verdict + test(exit 0) + build/typecheck/lint + diff 非空 + git 证据 +
+ *   ocr/fallback 结论 + issues 处置。
+ *
+ * @returns 缺失清单（空数组 = 证据完整）。
+ */
+export declare function validateReviewEvidence(role: 'pt' | 'dt', handoff: Handoff | undefined): string[];

package/lib/domain/review-evidence.js

@@ -0,0 +1,76 @@
+/**
+ * 评审证据机械校验（交付质量链 PT/DT 共用）：
+ * PT/DT 完成交接 metadata.review_evidence 必须满足角色所需的证据结构，
+ * 缺证据拒绝 pass（评审卡 complete 被拒 / orchestrator 不推进）。
+ *
+ * - PT（计划评审）：必需 verdict + issues + 计划结构字段（对齐需求/完整性/逻辑交互一致性的产物引用）。
+ * - DT（实现评审）：必需 verdict + test(exit 0) + build/typecheck/lint + diff 非空 + git 证据 +
+ *   ocr/fallback 结论 + issues 处置。
+ *
+ * @returns 缺失清单（空数组 = 证据完整）。
+ */
+export function validateReviewEvidence(role, handoff) {
+    const missing = [];
+    if (!handoff)
+        return ['handoff missing'];
+    const ev = (handoff.metadata ?? {})['review_evidence'];
+    if (!ev || typeof ev !== 'object')
+        return ['review_evidence missing'];
+    if (ev.verdict !== 'pass' && ev.verdict !== 'fail')
+        missing.push('review_evidence.verdict');
+    if (!Array.isArray(ev.issues))
+        missing.push('review_evidence.issues');
+    if (role === 'pt') {
+        // 计划结构字段：评审须给出被评审计划产物引用（如 artifacts_path/page 结构）——缺则视为证据不足
+        const planRef = ev.reviewPage ?? (handoff.metadata ?? {})['artifacts_path'];
+        if (!planRef)
+            missing.push('review_evidence.plan (artifacts_path/reviewPage)');
+    }
+    else {
+        // DT：实证校验证据（fail 评审同样必须已实证——test 字段必须存在；仅 pass 要求 exit 0）
+        if (!ev.test || typeof ev.test !== 'object')
+            missing.push('review_evidence.test');
+        else if (ev.verdict === 'pass' && ev.test['exit'] !== 0)
+            missing.push('review_evidence.test (exit 0)');
+        const buildOk = ev.build && typeof ev.build === 'object';
+        const tcOk = ev.typecheck && typeof ev.typecheck === 'object';
+        if (!buildOk && !tcOk)
+            missing.push('review_evidence.build/typecheck');
+        if (ev.lint === undefined)
+            missing.push('review_evidence.lint');
+        const diffOk = ev.diff && typeof ev.diff === 'object' && Object.keys(ev.diff).length > 0;
+        if (!diffOk)
+            missing.push('review_evidence.diff (non-empty)');
+        if (!ev.git || typeof ev.git !== 'object')
+            missing.push('review_evidence.git');
+        if (!ev.openCodeReview || typeof ev.openCodeReview !== 'object')
+            missing.push('review_evidence.openCodeReview (ocr/fallback)');
+        // TDD 硬要求（2026-08-26）：代码变更必须带 tdd 证据（DT 只读 git 核验 test_first）。
+        // 镜像 test.exit 非对称：pass 必须 test_first===true；fail 允许 false 如实记录违规。
+        const tdd = ev.tdd;
+        if (!tdd || typeof tdd !== 'object') {
+            missing.push('review_evidence.tdd');
+        }
+        else if (tdd.skipped && typeof tdd.skipped === 'object') {
+            // skipped 与 test_files 二选一（XOR）：并存视为非法声明
+            if (Array.isArray(tdd.test_files) && tdd.test_files.length > 0) {
+                missing.push('review_evidence.tdd (skipped XOR test_files)');
+            }
+            if (typeof tdd.skipped['reason'] !== 'string' || !tdd.skipped['reason'].trim()) {
+                missing.push('review_evidence.tdd (skipped.reason)');
+            }
+        }
+        else {
+            if (!Array.isArray(tdd.test_files) || tdd.test_files.length === 0) {
+                missing.push('review_evidence.tdd (test_files)');
+            }
+            if (ev.test && typeof ev.test === 'object' && ev.test['runner'] !== 'vitest') {
+                missing.push('review_evidence.test (runner=vitest)');
+            }
+            if (ev.verdict === 'pass' && tdd.test_first !== true) {
+                missing.push('review_evidence.tdd (test_first=true)');
+            }
+        }
+    }
+    return missing;
+}

package/lib/domain/state-machine.d.ts

@@ -0,0 +1,4 @@
+import type { TaskStatus, ChainStatus, SpecCardStatus, EventKind } from './types.js';
+export declare const transitionTask: (c: TaskStatus, k: EventKind) => TaskStatus;
+export declare const transitionChain: (c: ChainStatus, k: EventKind) => ChainStatus;
+export declare const transitionSpecCard: (c: SpecCardStatus, k: EventKind) => SpecCardStatus;

package/lib/domain/state-machine.js

@@ -0,0 +1,32 @@
+const TASK_TRANSITIONS = {
+    triage: { 'task/claimed': 'running' },
+    todo: { 'task/claimed': 'running', 'task/archived': 'archived' },
+    ready: { 'task/claimed': 'running', 'task/archived': 'archived' },
+    running: { 'task/completed': 'done', 'task/blocked': 'blocked', 'task/failed': 'failed', 'task/heartbeat': 'running' },
+    blocked: { 'task/unblocked': 'ready', 'task/archived': 'archived' },
+    done: { 'task/archived': 'archived' },
+    failed: { 'task/claimed': 'running', 'task/blocked': 'blocked', 'task/archived': 'archived' },
+    archived: {},
+};
+const CHAIN_TRANSITIONS = {
+    planning: { 'chain/executing': 'executing' },
+    executing: { 'chain/completed': 'completed', 'chain/aborted': 'aborted' },
+    completed: {},
+    aborted: {},
+};
+// D23：'chain/audit-warning' / 'chain/audit-confirmed' 不是状态转换——
+// Chain 保持 completed，只向投影写入验收核对视图（auditWarnings）。
+// projection.ts 对这两类事件专门处理、不调用 transitionChain，故此处不注册。
+const SPEC_TRANSITIONS = {
+    draft: { 'spec-card/approved': 'approved' },
+    approved: {},
+};
+function step(name, table, current, kind) {
+    const next = table[current]?.[kind];
+    if (next === undefined)
+        throw new Error(`illegal transition: ${current} --${kind}--> (none)`);
+    return next;
+}
+export const transitionTask = (c, k) => step('task', TASK_TRANSITIONS, c, k);
+export const transitionChain = (c, k) => step('chain', CHAIN_TRANSITIONS, c, k);
+export const transitionSpecCard = (c, k) => step('spec', SPEC_TRANSITIONS, c, k);

package/lib/domain/task-parents.d.ts

@@ -0,0 +1,17 @@
+import type { Role, Task, TaskMode } from './types.js';
+/**
+ * 语义父依赖角色（不含状态判定）：返回当前阶段任务"本该依赖"的上游 (assignee, mode)。
+ * 供 resolveTaskParents（取终态 id）与 createTask 硬拦（查非终态）共用，保证依赖推导单一来源。
+ * w:kb 特判：链上 d/execute 已交付 → 父=D（w3）；否则父=P（w2）。
+ */
+export declare function semanticParentDeps(tasks: Iterable<Task>, chainId: string, assignee: Role, mode: TaskMode): Array<{
+    assignee: Role;
+    mode: TaskMode;
+}>;
+/** 语义上游中存在但非终态（非 done/archived）的父任务清单——createTask 硬拦依据。 */
+export declare function nonTerminalSemanticParents(tasks: Iterable<Task>, chainId: string, assignee: Role, mode: TaskMode): Task[];
+/**
+ * 解析某角色任务的语义父任务 id（终态 done/archived）。供 createTask 兜底与 V 建卡指令共用，
+ * 消除「V 建卡漏设 parents → 父交接注入断裂」的软约定风险（P 直接读规格卡，无 w1 预取父卡）。
+ */
+export declare function resolveTaskParents(tasks: Iterable<Task>, chainId: string, assignee: Role, mode: TaskMode): string[];

package/lib/domain/task-parents.js

@@ -0,0 +1,39 @@
+/**
+ * 每阶段任务卡的语义输入来源（R20 依赖)：第 1 项为主来源。
+ * key = `${assignee}:${mode}`；w:kb 特判（w2→P、w3→D）见 semanticParentDeps。
+ * 未列出的 mode（如旧兼容 align）不设语义 parents（返回空）。
+ */
+const PARENT_DEPS = {
+    'p:openspec': [], // v2：P 读规格卡（需求澄清清单附件）+ 父任务交接，无 w1 预取父卡
+    'pt:review-plan': [{ assignee: 'p', mode: 'openspec' }], // PT 评审 P 计划
+    'd:execute': [{ assignee: 'w', mode: 'kb' }], // D 接 W2（P 计划同步 KB 后的 page_path/kb_url，wiki_read 读实施计划执行）
+    'dt:review-impl': [{ assignee: 'd', mode: 'execute' }], // DT 评审 D 交付
+};
+/**
+ * 语义父依赖角色（不含状态判定）：返回当前阶段任务"本该依赖"的上游 (assignee, mode)。
+ * 供 resolveTaskParents（取终态 id）与 createTask 硬拦（查非终态）共用，保证依赖推导单一来源。
+ * w:kb 特判：链上 d/execute 已交付 → 父=D（w3）；否则父=P（w2）。
+ */
+export function semanticParentDeps(tasks, chainId, assignee, mode) {
+    if (assignee === 'w' && mode === 'kb') {
+        const dDone = [...tasks].some((t) => t.chainId === chainId && t.assignee === 'd' && t.mode === 'execute' &&
+            (t.status === 'done' || t.status === 'archived'));
+        return dDone ? [{ assignee: 'd', mode: 'execute' }] : [{ assignee: 'p', mode: 'openspec' }];
+    }
+    return PARENT_DEPS[`${assignee}:${mode}`] ?? [];
+}
+/** 语义上游中存在但非终态（非 done/archived）的父任务清单——createTask 硬拦依据。 */
+export function nonTerminalSemanticParents(tasks, chainId, assignee, mode) {
+    const chainTasks = [...tasks].filter((t) => t.chainId === chainId);
+    const terminal = ['done', 'archived'];
+    return semanticParentDeps(chainTasks, chainId, assignee, mode).flatMap((d) => chainTasks.filter((t) => t.assignee === d.assignee && t.mode === d.mode && !terminal.includes(t.status)));
+}
+/**
+ * 解析某角色任务的语义父任务 id（终态 done/archived）。供 createTask 兜底与 V 建卡指令共用，
+ * 消除「V 建卡漏设 parents → 父交接注入断裂」的软约定风险（P 直接读规格卡，无 w1 预取父卡）。
+ */
+export function resolveTaskParents(tasks, chainId, assignee, mode) {
+    const chainTasks = [...tasks].filter((t) => t.chainId === chainId);
+    const ids = (a, m) => chainTasks.filter((t) => t.assignee === a && t.mode === m && (t.status === 'done' || t.status === 'archived')).map((t) => t.id);
+    return semanticParentDeps(chainTasks, chainId, assignee, mode).flatMap((d) => ids(d.assignee, d.mode));
+}

package/lib/domain/tdd-classify.d.ts

@@ -0,0 +1,5 @@
+export declare function extOf(path: string): string;
+/** 命中 *.test.* / *.spec.* / __tests__/ / tests/ 即测试文件。 */
+export declare function isTestFile(path: string): boolean;
+/** 需测试的源码：非测试文件且扩展名在约定集合内。 */
+export declare function isTestableSource(path: string): boolean;

package/lib/domain/tdd-classify.js

@@ -0,0 +1,20 @@
+// src/domain/tdd-classify.ts
+/** 需测试的源码扩展名（TDD 硬要求判定口径：含 js/jsx/vue）。 */
+const TESTABLE_SOURCE_EXT = new Set(['ts', 'tsx', 'js', 'jsx', 'vue', 'rs', 'py', 'go', 'java']);
+export function extOf(path) {
+    const m = /\.([A-Za-z0-9]+)$/.exec(path);
+    return m ? m[1].toLowerCase() : '';
+}
+/** 命中 *.test.* / *.spec.* / __tests__/ / tests/ 即测试文件。 */
+export function isTestFile(path) {
+    const base = path.split('/').pop() ?? '';
+    if (/(\.test\.|\.spec\.)/i.test(base))
+        return true;
+    if (/__tests__\//.test(path) || /(^|\/)tests\//.test(path))
+        return true;
+    return false;
+}
+/** 需测试的源码：非测试文件且扩展名在约定集合内。 */
+export function isTestableSource(path) {
+    return !isTestFile(path) && TESTABLE_SOURCE_EXT.has(extOf(path));
+}

package/lib/domain/types.d.ts

@@ -0,0 +1,142 @@
+export type Role = 'v' | 'p' | 'w' | 'd' | 'pt' | 'dt';
+export type TaskMode = 'file' | 'external' | 'kb' | 'openspec' | 'mattpocock' | 'align' | 'execute' | 'review-plan' | 'review-impl';
+export type TaskStatus = 'triage' | 'todo' | 'ready' | 'running' | 'blocked' | 'done' | 'failed' | 'archived';
+export type ChainStatus = 'planning' | 'executing' | 'completed' | 'aborted';
+export type SpecCardStatus = 'draft' | 'approved';
+/** 评审状态（交付质量链）：not-required 普通卡 / pending 等待评审 / passed 通过 / failed 失败待返工 / gave-up 超限放弃。 */
+export type ReviewStatus = 'not-required' | 'pending' | 'passed' | 'failed' | 'gave-up';
+/** 评审结论：pass=通过 / fail=不通过。 */
+export type ReviewVerdict = 'pass' | 'fail';
+/** 评审问题条目（PT/DT 交接 evidence.issues）。 */
+export interface ReviewIssue {
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    title: string;
+    detail: string;
+    location?: string;
+    resolved: boolean;
+}
+/** TDD 硬要求证据（评审时收集的测试相关元信息）。 */
+export interface TddEvidence {
+    test_files: string[];
+    test_first: boolean;
+    skipped?: {
+        reason: string;
+    };
+}
+/** 评审证据（PT/DT 交接 metadata.review_evidence）：机械校验通过才允许评审卡 pass。 */
+export interface ReviewEvidence {
+    verdict: ReviewVerdict;
+    issues: ReviewIssue[];
+    tdd?: TddEvidence;
+    test?: Record<string, unknown>;
+    build?: Record<string, unknown>;
+    typecheck?: Record<string, unknown>;
+    lint?: Record<string, unknown>;
+    diff?: Record<string, unknown>;
+    git?: Record<string, unknown>;
+    openCodeReview?: Record<string, unknown>;
+    reviewPage?: {
+        pagePath: string;
+        kbUrl: string;
+    };
+}
+export type EventKind = 'chain/created' | 'chain/executing' | 'chain/completed' | 'chain/aborted' | 'chain/root-task-set' | 'chain/audit-warning' | 'chain/audit-confirmed' | 'chain/title-updated' | 'spec-card/created' | 'spec-card/edited' | 'spec-card/approved' | 'task/created' | 'task/claimed' | 'task/heartbeat' | 'task/commented' | 'task/completed' | 'task/blocked' | 'task/unblocked' | 'task/archived' | 'task/failed' | 'task/renamed' | 'review/passed' | 'review/failed' | 'review/gave-up';
+export interface SpecCardSections {
+    problem: string;
+    solution: string;
+    user_stories: string[];
+    impl_decisions: string[];
+    testing: string;
+    out_of_scope: string;
+}
+export interface SpecCardAttachment {
+    name: string;
+    kind: 'file-prefetch' | 'external' | 'kb' | 'other';
+    ref: string;
+}
+export interface Chain {
+    id: string;
+    title: string;
+    status: ChainStatus;
+    rootTaskId: string | null;
+    specCardId: string | null;
+    ownerSessionId: string;
+    /** 发起 /plan: 的主 agent 会话工作目录（Q5：角色会话统一创建于此，便于管理 profile 会话）。null=未捕获（GUI 建链），回退 kanban 存储。 */
+    workspaceDir: string | null;
+    createdAt: number;
+}
+export interface SpecCard {
+    id: string;
+    chainId: string;
+    status: SpecCardStatus;
+    sections: SpecCardSections;
+    attachments: SpecCardAttachment[];
+    rawDialogueRef: string | null;
+    approvedAt: number | null;
+    approvedBy: string | null;
+}
+export interface Task {
+    id: string;
+    chainId: string;
+    title: string;
+    body: string;
+    assignee: Role;
+    status: TaskStatus;
+    mode: TaskMode;
+    priority: number;
+    parents: string[];
+    children: string[];
+    createdBy: 'v' | 'human' | 'auto';
+    attempts: number;
+    heartbeats: number[];
+    /** 确定性会话 id（kbn-<taskId>），与角色会话 id 一致，供追踪定位与 resume。 */
+    sessionId: string;
+    /** 返工来源任务 id（评审失败 createReworkTask 生成）；null=非返工卡。 */
+    reworkOfTaskId: string | null;
+    /** resume 会话 id（返工卡沿用被返工任务的会话，避免重头）；null=默认 kbn-<taskId>。 */
+    resumeSessionId: string | null;
+    /** 返工尝试次数（从被返工任务继承 +1）。 */
+    reviewAttempt: number;
+    /** 评审状态（普通卡 not-required）。 */
+    reviewStatus: ReviewStatus;
+}
+export interface Handoff {
+    summary: string;
+    metadata: Record<string, unknown>;
+    completedAt: number;
+}
+/** D23 链完成验收核对证据：主会话越权写工作区产物的单个线索。 */
+export interface AuditEvidence {
+    source: 'main-session-scan' | 'artifact-reconciliation' | string;
+    detail: string;
+    paths: string[];
+    at?: number;
+}
+/** D23 链完成验收核对投影视图：warning 事件 + （可选）用户确认。 */
+export interface ChainAudit {
+    evidence: AuditEvidence[];
+    warnedAt: number;
+    warnedSeq: number;
+    confirmedAt: number | null;
+    confirmedBy: string | null;
+    confirmedSeq: number | null;
+}
+/** 审计事件不是状态转换（不改变 Chain 状态，见 state-machine.ts）。 */
+export declare const isAuditEventKind: (kind: EventKind) => boolean;
+export interface KanbanEvent {
+    seq: number;
+    chainId: string;
+    taskId: string | null;
+    kind: EventKind;
+    payload: Record<string, unknown>;
+    author: string;
+    at: number;
+}
+export interface BoardState {
+    chains: Map<string, Chain>;
+    tasks: Map<string, Task>;
+    specCards: Map<string, SpecCard>;
+    handoffs: Map<string, Handoff>;
+    auditWarnings: Map<string, ChainAudit>;
+    events: KanbanEvent[];
+}

package/lib/domain/types.js

@@ -0,0 +1,2 @@
+/** 审计事件不是状态转换（不改变 Chain 状态，见 state-machine.ts）。 */
+export const isAuditEventKind = (kind) => kind === 'chain/audit-warning' || kind === 'chain/audit-confirmed';

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { Config, type KanbanConfig } from './config.js';
+export declare const name = "dsh-swarm";
+export { Config };
+export declare function apply(ctx: Context, config: KanbanConfig): void;