@joekytc/dsh-swarm 0.1.0 → 0.1.2

package/README.md

@@ -6,7 +6,7 @@
 
 **A governed swarm of six specialist DSH agents that turns one requirement into a strict, evidence-verified pipeline.**
 
-An orchestrator (V) decomposes an approved spec into a strictly ordered phase chain (`p → (pt?) → w2 → d → dt → w3 → summary`); six single-purpose roles (V / P / W / D / PT / DT) run each phase with isolated, permission-gated tool faces; every handoff is machine-verified against an evidence contract; failures recover through idempotent retry and human-gated reviews; and a live Workflow kanban tab streams all state to the browser via SSE. Design inspired by the Hermes Agent kanban.
+An orchestrator (V) decomposes an approved spec into a strictly ordered phase chain (`p → (pt?) → w2 → d → dt → w3 → summary`); six single-purpose roles (V / P / W / D / PT / DT) run each phase with isolated, permission-gated tool faces; every handoff is machine-verified against an evidence contract; failures recover through idempotent retry and human-gated reviews; and a live Workflow kanban tab streams all state to the browser via SSE. Design inspired by the [Hermes Agent kanban](https://github.com/NousResearch/hermes-agent).
 
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
@@ -36,10 +36,10 @@ Six roles are dispatched by the scheduler as one-shot agent sessions (determinis
 | **P** | Planner | Reads spec + repo facts (incl. read-only self-checks), writes an OpenSpec implementation plan, opts into PT via `pt_decision.needed`. Never executes. | Task tools + spec view, read-only (writes only `openspec/changes/`) |
 | **PT** | Plan reviewer | Read-only review of P's plan (requirements alignment, completeness, logic). Outputs verdict + issues. | Task tools + spec view, **read-only ToolGuard** |
 | **W** | Wiki bridge | W2/W3 KB sync (`w:kb`). Never touches code/git. | Task tools + `wiki_search/read/write` + read-only spec view |
-| **D** | Executor | The *only* role that writes code: worktree → implement → verify → `[AI-GEN]` commit → push feature branch (merging into TARGET_BRANCH is done by the system only after DT passes). | Task tools + wiki read + bash/fs/run_code (full dev) + subagent (spawn/fork/list-agents) + goal |
+| **D** | Executor | The *only* role that writes code: worktree → implement → verify → `[AI-GEN]` commit → push feature branch (merging into the spec-declared target branch is done by the system only after DT passes). | Task tools + wiki read + bash/fs/run_code (full dev) + subagent (spawn/fork/list-agents) + goal |
 | **DT** | Implementation reviewer | Empirically verifies D's work (test/build/typecheck/diff/git + open-code-review), writes review page to KB. Read-only against the repo. | Task tools + wiki read/write (review namespace) + bash/fs/run_code, **read-only ToolGuard** |
 
-The pipeline (R20 phase order, strictly serial within a chain, parallel across chains):
+The pipeline (strictly serial within a chain, parallel across chains):
 
 ```text
 p ──> (pt?) ──> w2 ──> d ──> dt ──> w3 ──> summary
@@ -119,7 +119,7 @@ dsh plugin --profile <name> add ./dsh-swarm
    Handoff / Spec / Comments.
 
 4. When a chain completes, the system audits the workspace for out-of-chain writes
-   and (for D chains) merges D's feature branch into `TARGET_BRANCH`. If an audit
+   and (for D chains) merges D's feature branch into the spec-declared target branch. If an audit
    warning is raised, confirm ownership in the GUI before the final summary is shown.
 
 ---
@@ -131,7 +131,7 @@ All keys are optional; defaults shown. Schema lives in `src/config.ts`.
 | Key | Default | Description |
 |---|---|---|
 | `storageDir` | `$DSH_HOME/storages/kanban` | Event log (`events.jsonl`), orchestration state, per-task workspaces, `dispatcher.log` |
-| `wikiVault.baseUrl` | `http://192.168.122.111:3000` | wiki-vault HTTP service for KB reads/writes |
+| `wikiVault.baseUrl` | `''` (empty) | wiki-vault HTTP service for KB reads/writes — required for KB features; set to your own server |
 | `wikiVault.pagePrefix` | `projects/` | Whitelist prefix for W page writes |
 | `roles.models.<role>` | `{}` | Per-role model: `{ provider, model, reasoningEffort?, fallbacks?[] }` |
 | `roles.models.<role>.reasoningEffort` | `high` | Default reasoning effort for all roles |
@@ -231,7 +231,7 @@ blocks the save, and `/openspec:` mounts the checklist as the `file-prefetch` +
 - **PT/DT** are read-only: a ToolGuard mechanically denies writes to the repo
   sources, git mutations, and (for DT) wiki writes outside the review namespace.
 - **DT** review engine: `open-code-review` (ocr, delegation mode, diff
-  `--from TARGET_BRANCH --to <feature branch>`) → fallback `superpowers
+  `--from <target branch> --to <feature branch>`) → fallback `superpowers
   code-review` → block `review-tool-unavailable` only if both are unavailable.
 - `review_evidence` must pass `validateReviewEvidence` or the review card cannot
   complete: PT needs verdict + issues + plan ref; DT additionally needs
@@ -273,19 +273,20 @@ Two orthogonal failure paths, both human-recoverable:
 When the mechanical chain-complete rule fires, two gates run in the
 `chain/completed` hook:
 
-1. **Completion audit gate (D23)**: the `ChainAuditor` cross-checks the chain
+1. **Completion audit gate**: the `ChainAuditor` cross-checks the chain
    workspace for artifacts written outside the known task outputs. Orphaned writes
    emit `chain/audit-warning`; the UI shows a warning banner and blocks the final
    summary until the human confirms ownership (`chain/audit-confirmed`, human-only).
-2. **Merge gate (post-DT system merge)**: D never merges to `TARGET_BRANCH` and
+2. **Merge gate (post-DT system merge)**: D never merges to the target branch and
    never pushes it — it only commits to (and optionally pushes) its feature branch,
-   carrying `branch` in its handoff. After DT approves and the chain completes,
-   `merge-gate.ts` performs, as `system`: `git checkout TARGET_BRANCH → git merge
-   --no-ff <feature-branch> → git push`. Outcomes are recorded as idempotent
-   comments: `[merge-done]` (with hash), `[merge-skip]` (merge input unresolvable),
-   or `[merge-failed]` (checkout/merge/push failed, e.g. a conflict). Failures never
-   throw — a bad merge is never performed, which is the safe direction; humans can
-   repair afterwards.
+   carrying `branch` in its handoff. The target branch is the one declared in the
+   spec (written by V into the D task body). After DT approves and the chain
+   completes, `merge-gate.ts` performs, as `system`: `git checkout <target-branch>
+   → git merge --no-ff <feature-branch> → git push`. Outcomes are recorded as
+   idempotent comments: `[merge-done]` (with hash), `[merge-skip]` (merge input
+   unresolvable), or `[merge-failed]` (checkout/merge/push failed, e.g. a conflict).
+   Failures never throw — a bad merge is never performed, which is the safe
+   direction; humans can repair afterwards.
 
 ---
 
@@ -380,10 +381,10 @@ flowchart TB
 
     subgraph Dispatcher ["dispatcher/"]
         WAKER["event-waker (events → wake V)"]
-        VORCH["v-orchestrator (R20 phase machine)"]
+        VORCH["v-orchestrator (phase machine)"]
         RUNNER["agent-runner (one-shot role sessions, presets, ToolGuards)"]
         WD["watchdog (heartbeat / stale reclaim / circuit)"]
-        AUDIT["chain-auditor (D23 completion audit)"]
+        AUDIT["chain-auditor (completion audit)"]
         MG["merge-gate (post-DT system merge)"]
     end
 
@@ -423,7 +424,7 @@ flowchart TB
 - **Integration** (`src/tools/`, `src/routes/`) — cordis tools and routes:
   the role tool faces, main-session tools (`kanban_route` + read-only subset), and
   the `/kanban/*` HTTP/SSE bridge.
-- **Dispatcher** (`src/dispatcher/`) — event wake, R20 orchestration, one-shot
+- **Dispatcher** (`src/dispatcher/`) — event wake, phase orchestration, one-shot
   agent runner (persona preset mounting, model candidate chain, ToolGuard
   installation), watchdog, chain auditor, and merge gate.
 - **Roles** (`src/roles/`, `personas/`) — trimmed agent presets installed into
@@ -459,14 +460,14 @@ python tests/e2e/gui-check.py --url http://127.0.0.1:3080/
 ### Implemented (v0.1.0)
 
 - [x] Event-sourced domain + deterministic state machines (red-team replay)
-- [x] 6-role R20 pipeline with trimmed presets and session-bound permissions
+- [x] 6-role phase pipeline with trimmed presets and session-bound permissions
 - [x] Delivery contract + review evidence gates + rework lifecycle
 - [x] TDD hard gate (D `tdd` handoff + DT `test_first` / `runner=vitest` verification)
 - [x] Protocol-violation recovery, heartbeat watchdog, failure circuit
-- [x] Chain completion audit gate (D23) + human confirm
+- [x] Chain completion audit gate + human confirm
 - [x] Post-DT merge gate (D pushes feature branch only)
 - [x] Phase-0 planning checklist + `file-prefetch` attachment
-- [x] GUI chain/task rename + chain delete (T7, human-only)
+- [x] GUI chain/task rename + chain delete (human-only)
 - [x] Model candidate chain with silent fallback + high reasoning effort
 - [x] Live SSE kanban tab (Conversation → Trajectory → Kanban)
 

package/README.zh-CN.md

@@ -6,7 +6,7 @@
 
 **受管六角色 DSH agent 蜂群：把单个需求变成严格、证据可核验的流水线。**
 
-编排者（V）把已批准的规格拆成严格有序的相位链（`p → (pt?) → w2 → d → dt → w3 → summary`）；六个单一职责的角色（V / P / W / D / PT / DT）以隔离、受权限约束的工具面执行每个相位；每份交接都经过针对证据契约的机器校验；故障通过幂等重试与人工把关的评审恢复；实时 Workflow 看板标签页通过 SSE 把全部状态流式同步到浏览器。设计灵感源自 Hermes Agent kanban。
+编排者（V）把已批准的规格拆成严格有序的相位链（`p → (pt?) → w2 → d → dt → w3 → summary`）；六个单一职责的角色（V / P / W / D / PT / DT）以隔离、受权限约束的工具面执行每个相位；每份交接都经过针对证据契约的机器校验；故障通过幂等重试与人工把关的评审恢复；实时 Workflow 看板标签页通过 SSE 把全部状态流式同步到浏览器。设计灵感源自 [Hermes Agent kanban](https://github.com/NousResearch/hermes-agent)。
 
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
@@ -36,10 +36,10 @@ dsh-swarm 针对以上三种问题编码了*契约*：每个角色只有一项
 | **P** | 规划者 | 读取规格 + 仓库事实（含只读自查），编写 OpenSpec 实施计划，用 `pt_decision.needed` 决定是否需要 PT。绝不执行。 | 任务工具 + 规格查看，只读（仅写 `openspec/changes/`） |
 | **PT** | 计划评审者 | 对 P 的计划做只读评审（需求对齐、完整性、逻辑）。输出裁决 + 问题清单。 | 任务工具 + 规格查看，**只读 ToolGuard** |
 | **W** | 知识库桥 | W2/W3 知识库同步（`w:kb`）。绝不碰代码/git。 | 任务工具 + `wiki_search/read/write` + 只读规格查看 |
-| **D** | 执行者 | *唯一*写代码的角色：worktree → 实现 → 验证 → `[AI-GEN]` 提交 → 推送特性分支（合入 TARGET_BRANCH 由 system 在 DT 通过后执行）。 | 任务工具 + wiki 只读 + bash/fs/run_code（完整开发面）+ subagent（spawn/fork/list-agents）+ goal |
+| **D** | 执行者 | *唯一*写代码的角色：worktree → 实现 → 验证 → `[AI-GEN]` 提交 → 推送特性分支（合入规格声明的目标分支由 system 在 DT 通过后执行）。 | 任务工具 + wiki 只读 + bash/fs/run_code（完整开发面）+ subagent（spawn/fork/list-agents）+ goal |
 | **DT** | 实现评审者 | 实证验证 D 的工作（test/build/typecheck/diff/git + open-code-review），把评审页写入知识库。对仓库只读。 | 任务工具 + wiki 读写（评审命名空间）+ bash/fs/run_code，**只读 ToolGuard** |
 
-管线（R20 相位顺序，链路内严格串行，链路间并行）：
+管线（链路内严格串行，链路间并行）：
 
 ```text
 p ──> (pt?) ──> w2 ──> d ──> dt ──> w3 ──> summary
@@ -111,7 +111,7 @@ dsh plugin --profile <name> add ./dsh-swarm
    概览 / 轨迹 / 交接 / 规格 / 评论。
 
 4. 链路完成时，系统审计工作区中是否有链路之外的写入，并（对 D 链路）把 D 的特性分支
-   合并到 `TARGET_BRANCH`。若触发审计警告，需先在 GUI 中确认归属，才会展示最终汇报。
+   合并到规格声明的目标分支。若触发审计警告，需先在 GUI 中确认归属，才会展示最终汇报。
 
 ---
 
@@ -122,7 +122,7 @@ dsh plugin --profile <name> add ./dsh-swarm
 | 键 | 默认值 | 说明 |
 |---|---|---|
 | `storageDir` | `$DSH_HOME/storages/kanban` | 事件日志（`events.jsonl`）、编排状态、每任务工作区、`dispatcher.log` |
-| `wikiVault.baseUrl` | `http://192.168.122.111:3000` | 知识库读写用的 wiki-vault HTTP 服务 |
+| `wikiVault.baseUrl` | `''`（空） | 知识库读写用的 wiki-vault HTTP 服务——知识库功能必需，填你自己的服务地址 |
 | `wikiVault.pagePrefix` | `projects/` | W 页面写入的白名单前缀 |
 | `roles.models.<role>` | `{}` | 每角色模型：`{ provider, model, reasoningEffort?, fallbacks?[] }` |
 | `roles.models.<role>.reasoningEffort` | `high` | 所有角色默认推理强度 |
@@ -215,7 +215,7 @@ D 只有带 `tdd` 才能完成——`test_files`（含 `test_first`）或 `skipp
 - **D** 完成后**总是**创建 **DT** 卡。
 - **PT/DT 只读**：ToolGuard 机械性拒绝写仓库源码、git 变更，以及（对 DT）评审命名空间
   之外的 wiki 写入。
-- **DT 评审引擎**：`open-code-review`（ocr，委派模式，diff `--from TARGET_BRANCH --to <特性分支>`）
+- **DT 评审引擎**：`open-code-review`（ocr，委派模式，diff `--from <目标分支> --to <特性分支>`）
   → 回退 `superpowers code-review` → 两者都不可用才 block `review-tool-unavailable`。
 - `review_evidence` 必须通过 `validateReviewEvidence`，否则评审卡无法完成：PT 需要
   verdict + issues + 计划引用；DT 额外需要 test（通过时退出码 0）、build/typecheck、
@@ -250,15 +250,16 @@ D 只有带 `tdd` 才能完成——`test_files`（含 `test_first`）或 `skipp
 
 机械性链路完成规则触发时，两个闸门在 `chain/completed` 钩子中运行：
 
-1. **完成审计闸门（D23）**：`ChainAuditor` 交叉核对链路工作区中是否存在已知任务输出
+1. **完成审计闸门**：`ChainAuditor` 交叉核对链路工作区中是否存在已知任务输出
    之外的产物。发现孤儿写入即发出 `chain/audit-warning`；UI 显示警告横幅并阻塞最终
    汇报，直到人类确认归属（`chain/audit-confirmed`，仅限人类）。
-2. **合并闸门（DT 通过后的系统合并）**：D 从不合并到 `TARGET_BRANCH`，也不推送它——
-   D 只提交到（可选推送）自己的特性分支，并在交接中携带 `branch`。DT 批准且链路完成后，
-   `merge-gate.ts` 以 `system` 身份执行：`git checkout TARGET_BRANCH → git merge --no-ff
-   <feature-branch> → git push`。结果以幂等评论记录：`[merge-done]`（带 hash）、
-   `[merge-skip]`（合并输入无法解析）、`[merge-failed]`（checkout/merge/push 失败，例如
-   冲突）。失败绝不抛错——坏合并*不执行*，这是安全方向；人类事后可修复。
+2. **合并闸门（DT 通过后的系统合并）**：D 从不合并到目标分支，也不推送它——D 只提交到
+   （可选推送）自己的特性分支，并在交接中携带 `branch`。目标分支是规格中声明的分支
+   （V 写入 D 任务体）。DT 批准且链路完成后，`merge-gate.ts` 以 `system` 身份执行：
+   `git checkout <目标分支> → git merge --no-ff <特性分支> → git push`。结果以幂等评论记录：
+   `[merge-done]`（带 hash）、`[merge-skip]`（合并输入无法解析）、`[merge-failed]`
+   （checkout/merge/push 失败，例如冲突）。失败绝不抛错——坏合并*不执行*，这是安全方向；
+   人类事后可修复。
 
 ---
 
@@ -340,10 +341,10 @@ flowchart TB
 
     subgraph Dispatcher ["dispatcher/"]
         WAKER["event-waker (events → wake V)"]
-        VORCH["v-orchestrator (R20 phase machine)"]
+        VORCH["v-orchestrator (phase machine)"]
         RUNNER["agent-runner (one-shot role sessions, presets, ToolGuards)"]
         WD["watchdog (heartbeat / stale reclaim / circuit)"]
-        AUDIT["chain-auditor (D23 completion audit)"]
+        AUDIT["chain-auditor (completion audit)"]
         MG["merge-gate (post-DT system merge)"]
     end
 
@@ -381,7 +382,7 @@ flowchart TB
   单一权威的 `KanbanService` 门面。单测充分覆盖。
 - **集成层**（`src/tools/`、`src/routes/`）—— cordis 工具与路由：角色工具面、主会话
   工具（`kanban_route` + 只读子集）、`/kanban/*` HTTP/SSE 桥。
-- **调度层**（`src/dispatcher/`）—— 事件唤醒、R20 编排、一次性 agent 运行器（persona
+- **调度层**（`src/dispatcher/`）—— 事件唤醒、相位编排、一次性 agent 运行器（persona
   preset 挂载、模型候选链、ToolGuard 安装）、看门狗、链路审计器、合并闸门。
 - **角色层**（`src/roles/`、`personas/`）—— 安装到 `$DSH_HOME/.agent-presets/` 的裁剪
   preset、每角色工具装配、写保护逻辑。
@@ -414,14 +415,14 @@ python tests/e2e/gui-check.py --url http://127.0.0.1:3080/
 ### 已实现（v0.1.0）
 
 - [x] 事件溯源领域 + 确定性状态机（红队回放）
-- [x] 6 角色 R20 管线 + 裁剪 preset + 会话绑定权限
+- [x] 6 角色相位管线 + 裁剪 preset + 会话绑定权限
 - [x] 交付契约 + 评审证据闸门 + 返工生命周期
 - [x] TDD 硬闸（D `tdd` 交接 + DT `test_first` / `runner=vitest` 核验）
 - [x] 协议违规恢复、心跳看门狗、失败熔断
-- [x] 链路完成审计闸门（D23）+ 人工确认
+- [x] 链路完成审计闸门 + 人工确认
 - [x] DT 通过后合并闸门（D 只推送特性分支）
 - [x] 阶段 0 规划清单 + `file-prefetch` 附件
-- [x] GUI 链/任务改名 + 整链删除（T7，仅 human）
+- [x] GUI 链/任务改名 + 整链删除（仅 human）
 - [x] 模型候选链：静默回退 + High 推理强度
 - [x] 实时 SSE 看板标签页（对话 → 轨迹 → 看板）
 

package/client/TaskDrawer.tsx

@@ -1,6 +1,7 @@
 import { useState } from 'react';
 import type { Chain, Handoff, KanbanEvent, SpecCard, Task } from '../src/domain/types.js';
 import { statusLabelOf } from './workflow-model.js';
+import { foldTimeline } from './timeline-model.js';
 
 const ROLE_NAME: Record<Task['assignee'], string> = {
   v: 'orchestrator', p: 'planner', w: 'wiki-bridge', d: 'fullstack-dev', pt: 'plan-review', dt: 'impl-review',
@@ -138,11 +139,34 @@ export function TaskDrawer(props: {
       )}
       {tab === 'timeline' && (
         <section role="tabpanel">
-          <ol>
-            {timeline.map((event) => (
-              <li key={event.seq}><code>{event.kind}</code><span>seq {event.seq} · {event.author} · {event.at}</span></li>
-            ))}
-          </ol>
+          {(() => {
+            const items = foldTimeline(timeline);
+            return (
+              <ol className="dsh-kb-timeline">
+                {items.map((item, i) => (
+                  <li
+                    key={item.seq}
+                    className={`dsh-kb-timeline__item dsh-kb-timeline__item--${item.status}${i === 0 ? ' dsh-kb-timeline__item--latest' : ''}`}
+                    data-exception={item.exception || undefined}
+                  >
+                    <div className="dsh-kb-timeline__axis">
+                      <span className="dsh-kb-timeline__dot" aria-hidden="true" />
+                    </div>
+                    <div className="dsh-kb-timeline__body">
+                      <div className="dsh-kb-timeline__row">
+                        <strong className="dsh-kb-timeline__label">
+                          {item.count ? `${item.label}（${item.count} 次）` : item.label}
+                        </strong>
+                        <time dateTime={new Date(item.at).toISOString()}>{formatTime(item.at)}</time>
+                      </div>
+                      {item.summary && <p className="dsh-kb-timeline__summary" title={item.summary}>{item.summary}</p>}
+                      <span className="dsh-kb-timeline__author">{item.author}</span>
+                    </div>
+                  </li>
+                ))}
+              </ol>
+            );
+          })()}
         </section>
       )}
       {tab === 'handoff' && (

package/client/kanban.css

@@ -511,6 +511,121 @@
 .dsh-kb-detail dd { margin: 0; }
 .dsh-kb-detail time { opacity: 0.6; font-size: 12px; margin-inline-end: 4px; }
 
+/* 轨迹 tab 可读化：物流式纵向时间轴（四态配色 + 最新节点高亮；异常整行标红） */
+.dsh-kb-timeline {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+}
+.dsh-kb-timeline__item {
+  position: relative;
+  display: grid;
+  grid-template-columns: 16px 1fr;
+  gap: 8px;
+  padding: 0 0 14px;
+}
+.dsh-kb-timeline__item:last-child {
+  padding-bottom: 0;
+}
+/* 纵向时间线：贯穿节点（最新节点上方线不延伸，模拟物流头节点） */
+.dsh-kb-timeline__axis {
+  position: relative;
+}
+.dsh-kb-timeline__item:not(:last-child) .dsh-kb-timeline__axis::after {
+  content: '';
+  position: absolute;
+  left: 50%;
+  top: 14px;
+  bottom: -4px;
+  width: 2px;
+  transform: translateX(-50%);
+  background: var(--dsh-kb-border);
+}
+.dsh-kb-timeline__dot {
+  position: relative;
+  z-index: 1;
+  display: block;
+  width: 10px;
+  height: 10px;
+  /* 水平居中于 16px 轴列（中心=8px），与 left:50% 连接线对齐 */
+  margin: 2px auto 0;
+  border-radius: 50%;
+  border: 2px solid var(--dsh-kb-surface);
+  box-sizing: border-box;
+  background: var(--dsh-kb-text-tertiary);
+}
+/* 四态配色：neutral 灰 / running 蓝 / success 绿 / exception 红 */
+.dsh-kb-timeline__item--running .dsh-kb-timeline__dot {
+  background: var(--dsh-kb-active);
+}
+.dsh-kb-timeline__item--success .dsh-kb-timeline__dot {
+  background: var(--dsh-kb-complete);
+}
+.dsh-kb-timeline__item--exception .dsh-kb-timeline__dot {
+  background: var(--dsh-kb-blocked);
+}
+/* 最新节点高亮：主色圆点放大 + 柔和辉光 */
+.dsh-kb-timeline__item--latest .dsh-kb-timeline__dot {
+  width: 12px;
+  height: 12px;
+  margin-top: 0;
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--dsh-kb-active) 22%, transparent);
+}
+.dsh-kb-timeline__item--latest.dsh-kb-timeline__item--success .dsh-kb-timeline__dot {
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--dsh-kb-complete) 22%, transparent);
+}
+.dsh-kb-timeline__item--latest.dsh-kb-timeline__item--exception .dsh-kb-timeline__dot {
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--dsh-kb-blocked) 22%, transparent);
+}
+/* 异常行：浅红底 + 左侧红条，摘要红加粗 */
+.dsh-kb-timeline__item--exception .dsh-kb-timeline__body {
+  background: color-mix(in srgb, var(--dsh-kb-blocked) 8%, transparent);
+  border-left: 3px solid var(--dsh-kb-blocked);
+  border-radius: var(--dsh-kb-radius-sm);
+  padding: 6px 8px;
+}
+.dsh-kb-timeline__body {
+  min-width: 0;
+}
+.dsh-kb-timeline__row {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+.dsh-kb-timeline__label {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--dsh-kb-text-primary);
+}
+.dsh-kb-timeline__item--success .dsh-kb-timeline__label {
+  color: var(--dsh-kb-complete);
+}
+.dsh-kb-timeline__item--exception .dsh-kb-timeline__label {
+  color: var(--dsh-kb-blocked);
+}
+.dsh-kb-timeline__summary {
+  margin: 2px 0 0;
+  font-size: 12px;
+  color: var(--dsh-kb-text-secondary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.dsh-kb-timeline__item--exception .dsh-kb-timeline__summary {
+  color: var(--dsh-kb-blocked);
+  font-weight: 600;
+}
+.dsh-kb-timeline__author {
+  display: block;
+  margin-top: 2px;
+  font-size: 11px;
+  opacity: 0.7;
+  color: var(--dsh-kb-text-tertiary);
+}
+
 .dsh-kb-spec-attachments {
   list-style: none;
   margin: 4px 0;

package/client/timeline-model.ts

@@ -0,0 +1,201 @@
+// client/timeline-model.ts — 轨迹 tab 纯投影（TDD）：事件 → 人类可读时间线条目。
+// 只做展示层派生，不触碰领域事件结构。
+import type { EventKind, KanbanEvent } from '../src/domain/types.js';
+
+/** 轨迹单条目：心跳折叠后的事件 + 展示派生字段。 */
+export interface TimelineItem {
+  seq: number;
+  kind: EventKind;
+  label: string;
+  author: string;
+  at: number;
+  /** 心跳折叠：连续心跳数量（非心跳条目为 undefined）。 */
+  count?: number;
+  /** 心跳折叠：末条心跳时间。 */
+  lastAt?: number;
+  /** 摘要（payload 关键字段），无可展示则为空串。 */
+  summary: string;
+  /** 异常事件（阻塞/失败/评审驳回/超限放弃/越权警告）醒目标红。 */
+  exception: boolean;
+  /** 状态语义（物流式四态配色）。 */
+  status: TimelineStatus;
+}
+
+/** 节点状态语义：neutral 常规 / running 进行中 / success 成功 / exception 异常。 */
+export type TimelineStatus = 'neutral' | 'running' | 'success' | 'exception';
+
+/** 异常事件全集（红系高亮）。 */
+const EXCEPTION_KINDS: ReadonlySet<EventKind> = new Set<EventKind>([
+  'task/blocked', 'task/failed', 'review/failed', 'review/gave-up', 'chain/audit-warning', 'chain/aborted',
+]);
+
+/** 四态状态映射：异常集优先，其余按成功/进行中/中性归类。 */
+const STATUS_OF: Record<EventKind, TimelineStatus> = {
+  'chain/created': 'neutral',
+  'chain/executing': 'running',
+  'chain/completed': 'success',
+  'chain/aborted': 'exception',
+  'chain/root-task-set': 'neutral',
+  'chain/audit-warning': 'exception',
+  'chain/audit-confirmed': 'neutral',
+  'chain/title-updated': 'neutral',
+  'spec-card/created': 'neutral',
+  'spec-card/edited': 'neutral',
+  'spec-card/approved': 'success',
+  'task/created': 'neutral',
+  'task/claimed': 'running',
+  'task/heartbeat': 'running',
+  'task/commented': 'neutral',
+  'task/completed': 'success',
+  'task/blocked': 'exception',
+  'task/unblocked': 'neutral',
+  'task/archived': 'neutral',
+  'task/failed': 'exception',
+  'task/renamed': 'neutral',
+  'review/passed': 'success',
+  'review/failed': 'exception',
+  'review/gave-up': 'exception',
+};
+
+export function timelineStatusOf(kind: EventKind): TimelineStatus {
+  return STATUS_OF[kind] ?? 'neutral';
+}
+
+/** kind → 中文动作标签（缺省回退裸 kind）。 */
+const KIND_LABEL: Record<EventKind, string> = {
+  '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': '评审超限放弃',
+};
+
+/** author id → 友好名（复用 ROLE_NAME 语义，system/human 另映射）。 */
+const AUTHOR_NAME: Record<string, string> = {
+  v: 'orchestrator', p: 'planner', w: 'wiki-bridge', d: 'fullstack-dev',
+  pt: 'plan-review', dt: 'impl-review', system: '系统', human: '你',
+};
+
+export function eventLabelOf(kind: EventKind): string {
+  return KIND_LABEL[kind] ?? kind;
+}
+
+export function isExceptionEvent(e: KanbanEvent): boolean {
+  return EXCEPTION_KINDS.has(e.kind);
+}
+
+export function authorNameOf(author: string): string {
+  return AUTHOR_NAME[author] ?? author;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
+}
+
+/** 取字符串字段，缺失/非字符串返回 ''（优雅降级）。 */
+function strField(rec: Record<string, unknown>, key: string): string {
+  const v = rec[key];
+  return typeof v === 'string' ? v : '';
+}
+
+/** 截断长文本（>120 字），不截断短文本。 */
+function truncate(text: string, max = 120): string {
+  return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+
+/** 提取事件 payload 的展示摘要（按 kind 分支，缺失字段降级为空）。 */
+export function eventSummary(e: KanbanEvent): string {
+  const payload = asRecord(e.payload);
+  switch (e.kind) {
+    case 'task/completed': {
+      const summary = truncate(strField(payload, 'summary'));
+      return summary;
+    }
+    case 'task/blocked':
+    case 'task/failed':
+      return truncate(strField(payload, 'reason'));
+    case 'task/commented':
+      return truncate(strField(payload, 'body'));
+    case 'task/renamed':
+    case 'chain/title-updated': {
+      const from = strField(payload, 'from');
+      const to = strField(payload, 'to');
+      return from || to ? `${from} → ${to}` : '';
+    }
+    case 'review/passed':
+    case 'review/failed':
+    case 'review/gave-up': {
+      const evidence = asRecord(payload['evidence']);
+      const verdict = strField(evidence, 'verdict') || strField(payload, 'verdict');
+      const issues = Array.isArray(evidence['issues']) ? (evidence['issues'] as unknown[]).length : undefined;
+      const parts: string[] = [];
+      if (verdict) parts.push(`verdict: ${verdict}`);
+      if (issues !== undefined) parts.push(`issues: ${issues}`);
+      const reason = strField(payload, 'reason');
+      if (reason) parts.push(reason);
+      return truncate(parts.join(' · '));
+    }
+    default:
+      return '';
+  }
+}
+
+/** 相邻连续心跳折叠为一条（count + lastAt），其余事件原样透传；最新在上（seq 降序）。 */
+export function foldTimeline(events: KanbanEvent[]): TimelineItem[] {
+  const sorted = [...events].sort((a, b) => b.seq - a.seq);
+  const items: TimelineItem[] = [];
+  for (const e of sorted) {
+    if (e.kind !== 'task/heartbeat') {
+      items.push({
+        seq: e.seq,
+        kind: e.kind,
+        label: eventLabelOf(e.kind),
+        author: authorNameOf(e.author),
+        at: e.at,
+        summary: eventSummary(e),
+        exception: isExceptionEvent(e),
+        status: timelineStatusOf(e.kind),
+      });
+      continue;
+    }
+    // 与上一条（seq 更大、更晚）同为心跳 → 折叠计数
+    const prev = items[items.length - 1];
+    if (prev && prev.kind === 'task/heartbeat') {
+      prev.count = (prev.count ?? 1) + 1;
+      prev.lastAt = e.at;
+    } else {
+      items.push({
+        seq: e.seq,
+        kind: e.kind,
+        label: eventLabelOf(e.kind),
+        author: authorNameOf(e.author),
+        at: e.at,
+        lastAt: e.at,
+        count: 1,
+        summary: '',
+        exception: false,
+        status: timelineStatusOf(e.kind),
+      });
+    }
+  }
+  return items;
+}