# 项目文件与进度留档

Hub 创建项目资料目录、保存角色文件、维护成员清单、更新进度、完成阶段交接、跳转、回退或结项时读取。Etunel 负责附件传输，本文件只约束收到文件后的项目内整理和可追踪性。

## 责任边界

- 各角色负责形成、检查并提交自己的专业成果文件。
- Hub 负责接收后校验、按阶段归档、维护成果索引和项目进度，不改写角色专业内容。
- 必要成果文件未保存、不可访问或无法确认版本时，不宣布正式阶段交接完成。
- 目录整理不是新的专业评审。模拟、受控跳转、回退或暂缓可以继续，但必须先记录缺失项、原因、风险和恢复条件。
- 不强制项目使用 Git。项目已有 Git 时可正常提交，但 Git 提交不是阶段门禁。

## 固定目录

Hub 在项目开始时建立：

```text
项目资料/
├── 00-项目管理/
│   ├── 项目概览.md
│   ├── 项目进度.md
│   ├── 成果索引.md
│   └── 项目成员清单/
├── 01-业务需求/
├── 02-产品定义/
├── 03-方案设计/
├── 04-项目规划/
├── 05-软硬件实现/
├── 06-测试验证/
├── 07-业务验收/
└── 08-发布结项/
```

每个实际发生工作的阶段按需建立：

```text
阶段记录.md
正式成果/<角色名>/
过程记录/
```

默认角色目录使用稳定的中文角色名。自定义角色使用 `etunel_list_roles` 返回的 `display_name`，去除目标文件系统不允许的字符；没有参与的角色不创建空目录。不得把文件散放到 `项目资料/` 根目录。

## 项目概览与已确认规则

`00-项目管理/项目概览.md` 保存项目名称、模式、流程基线、目标和当前项目已经确认的特殊规则。每条特殊规则写清内容、适用范围、决定权角色或负责人、确认依据和生效时间；Hub 只能登记有权负责人明确确认的内容，不能把自己的推断写成规则。

项目规则持续有效，直到同一决定权人明确修改或取消。各角色只确认自己决定权内的规则：产品确认产品行为和验收边界，业务确认业务范围、客户联络和正式承诺，Hub 负责人确认其权限内的流程处理，专业角色确认本领域限制；改变既有正式基线时仍按《变更申请》处理。

## 项目成员清单

项目创建完成、首个正式任务派发前，Hub 调用 `mcp__etunel__etunel_list_roles`。角色增加、替换或关系变化后重新查询。每次把同一份返回快照保存为：

- JSON 事实版：保留工具实际返回的 `role`、`display_name`、`relationship`；
- HTML 中文阅读版：用中文表头展示相同事实；
- 可额外记录项目名称、清单版本和导出时间。

文件放入 `00-项目管理/项目成员清单/` 并版本化，不覆盖历史版本。工具未返回的 member ID、session ID、人员姓名或负责人 ID 不得补造；凭据不得进入清单。成员清单是项目过程记录，不替代阶段 4 的《角色分工》。

## 文件归档与版本

- Hub 校验并接受的文件放入当前阶段的 `正式成果/<角色名>/`。
- 有复盘价值的草案、退回材料、问题说明、会议决定、变更、豁免和阻塞资料放入 `过程记录/`。
- 普通问答、空确认、重复副本和没有改变行动的临时文件不留档。
- 已接受版本不得覆盖。新版本保留旧版，并在 `成果索引.md` 写明当前有效版本、旧版及替代关系。
- 文档类正式成果只有在范围、行为、验收、接口、专业决定或下游行动发生实质变化时才创建新版本。状态、转交、排版、相同副本和不改变结论的过程说明不升正式版本；有复盘价值时写入阶段记录。代码、固件、硬件、配置和构建物仍按本领域规则区分实际版本。
- 固件、源码包、设计源文件等有既定文件名的技术成果保留原文件名，通过版本目录或成果索引区分版本。
- `成果索引.md` 至少写明中文成果名、阶段、主责角色、文件位置、版本、确认状态、当前适用性和被替代关系。
- 每项成果只标记一个当前有效版本。下游默认只接收该版本；旧版和过程材料继续留存，但不参与当前完成判断，除非被明确恢复为有效版本。

## 项目进度与阶段记录

`00-项目管理/项目进度.md` 是当前状态快照，使用简洁中文说明：当前阶段、已完成事项、正在进行事项、实际阻塞、下一步、责任角色和更新时间。

每个阶段开始时，在 `阶段记录.md` 写下简短的“本阶段完成约定”，分为本阶段必须完成、后续阶段处理和当前不需要；它不是新的正式成果。此后按时间追加有复盘价值的事件：任务波次开始、成果接收、影响进度的退回、阻塞与解除、重要决定、变更、门禁和阶段交接。每条记录写清发生了什么、相关文件、影响和下一步，不转存完整聊天或大段日志。

在以下事件后更新：

- 项目创建；
- 正式任务或任务波次开始；
- 角色成果被接受，或退回会改变进度；
- 阻塞发生或解除；
- 重要决定、变更或成果豁免生效；
- 阶段交接、受控跳转、回退、暂缓或结项。

Etunel 的排队、送达、普通回复和空确认本身不触发留档。

## 阶段交接、跳转与回退

正式阶段交接前，Hub 确认本阶段必须完成的适用成果已保存、版本可识别、负责人确认已记录、成果索引已更新，并在来源阶段写入阶段小结。小结说明完成内容、有效文件、未决项、后续依赖、风险、门禁结论和下一阶段。

本阶段门禁通过并完成上述留档后，Hub 及时结束本阶段并启动下一阶段，不等待未来阶段的全部资料提前齐备。下一阶段根据实际任务按需索取自己的输入；可选完善和后续依赖不能继续占用已经完成的阶段。

跳转、回退、暂缓或返工时：

1. 不删除、不移动、不覆盖原阶段记录和旧成果；
2. 在来源阶段记录离开原因，在目标阶段记录进入原因；
3. 更新 `项目进度.md` 指向当前实际阶段；
4. 新成果使用新版本，旧版本在成果索引中保留并标明是否失效或被替代；
5. 暂缓写明恢复条件和下一责任角色；
6. 模拟跳转明确标注“流程模拟”，不得混入正式成果。

## 与钉钉的顺序

Hub 先完成成果校验、文件归档、成果索引和项目进度更新，再根据已留档事实发送钉钉进度。钉钉发送失败不回滚留档，也不阻塞 Etunel 主流程。