# Work Item Continuity

> Use only when explicitly invoked with $work-item-continuity for complex work with material recovery cost, independent handoff needs, blocked state, multi-repo coordination, complex validation, or a long lifecycle. Do not use for simple cross-thread routing, small one-off work, pure Q&A, or routine evidence returns.

- Skill: `xylvvv/work-item-continuity` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add xylvvv/work-item-continuity`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xylvvv/work-item-continuity/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xylvvv (https://skillmd.com/u/xylvvv)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xylvvv/work-item-continuity

---


# Work Item Continuity

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

默认工作区：

```text
/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 目录下运行：

```bash
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 写入、生产或准上线运维。