# Task Scope 规范

> 规范路径：`specs/task/task-scope.md`
> 状态：目标规范
> 范围：task scope、source scope 中的 task reference、parent task relation、task profile、task event、task scope message、owner_quote source refs、artifact、checkpoint、timeline projection、agent task authoring。
>
> 相关规范：
>
> - [`specs/task/board.md`](./board.md)
> - [`specs/task/task-timeline-messageization.md`](./task-timeline-messageization.md)
> - [`specs/task/embedded-view.md`](./embedded-view.md)
> - [`specs/task/collaborator-policy.md`](./collaborator-policy.md)
> - [`specs/task/agent-space-convergence.md`](./agent-space-convergence.md)
> - [`specs/message/scope-model.md`](../message/scope-model.md)
> - [`specs/message/delivery-runtime.md`](../message/delivery-runtime.md)
> - [`specs/collaboration/collaboration.md`](../collaboration/collaboration.md)

## 1. 产品目标

Task 是建立在 Scope 协作底座上的任务领域对象。Task 消息模型构建于 scope 消息模型之上，使 task 继承通用 message authoring、mention、reaction、read cursor、delivery、source reference、attachment、search 与 permalink 能力。每个 task 拥有自己的 canonical task scope。Channel、thread、DM 作为 source scope 发起 task，并通过 `#task_num`、task reference、task preview 与 task scope 建立连接。

Task scope 承载 task 的执行讨论、上下文、事件、交付物和协作消息。Parent task relation 形成 task tree；拥有 parent task 的 task 在展示层呈现为 subtask，并继续拥有自己的 task scope、task profile、task messages、typed activities 与 child tasks。Source scope 保留原位置对话，并通过 task reference 进入 task detail 与 task scope。

目标：

1. 每个 task 都拥有 canonical task scope。
2. Parent task relation 生成 task tree 与 subtask 展示。
3. Source scope 使用 task reference 指向 task scope。
4. Task scope 使用通用 `scope_messages` 保存协作消息。
5. Task timeline write 使用 TaskTimelinePlan 统一规划 message-backed item 与 typed activity。
6. Typed activity 通过统一 projection writer 写入 `scope_activity_events` 保存结构化任务事实。
7. Task profile 保存任务状态、来源、摘要和展示字段。
8. Timeline projection 组合 task scope messages 与 typed activities。
9. Mention、reaction、read cursor、delivery、search、permalink 复用 scope message 能力。
10. Board、source preview、search result、unread indicator 使用 task projection。
11. Task 只保存一个可空的 canonical `assignee`，Human 与 Agent 使用同一身份模型。
12. Activity 事实、协作消息和 attention delivery 分层；Watch、assignee 与本条消息 direct mention 共同决定当前事件的 attention recipients。

## 2. Scope 拓扑

与 task 相关的 scope 类型和关系：

| Scope 类型 | 职责 | 关键关系 |
| --- | --- | --- |
| Channel scope | 频道对话与频道内 task references | 可以发起 task，展示 `#task_num` |
| Thread scope | 话题对话与话题内 task references | 可以发起 task，展示 `#task_num` |
| DM scope | 私聊对话与私聊内 task references | 可以发起 task，展示 `#task_num` |
| Task scope | 单个 task 的执行空间 | 拥有 task profile、task messages、typed activities；拥有 parent task relation 时展示为 subtask |
| Parent task relation | task tree 关系 | 连接 parent task 与 child task；child task 继续拥有自己的 task scope 与 child tasks |

所有 task scope 共享 scope message 能力。Task reference 让 source scope 用户从原上下文进入 task scope。Parent task relation 让 task 在 board、detail、rollup 和 source preview 中形成层级展示。Owner_quote source refs 让 ordinary timeline 中的分享/转发消息展示来源消息、来源作者、分享者、引用快照与 jump-back。

## 3. 三层模型

| 层 | 职责 | 典型对象 |
| --- | --- | --- |
| Scope 协作底座 | 提供消息、成员、游标、delivery、reaction、source ref、permalink、search substrate | `scopes`、`scope_messages`、`scope_memberships`、`scope_message_reactions`、`scope_message_sources`、`scope_fanout_outbox` |
| Task 领域对象 | 提供 task profile、状态、协作者摘要、source refs、artifact、checkpoint、typed activity | task profile、task participants、task refs、task facts、typed activities |
| Task 派生读模型 | 提供高频读取、展示、搜索与 related-task preview | board card、source preview、timeline items、search docs、message-backed unread summaries、rollups |

