kld-sdd 2.4.8 → 2.4.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.4.8",
+  "version": "2.4.9",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 内置模版一键初始化",
   "main": "index.js",
   "bin": {

package/skywalk-sdd/index.js

@@ -171,7 +171,44 @@ function findActiveStage(projectRoot, criteria) {
     })
     .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
 
-  return candidates[0] || null;
+  if (candidates.length > 0) return candidates[0];
+
+  // 跨 session 匹配：当 session_id 变化（如 compaction 恢复）但 command+change 相同时，
+  // 在 events 目录中搜索最近的 stage_start 事件
+  if (criteria.command && criteria.change) {
+    const dataDir = getDataDir(projectRoot);
+    const eventsDir = path.join(dataDir, 'events');
+    if (fs.existsSync(eventsDir)) {
+      const changeDirs = fs.readdirSync(eventsDir).filter(d => {
+        return fs.statSync(path.join(eventsDir, d)).isDirectory();
+      });
+      const matchingStarts = [];
+      for (const changeDir of changeDirs) {
+        const dir = path.join(eventsDir, changeDir);
+        const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort().reverse();
+        for (const file of files) {
+          const lines = fs.readFileSync(path.join(dir, file), 'utf-8').split('\n').filter(Boolean);
+          for (let i = lines.length - 1; i >= 0; i--) {
+            try {
+              const event = JSON.parse(lines[i]);
+              if (event.type === 'stage_start' &&
+                  event.command === criteria.command &&
+                  event.change === criteria.change &&
+                  (!criteria.capability || event.capability === criteria.capability)) {
+                matchingStarts.push(event);
+              }
+            } catch {}
+          }
+        }
+      }
+      if (matchingStarts.length > 0) {
+        matchingStarts.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+        return matchingStarts[0];
+      }
+    }
+  }
+
+  return null;
 }
 
 function clearActiveStage(projectRoot, event) {
@@ -1805,6 +1842,16 @@ function renderPdfMvpMarkdown(metrics) {
   ].join('\n');
 }
 
