kld-sdd 2.6.13 → 2.6.15

package/skywalk-sdd/reporting/change-report-view-model.cjs

@@ -0,0 +1,340 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Shared change-report view model for Markdown / HTML / parity digests.
+ * Four desktop tabs: 概览 / 指标与阶段 / 问题与证据 / 产物与追溯
+ */
+
+const SECTION_ORDER = [
+  'overview',
+  'metrics-stages',
+  'issues-evidence',
+  'artifacts-trace',
+];
+
+const SECTION_TITLES = {
+  overview: '概览',
+  'metrics-stages': '指标与阶段',
+  'issues-evidence': '问题与证据',
+  'artifacts-trace': '产物与追溯',
+};
+
+function fractionText(verified, total) {
+  if (verified == null || total == null) return '暂无数据';
+  return `${verified}/${total}`;
+}
+
+function percentText(value, digits = 2) {
+  return Number.isFinite(Number(value))
+    ? `${(Number(value) * 100).toFixed(digits)}%`
+    : '暂无数据';
+}
+
+function durationText(value) {
+  if (!Number.isFinite(Number(value))) return '暂无数据';
+  const totalSeconds = Math.round(Number(value) / 1000);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  return [hours ? `${hours}小时` : '', minutes ? `${minutes}分` : '', `${seconds}秒`]
+    .filter(Boolean)
+    .join('');
+}
+
+function localTimeText(value) {
+  if (!value) return '—';
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime())
+    ? '—'
+    : parsed.toLocaleTimeString('zh-CN', { hour: '2-digit', minute: '2-digit' });
+}
+
+function buildSemanticDigestInput(report, sections) {
+  const audit = report.task_evidence_audit || {};
+  const tdd = report.tdd_pair_audit || {};
+  const changed = report.changed_files || {};
+  const evidence = report.change_summary?.evidence || {};
+  const artifacts = report.artifacts?.files || {};
+  return {
+    schema_version: report.schema_version || null,
+    metrics_contract: report.metrics_contract || null,
+    change: report.change || null,
+    section_ids: SECTION_ORDER.slice(),
+    conclusion_status: report.conclusion?.status || null,
+    tasks: {
+      document: report.change_summary?.tasks?.document || null,
+      direct_test_backlink: audit.direct_test_backlink || null,
+      strict_test_coverage: audit.strict_test_coverage || null,
+      traceability: report.change_summary?.tasks?.traceability || null,
+    },
+    tdd_pairs: {
+      required: tdd.required ?? null,
+      complete: tdd.complete ?? null,
+    },
+    tests: report.change_summary?.tests || null,
+    evidence: {
+      category_count: evidence.category_count ?? null,
+      occurrence_count: evidence.occurrence_count ?? null,
+      issues: (evidence.issues || []).map((issue) => ({
+        issue_id: issue.issue_id,
+        code: issue.code,
+        status: issue.status,
+        verdict: issue.verdict,
+        subject: issue.subject,
+        expected: issue.expected,
+        actual: issue.actual,
+        root_cause: issue.root_cause,
+        remediation: issue.remediation,
+        evidence_event_ids: issue.evidence_event_ids,
+        disposition: issue.disposition,
+      })),
+    },
+    changed_files: {
+      task_event_files_changed: changed.task_event_files_changed ?? null,
+      final_output_files_changed: changed.final_output_files_changed ?? null,
+      added_lines: changed.added_lines ?? null,
+      deleted_lines: changed.deleted_lines ?? null,
+      diff_source: changed.diff_source ?? null,
+      reconciliation_status: changed.reconciliation_status ?? null,
+    },
+    attribution: report.attribution_audit || null,
+    artifact_sizes: Object.fromEntries(
+      Object.entries(artifacts).map(([name, item]) => [name, item?.size_bytes ?? null]),
+    ),
+    section_summaries: Object.fromEntries(
+      SECTION_ORDER.map((id) => [id, sections[id]?.summary || null]),
+    ),
+  };
+}
+
+function buildChangeReportViewModel(report = {}) {
+  const summary = report.change_summary || {};
+  const audit = report.task_evidence_audit || {};
+  const tdd = report.tdd_pair_audit || {};
+  const changed = report.changed_files || {};
+  const evidence = summary.evidence || { categories: [], category_count: 0, occurrence_count: 0 };
+  const artifacts = report.artifacts?.files || {};
+  const metrics = report.metrics || {};
+  const efficiency = metrics.efficiency || {};
+  const quality = metrics.quality || {};
+  const process = metrics.process || {};
+  const telemetry = metrics.telemetry_health || {};
+  const minSet = report.minimum_metric_set || {};
+  const openIssueCount = (report.evidence_alerts?.open || []).length;
+  const totalDurationMs = efficiency.total_duration_ms
+    ?? efficiency.effective_stage_duration_including_rework_ms
+    ?? efficiency.e1_lead_time_ms
+    ?? null;
+  const e1 = efficiency.e1_scenario_delivery_efficiency_ms ?? null;
+  const e2 = efficiency.e2_coding_time_ratio_including_rework
+    ?? efficiency.e2_coding_time_ratio
+    ?? null;
+  const e3 = efficiency.e3_spec_time_ratio_including_rework
+    ?? efficiency.e3_spec_time_ratio
+    ?? null;
+  const metricCards = [
+    {
+      name: '每个场景平均用时',
+      code: 'E1',
+      value: Number.isFinite(e1) ? `${durationText(e1)} / 场景` : '暂无数据',
+      state: (
+        minSet.evidence_status?.e1 === 'trusted'
+        || minSet.trusted_metrics?.includes?.('e1')
+        || minSet.trusted?.includes?.('e1')
+      ) ? '可信' : '需补证',
+      explanation: '七个标准阶段总耗时（含返工）÷ 验收场景数。',
+      source: `公式：标准阶段总耗时 ÷ 场景数。场景数：${efficiency.scenario_count ?? '未知'}；当前值：${e1 ?? '不可计算'} ms。`,
+    },
+    {
+      name: '规约检查得分',
+      code: 'Q3',
+      value: quality.q3_spec_quality_score == null ? '暂无数据' : `${quality.q3_spec_quality_score} / 100`,
+      state: quality.q3_score_status === 'verified' ? '已验证' : '临时',
+      explanation: '最新规约检查结果；独立复核后才标记为已验证。',
+      source: `评审独立性：${quality.q3_reviewer_independence || '未知'}；证据状态：${quality.q3_score_status || '未知'}。`,
+    },
+    {
+      name: '编码前是否先检查',
+      code: 'P4',
+      value: percentText(process.p4_quality_gate_enforcement_rate),
+      state: Number.isFinite(process.p4_quality_gate_enforcement_rate) ? '可计算' : '需补证',
+      explanation: '首次进入编码前，是否存在已配对且成功或部分通过的检查。',
+      source: '只接受能与 check 开始事件配对、且发生在首次 apply 之前的成功或部分通过结果。',
+    },
+    {
+      name: '阶段重复次数',
+      code: 'P-R',
+      value: process.rework_summary?.total_rework_attempts == null
+        ? '暂无数据'
+        : `${process.rework_summary.total_rework_attempts} 次`,
+      state: process.rework_summary ? '可计算' : '需补证',
+      explanation: '七个标准阶段中，首次执行之后的重复尝试次数。',
+      source: '辅助 test / explore 阶段不计入标准阶段重复总数。',
+    },
+    {
+      name: '执行记录是否完整',
+      code: 'P-H',
+      value: telemetry.p_h_telemetry_health_score == null
+        ? '暂无数据'
+        : `${telemetry.p_h_telemetry_health_score} / 100`,
+      state: telemetry.p_h_telemetry_health_score == null ? '需补证' : '可计算',
+      explanation: '标准阶段的身份、开始结束配对和数据质量综合评分。',
+      source: '沿用既有权重，但只以 propose、spec、design、task、check、apply、archive 七阶段为计算范围。',
+    },
+  ];
+
+  const sections = {
+    overview: {
+      id: 'overview',
+      title: SECTION_TITLES.overview,
+      summary: report.conclusion?.text || '当前证据不足，暂不能形成可信结论。',
+      scope_duration: durationText(totalDurationMs),
+      cards: [
+        {
+          key: 'final_tests',
+          label: '最终测试',
+          value: fractionText(summary.tests?.passed, summary.tests?.total),
+        },
+        {
+          key: 'document_tasks',
+          label: '文档任务完成',
+          value: fractionText(summary.tasks?.document?.completed, summary.tasks?.document?.total),
+        },
+        {
+          key: 'direct_backlink',
+          label: '直接测试回链',
+          value: fractionText(
+            audit.direct_test_backlink?.verified,
+            audit.direct_test_backlink?.total,
+          ),
+        },
+        {
+          key: 'strict_coverage',
+          label: '严格测试覆盖',
+          value: fractionText(
+            audit.strict_test_coverage?.verified ?? summary.tasks?.traceability?.verified,
+            audit.strict_test_coverage?.total ?? summary.tasks?.traceability?.total,
+          ),
+        },
+        {
+          key: 'open_issues',
+          label: '开放证据问题',
+          value: String(openIssueCount),
+        },
+      ],
+      metric_cards: metricCards,
+    },
+    'metrics-stages': {
+      id: 'metrics-stages',
+      title: SECTION_TITLES['metrics-stages'],
+      summary: '本次变更效率、质量、过程与阶段执行',
+      metrics: {
+        total_duration_ms: totalDurationMs,
+        e1,
+        e2,
+        e3,
+        q3: quality.q3_spec_quality_score ?? null,
+        p4: process.p4_quality_gate_enforcement_rate ?? null,
+        p_r: process.rework_summary?.total_rework_attempts ?? null,
+        p_h: telemetry.p_h_telemetry_health_score ?? null,
+      },
+      metric_cards: metricCards,
+      metric_rows: [
+        { label: '七阶段总耗时', value: durationText(totalDurationMs) },
+        { label: '每个场景平均用时', code: 'E1', value: metricCards[0].value },
+        { label: '编码时间占比', code: 'E2', value: percentText(e2) },
+        { label: '规划与规约时间占比', code: 'E3', value: percentText(e3) },
+        { label: '阶段重复执行', code: 'P-R', value: metricCards[3].value },
+      ],
+      stages: (report.stage_timeline?.nodes || []).map((node) => ({
+        ...node,
+        display_stage: node.stage || node.command || '未知阶段',
+        display_round: node.round || 1,
+        display_start: localTimeText(node.start_ts),
+        display_end: localTimeText(node.end_ts),
+        display_duration: durationText(node.duration_ms),
+        display_result: node.result || '未知',
+      })),
+      tdd_pairs: {
+        required: tdd.required ?? null,
+        complete: tdd.complete ?? null,
+        pairs: tdd.pairs || [],
+      },
+    },
+    'issues-evidence': {
+      id: 'issues-evidence',
+      title: SECTION_TITLES['issues-evidence'],
+      summary: evidence.note
+        || `${evidence.category_count || 0} 类问题，${evidence.occurrence_count || 0} 次规则命中`,
+      categories: evidence.categories || [],
+      issues: evidence.issues || [],
+      open_alerts: report.evidence_alerts?.open || [],
+      task_evidence_audit: audit,
+      apply_findings: report.apply_evidence_audit?.findings || [],
+      warning_dispositions: report.warning_dispositions || [],
+    },
+    'artifacts-trace': {
+      id: 'artifacts-trace',
+      title: SECTION_TITLES['artifacts-trace'],
+      summary: changed.reconciliation_note || '产物与文件对账',
+      changed_files: {
+        task_event_files_changed: changed.task_event_files_changed ?? null,
+        final_output_files_changed: changed.final_output_files_changed ?? null,
+        added_lines: changed.added_lines ?? null,
+        deleted_lines: changed.deleted_lines ?? null,
+        diff_source: changed.diff_source || null,
+        reconciliation_status: changed.reconciliation_status ?? null,
+        reconciliation_note: changed.reconciliation_note || null,
+        final_output_files: changed.final_output_files || changed.files || null,
+        only_in_task_events: changed.only_in_task_events || [],
+        only_in_final_output: changed.only_in_final_output || [],
+      },
+      artifacts: Object.entries(artifacts).map(([name, item]) => ({
+        name,
+        path: item?.path || null,
+        exists: Boolean(item?.exists),
+        size_bytes: item?.size_bytes ?? null,
+        size_display: item?.size_display || null,
+        sha256: item?.sha256 ?? null,
+        integrity_note: item?.integrity_note || null,
+      })),
+      attribution: report.attribution_audit || null,
+      attribution_summary: {
+        linked_source_event_count: report.attribution_audit?.linked_source_event_count ?? 0,
+        active_link_count: report.attribution_audit?.active_links?.length ?? 0,
+        unassigned_candidate_count: report.attribution_audit?.unassigned_candidate_event_ids?.length ?? 0,
+        rejected_collision_count: report.attribution_audit?.rejected_direct_collision_event_ids?.length ?? 0,
+      },
+    },
+  };
+
+  return {
+    change: report.change || null,
+    schema_version: report.schema_version || null,
+    metrics_contract: report.metrics_contract || null,
+    generated_at: report.generated_at || null,
+    conclusion: report.conclusion || null,
+    minimum_metric_set: report.minimum_metric_set || null,
+    scheme_compliance: report.scheme_compliance || null,
+    known_risks: report.known_risks || null,
+    process_notes: report.process_notes || null,
+    telemetry_warnings: report.telemetry_warnings || null,
+    archive_result: report.archive_result || null,
+    report_scope: report.report_scope || null,
+    section_order: SECTION_ORDER.slice(),
+    sections,
+    semantic_digest_input: buildSemanticDigestInput(report, sections),
+    semantic_digest: crypto.createHash('sha256')
+      .update(JSON.stringify(buildSemanticDigestInput(report, sections)))
+      .digest('hex'),
+  };
+}
+
+module.exports = {
+  SECTION_ORDER,
+  SECTION_TITLES,
+  buildChangeReportViewModel,
+  buildSemanticDigestInput,
+};