Scope 协作底座处理通用协作能力。Task 领域对象处理任务语义。Task 派生读模型面向 UI、API、搜索、通知入口与 agent context。

## 4. Canonical 事实源

| 事实源 | 职责 |
| --- | --- |
| `scopes` | 保存 task 与 source scopes 的 identity、parent relation、seq 状态 |
| `scope_messages` | 保存 task scope 的普通协作消息 |
| `scope_message_sources` | 保存 message provenance、source scope、source message、ordinal、jump-back identity |
| `scope_message_reactions` | 保存 message reaction |
| `scope_memberships` | 保存 scope participant、visibility、message read cursor 与 activity cursor |
| `scope_activity_events` | 保存 typed activity projection 与 scope-local activity sequence；只能由 task timeline writer 写入 task event projection |
| `scope_fanout_outbox` | 保存 message / typed-activity attention 的稳定 recipient snapshot、human Inbox 更新、agent delivery / wake 与 realtime fanout work |
| `tasks` / `task_profiles` | 保存 task profile、task number、source anchor、parent relation、summary fields |
| task facts | 保存 context、artifact、checkpoint、handoff、lifecycle 事实 |
| attachment / URL / external target refs | 保存文件、链接、外部 target、外部证据与 workspace refs |
| task projections | 保存 board、source preview、search、timeline、message-backed unread summary 等读模型 |

Task scope message 保存人类可读协作内容。Typed activity 保存结构化任务事实，并由统一 task timeline writer 投影为 `scope_activity_events`。Task profile 保存任务状态。Task projections 从事实源生成面向读取的形态。`createdBy` 只回答谁创建了 Task；`executionOwner` 只回答哪个基础设施执行域拥有相关执行副作用；`assignee` 回答当前下一步由谁负责。三者不可互相回填或作为显示 fallback。

## 5. Task Profile

Task profile 是 task 的结构化 profile，服务 board、list、filter、routing、summary 与 agent context。

字段范围：

- `task_scope_id`
- `source_scope_id`
- `source_message_id`
- `parent_task_scope_id`
- child task summary
- `task_number`
- `task_reference_label`
- `title`
- `status`
- `priority`
- `labels`
- creator
- assignee（可空，Human / Agent）
- execution owner（执行基础设施所有权；不等于 assignee，也不参与 task attention recipient 选择）
- `description`
- acceptance criteria payload
- checklist / instruction payload
- `blocked_reason`
- source refs、URLs、workspace refs
- artifact summary
- checkpoint summary
- latest activity timestamp
- board fields 与 counters

`task_scope_id` 是 task 的 canonical identity。`parent_task_scope_id` 表达 parent task relation，并在展示层生成 subtask 形态。Child task summary 服务父 task 的 rollup 展示。`task_number` 与 `task_reference_label` 服务 source scope 展示与人类输入。Priority 与 labels 服务排序、过滤、分组与展示。Task body provenance 使用通用 message `ContributionSource` substrate：task source-thread anchor 产生 canonical `source`，其 `refType=message` / `refId=sourceThread.parentMessageId`，`kind` 由 canonical `createdByProfile` 判定；`sourceThread` 只保留为 jump-back/navigation projection，不作为 provenance source of truth。

## 6. Task Reference

Task reference 是 source scope 中指向 task scope 的可见引用，典型形态为 `#task_num`。Reference 可以展示为 chip、hover card、source preview 或 task card projection。

Task reference 提供：

- task number
- task title
- status
- assignee
- latest summary
- unread / mention indicator
- artifact badge
- task detail permalink

Source scope message 提到 `#task_num` 时，message 与 task scope 建立 reference。Reference 展示结合 source scope 可见性、task scope 可见性与 task participant relationship。

## 7. Task Scope Messages

Task scope message 使用通用 `scope_messages` schema。Task scope 与 channel、thread、DM 拥有同一组 message 基础能力：

- message id
- scope id
- seq
- workspace global seq
- author member id
- message runtime type
- content
- metadata
- attachments
- mentions
- reactions
- source refs
- created timestamp
- updated timestamp
- permalink
- read cursor

