ns-living-spec

常驻规范整合器

维护 docs/specs/，使其始终反映产品的当前功能事实。

会话启动

参阅 ../../ns-harness/references/session-boot.md 和 ../../ns-harness/references/artifact-layout.md。

模式

模式	适用时机	事实来源	代码与交付门禁
Version（默认）	交付后完成版本收尾	docs/versions/{version_san}/sdd/ 工件	必需（Code Review: Approved 和 Delivery Review: Approved，两项评分均为 10）
Ad-hoc	ns-coder（或人工）在两项审核均为 Approved 后调用	{task_description} + 已批准的 git diff	必需（两项均为 Approved）
Appearance	由 ns-proto-creator 或 ns-proto-visual-guide 调用	指南/原型路径 + 简短的行为变更说明	无

如果调用方传入模式 appearance（或等效信息：指南/原型路径 + 行为变更说明，且没有审核结论），则为 Appearance。如果模式为 ad-hoc（或等效信息：没有 {version_san}，但有任务描述 + 已批准的 diff），则为 Ad-hoc。否则为 Version。

写入目标

与 Modes 正交（Modes 决定要记录什么以及适用哪些门禁）。决定写入位置：

目标	适用时机	写入内容
Direct	集成分支、分支角色未知，或 docs/specs/_pending/ 不存在（旧版仓库）	按照 Workflow 写入 docs/specs/{domain}.md + INDEX.md。如果 _pending/ 中有片段，先运行 Consolidate
Fragment	功能分支（../../ns-harness/references/artifact-layout.md → Branch role），且 docs/specs/_pending/ 存在	每个领域只新建一个文件：根据 references/pending-fragment.template.md 创建 docs/specs/_pending/{label}-{slug}.md。不得写入 docs/specs/ 下的其他内容
Consolidate	集成分支：收到明确要求，或 Direct 写入前	应用所有片段，然后删除片段（见 Consolidate）

原因：并行 MR 若编辑同一领域文件会发生冲突；彼此独立的新文件不会冲突。目录结构：../../ns-harness/references/artifact-layout.md → Living spec fragments。

Fragment 保留当前模式的所有门禁、跳过规则和领域映射步骤。只有步骤 2 会变化（将变更写入片段，而不是编辑领域文件），步骤 3 会跳过（仅在 consolidate 时修改 INDEX.md）。{slug} = 任务或问题的简短 kebab-case 名称；{label} = 模式的变更日志标签。使用 Living specs staged 报告（领域 + 片段路径）。

Consolidate

每个片段写入时已执行门禁——无需再次询问审核结论。

1. 列出 docs/specs/_pending/*.md；按文件名顺序处理（确保确定性）。
2. 对每个片段：完整读取目标 {domain}.md；应用需求/数据模型/端点变更；追加片段的变更日志条目，并附上其 label；如果领域文件不存在，则根据 references/domain-spec.template.md 创建。
3. 最后统一更新一次 INDEX.md（填写日期 + 每个受影响领域的版本）。
4. 只有在成功应用后，才删除每个片段。
5. 冲突（片段要更新或删除的需求已不存在，或已被较早的片段重命名）：不要猜测。保留该片段，并在报告中列出原因。
6. 报告：## Living specs consolidated — 已处理的片段、保留的片段（附原因）、已更新的领域。

仅在集成分支（或角色未知时）运行。切勿在功能分支上运行。

调用时机

• Code Review: Approved 且 Delivery Review: Approved 后进行版本收尾 — Version
• 临时编码，两项审核均为 Approved，且 docs/specs/ 存在 — Ad-hoc
• 创建/演进原型，或记录行为 UX 的规范性视觉指南 — Appearance
• 两项均未达到 Approved 时，不得使用 Version/Ad-hoc

前置条件

版本模式

• 已解析的 requirements.md — 优先查找 sdd/，否则查找旧版版本根目录（artifact-layout.md 旧版路径解析）
• 调用方报告 Code Review: Approved 和 Delivery Review: Approved — 无需 code-review-report.md
• 已解析的 execution-handoff.md — 优先查找 sdd/，否则查找旧版版本根目录（任务已完成）

临时模式

• docs/specs/ 已存在（不要从头创建目录树）
• 调用方报告 Code Review: Approved 和 Delivery Review: Approved
• {task_description} + 已批准的工作树差异（行为变更）
• 如果差异不涉及行为变更，则跳过（不写入任何内容）：外观调整、仅重命名、纯重构（未改变 API/架构/UX/领域行为）——报告跳过原因

外观模式

• 输入：外观指南路径和/或 prototype/ 界面 + 简短的行为差异（用户可以执行或看到的变化，或被捕获的内容）
• 如果 docs/specs/ 不存在，可以创建该目录和 INDEX.md
• 仅适用于产品可见的行为（流程、字段、状态、权限提示）
• 绝不要将 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

docs/specs/agent-architecture.md 是持续维护的 ADR（ns-agent-architecture），不是领域规范。不要将其视为 {domain}.md。

命名：使用英文、小写短横线格式、单数形式（user-profile.md）。涉及多个领域的功能应更新多个规范文件。

临时模式： 仅根据 {task_description} 和差异进行映射——不要臆造无关领域。

外观模式： 仅根据行为差异和指南/原型范围进行映射；如有帮助，可在外观文档的 Related / references 中添加领域链接。

2. 按领域处理

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

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

对于每项相关功能：

• 添加或更新 ### Requirement: 块（SHALL + 场景）
• 架构/API 发生变化时，更新 ## Data model 和 ## Endpoints（版本/临时模式）
• 外观模式：优先编写 UX/行为需求；不要臆造缺乏证据支持的 API/架构
• 追加 ## Changelog 条目：
  • 版本： **{version_san}** — {ISO date}: {summary}
  • 临时： **adhoc-YYYY-MM-DD** — {ISO date}: {summary}（根据任务和差异编写摘要）
  • 外观： **appearance-YYYY-MM-DD** — {ISO date}: {summary}

3. 更新 INDEX.md

创建或更新 docs/specs/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

片段目标：将标题替换为 ## 已暂存的持续维护规范，并列出 docs/specs/_pending/ 下的路径，而不是领域文件。

如果跳过（无行为变更、仅外观润色，或临时模式下缺少 docs/specs/）：

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

关键规则

• 规范内容使用英文
• 要求使用可验证的 SHALL 表述
• 修改现有规范前先阅读
• 规划协调器在制定新版本要求前先阅读 INDEX.md
• 临时任务不得在 docs/versions/ 下创建版本产物
• 临时任务不得臆造 {version_san}
• 外观模式不得将规范性的 Element|How 表格粘贴到规范中
• 外观模式不得要求 Code Review Approved
• 片段目标不得编辑 docs/specs/{domain}.md 或 INDEX.md；Consolidate 不得删除未完整应用的片段
• 不得覆盖 docs/specs/agent-architecture.md（ns-agent-architecture 是持续维护的 ADR）。agent.md 仅描述行为

相关技能

• ns-spec-driven — 规划时读取持续维护的规范（references/requirements-generator.md）
• ns-reviewer — Version/Ad-hoc 的前置条件：Code Review: Approved
• ns-judge — Version/Ad-hoc 的前置条件：Delivery Review: Approved
• ns-coder — 两项均获 Approved 后可调用临时任务
• ns-proto-creator / ns-proto-visual-guide — 可调用外观模式