package/skywalk-sdd/runtime-metadata.cjs

@@ -0,0 +1,21 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * 解析运行时元数据，返回 producer 身份信息。
+ *
+ * 开发/测试模式：直接读取上级 package.json 的 version 字段。
+ * 部署模式：init.js 会生成一个版本号写死的 runtime-metadata.cjs 覆盖此文件。
+ *
+ * @returns {{ version: string, producer: string }}
+ */
+function resolveRuntimeMetadata() {
+  const pkg = require(path.join(__dirname, '..', 'package.json'));
+  return {
+    version: pkg.version,
+    producer: `kld-sdd@${pkg.version}`,
+  };
+}
+
+module.exports = { resolveRuntimeMetadata };

package/templates/skills/kld-sdd/opsx-apply/reference.md

@@ -17,10 +17,12 @@ description: opsx-apply 的详细模板：telemetry 命令、worktree 全套策
 ### task_update（每完成一个任务记录）
 
 ```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<本次任务更新稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json="{\"task_update\":{\"test_event_id\":\"<同一change内成功test_result的event_id>\",\"tdd_required\":<true|false>},\"files_changed\":[]}"
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<本次任务更新稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json="{\"task_update\":{\"test_event_id\":\"<同一change内成功test_result的event_id>\",\"tdd_required\":<true|false>,\"tdd_pair_id\":\"<pair-N>\",\"tdd_role\":\"green\"},\"files_changed\":[]}"
+
+也可互斥使用 `test_run_id`（同 change、覆盖当前任务、唯一严格完成候选）；解析成功后会补齐规范化 `test_event_id`。
 ```
 