Task scope message 的 content 保存人类可读叙事：计划、问题、进展、证据说明、交接说明、决策说明，以及 human/agent 显式发送的提醒消息。Task scope message 的 metadata 保存通用 display data、source data、schedule/service-event refs 与 related event refs。

## 8. Task Timeline Writes And Typed Activities

Task timeline write 使用 `TaskTimelinePlan.TypedActivityIntents` 统一规划 typed activity side effects。计划区分 message-backed item 与 typed activity：message-backed item 使用 `scope_messages` 与 message plan；typed activity mutation 先写 task 事实，再只声明 typed event intent，由统一 task timeline writer 分配 event id、timeline seq、actor/source projection 并投影到 `scope_activity_events`，其中 `scope_id = task_scope_id`、`activity_ref_type = 'task_event'`。

两类 item 都可以产生 attention，但仍各自只有一个投递源：

- message-backed item 由 message plan / message outbox 保存 recipient snapshot 并投递；同事务创建的 `discussion_added` activity 只用于 timeline，不得再次投递；
- pure typed activity 由 activity writer 写入 `activity_event` outbox，保存同一事件的稳定 recipient snapshot；
- 两者都不得维护 task 专用 durable unread counter、恢复旧 Task Inbox projection，或调用 `internal/store/taskattention`。

Typed activity projection envelope：

- `id`
- `workspace_id`
- `scope_id`
- `seq`
- `activity_type`
- `activity_ref_type`
- `activity_ref_id`
- `source_message_id`
- `actor_member_id`
- `reason`
- `payload`
- `created_at`

Typed activity 类型示例：

- `task.created`
- `task.status_changed`
- `task.field_updated`
- `task.participant_updated`
- `task.blocked`
- `task.unblocked`
- `task.checkpoint_added`
- `task.artifact_added`
- `task.child_added`
- `task.completed`

Payload 保存展示快照与引用：

- task id、task number、title
- source scope id、source message id
- from / to values
- changed field names
- participant role
- artifact refs
- checkpoint refs
- related message ids

Typed activity 服务 timeline activity、audit、projection refresh、schedule/service-event source、agent context、task tree rollup 与当前事件 attention projection。Feature code 不得直接插入 `scope_activity_events`，不得自行分配 task event id / timeline seq，也不得直接计算一套旁路通知；它必须通过 `TaskTimelinePlan.TypedActivityIntents` / task timeline writer 表达 typed event intent，再由统一 attention planner 计算 recipients。

创建 Task 只有一个命令，可选 `assigneeRef`；不再存在 Create / Create and assign / Create and start 三种 mode。创建时带 assignee、后续 assign、claim（把自己设为 assignee）都写 canonical Task facts 与对应 typed activity。若该事件需要启动 Agent，Agent wake 由同一 attention recipient snapshot 派生，不创建 hidden `task_dispatch` message，也不依赖一套 assign/start 专用的公开语义。

## 9. Task Timeline Projection

Task timeline projection 组合两种 item，并支持 parent task 与 child task 的 rollup 展示：

| Item | 来源 | 展示 |
| --- | --- | --- |
| Message item | `scope_messages` | task discussion、agent/human 协作消息 |
| Activity item | `scope_activity_events` typed activity projection | status changed、field updated、artifact added、checkpoint added 等结构化事件 |

Timeline projection 使用统一 ordering、pagination cursor、author presentation、timestamp、permalink 与 grouping 规则。Activity item 展示为系统事实行。Message item 展示为协作消息卡片，并从 message authority 读取正文、reaction、附件、搜索与可见性。Parent task detail 可以展示 child task timeline summary 与 child task status rollup。Message metadata 可以引用 related event id，用于把协作消息与触发事件关联展示。

## 10. Task Facts

Task facts 围绕 source refs、artifact、checkpoint、handoff、lifecycle 与 projections 组织。每个 fact 都可以引用 task scope messages、typed activities、attachments、URLs、external targets 与 ordinary message source refs。

通用 task primitives 保存跨 stage 共享的材料：source refs、checkpoint、artifact、message、event、status 与 parent relation。Stage-specific 语义通过 artifact labels、checkpoint links、tags 与 projections 表达。

### 10.1 Owner Quote Source Refs

