文档生命周期

分类维度

文档同时具有可见性和生命周期，两者独立判断：

可见性	位置	Git 规则
本地	`workRoot`、`.craftkit/local/handoff/`	必须被忽略
共享	`designRoot`、`.craftkit/knowledge/`、`.craftkit/handoff/`	可作为普通项目资产评审和提交

生命周期	典型内容	完成时处理
过程	调研、计划、草稿、验证记录、临时报告	删除、延后或提炼后删除
长期	生效设计、决策、规范、可复用知识	保留并维护引用
归档	有审计或历史价值的完成态材料	通过 `doc:archive` 复制并验证

共享不等于长期，长期也不等于必须归档。文件按真实用途逐项分类，不能只根据所在目录推断。

长期文档状态

正式需求、生效设计、项目规范和长期知识在文档自身保存 reviewStatus，使本地任务记录删除后仍能判断有效性：

状态	含义	后续动作
`pending`	新建或实质修改后尚未审核	继续修改或按项目规则审核
`approved`	内容已经确认，可作为当前依据	持续使用并在变更时复核
`outdated`	已确认与需求、实现或新证据不一致	更新后回到 `pending`

项目已有 Frontmatter 或元数据格式时沿用；没有约定时使用最小 Frontmatter：

---
reviewStatus: pending
reviewedAt: null
replacedBy: null
---

新建或改变业务含义、外部契约、数据模型、关键流程及结论时设为 pending。
已有需求或设计审批可作为审核依据；通过后设为 approved 并记录日期，不重复建立审批流程。
排版、错字、链接修复和不改变含义的修订不改变审核状态。
已知内容不再符合事实时设为 outdated；更新完成后设为 pending，复审通过后恢复 approved。
旧文档没有状态时视为“尚未确认”。只在任务实际使用或修改时补齐，不能批量推断为 approved。
历史归档不使用 approved 冒充当前依据；发现错误时增加勘误或新版链接，保留当时快照。

持续维护

留存不是生命周期终点。每次任务开始时检索相关需求、设计、规范和知识；优先更新已有权威文档，避免创建同义平行版本。实现、接口、数据模型、业务行为或验证结论变化后，检查已关联及检索命中的长期文档：

受到影响的文档纳入当前任务并完成更新，实质修改后重新审核。
暂时无法更新时标为 outdated，在任务关闭清单中列为“延后”，说明影响和后续责任。
新版替代旧版时更新索引和引用；旧版按真实价值删除或归档，并使用 replacedBy 指向当前版本。
当前任务关联旧文档只表示本次负责检查或更新，不转移文档所有权，也不产生删除权限。

任务记录

首次向 workRoot/<task>/ 写入文档时创建 task.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",
      "relationship": "created",
      "disposition": "review"
    }
  ]
}

status 只使用 active、paused、ready_to_close、closed_pending_cleanup、closed。
purpose 只使用 process、long-term、archive；visibility 只使用 local、shared。
owner 使用稳定任务名。一个文件只登记一个主要任务；共同资产使用 shared，关闭时不得自动删除。
relationship 使用 created、updated、referenced；关联旧文档通常使用 updated 或 referenced，不能据此取得删除权限。
disposition 使用 review、keep、distill、archive、delete、defer。
路径使用项目相对正斜杠，必须位于项目根内。task.json 本身不加入 files。
旧任务没有记录时，可以根据同一任务目录和 Git 状态生成候选清单，但所有归属均标记为待确认。

业务 Skill 直接写入过程文档时，只负责创建或更新上述记录，不修改项目级默认策略。共享文档位于 designRoot 时也登记在本地任务记录中，使关闭流程能够追踪，但审核状态保存在共享文档自身，文档保持正常 Git 可见。

状态流转

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 只表示登记文件已按确认清单处理且剩余引用有效；外部验收未完成时不得借此声称功能已验收。

关闭流程

核对任务完成证据、未完成事项和实际验证，并检查本次影响的长期文档已同步；需要作为当前依据的文档必须为 approved，决定是否进入 ready_to_close。
读取 task.json、登记文件、任务目录、Git 状态和指向这些文件的项目内引用。
将每个文件分入“保留、沉淀、归档、删除、延后”，说明依据、目标位置和 Git 影响。
distill 只处理经确认且可复用的知识；写入成功并校验后，来源文件才可继续进入删除候选。
archive 只处理有历史或审计价值的材料；目标复制与校验成功后，来源文件才可继续进入删除候选。
更新会因删除失效的索引和链接，检查共享或已跟踪文件的差异。
展示精确清单。配置为 preview 时在此停止；已有明确删除授权时进入 closed_pending_cleanup 并处理清单。
删除仅限已确认的精确文件，不得使用递归通配清理未枚举内容。除 task.json 外目录为空且记录无需保留时，才把任务记录作为单独清理项再次确认。
验证剩余文件、引用、Git 状态、忽略状态和归档目标，再将状态更新为 closed；若任务记录也获准删除，先完成状态验证再删除记录和空目录。

清理保护

.craftkit/local/config/、.craftkit/project.json 和个人机器配置永久排除在任务清理之外。
未登记文件、归属冲突、未验证知识、归档失败和断链风险一律进入“延后”。
localRetentionDays 只提示过期候选，不能跳过预览或授权。
trackedFiles 为 review-required 时，删除共享或已跟踪文件必须逐项列出；当前仅支持该值。
Git 历史可保留已提交文档的旧版本，但不能代替删除前的当前引用检查。
pending 或 outdated 的长期文档不能作为有效基线直接保留；不能及时处理时进入“延后”。

Worktree 联动

移除额外 Worktree 前，除普通 Git 状态外还要检查 workRoot 下该任务记录和 ignored 文件。存在 active、paused、ready_to_close 或 closed_pending_cleanup 任务，或存在未登记的忽略文件时，Worktree 标记为清理受阻。先执行关闭预览；用户明确选择保留现场时继续保留 Worktree。

7.5 KiB Raw Blame History Unescape Escape