kld-sdd 2.5.0 → 2.5.2

package/README.md

@@ -1,12 +1,87 @@
 # kld-sdd
 
-KLD SDD OpenSpec 项目初始化工具 - 一键初始化 AI 编辑器技能，支持完整的 SDD（规格驱动开发）研发工作流。
+KLD SDD OpenSpec 工程增强工具：一键初始化 AI 编辑器技能、语义化文档模板和本地本体运行时，支持完整的 SDD（规格驱动开发）研发工作流。
 
 ## 这是什么？
 
 **SDD（Specification-Driven Development）** 是一种以文档链驱动 AI 编码的研发方法：先写清楚"要做什么"，再让 AI 去实现，避免 AI 乱猜、反复返工。
 
-`kld-sdd` 帮你在项目中一键配置好这套工作流所需的全部 AI 技能，支持 **Cursor、Claude Code、CodeBuddy、Qoder、OpenCode、KunlunZhima、WorkBuddy、Codex** 等编辑器。
+`kld-sdd` 帮你在项目中一键配置好这套工作流所需的全部 AI 技能，支持 **Cursor、Claude Code、CodeBuddy、Qoder、OpenCode、KunlunZhima、WorkBuddy、Codex** 等编辑器。新模板和 Skills 会在产物生成时写入稳定编号与显式关系；本地运行时负责解析、对账和校验这些关系。
+
+## 本体语义闭环
+
+KLD-SDD 当前内置三项语义能力：
+
+1. 定义 Change、Capability、STMT、AC、Constraint、Design、Task、Artifact、DocumentSection、OntologySnapshot 的最小本体 Schema。
+2. 通过模板和 Skills 在产物生成时产生 `CHG/CAP/STMT/AC/CON/DES/TASK` 编号和显式引用。
+3. 将 Proposal→Spec→Design→Task 解析为本地工作态实例，并在 Check/Archive 阶段校验和固化。
+
+关系链示例：
+
+```text
+CHG contains CAP
+CAP contains STMT
+STMT acceptedBy AC
+STMT constrainedBy CON
+DES realizes STMT
+TASK implements DES / covers STMT / dependsOn TASK
+ART declares Entity
+Entity sourcedFrom SEC
+```
+
+每个本体实体使用双层身份：
+
+- `anchor`：`STMT-ORDER-005` 等人工可读编号，跨迭代保持稳定且删除后不复用。
+- `entity-id`：全局唯一 UUIDv7，同一逻辑实体跨迭代复用。
+- `version-id`：全局唯一 UUIDv7，每次 added/modified/removed 产生新版本；unchanged 复用历史版本。
+- `predecessor-version`：modified/removed 指向同一实体的直接前序版本。
+
+UUID 由本地命令生成，不依赖网络、机器号或中央 ID 服务：
+
+```bash
+node skywalk-sdd/log.cjs semantic-identity --delta-state=added
+node skywalk-sdd/log.cjs semantic-identity --delta-state=modified --entity-id=<uuid> --predecessor-version=<uuid>
+node skywalk-sdd/log.cjs semantic-identity --delta-state=unchanged --entity-id=<uuid> --version-id=<uuid>
+```
+
+项目级校验会同时扫描活动 Change 和 confirmed Archive：不同实体误用同一 UUID、同一版本 UUID 对应不同内容、modified/removed 前序版本断链或同 predecessor 并行分叉都会阻断 Check/Archive。Archive 只有在 manifest、正文 `facts_hash` 与 confirmed snapshot 一致时，才可成为继承来源。
+
+跨迭代 unchanged 不复制历史原文。当前 Spec 只保存实体 UUID、版本 UUID、来源路径、来源内容哈希和需要保留的显式关系；运行时从唯一 confirmed Archive 解析这些引用，与本次差量组成 Effective Graph。modified 实体也不会自动继承前序全部关系，未显式列入 inherited relations 的历史关系不会进入新版本。
+
+当前工作态 Schema 为 `kld-sdd-ontology/v2`。完全没有语义锚点的旧自由文本仍可读取，但已包含 CHG/CAP/STMT/AC/CON/DES/TASK 锚点的 v1 产物需要补齐 UUID 身份字段后才能通过 v2 Check/Archive，避免工具在迁移时猜测实体身份。
+
+本地命令：
+
+```bash
+# 解析与诊断；首次运行会为 Artifact/DocumentSection 分配并持久化结构 UUIDv7 sidecar
+node skywalk-sdd/log.cjs semantic-scan --project=. --change=<name>
+
+# 文件与工作态本体实例全量对账
+node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>
+
+# 按 simple/full/strict 校验；通过时标记 pending
+node skywalk-sdd/log.cjs semantic-check --project=. --change=<name> --profile=full
+
+# 查看工作态实例
+node skywalk-sdd/log.cjs semantic-status --project=. --change=<name>
+
+# 可选的文件变化采集与同步
+node skywalk-sdd/log.cjs semantic-observe --project=. --change=<name>
+```
+
+`semantic-observe` 不是 Hook 替代品：它不能阻止 Cursor、Qoder 或人工编辑，也不能在落盘前控制内容。Observer 启动/重启后会重新对账，暂态失败和锁冲突不会推进文件指纹；Check 和 Archive 始终重新执行 `semantic-reconcile`，以处理重复、乱序或丢失的文件事件。
+
+校验 profile：
+
+| Profile | 阻断规则 |
+|---|---|
+| `simple` | 强制 STMT→AC；Design/Task 不存在时跳过 |
+| `full` | 强制 STMT→AC→Design→Task 全链和 Task DAG |
+| `strict` | 在 full 基础上要求完整语义来源 |
+
+同一 Change 的 observe/reconcile/check/archive 共用跨进程事务锁。工作态按 revision 目录一次性提交，再原子切换 `current.json`，读取时会拒绝 working/diagnostics/file-index 的 revision 撕裂。
+
+Archive 使用两阶段事务：先复制到 staging，从 staging 重新解析正文并生成 manifest、Spec 投影和带 UUIDv7 `OntologySnapshot` 实体的 `archive-ontology.json`，所有步骤成功后才切换为正式 archive。语义校验、快照、manifest 或 Spec 同步失败时，活动 Change 会保留或恢复，不留下伪 confirmed 半成品。
 
 ## 快速开始
 
