| name | devbooks-ssot-maintainer |
| description | devbooks-ssot-maintainer：维护项目 SSOT 的"可寻址索引与派生进度视图"。用于"修改/同步 SSOT（上游或项目内）→ 生成可审计 delta → 同步 requirements.index.yaml →（可选）刷新 requirements.ledger.yaml"。通常由 `/devbooks:delivery` 在 `request_kind=governance` 路由下调用。注意：SSOT 初始化请使用 `brownfield-bootstrap`。 Use when this capability is needed. |
| metadata | {"author":"darkbluelr"} |
DevBooks：SSOT Maintainer（索引账本维护闭环）
渐进披露
基础层（必读）
目标：把"改 SSOT"从口头叙述升级为可机读、可审计、可裁判的闭环：ssot.delta.yaml → requirements.index.yaml →（可选）requirements.ledger.yaml。
输入：变更包路径、上游/项目内 SSOT 的引用锚点、以及本次变更的 delta。
输出：
<change-root>/<change-id>/inputs/ssot.delta.yaml（本次变更的最小机读输入）<devbooks-root>/ssot/requirements.index.yaml（真相：稳定 ID → anchor → statement）<devbooks-root>/ssot/requirements.ledger.yaml（派生缓存：进度视图，可丢弃可重建）
边界：- 不通读/不复制上游 SSOT 全库；只维护索引与引用锚点。
- 不改变
upstream_claims 的合同语义。
- 不负责 SSOT 初始化（初始化请使用
brownfield-bootstrap）。
证据：脚本输出日志、更新后的索引文件、（可选）ledger 刷新日志。
进阶层（可选）
适用：需要同时管理"上游 SSOT（外部目录）+ 项目级最小 SSOT 包"时的约束与最佳实践。
扩展层（可选）
适用：需要将 SSOT 维护纳入 Knife/Epic 切片（例如 slices[].ssot_ids）或更严格治理闸门时。
与 brownfield-bootstrap 的职责边界
| Skill | 职责 | 类比 | 触发时机 |
|---|
| brownfield-bootstrap | 创建 SSOT 骨架 | git init | ssot/ 不存在或为空 |
| ssot-maintainer | 维护 SSOT（增删改） | git commit | SSOT 已存在，需要变更 |
关键区分：
- 如果
<devbooks-root>/ssot/ 目录不存在或为空，应先使用 brownfield-bootstrap 初始化
- 本 Skill 只处理已有 SSOT 的增删改，不负责从零创建
SSOT 与 Spec 的区别
| 维度 | SSOT | Spec |
|---|
| 抽象层次 | 需求层（What） | 设计层（How） |
| 粒度 | 项目级 | 模块级 |
| 位置 | <devbooks-root>/ssot/ | <truth-root>/ |
| 内容 | 系统必须做什么 | 模块如何工作 |
详见 docs/SSOT与Spec边界说明.md
前置：配置发现（协议无关）
执行前必须按以下顺序查找配置（找到后停止）：
.devbooks/config.yaml（如存在）→ 解析映射（尤其是 paths.ssot）dev-playbooks/project.md（如存在）→ Dev-Playbooks 协议project.md（如存在）→ template 协议- 若仍无法确定 → 停止并询问用户
核心闭环（最小充分）
1) 确定 SSOT 来源（只索引，不复制）
- 若存在上游 SSOT 文档库：在项目
.devbooks/config.yaml 配置：
truth_mapping: { ssot_root: "SSOT docs/" }
- 若不存在上游 SSOT：确保
<devbooks-root>/ssot/SSOT.md 与 <devbooks-root>/ssot/requirements.index.yaml 存在
- 如果不存在，提示用户先运行
brownfield-bootstrap 初始化
2) 修改 SSOT（内容编辑）并产出 delta（机读）
你可以用 AI 讨论"要怎么改"，但最终必须落盘为 delta（禁止只留在聊天里）：
- 推荐落点：
<change-root>/<change-id>/inputs/ssot.delta.yaml
- 约束：
statement 必须是单行字符串（否则脚本会拒绝执行）
- 每条需求必须有稳定 id；若上游没有 id，可先在 delta 里生成新 id（或留空让脚本自动分配
R-###）
3) 同步索引（真相）
运行：
skills/devbooks-ssot-maintainer/scripts/ssot-index-sync.sh --delta <path> --apply
脚本会：
- 校验 delta 与现有索引（schema_version、唯一性、操作合法性）
- 对
requirements.index.yaml 执行 add/update/remove
- 失败则不写坏原文件
4) （可选）刷新进度账本（派生缓存）
若你需要"已做/未做"的可见性（仪表板/审计），可刷新：
skills/devbooks-delivery-workflow/scripts/requirements-ledger-derive.sh ...
注意：ledger 是 derived cache，可删可重建，不能当作 SSOT 采信。
推荐用法（通过 Delivery 统一入口）
当你的诉求是"修改 SSOT/同步索引/更新账本"，建议在 /devbooks:delivery 的输入里明确：
request_kind=governance- 变更类型：SSOT maintenance
- 受影响的 ssot_ids（如已知）
- 上游 SSOT 路径锚点（如果存在）
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