Owner_quote source refs 表达 Share/Forward 从 channel、thread、DM 或其他可读消息范围引入来源材料后的 provenance。来源材料必须落到一条具体 ordinary `owner_quote` message；provenance 保存在该消息的 `scope_message_sources` 上，而不是 task-owned source entry 或 task detail 中的独立来源列表。

Owner_quote source refs 保存：

- source scope id
- source message id
- source seq
- source author
- frozen quote
- share/forward actor
- created timestamp
- display owner_quote message id

Task timeline 与 task detail 如需展示来源，只渲染 ordinary `owner_quote` message 的 quote/source card、attribution 与 jump-back。Jump-back 仍受原 source message 的 readable predicate 校验；不存在 "add/manage context" 入口或 task-owned source list。

### 10.2 Checkpoint

Checkpoint 表达高信号进展与里程碑。

Checkpoint fact 保存：

- summary
- progress
- created actor
- created timestamp
- related task message ids
- related artifact refs
- related source refs

Checkpoint projection 提供 latest checkpoint summary、checkpoint count、board progress、evidence grouping 与 task detail section。

### 10.3 Artifact

Artifact 表达交付物、证据、文件、链接、外部 context 或输出目录。

Artifact fact 保存：

- title
- category
- payload
- attachment refs
- URL refs
- external target refs
- created actor
- created timestamp
- related task message ids

Artifact projection 提供 artifact list、artifact count、artifact card、evidence grouping 与 search fields。

### 10.4 Lifecycle and Handoff

Lifecycle fact 表达 status、claim、blocker、completion、field update 与 role update。Handoff fact 表达 human-agent 或 agent-agent 的 recipient、next step、evidence refs 与 context refs。

Lifecycle 与 handoff 的结构化变化写入 task event。人类可读说明保存在 task scope messages。Task profile 保存 profile 字段，projections 生成 latest activity、related-task preview 与 board summary。

## 11. Permissions and Membership

Task visibility 由 source scope visibility、task scope membership、task participant roles、owner-private grants 与 task policy 共同计算。

Task scope membership 支持：

- creator
- assignee
- watcher
- discussion author
- mentioned member
- collaborator / contributor
- task activity actor
- source participant grant
- owner-private participant grant

Task scope 的默认参与和通知语义如下：