-**⚠️ 注意**：`--task-id=<TASK-ID>` 必须替换为实际任务 ID。完成任务必须引用同一 change 内、`tdd_phase` 为 green/refactor/regression、退出码为 0、`failure_type=none` 的 `test_result.event_id`，并明确填写 `tdd_required=true/false`；禁止把测试计数复制进 `task_update`。
+**⚠️ 注意**：`--task-id=<TASK-ID>` 必须替换为实际任务 ID。完成任务必须引用同一 change 内、`tdd_phase` 为 green/refactor/regression、退出码为 0、`failure_type=none` 的 `test_result.event_id`（或可唯一解析的 `test_run_id`），并明确填写 `tdd_required=true/false`；TDD 任务应写同一 `tdd_pair_id` 与 `tdd_role`；禁止把测试计数复制进 `task_update`。
 
 只有文档、纯配置说明等确实不适用测试的任务，才能显式声明：
 

package/templates/skills/kld-sdd/opsx-archive/SKILL.md

@@ -112,7 +112,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" tasks-status --project=. --chan
 ```json
 {
   "maturity_evidence": {
-    "change_type": "config|document|report|composite|other",
+    "change_type": "config|transaction|report|composite",
     "e1_actual_ms": 500,
     "e1_target_ms": 600,
     "e1_type_target_met": true,

package/templates/skills/kld-sdd/opsx-archive/checklist.md

@@ -21,7 +21,7 @@ description: "opsx-archive 前后日志/总结自检清单 — 仅在 archive
 
 - [ ] 归档目录 `openspec/changes/archive/<日期>-<变更名称>/` 存在
 - [ ] `openspec/changes/archive/<日期>-<变更名称>/` 下 `archive-ontology.json`、`canonical-facts.json`、`conversion-report.json` 和 `archive-manifest.json` 均存在
-- [ ] 活动 change 目录下的 `artifacts/*.ontology.json` 与 `artifact-index.json` 已随归档目录一并迁移
+- [ ] 活动 change 目录下的 `artifacts/*.ontology.json` 与 `ontology/artifact-index.json` 已随归档目录一并迁移
 - [ ] `archive-manifest.json` 为 `kld-sdd-archive-manifest/v2`，且 `files` 精确覆盖 ZIP 内除 manifest 自身外的全部文件
 - [ ] `openspec/changes/archive/<日期>-<变更名称>.zip` 存在并可由知识库 `ArchivePackageReader` 读取
 - [ ] canonical facts 中每个实体/关系均能通过 `source.file`、`source.anchor_id`、`source.content_hash` 定向展开到包内原文

package/templates/skills/kld-sdd/opsx-check/SKILL.md

@@ -305,7 +305,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --type=conformance_revie
 `opsx-check` **不联网提问**。Agent 应在 propose/spec 已问完；本阶段只验证并入既有 apply 前门禁：
 
 - Continuity=`iteration` 时每个 CAP 具备 KB 回传 `entity-id` / `version-id`
-- 已写 spec 的 Capability：场景 `external-ref` 与 `continuity-resolution.json` 决议一致；同 key+同锚点未偷偷换 entity_id
+- 已写 spec 的 Capability：场景 `external-ref` 与 `ontology/continuity-resolution.json` 决议一致；同 key+同锚点未偷偷换 entity_id
 - 用户选「原对象」却仍用新 id、或选「新对象」却仍共用旧锚点 → 失败（`CONTINUITY_IDENTITY_MISMATCH` / `EXTERNAL_REF_CONFLICT`）
 - 决议缺失 / pending / 与产物不一致 → `CONTINUITY_DECISION_REQUIRED`
 - **编号诊断码**（并入五维报告与 apply gate）：
@@ -333,7 +333,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-check --project=. --ch
 - `added` 必须使用全新实体/版本 UUID；`modified/removed` 必须复用实体 UUID并指向直接前序版本；`unchanged` 必须复用历史实体和版本 UUID且不得复制历史正文。
 - 文件观察结果只能作为快速上下文，check 必须重新全量 semantic-reconcile。
 - propose/spec/design/task 对应工作态 JSON 应已在各作者阶段生成；check 不负责首次生成业务事实，只重新解析 Markdown、核对各 JSON 与同一 revision，并在全部通过时把派生 revision 更新为 `review_status=pending`。
-- Check 只读是指不修改 proposal/spec/design/tasks 原文；允许原子刷新 `openspec/changes/<变更名称>/` 下可再生的 `working-ontology.json`、`artifact-index.json` 与 `artifacts/*.ontology.json`。
+- Check 只读是指不修改 proposal/spec/design/tasks 原文；允许原子刷新 `openspec/changes/<变更名称>/` 下可再生的 `ontology/working-ontology.json`、`ontology/artifact-index.json` 与 `artifacts/*.ontology.json`。
 
 ## Guardrails
 

package/templates/skills/kld-sdd/opsx-check/checklist.md

@@ -57,5 +57,5 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
 
 ## F. 语义门禁与工作态
 
-- [ ] `openspec/changes/<变更名称>/artifact-index.json` 已覆盖当前全部 proposal/spec/design/tasks，且每份 `artifacts/*.ontology.json` 与 `working-ontology.json` revision 一致
+- [ ] `openspec/changes/<变更名称>/ontology/artifact-index.json` 已覆盖当前全部 proposal/spec/design/tasks，且每份 `artifacts/*.ontology.json` 与 `ontology/working-ontology.json` revision 一致
 - [ ] 全部语义门禁通过时工作态 JSON 已从 draft 刷新为 pending；check 未修改任何 Markdown 原文

package/templates/skills/kld-sdd/opsx-kb-ingest/SKILL.md

@@ -49,6 +49,20 @@ Task Progress:
 
 入库时：用户指定目标 KB（从 `targets` 中选择），仅对选中的 KB 执行上传。
 
+### 3.5 兜底：确保 project-identity.json 存在（上传前必做）
+
+> 正常情况下 `project-identity.json` 已在 `opsx-ontology-query` 首次配置 KB 时创建。
+> 本步是兜底：如果用户跳过了 ontology-query（如选择 archive 降级路径），直接来做入库，需要确保文件存在且 `project_id` 正确。
+
+1. 读取 spec 包裹包路径：
+   ```bash
+   SPEC_ROOT=$(node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root)
+   ```
+2. 检查 `$SPEC_ROOT/skywalk-sdd/project-identity.json`：
+   - **不存在** → 从 `targets[0].spaceKey` 创建（格式同 `opsx-ontology-query` Step 3.5）
+   - **已存在但 `project_id !== targets[0].spaceKey`** → 提示用户：`⚠️ project_id 与 Space spaceKey 不一致，入库将报 PROJECT_SPACE_MISMATCH。是否更新？`
+   - **已存在且一致** → 跳过
+
 ### 4. 入库操作
 
 路径前缀：`/api/v1/spaces/{spaceId}/knowledge-bases/{kbId}/ingestions`

package/templates/skills/kld-sdd/opsx-ontology-query/SKILL.md

@@ -56,6 +56,37 @@ Task Progress:
 
 **选择空间/KB**：`GET $API/v1/spaces?tenantKey=…` → 对每个 space `GET …/knowledge-bases` → 展示清单**允许多选** → 写入共享 `../.shared/kb-state.json` 的 `targets`。
 
+### 3.5 写入项目身份文件（首次配置 Space 后）
+
+> `project-identity.json` 是 spec 仓 Git 中的**团队共享**文件，记录 `project_id`（= KB Space 的 `spaceKey`）。Archive 阶段 `archive-docs` 读取此文件生成 `archive-manifest.json`，kb-ingest 上传时 KB 校验 `project_id === spaceKey`。
+
+选择 Space 完成后（Step 3 写入 `targets` 后），执行以下逻辑：
+
+1. 读取 spec 包裹包路径：
+   ```bash
+   SPEC_ROOT=$(node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root)
+   ```
+2. 检查 `$SPEC_ROOT/skywalk-sdd/project-identity.json` 是否已存在
+3. **不存在** → 创建（取 `targets[0].spaceKey` 作为 `project_id`）：
+   ```json
+   {
+     "schema_version": "kld-sdd-project-identity/v1",
+     "project_id": "<targets[0].spaceKey>",
+     "created_at": "<ISO timestamp>",
+     "kb_space_id": "<targets[0].spaceId>",
+     "kb_space_name": "<targets[0].spaceName>"
+   }
+   ```
+   输出：`✓ 已创建 skywalk-sdd/project-identity.json（project_id: <spaceKey>），请提交到 spec 仓 Git 以便团队共享`
+4. **已存在但 `project_id` 与 `targets[0].spaceKey` 不一致** → 用 AskUserQuestion 询问：
+   > "project-identity.json 中的 project_id 与当前选择的 KB Space spaceKey 不一致：
+   > - 文件中：`<existing project_id>`
+   > - 当前 Space：`<spaceKey>`
+   > 是否更新？"
+   - 用户确认 → 更新 `project_id` + `kb_space_id` + `kb_space_name`
+   - 用户拒绝 → 保留原值（可能入库时报 `PROJECT_SPACE_MISMATCH`）
+5. **已存在且一致** → 跳过，不输出
+
 > state.json 字段 schema、鉴权细节、列表接口 → [reference.md](reference.md)。
 
 ## 查询

package/templates/skills/kld-sdd/opsx-propose/SKILL.md

@@ -229,9 +229,9 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" --mode=resolve \
 5. 若申报了 feature-id：额外 `objectType=feature` resolve 一次，展示「该功能下已有能力 n 个（存活 m / 失效 k）」辅助勾选 CAP 范围；不改变 Continuity 判定优先级。
 6. 按 KB 结果确认 Continuity：`iteration` / `similar-reference` / `new`；勾选本次涉及的 CAP。
 7. 写入 proposal frontmatter：`requirement-refs`（含 `feature-id`）/ `numbering-waiver` + `continuity`。**禁止**写本地 archive 文件夹名作为 `base-archive`。
-8. CAP 级「同 key + 同锚点、不同 entity_id」当场问 A/B/C；决议写入 `continuity-resolution.json` 的 `capabilities[]`。
+8. CAP 级「同 key + 同锚点、不同 entity_id」当场问 A/B/C；决议写入 `ontology/continuity-resolution.json` 的 `capabilities[]`。
 9. KB 不可用 → `degraded` 继续，**禁止**扫本地 `archive/` 抄 UUID。KB degraded（用户选择跳过）时走路径 B（archive 降级）：
-   - 扫描 `openspec/changes/archive/*/ontology-identities.json` 匹配 canonicalKey
+   - 扫描 `openspec/changes/archive/*/ontology/ontology-identities.json` 匹配 canonicalKey
    - path B 的所有 entity-id 来源在 sdd-output.md 知识库使用表中必须标注 `source: archive(degraded)`，与 `source: KB current` 明确区分。
    - ⚠️ **降级风险**：archive 中的 version-id 可能已过时（如果该 capability 在 archive 之后又有新版本入库到 KB）。path B 的 predecessor-version 不保证是 KB current。入库时可能触发 `VERSION_CONFLICT`。
 10. **不得**在本阶段生成 STMT/AC/场景或裁决场景身份；**不得**铸/改 REQ/FEAT 号。
@@ -254,7 +254,7 @@ resolve(canonicalKey=CAP-USER-REGISTRATION) → CREATE_NEW
 ```
 # 扫描归档（仅 KB degraded 时）
 Read openspec/changes/archive/*/proposal.md 的能力分解章节
