kld-sdd 2.7.8-1 → 2.7.8-2

package/USABILITY.md

@@ -82,3 +82,23 @@ SDD 应帮助团队留下三类东西：明确的业务约定、能够证明实
 新增回归覆盖 Full/Simple 结果等价、正文增改删后的重新校验、跨 Change 身份冲突、strict profile、结束时重新解析、strict JSON 记录拒绝占位值，以及八种 Agent 的参考文件渲染。消费方需要重新安装/更新技能和 skywalk-sdd 运行时才能使用新参数；只更新技能文件会导致旧运行时缺少合并输出。
 
 验证结果（2026-09-08，本次 Check 优化）：完整 `npm test` 通过，包含新增 6 组 Check 回归与全部既有用例；`npm run bench:check` 的 7 轮结论与任务计数等价断言全部通过。
+
+## 2026-09-10：真实执行与故障恢复
+
+本次承接已发布的 `2.7.8-1`，继续提交在 `codex/sdd-usability`。以下新增能力尚未重新发布 npm；原有身份、入库协议、七种 Skill 使用上报保持兼容。
+
+- `kld-sdd log` 修正为实际打包的 `index.cjs` 入口。strict 记录失败会保留 details 文件，成功持久化后才清理。
+- `test-run` 执行真实命令，保存退出码、耗时、原始 stdout/stderr 及 SHA-256。当前自动识别 Node TAP/原生测试摘要；未识别的 runner 仍保存输出，标记计数未知，不能自动完成任务。
+- `test-run --completion-file` 为明确声明的任务关联实际测试事件并同步 checkbox。命令执行成功不等于业务覆盖充分，任务与测试的对应关系仍需评审核验；缺少测试、路径错误、超时不能记成有效 RED。
+- `check-record` 接收实际检查项与真实评审身份，自动计算分类统计、任务缺口和结果，可通过 `--end-event-id` 一次记录并结束。按预检 profile 重新核对正文和历史身份；变化时拒绝旧评审。结束阶段复用本次刚完成的校验，避免再跑一次同样的对账。
+- Archive 在启动归档阶段前运行 doctor；终态通知独立记为 `run_end`，旧 `stage_end + run_ended` 在计算时兼容归一化，避免虚增阶段或孤儿日志。通知保留，原始旧日志不改写。
+- 修复进程锁发布窗口：完整锁文件原子发布，其他进程不能把尚未写完的锁当作失效锁抢走。
+- 文档按实际业务决策与验收行为组织，不为填模板反复复制背景、堆空章节或按每个参数值拆一次任务。
+
+详细参数与示例在 [Apply 参考](templates/skills/kld-sdd/opsx-apply/reference.md) 和 [Check 指南](templates/skills/kld-sdd/opsx-check/SKILL.md)。新命令需要更新运行时和 Skills，旧 `record --strict` 仍可使用。
+
+验证：完整 `npm test` 通过；新增 19 个真实执行/恢复回归，涵盖测试输出篡改、零测试、超时、RED、任务关联、旧评审拒绝、单次最终复核、真实归档和六进程竞争。打包及初始化器均部署两个新模块，安装后的真实入口也有回归覆盖。预检基准七轮中位数由 294.6 ms 降至 156.3 ms，减少 46.9%；它仅测程序预检，不代表模型评审总耗时。
+
+本机独立后端联调确认七种 Skill 的使用事件均成功写入，断网事件保留并恢复补报，服务端统计为 8 次、覆盖 7 阶段。使用统计是独立的 usage 事件，不等于测试通过、归档完成或 Spec 已入库；当前服务端按提交次数计数，网络响应丢失后的重复提交不提供 exactly-once 保证。
+
+配置 Skill 与参考同步去除默认首目标、截短 UUID 和旧监控项目绑定步骤，修正 KB API 字段映射；切换查询目标不再引导改写团队项目身份，权限失败也不清空其他目标可能仍有效的密钥。

package/bin/kld-sdd-init.js

