kld-sdd 2.6.12 → 2.6.14

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,6 +104,25 @@ npx kld-sdd
 
 初始化完成后，打开你的 AI 编辑器，激活 `opsx-*` skills 开始工作。
 
+### 提效评估报告（SkyWalk V3）
+
+归档与独立 `report` 命令会基于同一 Report Model 生成 Markdown / HTML / JSON 三份同源产物（`schema_version=sdd-efficiency-report/v3`）。单次变更 HTML 使用桌面方案 A，只展示当前 change 的四个页签：概览、指标与阶段、问题与证据、产物与追溯，不混入跨变更趋势。
+
+报告中的业务名称优先于缩写：E1=每个验收场景平均用时，Q3=规约检查得分，P4=编码前检查覆盖，P-R=标准阶段重复次数，P-H=执行记录完整度。标准测量阶段固定为 propose、spec、design、task、check、apply、archive；test、explore 是辅助阶段，可展示但不进入效率分母。
+
+```bash
+# 单变更报告（默认 html；可指定 markdown/json）
+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 区。
+
 ---
 
 ## 核心工作流：5 个 skills
@@ -267,11 +286,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>/
@@ -285,6 +306,7 @@ your-project/
 │   └── tasks.md
 ├── skywalk-sdd/
 │   ├── log.cjs                      # Telemetry + semantic-* 命令入口
+│   ├── metrics-v3.cjs               # V3 提效评估纯计算模块（随 init 部署）
 │   ├── ontology/                    # 本地本体解析、校验、观察和对账运行时
 │   └── state/ontology/
 │       ├── .locks/<change>.lock     # observe/reconcile/check/archive 跨进程锁