-Read openspec/changes/archive/*/ontology-identities.json
+Read openspec/changes/archive/*/ontology/ontology-identities.json
 
 # 匹配结果示例：
 # "账号锁定从内存迁到DB" → 匹配归档 CAP-ACCOUNT-LOCKOUT (entity-id: 3d18c60e, version: 29e7f242)
@@ -272,7 +272,7 @@ Read openspec/changes/archive/*/ontology-identities.json
 
 **❗ 必须主动询问用户，不得默认选择**。在模式与测试策略选择附近，基于需求给出 `change-type` **推荐**并让用户确认；Auto 只能推荐，**禁止无提示静默写入**。
 
-允许值固定为：`config | document | report | composite | other`（写入 proposal.md YAML frontmatter 的 `change-type` 字段）。AskUserQuestion 文案与类型说明见 `./reference.md`「§7.5 变更类型选择」。
+允许值固定为：`config | transaction | report | composite`（写入 proposal.md YAML frontmatter 的 `change-type` 字段）。AskUserQuestion 文案与类型说明见 `./reference.md`「§7.5 变更类型选择」。
 
 ### 8. 【交互引导】测试策略选择
 
@@ -340,11 +340,11 @@ Read openspec/changes/archive/*/ontology-identities.json
 - **⛔ 阶段边界**：本阶段禁止执行任何代码创建/修改操作。若用户要求处理代码，回复：「当前处于 Propose 阶段，代码操作请在完成文档后使用 `/opsx-apply` 执行。」
 - **⛔ 单阶段原则**：完成 proposal.md 后必须立即停止。仅提示用户下一步可运行 `/opsx-spec`，绝对禁止自动执行 spec/design/task 等后续阶段。每个阶段必须由用户主动触发。
 - **⛔ Frontmatter 规范（L7）**：YAML frontmatter 中禁止写 `#` 注释（YAML 注释在 frontmatter 中可能导致解析问题）。如需说明，在 frontmatter 之前或之后用正文描述。
