93 lines
5.0 KiB
Markdown
93 lines
5.0 KiB
Markdown
# 文档生命周期
|
||
|
||
## 分类维度
|
||
|
||
文档同时具有可见性和生命周期，两者独立判断：
|
||
|
||
| 可见性 | 位置 | Git 规则 |
|
||
| --- | --- | --- |
|
||
| 本地 | `workRoot`、`.craftkit/local/handoff/` | 必须被忽略 |
|
||
| 共享 | `designRoot`、`.craftkit/knowledge/`、`.craftkit/handoff/` | 可作为普通项目资产评审和提交 |
|
||
|
||
| 生命周期 | 典型内容 | 完成时处理 |
|
||
| --- | --- | --- |
|
||
| 过程 | 调研、计划、草稿、验证记录、临时报告 | 删除、延后或提炼后删除 |
|
||
| 长期 | 生效设计、决策、规范、可复用知识 | 保留并维护引用 |
|
||
| 归档 | 有审计或历史价值的完成态材料 | 通过 `doc:archive` 复制并验证 |
|
||
|
||
共享不等于长期，长期也不等于必须归档。文件按真实用途逐项分类，不能只根据所在目录推断。
|
||
|
||
## 任务记录
|
||
|
||
首次向 `workRoot/<task>/` 写入文档时创建 `task.json`；已有记录时保守合并。推荐最小结构：
|
||
|
||
```json
|
||
{
|
||
"schemaVersion": 1,
|
||
"task": "document-lifecycle",
|
||
"status": "active",
|
||
"createdAt": "2026-09-03",
|
||
"updatedAt": "2026-09-03",
|
||
"files": [
|
||
{
|
||
"path": ".craftkit/local/tasks/document-lifecycle/design.md",
|
||
"purpose": "process",
|
||
"visibility": "local",
|
||
"owner": "document-lifecycle",
|
||
"disposition": "review"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
- `status` 只使用 `active`、`paused`、`ready_to_close`、`closed_pending_cleanup`、`closed`。
|
||
- `purpose` 只使用 `process`、`long-term`、`archive`；`visibility` 只使用 `local`、`shared`。
|
||
- `owner` 使用稳定任务名。一个文件只登记一个主要任务；共同资产使用 `shared`，关闭时不得自动删除。
|
||
- `disposition` 使用 `review`、`keep`、`distill`、`archive`、`delete`、`defer`。
|
||
- 路径使用项目相对正斜杠，必须位于项目根内。`task.json` 本身不加入 `files`。
|
||
- 旧任务没有记录时，可以根据同一任务目录和 Git 状态生成候选清单，但所有归属均标记为待确认。
|
||
|
||
业务 Skill 直接写入过程文档时，只负责创建或更新上述记录，不修改项目级默认策略。共享文档位于 `designRoot` 时也登记在本地任务记录中，使关闭流程能够追踪，但共享文件自身保持正常 Git 可见。
|
||
|
||
## 状态流转
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> active
|
||
active --> paused
|
||
paused --> active
|
||
active --> ready_to_close
|
||
paused --> ready_to_close
|
||
ready_to_close --> closed_pending_cleanup
|
||
closed_pending_cleanup --> closed
|
||
closed_pending_cleanup --> ready_to_close: 清理受阻或范围调整
|
||
```
|
||
|
||
- `ready_to_close` 表示开发和所需验证已经结束，可以生成关闭预览。
|
||
- `closed_pending_cleanup` 表示分类清单已经确认，清理尚未完全验证。
|
||
- `closed` 只表示登记文件已按确认清单处理且剩余引用有效；外部验收未完成时不得借此声称功能已验收。
|
||
|
||
## 关闭流程
|
||
|
||
1. 核对任务完成证据、未完成事项和实际验证，决定是否进入 `ready_to_close`。
|
||
2. 读取 `task.json`、登记文件、任务目录、Git 状态和指向这些文件的项目内引用。
|
||
3. 将每个文件分入“保留、沉淀、归档、删除、延后”，说明依据、目标位置和 Git 影响。
|
||
4. `distill` 只处理经确认且可复用的知识；写入成功并校验后，来源文件才可继续进入删除候选。
|
||
5. `archive` 只处理有历史或审计价值的材料；目标复制与校验成功后，来源文件才可继续进入删除候选。
|
||
6. 更新会因删除失效的索引和链接，检查共享或已跟踪文件的差异。
|
||
7. 展示精确清单。配置为 `preview` 时在此停止；已有明确删除授权时进入 `closed_pending_cleanup` 并处理清单。
|
||
8. 删除仅限已确认的精确文件，不得使用递归通配清理未枚举内容。除 `task.json` 外目录为空且记录无需保留时，才把任务记录作为单独清理项再次确认。
|
||
9. 验证剩余文件、引用、Git 状态、忽略状态和归档目标，再将状态更新为 `closed`；若任务记录也获准删除，先完成状态验证再删除记录和空目录。
|
||
|
||
## 清理保护
|
||
|
||
- `.craftkit/local/config/`、`.craftkit/project.json` 和个人机器配置永久排除在任务清理之外。
|
||
- 未登记文件、归属冲突、未验证知识、归档失败和断链风险一律进入“延后”。
|
||
- `localRetentionDays` 只提示过期候选，不能跳过预览或授权。
|
||
- `trackedFiles` 为 `review-required` 时，删除共享或已跟踪文件必须逐项列出；当前仅支持该值。
|
||
- Git 历史可保留已提交文档的旧版本，但不能代替删除前的当前引用检查。
|
||
|
||
## Worktree 联动
|
||
|
||
移除额外 Worktree 前，除普通 Git 状态外还要检查 `workRoot` 下该任务记录和 ignored 文件。存在 `active`、`paused`、`ready_to_close` 或 `closed_pending_cleanup` 任务，或存在未登记的忽略文件时，Worktree 标记为清理受阻。先执行关闭预览；用户明确选择保留现场时继续保留 Worktree。
|