kld-sdd 2.6.13 → 2.6.15

package/README.md

@@ -69,7 +69,7 @@ node skywalk-sdd/log.cjs semantic-status --project=. --change=<name>
 node skywalk-sdd/log.cjs semantic-observe --project=. --change=<name>
 ```
 
-`propose/spec/design/task` 在文档写入完成时就必须同步工作态 JSON，不等待 Check 或 Archive。各阶段的 `stage_end` 会自动执行一次 reconcile 作为无 Hook 环境的兜底；Skill 中的显式 `semantic-reconcile` 与该兜底幂等。每份 Markdown 的结构化结果写入 `openspec/changes/<name>/artifacts/<原相对路径>.ontology.json`，`openspec/changes/<name>/artifact-index.json` 与 `working-ontology.json` 提供统一索引与全量工作态视图；这些文件随 change 目录一起提交和归档。`skywalk-sdd/state/ontology/` 仅保留 revision 指针与跨进程锁，默认不提交。
+`propose/spec/design/task` 在文档写入完成时就必须同步工作态 JSON，不等待 Check 或 Archive。各阶段的 `stage_end` 会自动执行一次 reconcile 作为无 Hook 环境的兜底；Skill 中的显式 `semantic-reconcile` 与该兜底幂等。每份 Markdown 的结构化结果写入 `openspec/changes/<name>/artifacts/<原相对路径>.ontology.json`，聚合索引与全量工作态写入 `openspec/changes/<name>/ontology/`（含 `artifact-index.json`、`working-ontology.json` 等）；这些文件随 change 目录一起提交和归档。`skywalk-sdd/state/ontology/` 仅保留 revision 指针与跨进程锁，默认不提交。
 
 工作态 JSON 使用 `kld-sdd-working-artifact-facts/v1`，明确标记 `canonical=false` 和 `review_status=draft|pending`。它用于当前 Change 的渐进式展开、定向查询和跨文档校验，不能直接入知识库。Check 重新解析原文、校验并在全部通过时生成 pending revision；Archive 再次对账后才确认、转换为 `canonical-facts.json` 并打包。
 
@@ -83,7 +83,7 @@ node skywalk-sdd/log.cjs semantic-observe --project=. --change=<name>
 | `full` | 强制 STMT→AC→Design→Task 全链和 Task DAG |
 | `strict` | 在 full 基础上要求完整语义来源 |
 
-同一 Change 的作者阶段同步、observe、reconcile、check 和 archive 共用跨进程事务锁。`working-ontology.json`、diagnostics、file index、artifact index 及所有分文件 JSON 在 change 目录内原子提交，随后切换 `skywalk-sdd/state/ontology/<change>/current.json` 指针；读取时会拒绝任一文件缺失或 revision 撕裂。
+同一 Change 的作者阶段同步、observe、reconcile、check 和 archive 共用跨进程事务锁。`ontology/working-ontology.json`、diagnostics、file index、artifact index 及所有分文件 JSON 在 change 目录内原子提交，随后切换 `skywalk-sdd/state/ontology/<change>/current.json` 指针；读取时会拒绝任一文件缺失或 revision 撕裂。
 
 Archive 使用两阶段事务：先复制到 staging，从 staging 重新解析正文并生成本体快照、canonical facts、转换报告和 v2 manifest，所有步骤成功后才切换为正式 archive。归档完成后同时生成相邻的 `<日期>-<name>.zip`，其中 `archive-manifest.json` 的文件清单和 SHA-256 必须精确覆盖包内文件，可直接交给知识库消费。语义校验、快照、协议转换、打包或 Spec 同步失败时，活动 Change 会保留或恢复，不留下伪 confirmed 半成品。
 
@@ -104,24 +104,26 @@ npx kld-sdd
 
 初始化完成后，打开你的 AI 编辑器，激活 `opsx-*` skills 开始工作。
 
-### 提效评估报告（SkyWalk V3）
+### 提效评估报告（SkyWalk；单次变更为 v4）
 
-归档与独立 `report` 命令会基于同一 Report Model 生成 Markdown / HTML / JSON 三份同源产物（`schema_version=sdd-efficiency-report/v3`）。单次变更 HTML 使用桌面方案 A，只展示当前 change 的四个页签：概览、指标与阶段、问题与证据、产物与追溯，不混入跨变更趋势。
+归档与独立 `report --change=` 会基于同一 Report Model 生成 Markdown / HTML / JSON 三份同源产物（`schema_version=sdd-efficiency-report/v4`，指标契约 `4.0`）。**仅 change 级**破坏性删除公开 `legacy_metrics`、无折叠兼容附录；变更类型仅 `config|transaction|report|composite`。单次变更 HTML 使用桌面方案 A，只展示当前 change 的四个页签：概览、指标与阶段、问题与证据、产物与追溯，不混入跨变更趋势。
+
+`--period=biweekly|monthly` 等**项目/周期报告**仍使用既有长模板（可含历史兼容附录）。若要对 project 级同步去 legacy，须另开 change，勿在本发行中半迁移。
 
 报告中的业务名称优先于缩写：E1=每个验收场景平均用时，Q3=规约检查得分，P4=编码前检查覆盖，P-R=标准阶段重复次数，P-H=执行记录完整度。标准测量阶段固定为 propose、spec、design、task、check、apply、archive；test、explore 是辅助阶段，可展示但不进入效率分母。
 
 ```bash