-- **⛔ change-type 必采**：frontmatter 必须含 `change-type`，取值仅限 `config | document | report | composite | other`；Agent 可推荐但须经用户确认后写入，禁止静默默认。
+- **⛔ change-type 必采**：frontmatter 必须含 `change-type`，取值仅限 `config | transaction | report | composite`；Agent 可推荐但须经用户确认后写入，禁止静默默认。
 
 ---
 
 ## 渐进披露
 
 - Read `checklist.md` 仅在执行 propose 需要校验时 — 含阶段边界⛔（Propose 阶段约束）、§6 需求完整性检查、Guardrails ⛔ 强制项勾选表。
-- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end）、§7 文档拆分模式（Full/Simple/Auto）、§7.5 变更类型（config/document/report/composite/other）、§8 测试策略（TDD/Impl-First/None）、§10 质量红线自检清单（8 项）。
+- Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end）、§7 文档拆分模式（Full/Simple/Auto）、§7.5 变更类型（config/transaction/report/composite）、§8 测试策略（TDD/Impl-First/None）、§10 质量红线自检清单（8 项）。

package/templates/skills/kld-sdd/opsx-propose/reference.md

@@ -56,20 +56,19 @@ description: opsx-propose 的详细模板：telemetry 命令、文档拆分模
 
 > "📊 **变更类型（用于 V3 指标分层统计）**
 >
