kld-sdd 2.5.1 → 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/

package/kld-sdd-guide.html

@@ -810,7 +810,7 @@ npx kld-sdd">复制</button>
           <li>安装 CLI：<code>npm install -g @tencent-ai/codebuddy-code</code></li>
           <li>在项目目录运行 <code>codebuddy</code>，企业环境选择 Enterprise Domain 登录</li>
           <li>输入 <code>/opsx-propose &lt;变更名&gt;</code> 开始 SDD；<code>/skills</code> 查看已加载技能</li>
-          <li>初始化后运行 <code>/hooks</code> 审核 SDD Hook Pack，审批后门禁生效</li>
+          <li>SDD Hook Pack 已随初始化自动生效（lint / 测试 / 危险命令门禁），无需额外配置</li>
         </ol>
         <div class="cmd">/opsx-propose add-user-auth</div>
         <p class="note">项目 Skills 在 <code>.codebuddy/skills/</code>，上下文文件为 <code>CODEBUDDY.md</code>。Windows 可用 <code>Alt+M</code> 切换权限模式；Hooks 比 Prompt 更可靠，适合 lint/test 门禁。</p>

package/lib/init.js

@@ -531,7 +531,7 @@ function deployProfileArtifacts(selectedTools = Object.keys(TOOL_CONFIGS), cwd =
       if (!hookResult.ok) {
         throw new Error(hookResult.error || `CodeBuddy Hook 部署失败: ${profile.configDir}/settings.json`);
       }
-      console.log(`   ✓ ${config.name}: 部署 Hook Pack（运行 /hooks 审核后生效）`);
+      console.log(`   ✓ ${config.name}: 部署 Hook Pack（自动生效）`);
     }
 
     if (profile.hookProvider === 'claude') {
@@ -830,6 +830,15 @@ function deployTelemetryDataDir() {
     console.log(`   ⚠️  Telemetry CLI 源文件缺失: ${telemetrySrc}`);
   }
 
+  const ontologySrc = path.join(pkgPath, 'skywalk-sdd', 'ontology');
+  const ontologyDst = path.join(dataDir, 'ontology');
+  if (fs.existsSync(ontologySrc)) {
+    copyDir(ontologySrc, ontologyDst);
+    console.log('   ✓ 部署 skywalk-sdd/ontology/（本地本体语义运行时）');
+  } else {
+    console.log(`   ⚠️  本体语义运行时缺失: ${ontologySrc}`);
+  }
+
   const worktreeFinishSrc = path.join(pkgPath, 'skywalk-sdd', 'apply-worktree-finish.cjs');
   const worktreeFinishDst = path.join(dataDir, 'apply-worktree-finish.cjs');
   if (fs.existsSync(worktreeFinishSrc)) {
@@ -837,7 +846,7 @@ function deployTelemetryDataDir() {
     console.log('   ✓ 部署 skywalk-sdd/apply-worktree-finish.cjs（Apply 收尾脚本）');
   }
 
-  console.log('   ✓ 调用方式: node skywalk-sdd/log.cjs start|end|metrics');
+  console.log('   ✓ 调用方式: node skywalk-sdd/log.cjs start|end|metrics|semantic-identity|semantic-reconcile|semantic-check');
   console.log('   ✓ Apply worktree: record-base 在 §1.5；收尾 apply-worktree-finish.cjs --change=<name>');
   console.log('✅ Telemetry 已就绪（数据存储在 skywalk-sdd/，无需配置 MCP）');
   return true;
@@ -1111,7 +1120,7 @@ async function main() {
     console.log('  ℹ️  KunlunZhima 通过 commands/skills 入口使用 SDD，未启用自动 Hook');
   }
   if (selectedTools.includes('codebuddy')) {
-    console.log('  🪝 .codebuddy/hooks/              # CodeBuddy SDD Hook Pack（运行 /hooks 审核后生效）');
+    console.log('  🪝 .codebuddy/hooks/              # CodeBuddy SDD Hook Pack（自动生效）');
   }
   if (selectedTools.includes('claude')) {
     console.log('  🪝 .claude/hooks/                 # Claude Code SDD Hook Pack（可选增强）');
@@ -1142,7 +1151,7 @@ async function main() {
   console.log('  3. 激活 opsx-check 验证文档质量');
   console.log('  4. 激活 opsx-apply 申请实施，opsx-archive 归档完成');
   if (selectedTools.includes('codebuddy')) {
-    console.log('  5. CodeBuddy 用户：重启会话后运行 /hooks 审核 SDD Hook，审批后门禁生效');
+    console.log('  5. CodeBuddy 用户：SDD Hook Pack 已随初始化自动部署，门禁自动生效，无需手动配置');
   }
   if (selectedTools.includes('kunlunzhima')) {
     console.log('  5. KunlunZhima 用户：在 Craft 模式使用 /opsx:propose 等 OPSX 命令（.kunlunzhima/commands/opsx/）');

package/lib/tool-profiles.js

@@ -62,7 +62,7 @@ const TOOL_PROFILES = Object.freeze({
     rulesWiring: 'none',
     templateVariables: {
       SKILL_RUNTIME_DIR: '.codebuddy/skills',
-      HOOK_GATE_DESCRIPTION: 'CodeBuddy CLI 已部署 SDD Hook Pack（.codebuddy/hooks + settings.json）；运行 /hooks 审核后生效。',
+      HOOK_GATE_DESCRIPTION: 'CodeBuddy CLI 已部署 SDD Hook Pack（.codebuddy/hooks + settings.json），初始化后自动生效。',
       SHELL_GUIDANCE: 'CodeBuddy Hooks 在 Windows 上通过 Git Bash 执行；命令使用 node "$CODEBUDDY_PROJECT_DIR/..." 引用项目路径。',
     },
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.5.1",
+  "version": "2.5.2",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
     "kld-sdd-init": "bin/kld-sdd-init.js"
   },
   "scripts": {
-    "test": "node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs"
+    "test": "node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs"
   },
   "keywords": [
     "kld",
@@ -32,6 +32,7 @@
     "templates/",
     "kld-sdd-guide.html",
     "skywalk-sdd/index.cjs",
+    "skywalk-sdd/ontology/",
     "skywalk-sdd/apply-worktree-finish.cjs",
     "README.md"
   ]