-# 单变更报告（默认 html；可指定 markdown/json）
+# 单变更报告（默认 html；可指定 markdown/json）→ v4
 node skywalk-sdd/log.cjs report --project=. --change=<name> --format=json --output=reports/demo.json
 
-# 双周 / 月度周期对比（需完整窗口）
+# 双周 / 月度周期对比（需完整窗口）→ 仍为项目级模板
 node skywalk-sdd/log.cjs report --project=. --period=biweekly --date-from=YYYY-MM-DD --date-to=YYYY-MM-DD
 node skywalk-sdd/log.cjs report --project=. --period=monthly --date-from=YYYY-MM-DD --date-to=YYYY-MM-DD
 ```
 
 `propose` 须确认 `change-type`；所有阶段必须显式携带 change，历史 general 事件只能通过 `scope_link` 归属。`check_result` 应携带 reviewer 独立性与 warning 处置元数据；归档 `archive_result` 只列真实写入成功的 `report_path` / `report_html_path` / `report_json_path`。
 
-任务采用两个不可混淆的口径：“文档完成度”来自 tasks checkbox，“事件可追溯度”来自严格 task/test 证据。问题同时显示“类别数”和“规则命中次数”；指标同时显示“可计算性”和“可信度”。旧 E4/P1/P2/Q5 与旧 Q3 构建一次通过率仅出现在 legacy 区。
+任务采用两个不可混淆的口径：“文档完成度”来自 tasks checkbox，“事件可追溯度”来自严格 task/test 证据。问题同时显示“类别数”和“规则命中次数”；指标同时显示“可计算性”和“可信度”。change 级主视图不再渲染旧 E4/P1/P2/Q5；上述旧指标若仍出现，只可能在**项目级**兼容附录中。
 
 ---
 
@@ -286,11 +288,13 @@ your-project/
 │   └── changes/
 │       └── <name>/
 │           ├── proposal.md
-│           ├── working-ontology.json
-│           ├── artifact-index.json
-│           ├── diagnostics.json
-│           ├── file-index.json
-│           ├── ontology-identities.json
+│           ├── ontology/
+│           │   ├── working-ontology.json
+│           │   ├── artifact-index.json
+│           │   ├── diagnostics.json
+│           │   ├── file-index.json
+│           │   ├── ontology-identities.json
+│           │   └── continuity-resolution.json
 │           └── artifacts/
 │               ├── proposal.ontology.json
 │               └── specs/<capability>/

package/kld-sdd-guide.html

@@ -680,7 +680,7 @@ npx kld-sdd --version">复制</button>
         <div class="top"><span class="idx">01</span><h3>opsx-propose <span class="arg">&lt;变更名称&gt;</span></h3><span class="role">Why · 业务意图</span></div>
         <p>创建业务意图文档，明确“为什么做”。除痛点、目标、影响模块与约束外，还会让你确认 <b>Full / Simple 模式、测试策略和 change-type</b>（config / document / report / composite / other），并写入稳定的 <code>change-id</code>。</p>
         <p>若提供 REQ / FEAT 外部编号，会通过 <code>opsx-ontology-query</code> 做 Continuity 查询，识别新增、延续或迭代能力；不会把本地 archive 当成跨迭代权威。</p>
-        <div class="out">proposal.md + artifacts/proposal.ontology.json + working-ontology.json</div>
+        <div class="out">proposal.md + artifacts/proposal.ontology.json + ontology/working-ontology.json</div>
       </div>
 
       <div class="skill reveal" id="sk-spec" style="border-left-color:#38bdf8">
@@ -824,7 +824,7 @@ npx kld-sdd --version">复制</button>
       <article class="feature-card reveal">
         <div class="eyebrow">Materialize</div>
         <h3>写完即生成工作态事实</h3>
-        <p>propose/spec/design/task 每次写入后立即 reconcile，产出 <code>artifacts/**/*.ontology.json</code>、<code>artifact-index.json</code> 与 <code>working-ontology.json</code>，状态为 draft/pending，尚不能直接入库。</p>
+        <p>propose/spec/design/task 每次写入后立即 reconcile，产出 <code>artifacts/**/*.ontology.json</code>、<code>ontology/artifact-index.json</code> 与 <code>ontology/working-ontology.json</code>，状态为 draft/pending，尚不能直接入库。</p>
       </article>
       <article class="feature-card reveal">
         <div class="eyebrow">Traceability</div>
@@ -913,9 +913,8 @@ node skywalk-sdd/log.cjs semantic-observe --project=. --change=add-user-auth">
 │       │   ├── <span class="file">proposal.md</span>        <span class="cmt"># mode / change-id / change-type / test-strategy</span>
 │       │   ├── <span class="dir">specs/&lt;capability&gt;/</span> <span class="cmt"># Full：spec / design / tasks</span>
 │       │   ├── <span class="file">spec · design · tasks.md</span> <span class="cmt"># Simple：根目录三文档</span>
-│       │   ├── <span class="file">working-ontology.json</span>
-│       │   ├── <span class="dir">artifact-index/ · diagnostics/ · file-index/</span>
-│       │   ├── <span class="dir">ontology-identities/ · artifacts/**/*.ontology.json</span>
+│       │   ├── <span class="dir">ontology/</span>          <span class="cmt"># working-ontology · artifact-index · diagnostics · file-index · identities · continuity-resolution</span>
+│       │   ├── <span class="dir">artifacts/**/*.ontology.json</span>
 │       │   └── <span class="file">logs/execution-log.md</span>
 │       └── <span class="dir">archive/</span>
 │           ├── <span class="dir">&lt;date&gt;-&lt;name&gt;/</span>

package/lib/init.js

@@ -831,24 +831,22 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
     console.log(`   ⚠️  V3 指标模块源文件缺失: ${metricsV3Src}（report/metrics 可能无法加载 metrics-v3）`);
   }
 
-  const runtimeMetadataSrc = path.join(pkgPath, 'skywalk-sdd', 'runtime-metadata.cjs');
+  const packageVersion = require(path.join(pkgPath, 'package.json')).version;
   const runtimeMetadataDst = path.join(dataDir, 'runtime-metadata.cjs');
-  if (fs.existsSync(runtimeMetadataSrc)) {
-    fs.copyFileSync(runtimeMetadataSrc, runtimeMetadataDst);
-    const packageVersion = require(path.join(pkgPath, 'package.json')).version;
-    fs.writeFileSync(path.join(dataDir, 'runtime-metadata.json'), `${JSON.stringify({
-      schema_version: 'kld-sdd-runtime-metadata/v1',
-      package_name: '@hunterzheng/kld-sdd',
-      version: packageVersion,
-    }, null, 2)}\n`, 'utf8');
-    console.log(`   ✓ 部署 kld-sdd 运行时身份（${packageVersion}）`);
-  }
+  fs.writeFileSync(
+    runtimeMetadataDst,
+    `'use strict';\nmodule.exports = { resolveRuntimeMetadata() { return { version: '${packageVersion}', producer: 'kld-sdd@${packageVersion}' }; } };\n`,
+    'utf8',
+  );
+  console.log(`   ✓ 部署 kld-sdd 运行时身份（${packageVersion}）`);
 
   const reportingSrc = path.join(pkgPath, 'skywalk-sdd', 'reporting');
   const reportingDst = path.join(dataDir, 'reporting');
   if (fs.existsSync(reportingSrc)) {
     copyDir(reportingSrc, reportingDst);
     console.log('   ✓ 部署 skywalk-sdd/reporting/（V3 单次变更报告）');
+  } else {
+    throw new Error(`E_INIT_MISSING_CRITICAL: reporting/ 目录缺失: ${reportingSrc}（归档报告生成将失败）`);
   }
 
   const contextClientSrc = path.join(pkgPath, 'skywalk-sdd', 'context-client.cjs');
@@ -874,6 +872,8 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   if (fs.existsSync(worktreeFinishSrc)) {
     fs.copyFileSync(worktreeFinishSrc, worktreeFinishDst);
     console.log('   ✓ 部署 skywalk-sdd/apply-worktree-finish.cjs（Apply 收尾脚本）');
+  } else {
+    console.log('   ⚠️  apply-worktree-finish.cjs 源文件缺失，Apply 阶段收尾需要手动执行');
   }
 
   const openspecShimSrc = path.join(pkgPath, 'skywalk-sdd', 'openspec-shim.cjs');
@@ -881,12 +881,15 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   if (fs.existsSync(openspecShimSrc)) {
     fs.copyFileSync(openspecShimSrc, openspecShimDst);
     console.log('   ✓ 部署 skywalk-sdd/openspec-shim.cjs（openspec 包裹包路径 shim）');
+  } else {
+    console.log('   ⚠️  openspec-shim.cjs 源文件缺失，openspec 命令需要手动 cd 到 spec 包执行');
   }
 
   console.log('   ✓ 调用方式: node skywalk-sdd/log.cjs start|end|metrics|semantic-identity|semantic-reconcile|semantic-check');
   console.log('   ✓ openspec: node skywalk-sdd/openspec-shim.cjs list（自动 cd 到 *-sdd-specs）');
   console.log('   ✓ Spec Context: node skywalk-sdd/context-client.cjs --query="<自然语言需求>" --target-stage=spec');
   console.log('   ✓ Apply worktree: record-base 在 §1.5；收尾 apply-worktree-finish.cjs --change=<name>');
+  console.log('   ℹ️  project-identity.json 将在首次配置 KB（opsx-ontology-query）时自动创建');
   console.log('✅ Telemetry 已就绪（数据存储在 skywalk-sdd/，无需配置 MCP）');
   return true;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.6.13",
+  "version": "2.6.15",
   "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/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/workspace-layout.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.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-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node --test test/change-report-correctness.cjs test/report-metrics-correctness.cjs test/change-report-model-ui.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 && node test/init-report-runtime.cjs"
+    "test": "node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/workspace-layout.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.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-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node --test test/evidence-integrity-oracle.cjs test/evidence-integrity-wiring.cjs test/change-report-correctness.cjs test/report-metrics-correctness.cjs test/change-report-model-ui.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 && node test/init-report-runtime.cjs"
   },
   "keywords": [
     "kld",