-> 根据本次需求，推荐类型：**[config | document | report | composite | other]** — [一句话理由]
+> 根据本次需求，推荐类型：**[config | transaction | report | composite]** — [一句话理由]
 >
 > 请选择或确认：
 > - **config** — 配置/开关/环境/依赖调整，几乎不改业务逻辑
-> - **document** — 文档、规范、模板、注释类变更
-> - **report** — 报告、度量、仪表盘、采集契约类变更
+> - **transaction** — 单据类：业务流程、状态流转、CRUD/交易路径变更
+> - **report** — 报表类：报表查询、度量展示、采集契约（不是“度量报告工具”本身的专属类型）
 > - **composite** — 跨多类能力的组合变更
-> - **other** — 以上均不合适时使用
 >
 > A) 采用推荐  B) 手动选择其他类型"
 
-根据用户确认，在 proposal.md YAML frontmatter 写入 `change-type: <值>`。允许值固定：`config | document | report | composite | other`。
+根据用户确认，在 proposal.md YAML frontmatter 写入 `change-type: <值>`。允许值固定：`config | transaction | report | composite`。
 
-> 历史 proposal 缺该字段时，报告侧归为 `unknown`；本阶段不得替用户猜测补写。
+> 历史 proposal 的 `document`/`other` 读取侧迁移为 `unknown` 并告警，不写入新 proposal；本阶段不得替用户猜测补写。
 
 ---
 
