Work item continuity

Work Item Continuity

用于显式维护需要持久连续性的 Work Item。目标是让复杂任务在新线程、派生线程或多仓现场中可恢复、可接力、可验证；跨线程本身不自动等于必须建档。它不改变 Memory 设置，不替代项目 AGENTS.md、KB 规则或工程事实源。

默认工作区：

/Users/lvxuyang/Library/Mobile Documents/iCloud~md~obsidian/Documents/KB/_工作区

先选择使用级别

级别	适用场景	默认动作
none	简单任务、单线程规划、一次性审计、小型机械修改、短文档治理，无明显恢复或接力成本	不创建 Work Item；按项目规则执行和收尾
attach	已有父 Work Item，当前线程只是其派生实施、验证或证据补充	只读父项当前快照和必要事实源，向父 owner 回传 evidence；默认不创建子 Work Item、不直接写父项
owned	专项可独立恢复、独立验收、独立交接，或确有 blocked、多仓协调、复杂验证、较长周期	创建或接管独立 Work Item，执行完整生命周期

先选最轻级别。一个连续工作流优先只有一个父 Work Item；T1 / T2 / T2.1 等派生线程默认使用 attach，由父 owner 聚合里程碑。只有专项能独立恢复、验收和交接时才升级为 owned。

建档阈值

跨线程、使用子代理或存在 parentThread 只是信号，不是充分条件。只有存在实质连续性成本时才使用 owned，典型条件包括：

• 中断后需要恢复较多决策、假设、验证状态或现场信息。
• 需要明确 owner 接力，或任务已 blocked 等待外部条件。
• 多仓、多模块联调，或复杂排查需要多轮假设和验证。
• 验收包含多阶段、跨环境或高复杂度验证。
• 周期较长，聊天记录不足以支撑可靠恢复。
• 专项具备独立目标、完成定义和交接边界。

默认使用 none：

• 简单问答、临时解释或一次性命令。
• 单线程可完成的规划、审计或短文档治理。
• 单线程内可完成的小型机械修改。
• 格式修正、机械文档调整、无接力价值的临时检查或审计。
• 仅需执行和回报结果、不会产生后续恢复成本的短任务。

禁止为了每个微小实施线程、验证切片或同步动作重复建档。已有父 Work Item 时，先判断能否 attach，不要因为新开线程就创建子 Work Item。

启动读取预算

新线程默认只读取：

• 项目最小启动卡片：项目 AGENTS.md 和仓库 KB 索引 / 入口。
• 本次目标、非目标和验收要求。
• attach / owned 对应 Work Item 的当前快照；默认不读完整事件日志。
• 2-4 个直接支持当前判断的代码、测试、文档、DB 或运行记录入口。

只有发生现场冲突、revision 争议、历史决策追溯或复杂恢复时，才按需读取事件日志。archive 默认只用于查重或恢复历史同类任务。不在提示词中重复粘贴完整 Skill、KB 规则、历史同步包或 Work Item 正文；传 ID、路径和本次必要摘录即可。

标准流程

1. mode

   • 先在 none / attach / owned 中选择。
   • none 不进入 Work Item 流程；attach 不创建新项；只有 owned 才继续 identify / discover / create。

2. identify

   • 先运行 scripts/identify-project.mjs 采集 cwd、Git root、common dir、脱敏 remote、branch、HEAD 和 dirty 摘要。
   • 项目识别歧义时停止自动创建，由 owner 根据用户目标、AGENTS.md 和任务范围确认。

3. discover

   • 创建前必须运行 scripts/find-work-items.mjs 搜索 active；只有查重或恢复历史同类任务时才查 archive。
   • 命中同一任务时 resume 或 reopen；目标相近但不同的任务互相链接，不合并成大杂烩。
   • 命中父 Work Item 且当前专项不具备独立恢复、验收和交接边界时，改用 attach。