@@ -38,9 +113,9 @@ opsx-propose → opsx-spec → opsx-design → opsx-task → opsx-check
 **AI 会做什么**：
 - 如果你没说清楚，AI 会主动问你 4 个问题（痛点/目标/影响模块/约束）
 - 推导出变更的 kebab-case 名称，如 `add-user-auth`
-- 生成 `propose.md` 并展示摘要让你确认
+- 生成 `proposal.md` 并展示摘要让你确认
 
-**产出**：`openspec/changes/<name>/propose.md`
+**产出**：`openspec/changes/<name>/proposal.md`
 
 ---
 
@@ -51,7 +126,7 @@ opsx-propose → opsx-spec → opsx-design → opsx-task → opsx-check
 **这是代码生成的唯一依据，必须精确无歧义。**
 
 **AI 会做什么**：
-- 读取 propose.md，检查上下文是否完整
+- 读取 proposal.md，检查上下文是否完整
 - 发现模糊描述时主动追问（如"高性能"→ 具体 QPS/RT 是多少？）
 - 向你确认 API 范围、性能指标、安全要求后，生成 `spec.md`
 
@@ -98,7 +173,7 @@ opsx-propose → opsx-spec → opsx-design → opsx-task → opsx-check
 - 100% 覆盖 design.md 的每个模块和接口
 - 每个任务有明确验收标准和单测要求
 
-**产出**：`openspec/changes/<name>/task.md`
+**产出**：Full 模式为 `openspec/changes/<name>/specs/<capability>/tasks.md`，Simple 模式为根目录 `tasks.md`
 
 ---
 
@@ -114,6 +189,7 @@ opsx-propose → opsx-spec → opsx-design → opsx-task → opsx-check
 | 完整性 | 4 个文档是否存在，每个文档章节是否完整 |
 | 一致性 | spec 的 API 在 design 中是否有对应方案；各文档字段命名是否一致 |
 | 可执行性 | task 的每个任务是否可独立执行；验收标准是否可验证 |
+| 本体追溯 | 编号是否唯一，STMT/AC/DES/TASK 关系是否完整，Task DAG 是否成环 |
 
 **发现问题时**，AI 会列出严重问题和警告，并提供三种处理方式供你选择。
 
@@ -176,10 +252,21 @@ kld-sdd-init --tool codex       # 仅配置 Codex
 ```
 your-project/
 ├── openspec-templates/              # openSpec 四文档参考模版
-│   ├── propose.md
+│   ├── proposal.md
 │   ├── spec.md
 │   ├── design.md
-│   └── task.md
+│   └── tasks.md
+├── skywalk-sdd/
+│   ├── log.cjs                      # Telemetry + semantic-* 命令入口
+│   ├── ontology/                    # 本地本体解析、校验、观察和对账运行时
+│   └── state/ontology/
+│       ├── .locks/<change>.lock     # observe/reconcile/check/archive 跨进程锁
+│       └── <change>/
+│           ├── current.json         # 当前 revision 原子指针
+│           └── revisions/<revision>/
+│               ├── working-ontology.json
+│               ├── diagnostics.json
+│               └── file-index.json
 ├── .cursor/
 │   └── skills/opsx-*/               # SDD skills（扁平一层）
 ├── .claude/