@@ -107,6 +106,6 @@ description: opsx-propose 的详细模板：telemetry 命令、文档拆分模
 - [ ] 前置依赖使用 checkbox 格式
 - [ ] 文档末尾包含质量红线检查清单
 - [ ] 能力分解章节已明确（决定后续 specs 文件夹结构）
-- [ ] frontmatter 含 `change-type`，取值为 `config | document | report | composite | other` 之一且经用户确认
+- [ ] frontmatter 含 `change-type`，取值为 `config | transaction | report | composite` 之一且经用户确认
 
 **如有任意一项未满足，重新生成对应章节，直至全部通过。**

package/templates/skills/kld-sdd/opsx-spec/SKILL.md

@@ -170,7 +170,7 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
   2. 新场景：`SCN-<slug>-<NNN>`；slug=kebab-case 小写 ≤40；NNN=该 REQ 命名空间内 max+1（已用集合=KB 回传 ∪ 本 Change 已写键，含 removed 墓碑）。
   3. removed 号是墓碑：永不复用、永不重排；序号达 999 → 硬错误，回需求系统拆分需求，不扩位。
   4. 写完立即用 `cli.cjs external-key --validate … --type scenario` 校验；REQ 前缀必须 ∈ proposal `requirement-refs`。
-- 场景级「同 SCN key + 同锚点、不同 entity_id」当场问 A/B/C；未决不得进入下一 CAP / design。决议追加到 `continuity-resolution.json` 的 `scenarios[]`；决议中的 `externalKey` 必须是归一化形态。
+- 场景级「同 SCN key + 同锚点、不同 entity_id」当场问 A/B/C；未决不得进入下一 CAP / design。决议追加到 `ontology/continuity-resolution.json` 的 `scenarios[]`；决议中的 `externalKey` 必须是归一化形态。
 - 优先消费 `reuseBundles[].statements`；`designElements` 只作理解上下文，不能写成 Spec 的 How。
 - 所有知识库内容均为 advisory；与用户确认 / proposal 冲突时以当前确认与 proposal 为准。
 - **禁止**铸/改 REQ/FEAT；**禁止**自动重排/回收 SCN。