4. create

   • 只有达到建档阈值且没有重复项时才创建。
   • 必须运行 scripts/create-work-item.mjs 创建，禁止手工复制模板绕过协议检查；创建脚本只接受 schemaVersion: 2 模板，发现 v1 或缺失版本时直接报错，不静默创建。
   • 设置唯一 owner、目标、非目标、完成定义和创建现场。
   • 当前快照四栏 bullet 总数最多 8 项，事实、假设、待验证和下一步/阻塞必须分开写。

5. resume

   • 先重读 Work Item，运行 validate-work-item.mjs --owner <owner> --revision <expected>。
   • 重新运行 identify 并核对现场 Git。现场与旧快照冲突时，以现场为准，追加“现场偏差”事件。
   • owner 不一致且没有明确 handoff 时，只读恢复，不写入；接管必须记录确认来源。

6. update

   • 只在关键验证、方向变化、阻塞、handoff 或 done 时更新，不记录每个命令、微小修改或每个派生线程状态。
   • 同一阶段的微小完成状态由父 owner 阶段性聚合，不要求逐切片追加事件。
   • 事件日志最多 10 条，超出后压缩为里程碑摘要。
   • owner 发生变化时同时写 previousOwnerThread 和 ownerTakeoverRef；后者必须指向可定位的本地 Markdown 文件及真实标题锚点，例如 KB/_工作区/00-说明.md#最近维护。
   • 事件 evidenceRefs 使用四类明确值：none、Command: <实际命令>、可定位的本地文件路径、或 thread: / commit 等非文件事实标识；不要把命令伪装成文件路径。
   • 写入前检查 owner 和 revision；成功写入后 revision 加 1。

7. done

   • 必须逐项核对完成定义。
   • 必须记录实际执行的验证、结果、未覆盖项和残余风险。
   • 必须再次采集最终 Git 现场。
   • 必须判断是否形成长期知识；Work Item 负责给出 kbImpact 判断，但创建或完成 Work Item 不自动触发长期 KB 修改。
   • 只有稳定功能逻辑、边界、决策、复用规则或长期 Runbook 进入 KB；lint 数字、临时 artifact、命令流水和事件日志留在 Work Item 或工程事实源。
   • kbImpact 必须稳定落入三类之一：已回灌、候选、或不回灌原因。
   • 必须写明接力信息或 none。

8. archive

   • 只能由 owner 在 done 后显式归档。
   • schemaVersion: 2 必须保留按时间发生的 done → archived 事件；最新 archived 事件的 actor 必须等于当前 ownerThread。
   • 归档前保留最终快照、实际验证、KB 影响和接力信息。
   • 错误完成时使用 reopened 事件回到 active，不覆盖原 done 记录。

校验版本与历史兼容

• 将 schemaVersion: 2 作为新协议和严格校验边界；不要按创建日期、更新时间或文件目录猜测协议版本。
• 将现有 schemaVersion: 1 保持为历史兼容项；不要为了满足新顺序补造 done、archived、handoff 或 takeover 历史。
• 对 v2 严格校验归档 actor、done → archived 顺序和事件本地 evidence 文件存在性；对 v1 的归档 actor 差异和缺失本地 evidence 只给兼容 warning。
• 对两版都强制校验 owner 接管链：存在 previousOwnerThread 时必须存在 ownerTakeoverRef，且该引用必须唯一定位到本地 .md 文件和实际存在的标题锚点；无法解析、文件缺失、路径歧义或锚点缺失都报错。
• 将已从 active/ 移到 archive/ 的同名历史 evidence 引用识别为 historicalActivePath，只给兼容 warning，不批量改写历史。
• 将已登记在 _工作区/evidence-path-migrations.json 的旧工程 evidence 路径解析到迁移后文件，分类为 migratedLocalPath 并给兼容 warning；目标文件必须真实存在。v2 映射使用 repoId + 仓内相对路径，仓库根目录默认允许 ~，也可用 WORK_ITEM_REPO_ROOT_<REPO_ID> 覆盖；只为历史兼容读取 v1 绝对路径映射。不得借映射掩盖普通缺失引用，也不得批量改写历史 Work Item 原文。
• 仅在历史项的真实事件和引用已经满足 v2 时人工将其升级为 schemaVersion: 2；否则继续保留 v1。