- 创建 task 时，creator 立即成为 task scope member。
- 创建时设置 assignee、后续 assign / claim / reassign 时，当前 assignee 立即成为 task scope member。
- task discussion 发送者、正文中被 `@` 到的成员、被加入 task 的 collaborator / contributor、以及写入 task lifecycle / checklist / context / checkpoint / artifact activity 的 actor，都会成为 task scope member。
- 自动加入只表达可见性与参与上下文，不表达订阅。没有显式偏好时 Human 使用 `mute`，Agent 使用 `no-wake`。
- 显式 Watch 复用 `scope_notification_settings` 的 Task-only `task_watch_state` authority：Human 写 `active`，Agent 写 `auto-wake`；显式 Unwatch 写回 Human `mute` / Agent `no-wake`。Task 不增加 watchers 表。rolling deploy 期间同时镜像 legacy `state` 供旧节点读取，但新节点的 Task UI、Inbox 与 attention planner 只读 `task_watch_state`；旧节点覆盖 `state` 不得改变 v2 Watch。
- Web Task Detail 必须为当前具体 Task 提供显式 Watch / Unwatch 入口，并从上述 `task_watch_state` authority 读取和更新状态；打开、切换或关闭 Task Detail 本身不得隐式改变 Watch 状态。
- Task Detail 的 Watch 入口同时展示完整显式 watcher count 与 bounded avatar preview；完整名单通过独立 cursor pagination 按需读取，不能把全量名单塞进 notification-policy GET / PUT。名单只投影 Human `active` 与 Agent `auto-wake`，不从 creator、assignee、mention、collaborator 或 activity 推断。
- Task Detail 的 Members Header badge 展示当前有效 Task scope membership 的去重总数，必须与显式 watcher count 分离；成员是否接收通知不得改变该 badge。
- 任何通过 canonical Task read gate 的 viewer 都看到相同的完整显式 watcher 名单与 count，包括 private Human / Agent；名单只返回安全的 AuthorProfile（类型、名称、头像与 canonical identity），不返回 visibility、owner、权限或 runtime metadata。已移除 / 归档 / 过期 membership 与 inactive principal 不进入名单。
- 完整 roster 可见性不扩大 mutation 权限：Human 只能改变自己的 Watch 状态；Agent Watch / Unwatch 只能由该 Agent 的 canonical owner 操作，其他 watcher 行保持只读。
- Watcher 分页是按稳定 keyset 排序的 live read，不是冻结快照；并发 display-name、Watch 或 visibility 变化可能改变后续页与 count，Web 每次显式打开名单时重新校验第一页，跨页重复项在客户端按 canonical identity 去重。
- assignee attention 是由当前 Task fact 派生的事件级责任，不写成持久 Watch。assignee 即使 Unwatch，仍会收到自己负责期间的后续事件；要停止该责任必须 reassign 或 unassign。
- 对一条已提交事件，attention recipients 固定为 `explicit watchers ∪ current assignee ∪ current message direct mentions − actor`。只有 message 有 direct mentions；typed activity 不从 payload 猜 mention。
- Direct mention 与 assignee attention 都可以穿透该 recipient 的 `mute` / `no-wake`，但不会改变其持久 Watch 状态。普通 participant、creator、commenter、activity actor 和 source-scope participant 不因 membership 自动成为 recipient。
- Human recipient 获得同一个聚合 Task Inbox row 的 unread；Agent recipient 获得同一个事件的 delivery / wake。Activity、Message、Inbox unread 和 Agent wake 是不同投影，不能通过合成消息或改变 membership 来互相代替。对 Human member-local Inbox，显式 `task_watch_state=mute` 只过滤当前 member 的精确 Task row；它不归档或删除 index/source，也不清除 unread、read cursor 或 Task timeline，重新 Watch 时复用既有 row。
- actor 不会因自己产生的 message 或 activity 通知 / 唤醒自己；self-filter 位于统一 attention planner，而不是通过改写其 notification setting 实现。
- parent task 与 subtask 拥有独立 task scope 与 Watch 状态；parent watcher 不自动扩散到 subtask。

Permission decisions 生成 task detail 可见性、task message authoring、task event visibility、task reference rendering、owner_quote source-ref jump-back 与 agent context eligibility。

## 12. Search and Attention

Search projection 组合 task profile fields、task scope messages、owner_quote source-ref quotes、artifact metadata、checkpoint summaries 与 task tree relation。Task profile browse/search 的 canonical query normalization、profile search SQL、scope visibility 与 task id resolution 由 `internal/store/taskboard` 统一拥有；message body search 继续由 message search substrate 负责。Taskboard browse/list/count/column query 必须先通过该 search owner 解析 task ids，再应用 status/filter/sort/cursor 规则；不能在 taskboard query builder 里拼 profile search SQL、`LIKE` 条件或 normalization。Web board/workbench 只能把 search query 作为 browse 参数交给后端并渲染返回页，不能在浏览器里重建 task profile search text 或二次过滤。

Related-task 和 search projections 组合 mentions、Task attention unread、reaction activity、status activity、blocker state、handoff state 与 artifact readiness。Human 的 Task attention 进入统一 Inbox 中一个按 task scope 聚合的 conversation row；message 与 typed activity 都只推进这一个 row，不生成每条 activity 一个 Inbox item。Inbox 提供 `Tasks` 分类，但分类只是统一 conversation index 的 filter，不是第二套 Task notification store。

Task reference、board card、workspace hub 与 agent delivery/read hints 使用同一组 projections。

## 13. Agent Task Authoring

Agent 在 task scope 中 author 普通协作消息，使用通用 message append path。Agent tool 对 task profile、facts、events 的修改使用 task domain commands。

推荐 authoring 形态：

| Agent 行为 | 写入 |
| --- | --- |
| 常规讨论、问题、说明、交接 | `scope_messages` |
| 状态、协作者、字段变化 | task profile + typed activity projection (`scope_activity_events`) |
| 阶段性进展 | checkpoint fact + related message/event |
| 交付物 | artifact fact + related message/event |
| 引入来源材料 | ordinary `owner_quote` message + `scope_message_sources` provenance |

Agent delivery/read context 包含 task profile、latest timeline projection、owner_quote source refs、artifact summary、checkpoint summary、relevant refs 与 active task target。