package/templates/skills/kld-sdd/tdd-core/reference.md

@@ -129,7 +129,9 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=test_res
 **实现任务**（不带 `task_kind`）：
 
 ```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<任务更新稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"files_changed":[],"task_update":{"test_event_id":"<成功的green/refactor测试event_id>","tdd_required":true}}'
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<任务更新稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"files_changed":[],"task_update":{"test_event_id":"<成功的green/refactor测试event_id>","tdd_required":true,"tdd_pair_id":"<pair-N>","tdd_role":"green"}}'
+
+> RED/GREEN 同对必须写相同 `tdd_pair_id`；也可用互斥的 `test_run_id`（唯一严格完成候选）代替 `test_event_id`。
 ```
 
 ## §9 单元测试真实执行

package/templates/skills/kld-sdd/tdd-rules/rules/test-skeleton-telemetry.md

@@ -15,5 +15,5 @@ node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=test_res
 实现任务不带 `task_kind`（默认 implementation），按真实测试结果记录。
 
 ```bash
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<任务更新稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"files_changed":[],"task_update":{"test_event_id":"<成功的green/refactor测试event_id>","tdd_required":true}}'
+node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" record --strict --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --run-id=<任务更新稳定ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"files_changed":[],"task_update":{"test_event_id":"<成功的green/refactor测试event_id>","tdd_required":true,"tdd_pair_id":"<pair-N>","tdd_role":"green"}}'
 ```