技能：对齐工作项清单（Align Work-Item Manifest）

用途：当项目使用中央清单文件（如 docs/process-management/now/<slug>.md）登记相关制品时，检测清单文件与物理制品的漂移。

目的 (Purpose)

中央清单风格的项目为每个主题或 Now tier 条目维护一份清单文件（如 docs/process-management/now/<slug>.md）登记关联的 requirement / design / tasks / PR。清单容易漂移：文件新增未登记、文件删除未清除、清单列了但物理文件不存在。本技能只读检测这些漂移并输出对齐报告；维护由用户或下游工具完成。

v1.0.0 advisory-only：不自动写清单、不移动文件、不修改 frontmatter。

核心目标（Core Objective）

首要目标：准确检测清单-物理漂移并输出可操作的差异清单。

成功标准（必须全部满足）：

✅ 已扫描项目中所有符合清单 glob（默认 docs/process-management/now/*.md，可由 ARTIFACT_NORMS.md 覆盖）的文件；若无清单文件存在，明示项目未采用中央清单风格，停止并返回诊断
✅ 已对每份清单对比其声明的文件列表与物理文件的存在性
✅ 已输出三类漂移：悬挂引用（清单有，文件无）/ 未登记（文件有，清单无）/ 命名不符（文件路径与清单声明不一致）
✅ 未自动写任何清单或制品

验收测试：报告是否可被 plan-next 作为 G3 真相漂移直接消费？

范围边界（Scope Boundaries）

本技能负责：

清单扫描与物理文件存在性对比
漂移分类与报告产出
给出建议性修复步骤（不执行）

本技能不负责：

维护清单（用户或未来 v2.x 的自动维护机制）
链接模式识别（由 discover-docs-norms）
链接模式选择（由 define-docs-norms）
下游文件的实际创建 / 删除 / 移动

Handoff Point：漂移报告输出后，由用户手动修正清单 / 文件，或由 plan-next 的 G3 路由进一步路由到 align-planning / tidy-repo。

使用场景（Use Cases）

中央清单风格的项目定期健康检查
plan-next 报告 G3 漂移且检测到清单文件时的深入诊断
迭代收尾前清单盘点
从无清单迁移到中央清单风格后的初次对齐

行为（Behavior）

第 0 阶段：Norms Resolution

按 specs/artifact-contract.md §8 Runtime Norms Resolution Protocol 的 §8.2 / §8.3 / §8.5 实现：

读项目规范 → 确定本技能产出 work-item-manifest-alignment 的 path_pattern（默认 docs/calibration/work-item-manifest-alignment.md）
从规范读取 manifest glob 模式（默认 docs/process-management/now/*.md；可由 ARTIFACT_NORMS.md 覆盖）
前置检查：若 manifest glob 未匹配到任何文件，停止并输出诊断说明项目未采用中央清单风格
本技能为固定路径治理产出，不涉及路径之外的模式分支

第 1 阶段：清单扫描

按 Step 0 得到的 manifest 位置模式 glob 所有清单文件
对每份清单，解析其列出的子制品引用（requirement / design / tasks / PR）
构建清单声明映射：manifest → [declared_file_paths]

第 2 阶段：物理对比

对每个 declared_file_path 检查物理存在
扫描清单覆盖目录（如 requirements / designs / tasks 目录）列出所有实际物理文件
交叉对比：
- 悬挂引用：清单列但物理无
- 未登记：物理有但无清单列出
- 命名不符：清单声明 docs/foo/bar.md，实际文件在 docs/foo/bar-v2.md（模糊匹配同 slug）

第 2.5 阶段：漂移检测决策分支（Decision Branches）

分支 ID	触发条件	判定结果	报告动作
D1-no-manifest	manifest glob 无任何匹配	项目未采用中央清单风格	停止流程，返回诊断信息，不写报告文件
D2-declared-missing	`declared_file_path` 不存在	悬挂引用	记入“悬挂引用”分组，建议删除清单条目或补建文件
D3-physical-unregistered	物理文件存在但未被任何清单声明	未登记	记入“未登记”分组，建议追加到清单或归档文件
D4-slug-mismatch	清单路径不存在，但存在同 slug 的候选文件	命名不符	记入“命名不符”分组，建议更新清单路径或重命名文件
D5-consistent	清单声明与物理文件一一对应	无漂移	不记录问题，仅累计“已对齐项”计数
D6-parse-error	清单内容无法解析出声明路径	数据质量异常（非三类漂移）	记入诊断附录并标记需人工修复清单格式

判定优先级：D1 > D6 > D2/D4 > D3 > D5。当同一声明同时命中多个条件时，按优先级取首个分支，避免重复计数。

第 3 阶段：报告产出

写入 Stage 0 解析的路径（默认 docs/calibration/work-item-manifest-alignment.md）：

# 工作项清单对齐报告

**日期**：<ISO>
**清单数量**：<N>
**漂移总数**：<M>（悬挂 <X> / 未登记 <Y> / 命名不符 <Z>）

## 悬挂引用（清单有，文件无）

| 清单 | 清单声明路径 | 建议 |
|---|---|---|
| ... | ... | 删除清单条目 or 创建缺失文件 |

## 未登记（文件有，清单无）

| 文件 | 疑似所属清单 | 建议 |
|---|---|---|
| ... | ... | 追加到清单 or 归档文件 |

## 命名不符（同 slug，路径异）

| 清单声明 | 物理文件 | 建议 |
|---|---|---|
| ... | ... | 更新清单路径 or 重命名文件 |

输入与输出 (Input & Output)

输入：

项目路径（默认 CWD）
可选 manifest glob pattern（覆盖规范）
可选 artifact_norms_path

输出：

docs/calibration/work-item-manifest-alignment.md（默认）或规范声明的路径
机器可读漂移摘要（嵌在报告里作 YAML fence）供 plan-next 消费

限制（Restrictions）

硬边界（Hard Boundaries）

只读：v1.0.0 不写任何清单文件、不创建 / 删除 / 移动任何制品
无物理 manifest 文件时必须停止并诊断说明
不自行识别链接模式（依赖 discover-docs-norms 的产出）
不越权触发下游技能（tidy-repo / align-planning 由用户或 plan-next 路由）

技能边界 (Skill Boundaries)

动作	归属
模式识别	`discover-docs-norms`
模式选择	`define-docs-norms`
清单维护（自动）	未来 v2.x 或下游技能职责
文件归档 / 重命名	`tidy-repo`
规划漂移修正	`align-planning`

自检（Self-Check）

已按 Stage 0 Norms Resolution 读项目规范
已 glob manifest 文件；若无匹配，已停止并诊断（项目未用中央清单）
已扫描全部清单文件并对比物理
已分类三类漂移（悬挂 / 未登记 / 命名不符）
报告嵌入机器可读漂移摘要供 plan-next 消费
未自动修改任何清单 / 文件

示例（Examples）

示例 1：纯 manifest 项目健康检查

场景：项目使用中央清单风格；存在 3 份清单文件 docs/process-management/now/user-auth.md / billing.md / onboarding.md。

扫描发现：

now/user-auth.md 列了 docs/designs/user-auth.md，但该文件已被重命名为 docs/designs/2026-04-20-user-auth.md → 命名不符
now/billing.md 清单完整，所有文件存在 → 无漂移
docs/designs/onboarding-v2.md 存在但 now/onboarding.md 未列 → 未登记

输出：报告 2 条漂移；建议 now/user-auth.md 更新路径、now/onboarding.md 追加 onboarding-v2.md 条目。

示例 2：项目未采用中央清单（边缘场景）

场景：项目仓库里无 docs/process-management/now/*.md 或等价清单文件。

输出：Stage 0 前置检查不通过，停止并输出：

未检测到任何 manifest 文件（glob: docs/process-management/now/*.md）。
本技能适用于采用中央清单文件登记制品的项目；当前项目未见此风格文件。
如需启用，可手动建清单文件（例：docs/process-management/now/user-auth.md），再重跑本技能。

不写报告文件；返回诊断信息。

附录：输出合约 (Appendix: Output Contract)

本技能产出 Work Item Manifest Alignment Report（仅建议，不写入 manifest）：

元素	格式	必填字段	路径模式
报告主体	Markdown	front-matter；章节：摘要 / 三类漂移分组（registered_missing / unregistered_present / metadata_mismatch）/ 建议人工动作	docs/calibration/work-item-manifest-alignment.md
漂移条目	列表项	id / category / manifest_entry / artifact_path / evidence / proposed_action（advisory，不自动执行）	三类漂移分组下
机器可读块	YAML fenced `yaml drift_summary:`	counts{registered_missing,unregistered_present,metadata_mismatch}；items[] 每项含 id/category/artifact_path/proposed_action	报告末尾，供 plan-next 消费

align-work-item-manifest