人工闸口

以下事项必须由 owner 明确判断，不交给脚本自动决定：

• 是否值得建档。
• 项目识别歧义和参考仓关系。
• owner 接管、revision 冲突和 iCloud 冲突合并。
• 某条内容属于事实、假设还是待验证。
• 验证是否足以进入 done。
• 哪些内容值得回灌长期 KB。
• 是否向长期线程实际发送同步包。
• 真实 provider、部署、发包、DB 写入、生产或准上线运维等高风险动作是否允许执行。

工程事实和同步边界

• 工程现场、代码、测试、DB、run record、case matrix、部署 release、public smoke 等事实优先于 Work Item、KB 摘要、聊天、同步包和 Memory。
• Work Item 保存任务连续性、恢复快照和 kbImpact 判断；不替代项目 KB、项目 AGENTS.md 或工程事实源。
• 通用 KB 方法论决定长期知识如何沉淀；项目 AGENTS.md 和项目 KB 入口声明项目级 KB 位置、回灌规则、fallback 和硬边界。
• 项目 KB 保存长期稳定知识，但需要证明时仍回到工程事实源；Memory、聊天和同步包只用于定向。
• 子代理只回传 evidence 摘要，不直接写同一个 Work Item。
• 派生实施 / 验证线程默认 attach 到父 Work Item，只回传 evidence；父 owner 决定是否更新里程碑。
• 长期线程只引用 Work Item ID、路径和当前结论，不复制事件日志。
• 同一阶段的微小完成状态可以聚合后再同步，不要求每个微切片都同步整体规划。
• 外部同步包固定使用 stableFacts / requestedAction / evidenceRefs / nonGoals / kbImpact / affectedThreads 六字段，只写稳定事实、动作请求和事实源入口。实际发送前先向用户展示目标和内容，等待确认。

脚本

在本 Skill 目录下运行：

node scripts/identify-project.mjs --cwd "$PWD"
node scripts/find-work-items.mjs --cwd "$PWD"
# 仅在查重或恢复历史同类任务时追加 --include-archive
node scripts/create-work-item.mjs --id "<WI-YYYYMMDD-slug>" --title "<标题>" --project "<project-id>" --owner "<owner>"
node scripts/validate-work-item.mjs --file "<work-item.md>" --owner "<owner>" --revision "<n>"
node scripts/update-work-item.mjs --file "<work-item.md>" --owner "<owner>" --expect-revision "<n>" --append-event validation --summary "<一句话>"

脚本只做确定性辅助：识别、搜索、v2 创建、校验、受控更新、revision 检查、事件上限压缩和 remote 脱敏。脚本不得修改 Git 工作区状态，不读取或输出 secret。

P2C 试点口径

• 项目映射只登记 P2C 四个执行仓和两个只读参考仓。
• 参考仓命中只表示关联，不自动判定为 P2C 任务。
• 3 个正式 $work-item-continuity 显式调用样本已通过，只证明脚本和生命周期可用，不提高 owned 建档阈值。
• agents/openai.yaml 继续保持 allow_implicit_invocation: false；不启用隐式自动调用。
• P2C 先按 none / attach / owned 选择最轻级别；跨线程本身不自动建档。
• attach 适用于已有父 Work Item 的派生实施 / 验证线程；默认只读当前快照并回传 evidence。
• owned 适用于可独立恢复、独立验收、独立交接，或确有 blocked、多仓协调、复杂验证、较长周期的专项。
• 不适用简单问答、单线程规划、一次性命令、小型机械修改、短文档治理和无接力价值的临时检查。
• P2C 复杂任务建档后，done 前仍需按 P2C KB 回灌协议和通用 KB 方法论判断 kbImpact，并区分已回灌、候选或不回灌原因。
• 高风险任务仍需单独确认：真实 provider、部署、发包、DB 写入、生产或准上线运维。