+function formatMsToSeconds(ms) {
+  if (ms == null) return 'null';
+  return `${(ms / 1000).toFixed(2)} s`;
+}
+
+function formatRatioToPercent(ratio) {
+  if (ratio == null) return 'null';
+  return `${(ratio * 100).toFixed(1)}%`;
+}
+
 function renderExecutiveReportMarkdown(report) {
   const metrics = report.metrics;
   const health = report.doctor;
@@ -1818,28 +1865,28 @@ function renderExecutiveReportMarkdown(report) {
     `- 统计范围：${report.change ? `change/${report.change}` : 'project'}`,
     '',
     '## 执行摘要',
-    `- Telemetry 健康分：${health.telemetry_health_score ?? 'null'}`,
-    `- 阶段闭环率：${health.matched_stage_rate ?? 'null'}`,
-    `- 严重问题数：${health.severe_issues?.length || 0}`,
+    `- Telemetry 健康分：${formatRatioToPercent(health.telemetry_health_score)}（0-100%，反映遥测数据的完整性，扣分项包括未闭环阶段、孤儿事件等）`,
+    `- 阶段闭环率：${formatRatioToPercent(health.matched_stage_rate)}（已配对 start/end 的阶段占有效阶段总数的比例）`,
+    `- 严重问题数：${health.severe_issues?.length || 0}（存在未闭环阶段、孤儿事件或未知命令等阻断级问题的数量）`,
     '',
     '## 效率指标',
-    `- E1 需求到归档总时长：${metrics.efficiency?.e1_lead_time_ms ?? 'null'} ms`,
-    `- E2 编码时间占比：${metrics.efficiency?.e2_coding_time_ratio ?? 'null'}`,
-    `- E3 规约时间占比：${metrics.efficiency?.e3_spec_time_ratio ?? 'null'}`,
-    `- E4 AI 一次成码率：${metrics.efficiency?.e4_ai_code_first_pass_rate ?? 'null'}`,
-    `- 有效阶段总耗时：${metrics.efficiency?.effective_stage_duration_ms ?? 'null'} ms`,
-    `- 返工阶段总耗时：${metrics.efficiency?.rework_stage_duration_ms ?? 'null'} ms`,
+    `- E1 需求到归档总时长：${formatMsToSeconds(metrics.efficiency?.e1_lead_time_ms)}`,
+    `- E2 编码时间占比：${formatRatioToPercent(metrics.efficiency?.e2_coding_time_ratio)}`,
+    `- E3 规约时间占比：${formatRatioToPercent(metrics.efficiency?.e3_spec_time_ratio)}`,
+    `- E4 AI 一次成码率：${formatRatioToPercent(metrics.efficiency?.e4_ai_code_first_pass_rate)}`,
+    `- 有效阶段总耗时：${formatMsToSeconds(metrics.efficiency?.effective_stage_duration_ms)}`,
+    `- 返工阶段总耗时：${formatMsToSeconds(metrics.efficiency?.rework_stage_duration_ms)}`,
     '',
     '## 质量指标',
     `- Q1 规约符合度：${metrics.quality?.q1_spec_conformance_score ?? 'null'}`,
-    `- Q3 构建一次通过率：${metrics.quality?.q3_build_first_pass_rate ?? 'null'}`,
-    `- Q4 规约驱动测试覆盖率：${metrics.quality?.q4_spec_driven_test_coverage ?? 'null'}`,
+    `- Q3 构建一次通过率：${formatRatioToPercent(metrics.quality?.q3_build_first_pass_rate)}`,
+    `- Q4 规约驱动测试覆盖率：${formatRatioToPercent(metrics.quality?.q4_spec_driven_test_coverage)}`,
     `- Q5 跨文档一致性得分：${metrics.quality?.q5_cross_doc_consistency_score ?? 'null'}`,
     '',
     '## 过程指标',
     `- P1 文档迭代次数：${metrics.process?.p1_spec_iteration_count ?? 'null'}`,
-    `- P2 AI 代码保留率：${metrics.process?.p2_ai_code_adoption_rate ?? 'null'}`,
-    `- P4 质量门前置率：${metrics.process?.p4_quality_gate_enforcement_rate ?? 'null'}`,
+    `- P2 AI 代码保留率：${formatRatioToPercent(metrics.process?.p2_ai_code_adoption_rate)}`,
+    `- P4 质量门前置率：${formatRatioToPercent(metrics.process?.p4_quality_gate_enforcement_rate)}`,
     `- 返工次数：${metrics.process?.rework_summary?.total_rework_attempts ?? 'null'}`,
     `- 被后续成功执行覆盖的未闭环阶段数：${metrics.process?.rework_summary?.superseded_open_stages ?? 'null'}`,
     '',
@@ -1853,22 +1900,9 @@ function renderExecutiveReportMarkdown(report) {
     `- 未勾选任务项：${taskCompletion?.incomplete ?? 'null'}`,
     `- 任务项总数：${taskCompletion?.total ?? 'null'}`,
     '',
-    '## 人工反馈',
-    `- 平均 NPS：${metrics.manual_insights?.avg_nps ?? 'null'}`,
-    `- 平均认知负荷：${metrics.manual_insights?.avg_cognitive_load ?? 'null'}`,
-    `- 平均规约疲劳指数：${metrics.manual_insights?.avg_spec_fatigue_index ?? 'null'}`,
-    `- 相对传统方式节省时长比例：${metrics.manual_insights?.baseline_time_saved_ratio ?? 'null'}`,
-    '',
-    '## 数据质量',
-    `- 未闭环阶段数：${health.open_stages ?? 'null'}`,
-    `- 已被后续成功执行覆盖的未闭环阶段数：${health.superseded_open_stages ?? 'null'}`,
-    `- 返工次数：${health.rework_attempts ?? 'null'}`,
-    `- 孤儿结束事件数：${health.orphan_events ?? 'null'}`,
-    `- 未知命令事件数：${health.unknown_command_events ?? 'null'}`,
-    '',
     '## 说明',
     '- `null` 表示当前还没有采集到对应事件或该指标暂不适用。',
-    '- Q1 与人工反馈类指标属于评审信号，默认不作为强阻断门禁。',
+    '- Q1 规约符合度与人工反馈类指标属于评审信号，默认不作为强阻断门禁。',
   ].join('\n');
 }
 
@@ -2156,7 +2190,7 @@ function cmdEnd(args, options = {}) {
     task_id: args['task-id'] || args.task_id || startEvent?.task_id,
     agent_type: args.agent || args['agent-type'] || startEvent?.agent_type || 'unknown',
     project_root: projectRoot,
-    session_id: args['session-id'] || args.session_id || startEvent?.session_id,
+    session_id: startEvent?.session_id || args['session-id'] || args.session_id,
     git_sha: args['git-sha'] || args.git_sha || startEvent?.git_sha,
     timestamp,
     duration_ms: durationMs,
@@ -2244,6 +2278,12 @@ function cmdRecord(args) {
   }
 
   const dataDir = getDataDir(projectRoot);
+  const activeStage = findActiveStage(projectRoot, {
+    session_id: args['session-id'] || args.session_id,
+    change,
+    command: args.command,
+    agent_type: agentType,
+  });
   const eventId = args['event-id'] || args.event_id || generateEventId();
   const timestamp = nowISO();
   const event = cleanOptionalFields({
@@ -2258,7 +2298,7 @@ function cmdRecord(args) {
     task_id: args['task-id'] || args.task_id,
     agent_type: agentType,
     project_root: projectRoot,
-    session_id: args['session-id'] || args.session_id,
+    session_id: activeStage?.session_id || args['session-id'] || args.session_id,
     git_sha: args['git-sha'] || args.git_sha,
     timestamp,
     result: args.result,

package/templates/git-hooks/pre-push-sdd-check.js

@@ -20,9 +20,9 @@ function main() {
     return;
   }
 
-  const args = [logCli, 'doctor', '--project', projectRoot];
+  const args = [logCli, 'doctor', `--project=${projectRoot}`];
   if (changeName) {
-    args.push('--change', changeName);
+    args.push(`--change=${changeName}`);
   }
 
   const result = spawnSync(process.execPath, args, {

package/templates/opsx-commands/apply.md

@@ -390,8 +390,10 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
       每完成一个任务后，必须立即：
       
       1. **修改 tasks.md 文件**：
-         - 将 `- **状态**: [ ] 未完成` 改为 `- **状态**: [x] 已完成`
-      2. **验证修改成功**：读取文件确认状态已更新
+         - 将该任务对应的 `- [ ]` 替换为 `- [x]`（包括任务执行拓扑图中的复选框和任务详情中的状态行）
+         - 将 `- **状态**: [ ] 未完成` 替换为 `- **状态**: [x] 已完成`
+         - **两种格式必须同步更新**，不可遗漏
+      2. **验证修改成功**：读取文件确认两种格式的复选框均已勾选
       3. **显示进度提示**：
          > "✅ **[TASK-XXX-01] 已完成** [N/M]
          > - 编译检查: ✅ 通过
@@ -462,7 +464,7 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
 - **⛔ 渐进式加载**：只加载当前 Capability 的四文档链（overview + proposal + spec + design + tasks）
 - **⛔ 隔离红线**：绝对禁止加载同级其他 Capability 的文档
 - **⛔ 拓扑依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截
-- **⛔ 必须实时更新任务状态**：每完成一个任务，**立即**修改 tasks.md 状态，禁止批量更新
+- **⛔ 必须实时更新任务状态**：每完成一个任务，**立即**修改 tasks.md 中的 `- [ ]` 为 `- [x]`，**同时修改** `**状态**: [ ] 未完成` 为 `**状态**: [x] 已完成`，两种格式不可遗漏，禁止批量更新
 - **⛔ 算法一致性门禁**：对于 IMPL 任务，检查实现代码与 design.md 伪代码的一致性，核心逻辑不一致时拦截
 - **⛔ 编译检查门禁**：每完成一个任务后，**必须运行编译检查**，编译失败禁止标记已完成
 - **⛔ 测试执行门禁**：根据 `test-strategy` 决定测试门禁行为（tdd=强制, impl-first=警告, none=跳过）

package/templates/opsx-commands/task.md

@@ -291,7 +291,7 @@ argument-hint: "[change-name] [capability-name] [上下文文件...]"
    ### [TASK-XXX-01] 任务名称
    - **类型**: 数据层 / 接口层 / UI层 / 测试
    - **依赖**: 无
-   - **状态**: [ ] 未完成
+   - **状态**: [ ] 未完成（勾选格式统一使用 GitHub 标准的 `- [ ]` / `- [x]`）
 
    #### 任务描述
    <!-- 一句话描述本任务要做什么 -->

package/templates/skills/opsx-apply/SKILL.md

@@ -180,7 +180,9 @@ e. **⛔ 测试执行门禁**
    | `none` | **跳过**：不执行测试门禁 |
 
 f. **⛔ 立即更新任务状态**
-   - 修改 tasks.md：`状态: [ ] 未完成` → `状态: [x] 已完成`
+   - 修改 tasks.md：将 `- [ ]` 替换为 `- [x]`（包括拓扑图和任务详情中的复选框）
+   - 同时修改：`- **状态**: [ ] 未完成` → `- **状态**: [x] 已完成`
+   - **两种格式必须同步更新**，不可遗漏
    - 验证修改成功
    - 显示进度：`✅ [TASK-ID] 已完成 [N/M]`
    - 记录任务级 Telemetry：
@@ -216,7 +218,7 @@ node skywalk-sdd/log.js record --type=ai_adoption_review --command=apply --proje
 - **⛔ DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截
 - **⛔ 编译检查门禁**：每完成一个任务后，**必须运行编译检查**，编译失败禁止标记已完成
 - **⛔ 测试执行门禁**：根据 `test-strategy` 决定测试门禁行为（tdd=强制, impl-first=警告, none=跳过）
-- **⛔ 必须实时更新任务状态**：每完成一个任务，**立即**修改 tasks.md 状态
+- **⛔ 必须实时更新任务状态**：每完成一个任务，**立即**修改 tasks.md 中的 `- [ ]` 为 `- [x]`，**同时修改** `**状态**: [ ] 未完成` 为 `**状态**: [x] 已完成`，两种格式不可遗漏
 - **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目使用 `vcs_mode=no-git` 继续执行
 - **显示进度反馈**：每完成一个任务，显示「✅ [TASK-ID] 已完成 [N/M]」
 - **保持任务聚焦**：每次只处理一个任务