@@ -16,7 +16,7 @@ const args = process.argv.slice(2);
 
 if (args[0] === 'log') {
   // Telemetry CLI 模式
-  require('../skywalk-sdd/index.js').main();
+  require('../skywalk-sdd/index.cjs').main();
 } else if (args[0] === 'link-spec') {
   const sddConfig = require('../skywalk-sdd/ontology/sdd-config.cjs');
   const pathArg = args.find((item) => item.startsWith('--path='));

package/lib/init.js

@@ -1018,6 +1018,13 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   if (!fs.existsSync(sharedLibDir)) {
     fs.mkdirSync(sharedLibDir, { recursive: true });
   }
+  for (const name of ['test-execution.cjs', 'check-review.cjs']) {
+    const src = path.join(pkgPath, 'skywalk-sdd', 'lib', name);
+    if (!fs.existsSync(src)) throw new Error(`E_INIT_MISSING_CRITICAL: lib/${name} 源文件缺失`);
+    fs.copyFileSync(src, path.join(sharedLibDir, name));
+    deployedModules += 1;
+    vlog(`   ✓ 部署 skywalk-sdd/lib/${name}`);
+  }
   const sharedSrc = path.join(pkgPath, 'skywalk-sdd', 'lib', 'shared.cjs');
   const sharedDst = path.join(sharedLibDir, 'shared.cjs');
   if (fs.existsSync(sharedSrc)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.7.8-1",
+  "version": "2.7.8-2",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "index.js",
   "bin": {
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "bench:check": "node test/benchmark-check.cjs",
-    "test": "node --test test/kb-fact-lifecycle.test.cjs test/workflow-usability.test.cjs test/check-efficiency.test.cjs && 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/prompt-spec-path.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 && node test/init-output-verbosity.cjs && node --test test/usage-contract.test.cjs test/user-config.test.cjs test/usage-runtime-removal.test.cjs skywalk-sdd/usage-reporter.test.cjs skywalk-sdd/usage-reporting.test.cjs && node test/progress-package-artifact.test.cjs && node --test test/progress-package-install.e2e.cjs && node test/consistency-check-core.cjs"
+    "test": "node --test test/execution-friction.test.cjs test/kb-fact-lifecycle.test.cjs test/workflow-usability.test.cjs test/check-efficiency.test.cjs && 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/prompt-spec-path.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 && node test/init-output-verbosity.cjs && node --test test/usage-contract.test.cjs test/user-config.test.cjs test/usage-runtime-removal.test.cjs skywalk-sdd/usage-reporter.test.cjs skywalk-sdd/usage-reporting.test.cjs && node test/progress-package-artifact.test.cjs && node --test test/progress-package-install.e2e.cjs && node test/consistency-check-core.cjs"
   },
   "keywords": [
     "kld",

package/skywalk-sdd/index.cjs

@@ -1313,28 +1313,32 @@ function acquireEventWriteLock(dataDir, changeName, options = {}) {
       created_at: nowISO(),
       change: safeChangeName(changeName),
     };
-    let descriptor;
+    const candidatePath = `${lockPath}.${token}.tmp`;
     try {
-      descriptor = fs.openSync(lockPath, 'wx');
-      fs.writeFileSync(descriptor, JSON.stringify(payload), 'utf8');
-      fs.closeSync(descriptor);
+      fs.writeFileSync(candidatePath, JSON.stringify(payload), { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+      // Publish a complete payload atomically. A contender must never observe an
+      // empty lock and remove it while its owner is still initializing it.
+      fs.linkSync(candidatePath, lockPath);
       return { ...payload, path: lockPath };
     } catch (error) {
-      if (descriptor !== undefined) fs.closeSync(descriptor);
       if (error?.code !== 'EEXIST') throw error;
       let existing = null;
       try {
         existing = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
       } catch {}
       const createdAt = Date.parse(existing?.created_at || '');
-      const stale = !Number.isFinite(createdAt)
-        || Date.now() - createdAt > staleMs
-        || !isProcessAlive(Number(existing?.pid));
+      let age = 0;
+      try { age = Date.now() - fs.statSync(lockPath).mtimeMs; } catch {}
+      const stale = existing && Number.isFinite(createdAt)
+        ? !isProcessAlive(Number(existing.pid))
+        : age > staleMs;
       if (stale) {
         try { fs.rmSync(lockPath, { force: true }); } catch {}
         continue;
       }
       Atomics.wait(EVENT_LOCK_WAIT_BUFFER, 0, 0, 10);
+    } finally {
+      try { fs.unlinkSync(candidatePath); } catch {}
     }
   }
   const error = new Error(`EVENT_WRITE_LOCK_TIMEOUT: 等待 change "${changeName}" 的事件写锁超时`);
@@ -1539,7 +1543,15 @@ function readAllEvents(dataDir) {
 /**
  * 计算单个 change 的四维指标
  */
+function normalizeLifecycleEvents(events) {
+  // Older clients stored run notifications as stage_end with a different event ID.
+  // Preserve the event and its wire kind without counting it as another stage.
+  return events.map(event => event.type === 'stage_end' && event.event_kind === 'run_ended'
+    ? { ...event, type: 'run_end' } : event);
+}
+
 function computeChangeMetrics(changeName, events) {
+  events = normalizeLifecycleEvents(events);
   const changeEvents = events.filter(e => e.change === changeName && !e.orphan);
   if (changeEvents.length === 0) return null;
 
@@ -1868,6 +1880,7 @@ function createReworkBucket(command, capability) {
 }
 
 function summarizeStageExecutions(events) {
+  events = normalizeLifecycleEvents(events);
   const stageEvents = events.filter(e => !e.orphan && (e.type === 'stage_start' || e.type === 'stage_end'));
   const starts = stageEvents
     .filter(e => e.type === 'stage_start')
@@ -3329,6 +3342,7 @@ function computeTelemetryHealthMetrics(events, options = {}) {
 }
 
 function computePdfMvpMetrics(events, options = {}) {
+  events = normalizeLifecycleEvents(events);
   if (options.level === 'capability' || options.capability) {
     return computeCapabilityMetrics(options.capability, events, options);
   }
@@ -4856,6 +4870,7 @@ function tddPairFinding(pair) {
 }
 
 function buildReport(projectRoot, events, options = {}) {
+  events = normalizeLifecycleEvents(events);
   const scopedReport = scopeEventsForChangeReport(events, options.change);
   events = scopedReport.events;
   const archiveEvent = latestByTimestamp(events.filter(e => {
@@ -5208,6 +5223,7 @@ function filterEventsByDate(events, dateFrom, dateTo) {
 }
 
 function computeDoctorReport(events, options = {}) {
+  events = normalizeLifecycleEvents(events);
   const scopedEvents = options.change
     ? events.filter(e => e.change === options.change)
     : events;
@@ -5418,12 +5434,12 @@ function cmdStart(args) {
 
 const ONTOLOGY_AUTHORING_STAGES = new Set(['propose', 'spec', 'design', 'task', 'check']);
 
-function syncWorkingOntologyForStage(projectRoot, changeName, command, result) {
+function syncWorkingOntologyForStage(projectRoot, changeName, command, result, verifiedReconciliation = null) {
   if (!ONTOLOGY_AUTHORING_STAGES.has(command) || result === 'failure') return null;
   if (!changeName || changeName === 'general') return null;
   const changeDir = getChangeDir(projectRoot, changeName);
   if (!fs.existsSync(changeDir)) return null;
-  const reconciled = require('./ontology/runtime.cjs').reconcileChange(
+  const reconciled = verifiedReconciliation || require('./ontology/runtime.cjs').reconcileChange(
     projectRoot,
     changeName,
     {
@@ -5592,7 +5608,8 @@ function cmdEnd(args, options = {}) {
 
   let semanticState = null;
   try {
-    semanticState = syncWorkingOntologyForStage(projectRoot, change, command, result);
+    semanticState = syncWorkingOntologyForStage(projectRoot, change, command, result,
+      command === 'check' ? options.verifiedReconciliation : null);
     if (semanticState) {
       details = {
         ...details,
@@ -5779,7 +5796,7 @@ function cmdEnd(args, options = {}) {
       appendEvent(dataDir, event.change, cleanOptionalFields({
         schema_version: SCHEMA_VERSION,
         event_id: generateEventId(),
-        type: 'stage_end',
+        type: 'run_end',
         event_kind: 'run_ended',
         source: event.source,
         command: 'archive',
@@ -6434,8 +6451,10 @@ function normalizeStrictTestResult(args, details) {
     failure_type: failureType,
     expected_failure: expectedFailure,
     evidence_tier: 'strict',
+    ...(input.execution ? { execution: input.execution } : {}),
     valid_red: tddPhase === 'red'
       ? expectedFailure && exitCode !== 0 && ['assertion', 'contract'].includes(failureType)
+        && (!input.execution || (input.counts_known && Number(input.failed) > 0))
       : false,
   };
   if (input.counts_known) {
@@ -6453,6 +6472,7 @@ function isValidCompletionTestResults(testResults) {
   if (!testResults || typeof testResults !== 'object') return false;
   if (!['green', 'refactor', 'regression'].includes(testResults.tdd_phase)) return false;
   if (testResults.exit_code !== 0 || testResults.failure_type !== 'none') return false;
+  if (testResults.execution && (!testResults.counts_known || !(testResults.passed > 0))) return false;
   if (testResults.counts_known === true && Number(testResults.failed) !== 0) return false;
   return true;
 }
@@ -7348,18 +7368,6 @@ function cmdRecord(args) {
   try {
     details = parseJsonOption(args, 'details-json', 'details-file', projectRoot, {});
     detailsFilePath = args['details-file'] || args.details_file || null;
-    // 默认清理 details-file，避免项目根目录被临时 JSON 污染；--keep-details 保留调试用
-    if (detailsFilePath && !args['keep-details'] && !args.keep_details) {
-      try {
-        const fileToRemove = normalizeDetailsFilePath(detailsFilePath, projectRoot);
-        if (fs.existsSync(fileToRemove)) {
-          fs.unlinkSync(fileToRemove);
-        }
-      } catch (cleanupErr) {
-        // 清理失败不阻塞主流程
-        try { console.error(`[telemetry] details-file 清理失败（不阻塞）: ${cleanupErr.message}`); } catch {}
-      }
-    }
   } catch (err) {
     fail(`details JSON 解析失败: ${err.message}`);
   }
@@ -7467,6 +7475,9 @@ function cmdRecord(args) {
     };
   }
   if (strict && type === 'test_result') {
+    if (details?.test_results?.execution) {
+      require('./lib/test-execution.cjs').verifyCapture(details.test_results, projectRoot);
+    }
     const testResults = normalizeStrictTestResult(args, details);
     strictRunId = testResults.run_id;
     strictTaskId = testResults.task_id;
@@ -7560,6 +7571,7 @@ function cmdRecord(args) {
       const taskId = strictTaskId || details?.task_id || null;
       if (taskId) runCheckTaskSync(projectRoot, change, taskId);
     } catch (taskErr) {
+      if (args['require-projection']) throw taskErr;
       try { console.error(`[telemetry] tasks.md 主任务状态自动同步失败（不阻塞）: ${taskErr.message}`); } catch {}
     }
   };
@@ -7636,6 +7648,85 @@ function cmdRecord(args) {
   } catch (error) {
     fail(error.message || String(error));
   }
+  // Keep retry input until validation, persistence and task projection all succeed.
+  if (detailsFilePath && !args['keep-details'] && !args.keep_details) {
+    try { fs.unlinkSync(normalizeDetailsFilePath(detailsFilePath, projectRoot)); }
+    catch (error) {
+      if (error.code !== 'ENOENT') console.error(`[telemetry] details-file 清理失败（不阻塞）: ${error.message}`);
+    }
+  }
+  if (!args.quiet) console.log(JSON.stringify(output, null, 2));
+  return output;
+}
+
+function cmdTestRun(args) {
+  const projectRoot = normalizeProjectRoot(args.project || process.cwd());
+  requireValidChangeName(args.change);
+  requireStrictString(args['session-id'], 'TEST_SESSION_REQUIRED', 'session-id');
+  const completion = args['completion-file']
+    ? JSON.parse(fs.readFileSync(path.resolve(args['completion-file']), 'utf8')) : [];
+  const declared = String(args['task-ids'] || args['task-id'] || '').split(',').map(x => x.trim());
+  if (!Array.isArray(completion) || completion.some(item => !declared.includes(item.task_id)
+      || typeof item.tdd_required !== 'boolean'
+      || (!Array.isArray(item.files) && !item.no_file_change_reason))) {
+    throw new Error('TEST_COMPLETION_INVALID: 完成信息须关联本轮明确任务，并包含实际文件及 tdd_required');
+  }
+  for (const item of completion) {
+    normalizeRepositoryRelativeFiles(item.files || []);
+    runCheckTaskSync(projectRoot, args.change, item.task_id, true);
+  }
+  const captured = require('./lib/test-execution.cjs').captureTest(args, projectRoot, args.change);
+  const record = cmdRecord({ ...args, quiet: true, strict: true, type: 'test_result',
+    command: 'test', project: projectRoot, change: args.change, 'run-id': captured.runId,
+    source: args.source || 'test-run', summary: args.summary || `执行测试：${captured.testResults.command}`,
+    result: captured.testResults.result, details: undefined,
+    'details-file': captured.receipt, 'keep-details': true,
+  });
+  const completed = [];
+  if (isValidCompletionTestResults(captured.testResults)) {
+    for (const item of completion) {
+      const updated = cmdRecord({ ...args, quiet: true, strict: true, type: 'task_update', command: 'apply',
+        'require-projection': true,
+        project: projectRoot, 'run-id': `${captured.runId}:${item.task_id}`, 'task-id': item.task_id,
+        status: 'completed', result: 'success', source: args.source || 'test-run', summary: `${item.task_id} 通过本轮测试`,
+        'details-json': JSON.stringify({ task_update: { ...item, test_event_id: record.event_id } }),
+      });
+      completed.push({ task_id: item.task_id, event_id: updated.event_id, test_event_id: record.event_id });
+    }
+  }
+  const output = { ...record, test_results: captured.testResults, receipt: captured.receipt, completed_tasks: completed };
+  console.log(JSON.stringify(output, null, 2));
+  process.exitCode = captured.testResults.exit_code;
+  return output;
+}
+
+function cmdCheckRecord(args) {
+  const projectRoot = normalizeProjectRoot(args.project || process.cwd());
+  requireValidChangeName(args.change);
+  const preflight = JSON.parse(fs.readFileSync(path.resolve(args['preflight-file']), 'utf8'));
+  const review = JSON.parse(fs.readFileSync(path.resolve(args['review-file']), 'utf8'));
+  const state = require('./ontology/runtime.cjs').reconcileChange(projectRoot, args.change, { profile: preflight.profile || 'auto', markPending: true });
+  if (!preflight.valid || !state.valid || preflight.revision !== state.revision
+      || preflight.review_inputs?.identity_history_hash !== state.state.identity_history_hash
+      || JSON.stringify(preflight.review_inputs?.files) !== JSON.stringify(state.state.files)) {
+    throw new Error('CHECK_REVIEW_STALE: 文档或历史身份已变化，重新预检并评审受影响内容');
+  }
+  const events = readEvents(getDataDir(projectRoot), args.change);
+  const beforeApply = !events.some(e => (e.type === 'stage_start' && ['apply', 'test', 'archive'].includes(e.command)) || ['test_result', 'task_update', 'build_result'].includes(e.type));
+  const previous = events.filter(e => e.type === 'check_result').slice(-1)[0]?.details?.check_results;
+  const assembled = require('./lib/check-review.cjs').assembleReview(review, scanTaskCompletion(projectRoot, args.change), {
+    beforeApply, previousBeforeApply: previous?.fixed_before_apply, revision: preflight.revision,
+  });
+  const record = cmdRecord({ ...args, quiet: true, strict: true, type: 'check_result', command: 'check',
+    project: projectRoot, result: assembled.result, 'run-id': args['run-id'] || generateEventId(),
+    source: args.source || 'opsx-command', summary: args.summary || '按实际评审项生成 Check 结果',
+    'session-id': args['session-id'] || review.reviewer?.parent_session_id || review.reviewer?.review_session_id,
+    'details-json': JSON.stringify(assembled.details),
+  });
+  const ended = args['end-event-id'] ? cmdEnd({ ...args, 'event-id': args['end-event-id'], command: 'check',
+    project: projectRoot, result: assembled.result, summary: args.summary || 'Check 已记录，复核文档状态',
+  }, { silent: true, verifiedReconciliation: state }) : null;
+  const output = { ...record, result: assembled.result, check_results: assembled.details.check_results, stage_end: ended };
   console.log(JSON.stringify(output, null, 2));
   return output;
 }
@@ -8424,6 +8515,12 @@ function main() {
     case 'record':
       cmdRecord(flags);
       break;
+    case 'test-run':
+      cmdTestRun(flags);
+      break;
+    case 'check-record':
+      cmdCheckRecord(flags);
+      break;
     case 'metrics':
       cmdMetrics(flags);
       break;
@@ -8504,6 +8601,8 @@ SDD Telemetry CLI - 流程度量采集工具
   start    记录 SDD 阶段开始，返回 event_id
   end      记录 SDD 阶段结束，关联 event_id
   record   记录 task_update/check_result/test_result 等结构化事件
+  test-run 执行 --command-json 参数数组，采集退出码、测试计数、原始输出与任务关联
+  check-record 从 --review-file 与 --preflight-file 计算并记录 Check 结果
   metrics  查询度量指标（四维分析）
   report   生成只读度量报告（不写入事件）
   doctor   诊断 Telemetry 数据质量

package/skywalk-sdd/lib/check-review.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+const CATEGORIES = ['completeness', 'consistency', 'executability', 'tdd_compliance'];
+
+function assembleReview(review, taskCompletion, options = {}) {
+  if (!review || !Array.isArray(review.items) || !review.items.length) throw new Error('CHECK_ITEMS_REQUIRED: 提供实际评审项，不能提交空模板');
+  const categories = Object.fromEntries(CATEGORIES.map(key => [key, { passed: 0, total: 0 }]));
+  const warnings = [], suggestions = [], ids = new Set();
+  for (const item of review.items) {
+    if (!item.id || ids.has(item.id)) throw new Error('CHECK_ITEM_ID_INVALID: 检查项必须有唯一 ID');
+    ids.add(item.id);
+    if (!CATEGORIES.includes(item.category) || !['passed', 'error', 'warning', 'suggestion', 'na'].includes(item.status)) throw new Error('CHECK_ITEM_STATUS_INVALID');
+    if (typeof item.evidence !== 'string' || !item.evidence.trim()) throw new Error(`CHECK_ITEM_EVIDENCE_REQUIRED: ${item.id} 缺少来源证据或不适用原因`);
+    if (item.status === 'na') continue;
+    categories[item.category].total++;
+    if (item.status !== 'error') categories[item.category].passed++;
+    if (item.status === 'warning') warnings.push({ category: item.category, warning: item.id, description: item.description || item.evidence, target: item.evidence });
+    if (item.status === 'suggestion') suggestions.push(item);
+  }
+  const total = Object.values(categories).reduce((n, c) => n + c.total, 0);
+  const passed = Object.values(categories).reduce((n, c) => n + c.passed, 0);
+  if (!total) throw new Error('CHECK_ITEMS_REQUIRED: 至少有一个实际适用的评审项');
+  if (taskCompletion.has_incomplete) warnings.push({ category: 'task_completion', warning: 'TASKS_INCOMPLETE', description: `${taskCompletion.incomplete} 个任务尚未完成`, target: 'tasks.md' });
+  const result = total !== passed ? 'failure' : (warnings.length ? 'partial' : 'success');
+  return {
+    result,
+    details: { check_results: {
+      ...review.reviewer,
+      total, errors: total - passed, warnings: warnings.length, suggestions: suggestions.length,
+      categories, warning_items: warnings, warning_dispositions: review.warning_dispositions || [],
+      // This field means items satisfied before implementation, not defect fixes.
+      fixed_before_apply: options.beforeApply ? passed : Math.min(total, options.previousBeforeApply || 0),
+      consistency_score: null,
+      task_completion: { ...taskCompletion, checked_for_archive_readiness: !options.beforeApply },
+      review_items: review.items,
+      review_revision: options.revision,
+    } },
+  };
+}
+
+module.exports = { assembleReview };

package/skywalk-sdd/lib/test-execution.cjs

@@ -0,0 +1,110 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+function parseCounts(output) {
+  // Prefer runner totals: counting TAP parent suites as tests double-counts nested tests.
+  const value = name => {
+    const matches = [...output.matchAll(new RegExp(`^(?:#|ℹ)\\s+${name}\\s+(\\d+)\\s*$`, 'gm'))];
+    return matches.length ? Number(matches[matches.length - 1][1]) : null;
+  };
+  const total = value('tests'), passed = value('pass'), failed = value('fail');
+  const skipped = value('skipped'), todo = value('todo');
+  if ([total, passed, failed].every(Number.isInteger)
+      && total === passed + failed + (skipped || 0) + (todo || 0)) {
+    return { counts_known: true, passed, failed, skipped: (skipped || 0) + (todo || 0) };
+  }
+  return { counts_known: false };
+}
+
+function classifyFailure(output, exitCode, error, signal) {
+  if (error?.code === 'ETIMEDOUT') return 'timeout';
+  if (error || signal) return 'infrastructure';
+  if (exitCode === 0) return 'none';
+  // A missing executable/module/test path is not evidence of a failing business assertion.
+  if (/MODULE_NOT_FOUND|ERR_MODULE_NOT_FOUND|Cannot find module|Could not find|ENOENT|SyntaxError|ERR_TEST_FAILURE.*cancelled/i.test(output)) return 'infrastructure';
+  if (/ERR_ASSERTION|AssertionError|AssertionFailedError|org\.opentest4j\.AssertionFailedError/.test(output)) return 'assertion';
+  return 'infrastructure';
+}
+
+function captureTest(args, projectRoot, change) {
+  let command;
+  try { command = JSON.parse(args['command-json'] || 'null'); } catch { /* validated below */ }
+  if (!Array.isArray(command) || !command.length || command.some(x => typeof x !== 'string' || x.includes('\0')) || !command[0]) {
+    throw new Error('TEST_COMMAND_REQUIRED: --command-json 必须是非空命令参数数组，不通过 shell 执行');
+  }
+  const phase = args['tdd-phase'] || 'regression';
+  if (!['red', 'green', 'refactor', 'regression', 'not-applicable'].includes(phase)) throw new Error('TEST_PHASE_INVALID');
+  const taskIds = [...new Set(String(args['task-ids'] || args['task-id'] || '').split(',').map(x => x.trim()).filter(Boolean))];
+  if (!taskIds.length) throw new Error('TEST_TASKS_REQUIRED: 明确指定 --task-ids，工具不猜测测试覆盖的任务');
+  const timeout = Number(args['timeout-ms'] || 120000);
+  if (!Number.isInteger(timeout) || timeout < 1 || timeout > 3600000) throw new Error('TEST_TIMEOUT_INVALID');
+  const cwd = path.resolve(args.cwd || projectRoot);
+  if (!fs.statSync(cwd).isDirectory()) throw new Error('TEST_CWD_INVALID');
+  const runId = args['run-id'] || crypto.randomUUID();
+  const key = crypto.createHash('sha256').update(`${change}:${runId}`).digest('hex');
+  const dir = path.join(projectRoot, 'skywalk-sdd', 'state', 'test-runs', key);
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  // A run ID identifies one execution. Never re-execute a command under an old receipt.
+  try { fs.mkdirSync(dir); } catch (error) {
+    if (error.code === 'EEXIST') throw new Error('TEST_RUN_EXISTS: 此 run-id 已执行；使用保存的 details.json 重试记录，重新执行须使用新 run-id');
+    throw error;
+  }
+  const startedAt = new Date().toISOString();
+  const started = process.hrtime.bigint();
+  const childEnv = { ...process.env };
+  // The wrapper can itself run inside node:test; its child is a fresh test runner.
+  delete childEnv.NODE_TEST_CONTEXT;
+  const child = spawnSync(command[0], command.slice(1), {
+    cwd, env: childEnv, shell: false, encoding: 'utf8', timeout, maxBuffer: 16 * 1024 * 1024,
+  });
+  const duration = Math.round(Number(process.hrtime.bigint() - started) / 1e6);
+  const stdout = child.stdout || '', stderr = child.stderr || '';
+  const output = stdout + '\n' + stderr;
+  const exitCode = Number.isInteger(child.status) ? child.status : (child.error?.code === 'ETIMEDOUT' ? 124 : 1);
+  const failureType = classifyFailure(output, exitCode, child.error, child.signal);
+  const counts = parseCounts(output);
+  const files = {};
+  for (const [name, content] of Object.entries({ 'stdout.log': stdout, 'stderr.log': stderr })) {
+    fs.writeFileSync(path.join(dir, name), content, { mode: 0o600 });
+    files[name] = crypto.createHash('sha256').update(content).digest('hex');
+  }
+  const execution = {
+    origin: 'command-execution', argv: command, cwd, started_at: startedAt,
+    finished_at: new Date().toISOString(), signal: child.signal || null,
+    error: child.error ? { code: child.error.code, message: child.error.message } : null,
+    output_files: Object.entries(files).map(([name, sha256]) => ({ path: path.join(dir, name), sha256 })),
+    task_association: 'explicit-caller-declaration',
+    receipt_path: path.join(dir, 'execution.json'),
+  };
+  const testResults = {
+    run_id: runId, verified_task_ids: taskIds, tdd_phase: phase,
+    command: JSON.stringify(command), result: exitCode === 0 ? 'success' : 'failure',
+    exit_code: exitCode, duration_ms: duration, ...counts, failure_type: failureType,
+    expected_failure: phase === 'red' && args['expected-failure'] === true,
+    execution,
+  };
+  const receipt = path.join(dir, 'details.json');
+  fs.writeFileSync(execution.receipt_path, JSON.stringify(testResults, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+  fs.writeFileSync(receipt, JSON.stringify({ test_results: testResults }, null, 2) + '\n', { mode: 0o600 });
+  return { testResults, runId, receipt };
+}
+
+function verifyCapture(input, projectRoot) {
+  const base = fs.realpathSync(path.join(projectRoot, 'skywalk-sdd/state/test-runs')) + path.sep;
+  const receiptPath = fs.realpathSync(input.execution.receipt_path);
+  if (input.execution.origin !== 'command-execution' || !receiptPath.startsWith(base)) throw new Error('TEST_CAPTURE_INVALID: 执行回执不在当前项目');
+  const receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
+  for (const key of Object.keys(receipt)) {
+    if (JSON.stringify(receipt[key]) !== JSON.stringify(input[key])) throw new Error(`TEST_CAPTURE_MISMATCH: ${key} 与真实执行回执不一致`);
+  }
+  for (const output of receipt.execution.output_files) {
+    const file = fs.realpathSync(output.path);
+    if (!file.startsWith(base) || crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== output.sha256) throw new Error('TEST_CAPTURE_HASH_MISMATCH: 原始测试输出已变化');
+  }
+}
+
+module.exports = { captureTest, parseCounts, classifyFailure, verifyCapture };

package/templates/git-hooks/commit-msg

@@ -10,13 +10,24 @@ git_root=$(git rev-parse --show-toplevel 2>/dev/null) || {
   exit 1
 }
 hooks_dir=""
+# 统一反斜杠为正斜杠，保证 Windows 盘符路径（P:\a\b → P:/a/b）能被 case 判定为绝对路径
+normalize_path() {
+  printf '%s' "$1" | tr '\\' '/'
+}
+# 绝对路径（/ 开头或盘符 X: 开头）直接使用；相对路径基于 git 根拼接
+resolve_spec_dir() {
+  raw=$(normalize_path "$1")
+  case "$raw" in
+    /*|[A-Za-z]:*) printf '%s' "$raw" ;;
+    *) printf '%s' "$git_root/$raw" ;;
+  esac
+}
 spec_path=$(git -C "$git_root" config --local sdd.specPath 2>/dev/null)
 if [ -n "$spec_path" ]; then
-  case "$spec_path" in /*) ;; *) spec_path="$git_root/$spec_path" ;; esac
-  hooks_dir="$spec_path/skywalk-sdd/git-hooks"
+  hooks_dir="$(resolve_spec_dir "$spec_path")/skywalk-sdd/git-hooks"
 elif [ -f "$git_root/.sdd-spec-root" ]; then
   spec_rel=$(head -1 "$git_root/.sdd-spec-root" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
-  case "$spec_rel" in /*) hooks_dir="$spec_rel/skywalk-sdd/git-hooks" ;; *) hooks_dir="$git_root/$spec_rel/skywalk-sdd/git-hooks" ;; esac
+  hooks_dir="$(resolve_spec_dir "$spec_rel")/skywalk-sdd/git-hooks"
 fi
 if [ -n "$hooks_dir" ] && [ ! -d "$hooks_dir" ]; then
   echo "[SDD] 已配置的 Spec 路径失效：$hooks_dir"
@@ -27,12 +38,15 @@ fi
 # 方法3: 从 git 根向上搜索 skywalk-sdd/git-hooks（spec 仓本身或父级）
 if [ -z "$hooks_dir" ]; then
   search_dir="$git_root"
-  while [ "$search_dir" != "/" ] && [ "$search_dir" != "" ]; do
+  while [ -n "$search_dir" ] && [ "$search_dir" != "/" ]; do
     if [ -d "$search_dir/skywalk-sdd/git-hooks" ]; then
       hooks_dir="$search_dir/skywalk-sdd/git-hooks"
       break
     fi
-    search_dir="$(dirname "$search_dir")"
+    # Windows 盘符根（P:/）dirname 后不变，需显式收敛，避免死循环
+    parent_dir="$(dirname "$search_dir")"
+    [ "$parent_dir" = "$search_dir" ] && break
+    search_dir="$parent_dir"
   done
 fi