ns-sdd-living-spec-consolidator

现行规范整合器

将 {specs_root}/ 维护为产品当前功能的真实依据。

默认 {specs_root} = {product_root}/docs/specs/。

Harness 发现

参见 ../ns-harness/references/harness-discovery.md 和 ../ns-harness/references/artifact-layout.md。

模式

模式	适用时机	真实依据	代码审查关卡
Version（默认）	交付后完成版本收尾	docs/versions/{version_san}/ 工件	必需（Approved）
Ad-hoc	ns-code-coder（或人工）在 Code Review: Approved 后调用	{task_description} + 已批准的 git diff	必需（Approved）
Appearance	由 ns-proto-creator 或 ns-proto-visual-guide 调用	指南／原型路径 + 简短的行为变化说明	无

当调用方传入模式 appearance 时（或等效情况：提供指南／原型路径 + 行为变化说明，且没有审查结论），判定为 Appearance。当模式为 ad-hoc 时（或等效情况：没有 {version_san}，且提供任务描述和已批准的 diff），判定为 Ad-hoc。其他情况均判定为 Version。

调用时机

• 版本收尾后（Code Review: Approved 之后）—— Version
• 临时编码通过 Approved 审查且已有 {specs_root}/ 后—— Ad-hoc
• 创建／演进原型或编写记录行为式 UX 的规范性视觉指南后—— Appearance
• 代码审查批准（结论为 Approved）之前，不得使用 Version／Ad-hoc

前置条件

Version 模式

• {product_root}/docs/versions/{version_san}/requirements.md
• 调用方报告 Code Review: Approved（分数 ≥ 9）——不要求提供 code-review-report.md
• {product_root}/docs/versions/{version_san}/execution-handoff.md（任务已完成）

Ad-hoc 模式

• {specs_root}/ 已存在（Ad-hoc 模式下不要从头创建目录树）
• 调用方报告 Code Review: Approved（分数 ≥ 9）
• {task_description} + 已批准的工作树 diff（行为变化）
• 如果 diff 不涉及行为变化，则跳过（不写入任何内容）：仅外观调整、仅重命名，或不改变 API／schema／UX／领域行为的纯重构——报告跳过原因

Appearance 模式

• 输入：视觉指南路径和／或 prototype/ 页面，以及简短的行为变化说明（用户可以执行／看到哪些新增、变化或已记录的内容）
• 如果 {specs_root}/ 不存在，可以创建该目录和 INDEX.md
• SHALL 语言仅用于产品可见的行为（流程、字段、状态、权限提示）
• 切勿将 Element | How it should appear 表格粘贴到领域规范中——改为链接至指南
• 跳过纯界面润色（间距、颜色调整、字体替换，且不改变行为）——报告原因
• 不要求 Code Review／Approved

工作流

所有模式均采用共享步骤 1–4。变更日志标签因模式而异。

1. 确定受影响的领域

将功能映射到规范领域（示例）：

功能区域	领域文件
身份验证、登录、RBAC	auth.md
用户、个人资料	users.md
计费	billing.md
通知	notifications.md
报告	reports.md
集成	integrations.md
Agent／图	agent.md

命名规则：使用英文、小写连字符形式、单数（user-profile.md）。涉及多个领域的功能需要更新多份规范。

Ad-hoc： 仅根据 {task_description} + diff 进行映射——不要添加与变更无关的领域。

Appearance： 仅根据行为变化说明和指南／原型范围进行映射；必要时，在外观文档的 Related／references 下添加领域链接。

2. 按领域

如果 {specs_root}/{domain}.md 不存在： 根据 references/domain-spec.template.md 创建

如果存在： 完整阅读；追加或更新——绝不盲目覆盖

针对每项相关功能：

• 添加或更新 ### Requirement: 块（SHALL + 场景）
• 当架构/API 发生变化时（Version/Ad-hoc），更新 ## Data model 和 ## Endpoints
• 外观：优先编写 UX/行为要求；避免臆造缺乏依据的 API/架构
• 追加 ## Changelog 条目：
  • Version： **{version_san}** — {ISO date}: {summary}
  • Ad-hoc： **adhoc-YYYY-MM-DD** — {ISO date}: {summary}（摘要来自任务 + diff）
  • Appearance： **appearance-YYYY-MM-DD** — {ISO date}: {summary}

3. 更新 INDEX.md

创建或更新 {specs_root}/INDEX.md：

# Domain specs — {product_name}

| Domain | File                 | Last updated | Versions      |
| ------ | -------------------- | ------------ | ------------- |
| auth   | `docs/specs/auth.md` | {date}       | {version_san or adhoc-YYYY-MM-DD or appearance-YYYY-MM-DD} |

4. 汇总报告

输出简短报告以便交接：

## Living specs updated
| Domain | Action | File |
...
Mode: {version|ad-hoc|appearance}
Requirements added: N
Requirements updated: N
New specs: N

如果跳过（非行为性、仅润色，或 Ad-hoc 缺少 {specs_root}/）：

## Living specs skipped
Reason: {missing specs_root|non-behavioral diff|chrome polish only}

关键规则

• 规范内容使用英文
• 要求使用可验证的 SHALL 表述
• 先读取再写入现有规范
• 规划协调器在制定新版本要求前应读取 INDEX.md
• Ad-hoc 不得在 docs/versions/ 下创建版本工件
• Ad-hoc 不得臆造 {version_san}
• Appearance 不得将规范性 Element|How 表格粘贴到规范中
• Appearance 不得要求 Code Review Approved

相关技能

• ns-sdd-requirements-generator — 规划时读取现有规范
• ns-code-reviewer — Version/Ad-hoc 的前置审批
• ns-code-coder — Approved 后可调用 Ad-hoc 模式
• ns-proto-creator / ns-proto-visual-guide — 可调用 Appearance 模式