kld-sdd 2.5.1 → 2.6.0

package/skywalk-sdd/ontology/working-artifacts.cjs

@@ -0,0 +1,243 @@
+'use strict';
+
+const crypto = require('crypto');
+const path = require('path');
+
+const WORKING_ARTIFACT_SCHEMA_VERSION = 'kld-sdd-working-artifact-facts/v1';
+const ARTIFACT_INDEX_SCHEMA_VERSION = 'kld-sdd-working-artifact-index/v1';
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function prefixedHash(value) {
+  const normalized = String(value || '').trim().toLowerCase().replace(/^sha256:/, '');
+  return normalized ? `sha256:${normalized}` : '';
+}
+
+function safeRelativePath(value) {
+  const input = String(value || '').trim().replace(/\\/g, '/');
+  const normalized = path.posix.normalize(input);
+  if (
+    !input
+    || input.startsWith('/')
+    || normalized !== input
+    || normalized === '..'
+    || normalized.startsWith('../')
+    || input.includes('\0')
+  ) {
+    throw new Error(`工作态 Artifact 路径不安全: ${value}`);
+  }
+  return normalized;
+}
+
+function artifactJsonPath(sourcePath) {
+  const normalized = safeRelativePath(sourcePath);
+  const extension = path.posix.extname(normalized);
+  const withoutExtension = extension
+    ? normalized.slice(0, -extension.length)
+    : normalized;
+  return `artifacts/${withoutExtension}.ontology.json`;
+}
+
+function normalizedSource(source, fallbackAnchor) {
+  const input = source && typeof source === 'object' ? source : {};
+  const line = Number(input.line || 0);
+  return {
+    artifact_type: String(input.artifact_type || 'unknown').trim().toLowerCase(),
+    file: safeRelativePath(input.file),
+    ...(Number.isInteger(line) && line > 0 ? { line } : {}),
+    anchor_id: String(input.anchor_id || fallbackAnchor || '').trim().toUpperCase(),
+    content_hash: prefixedHash(input.content_hash),
+  };
+}
+
+function workingEntity(entity, reviewStatus) {
+  const anchorId = String(entity.anchor_id || entity.id || '').trim().toUpperCase();
+  return {
+    anchor_id: anchorId,
+    type: entity.type,
+    name: String(entity.name || anchorId).trim(),
+    entity_id: String(entity.entity_id || '').trim().toLowerCase(),
+    entity_version_id: String(entity.entity_version_id || entity.version_id || '').trim().toLowerCase(),
+    predecessor_version_id: entity.predecessor_version_id
+      ? String(entity.predecessor_version_id).trim().toLowerCase()
+      : null,
+    delta_state: String(entity.delta_state || 'unresolved').trim().toLowerCase(),
+    content_hash: String(entity.content_hash || '').trim().toLowerCase(),
+    fact_kind: 'semantic',
+    assertion_type: 'asserted',
+    review_status: reviewStatus,
+    generation_role: entity.generation_role || 'current',
+    ...(entity.inherited_from ? { inherited_from: entity.inherited_from } : {}),
+    attributes: entity.attributes && typeof entity.attributes === 'object' ? entity.attributes : {},
+    source: normalizedSource(entity.source, anchorId),
+  };
+}
+
+function normalizeRelationDirection(relation, entityByAnchor) {
+  const originalType = String(relation.type || '').trim();
+  const originalFrom = String(relation.from || '').trim().toUpperCase();
+  const originalTo = String(relation.to || '').trim().toUpperCase();
+  if (originalType === 'acceptedBy') {
+    return { type: 'verifiedBy', from: originalFrom, to: originalTo };
+  }
+  if (originalType !== 'constrains') {
+    return { type: originalType, from: originalFrom, to: originalTo };
+  }
+  const fromType = entityByAnchor.get(originalFrom)?.type;
+  const toType = entityByAnchor.get(originalTo)?.type;
+  if (fromType === 'Constraint' && toType === 'SpecificationStatement') {
+    return { type: 'constrainedBy', from: originalTo, to: originalFrom };
+  }
+  return { type: 'constrainedBy', from: originalFrom, to: originalTo };
+}
+
+function workingRelation(relation, entityByAnchor, reviewStatus, producerVersion) {
+  const normalized = normalizeRelationDirection(relation, entityByAnchor);
+  const fromEntity = entityByAnchor.get(normalized.from);
+  const toEntity = entityByAnchor.get(normalized.to);
+  const assertionType = String(relation.assertion_type || 'asserted').trim().toLowerCase();
+  const output = {
+    type: normalized.type,
+    from_anchor_id: normalized.from,
+    to_anchor_id: normalized.to,
+    from_entity_id: String(fromEntity?.entity_id || '').trim().toLowerCase(),
+    to_entity_id: String(toEntity?.entity_id || '').trim().toLowerCase(),
+    assertion_type: assertionType,
+    fact_kind: 'semantic',
+    review_status: assertionType === 'suggested' ? 'pending' : reviewStatus,
+    generation_role: relation.generation_role || 'current',
+    ...(relation.inherited_from ? { inherited_from: relation.inherited_from } : {}),
+    source: normalizedSource(
+      relation.source,
+      `${normalized.from}-${normalized.type}-${normalized.to}`,
+    ),
+  };
+  if (assertionType === 'inferred') {
+    output.rule_id = String(relation.rule_id || '').trim();
+    output.generator = relation.generator || 'kld-sdd';
+    output.generator_version = relation.generator_version || producerVersion;
+  } else if (relation.rule_id) {
+    output.rule_id = relation.rule_id;
+  }
+  if (assertionType === 'suggested') {
+    output.generator = relation.generator;
+    output.generator_version = relation.generator_version;
+    output.confidence = relation.confidence;
+    output.support_evidence = Array.isArray(relation.support_evidence) ? relation.support_evidence : [];
+    output.opposition_evidence = Array.isArray(relation.opposition_evidence) ? relation.opposition_evidence : [];
+  }
+  return output;
+}
+
+function compareFacts(left, right) {
+  return (
+    String(left.anchor_id || left.type || '').localeCompare(String(right.anchor_id || right.type || ''))
+    || String(left.from_entity_id || '').localeCompare(String(right.from_entity_id || ''))
+    || String(left.to_entity_id || '').localeCompare(String(right.to_entity_id || ''))
+  );
+}
+
+function buildWorkingArtifactFacts(result, options = {}) {
+  const state = result.state || {};
+  const producerVersion = String(options.producerVersion || require('../../package.json').version);
+  const reviewStatus = state.review_status === 'pending' ? 'pending' : 'draft';
+  const rawEntities = Array.isArray(state.entities) ? state.entities : [];
+  const entityByAnchor = new Map(rawEntities.map((entity) => [
+    String(entity.anchor_id || entity.id || '').trim().toUpperCase(),
+    entity,
+  ]));
+  const artifactFiles = [];
+  const artifactIndex = [];
+
+  for (const artifact of state.artifacts || []) {
+    const sourcePath = safeRelativePath(artifact.path);
+    const jsonPath = artifactJsonPath(sourcePath);
+    const artifactDiagnostics = (result.diagnostics || []).filter((diagnostic) => (
+      !diagnostic.file || String(diagnostic.file).replace(/\\/g, '/') === sourcePath
+    ));
+    const artifactEntities = rawEntities
+      .filter((entity) => (
+        entity.source && String(entity.source.file).replace(/\\/g, '/') === sourcePath
+      ))
+      .map((entity) => workingEntity(entity, reviewStatus))
+      .sort(compareFacts);
+    const artifactRelations = (state.relations || [])
+      .filter((relation) => (
+        relation.source && String(relation.source.file).replace(/\\/g, '/') === sourcePath
+      ))
+      .map((relation) => workingRelation(relation, entityByAnchor, reviewStatus, producerVersion))
+      .sort(compareFacts);
+    const inheritedReferences = (state.inherited_references || []).filter((reference) => (
+      reference.source && String(reference.source.file).replace(/\\/g, '/') === sourcePath
+    ));
+    const inheritedRelations = (state.inherited_relations || []).filter((relation) => (
+      relation.source && String(relation.source.file).replace(/\\/g, '/') === sourcePath
+    ));
+    const semanticFacts = {
+      entities: artifactEntities,
+      relations: artifactRelations,
+      inherited_references: inheritedReferences,
+      inherited_relations: inheritedRelations,
+    };
+    const artifactFacts = {
+      schema_version: WORKING_ARTIFACT_SCHEMA_VERSION,
+      producer: `kld-sdd@${producerVersion}`,
+      canonical: false,
+      change: state.change,
+      change_id: state.change_id,
+      profile: state.profile,
+      stage: artifact.type,
+      review_status: reviewStatus,
+      valid: !artifactDiagnostics.some((diagnostic) => diagnostic.severity === 'error'),
+      revision: result.revision,
+      source: {
+        artifact_type: artifact.type,
+        path: sourcePath,
+        capability_id: artifact.capability_id || null,
+        content_hash: prefixedHash(artifact.content_hash),
+      },
+      facts_hash: sha256(JSON.stringify(semanticFacts)),
+      ...semanticFacts,
+      diagnostics: artifactDiagnostics,
+    };
+    artifactFiles.push({ path: jsonPath, value: artifactFacts });
+    artifactIndex.push({
+      artifact_type: artifact.type,
+      source_path: sourcePath,
+      json_path: jsonPath,
+      capability_id: artifact.capability_id || null,
+      source_content_hash: prefixedHash(artifact.content_hash),
+      facts_hash: artifactFacts.facts_hash,
+      entity_count: artifactEntities.length,
+      relation_count: artifactRelations.length,
+      diagnostic_count: artifactDiagnostics.length,
+    });
+  }
+
+  return {
+    index: {
+      schema_version: ARTIFACT_INDEX_SCHEMA_VERSION,
+      producer: `kld-sdd@${producerVersion}`,
+      canonical: false,
+      change: state.change,
+      change_id: state.change_id,
+      profile: state.profile,
+      review_status: reviewStatus,
+      valid: Boolean(result.valid),
+      revision: result.revision,
+      working_ontology_path: 'working-ontology.json',
+      artifacts: artifactIndex,
+    },
+    files: artifactFiles,
+  };
+}
+
+module.exports = {
+  WORKING_ARTIFACT_SCHEMA_VERSION,
+  ARTIFACT_INDEX_SCHEMA_VERSION,
+  safeRelativePath,
+  artifactJsonPath,
+  buildWorkingArtifactFacts,
+};

package/templates/openspec/design.md

@@ -1,3 +1,7 @@
+---
+capability-id: "CAP-<CAPABILITY>" # 必须与对应 spec.md 一致
+---
+
 # 局部技术实现方案 - [Capability 名称]
 
 > **定位**：单一 Capability 的业务维度技术实现方案
@@ -8,6 +12,20 @@
 
 ---
 
+## 0. 本体语义锚点
+
+<!-- 每个独立设计单元创建一个 DES；修改既有设计时复用原 ID -->
+
+### [DES-<CAPABILITY>-NNN] <!-- 设计单元名称 -->
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
+- **realizes**: STMT-<CAPABILITY>-NNN
+- **设计范围**: <!-- 本设计负责实现的局部范围 -->
+
+---
+
 ## 1. 字段完整性追溯表
 
 > **⛔ 核心红线**：用户在 Spec 中输入的所有字段必须在此表中体现，严禁无故丢弃！

package/templates/openspec/proposal.md

@@ -1,5 +1,11 @@
 ---
 # 【用户选择配置 - 由 /opsx:propose 引导填写】
+change-id: "CHG-<CHANGE-SLUG>" # 创建时生成，后续不得修改
+entity-id: "<UUID>" # Change 的全局逻辑实体 UUID，added 时生成
+version-id: "<UUID>" # 本次 Change 版本 UUID
+delta-state: "added"
+predecessor-version: "" # added 留空；modified/removed 指向直接前序版本
+mode: "" # full=分 Capability 产物，simple=根目录精简产物
 test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
 ---
 
@@ -7,7 +13,7 @@ test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
 
 > **定位**：变更的业务意图（Why）与上下文总览
 >
-> **可选性**：【可跳过，直入spec】若跳过，必须将"影响范围"在 specs 中补齐
+> **必需性**：ontology v2 新产物必须保留 proposal，用于承载 Change/Capability 身份和 profile；旧 proposal-less Simple 只能兼容扫描，不能直接归档为 confirmed
 
 ---
 
@@ -41,11 +47,19 @@ test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
 
 ### 3.1 新增能力
 <!-- 每个能力会创建 specs/<name>/spec.md，使用 kebab-case 命名 -->
-- `<capability-name>`: <能力简要描述>
+- [CAP-<CAPABILITY>] `<capability-name>`: <能力简要描述>
+  - **entity-id**: <UUID>
+  - **version-id**: <UUID>
+  - **delta-state**: added
+  - **predecessor-version**: 无
 
 ### 3.2 修改能力
-<!-- 仅当已有能力的需求级别变更时填写，检查 openspec/specs/ 现有规格 -->
-- `<existing-name>`: <修改什么需求>
+<!-- 修改既有能力必须复用原 CAP ID，不得重新编号 -->
+- [CAP-<EXISTING>] `<existing-name>`: <修改什么需求>
+  - **entity-id**: <复用历史 UUID>
+  - **version-id**: <新 UUID>
+  - **delta-state**: modified
+  - **predecessor-version**: <直接前序 version UUID>
 
 ---
 
@@ -103,5 +117,4 @@ test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
 > - [ ] 逻辑链路已闭环
 > - [ ] 受影响模块已明确
 > - [ ] 依赖关系已梳理
-> - [ ] 若跳过本文档，影响范围已在 specs 中补齐
-> - [ ] 能力分解章节已明确列出所有能力
+> - [ ] 能力分解章节已明确列出所有能力

package/templates/openspec/spec.md

@@ -1,3 +1,7 @@
+---
+capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID 一致
+---
+
 # spec.md - 能力规格定义
 
 > **定位**：单个能力（capability）的技术规格定义，用于 `specs/<capability>/spec.md`
@@ -14,29 +18,49 @@
 
 ### 新增需求
 
-<!-- 新增的需求，使用「必须」强制要求 -->
+<!-- 新增实体按当前最大序号 + 1 分配 ID；已有实体修改时复用原 ID -->
 
-#### 需求项：<!-- 需求名称 -->
+#### 需求项：[STMT-<CAPABILITY>-NNN] <!-- 需求名称 -->
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
 
 <!-- 需求描述，使用「必须」而非「应该」「可以」 -->
 系统必须 ...
 
-##### 场景：<!-- 场景名称 -->
+##### 场景：[AC-<CAPABILITY>-NNN] <!-- 场景名称 -->
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
-##### 场景：<!-- 另一个场景 -->
+##### 场景：[AC-<CAPABILITY>-NNN] <!-- 另一个场景 -->
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
 ### 修改需求
 
-<!-- 仅当修改已有需求时使用，必须复制完整原需求内容再修改 -->
+<!-- 修改已有需求时复用原 STMT/AC/CON ID，只展开实际变化内容 -->
 
-#### 需求项：<!-- 已有需求名称 -->
+#### 需求项：[STMT-<CAPABILITY>-NNN] <!-- 已有需求名称，复用原 ID -->
+- **entity-id**: <复用历史 UUID>
+- **version-id**: <新 UUID>
+- **delta-state**: modified
+- **predecessor-version**: <直接前序 version UUID>
 系统必须 ...
 
-##### 场景：<!-- 场景名称 -->
+##### 场景：[AC-<CAPABILITY>-NNN] <!-- 场景名称，复用或新增 ID -->
+- **entity-id**: <复用历史 UUID；新增场景则生成新 UUID>
+- **version-id**: <新 UUID>
+- **delta-state**: <modified|added>
+- **predecessor-version**: <modified 时填写；added 为无>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
@@ -44,10 +68,40 @@
 
 <!-- 仅当移除已有需求时使用 -->
 
-#### 需求项：<!-- 被移除的需求名称 -->
+#### 需求项：[STMT-<CAPABILITY>-NNN] <!-- 被移除的需求名称，复用原 ID -->
+- **entity-id**: <复用历史 UUID>
+- **version-id**: <新墓碑版本 UUID>
+- **delta-state**: removed
+- **predecessor-version**: <直接前序 version UUID>
 **移除原因**：<!-- 移除原因 -->
 **迁移方案**：<!-- 迁移方案 -->
 
+### 约束
+
+#### 约束：[CON-<CAPABILITY>-NNN] <!-- 约束名称 -->
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
+- **constrains**: STMT-<CAPABILITY>-NNN
+- **约束内容**: <!-- 可量化、可验证的约束 -->
+
+### 继承引用
+
+<!-- unchanged 内容只记录既有实体/版本引用，不复制历史正文；断链时 opsx-check 必须阻断 -->
+- **anchor**: `STMT-<CAPABILITY>-NNN`
+- **entity-id**: `<复用历史 UUID>`
+- **version-id**: `<复用历史 version UUID>`
+- **delta-state**: `unchanged`
+- **source**: `<archive>/<artifact>#<anchor>`
+- **source-version-hash**: `<前序实体版本内容 SHA-256>`
+
+### 继承关系
+
+<!-- 历史关系不会自动全部继承；只有本节显式列出的 confirmed 关系进入 Effective Graph -->
+- **relation**: `STMT-<CAPABILITY>-NNN acceptedBy AC-<CAPABILITY>-NNN`
+- **source**: `<archive>/<artifact>#<from>-<relation>-<to>`
+
 ---
 
 ## 2. 技术契约（SDD 扩展）

package/templates/openspec/tasks.md

@@ -1,3 +1,7 @@
+---
+capability-id: "CAP-<CAPABILITY>" # 必须与对应 spec/design 一致
+---
+
 # 实施任务拆解 - [Capability 名称]
 
 > **定位**：单一 Capability 的 AI 编码引擎执行单元
@@ -116,10 +120,16 @@
 
 ---
 
-### [TASK-XXX-01] 任务名称
+### [TASK-<CAPABILITY>-NNN] 任务名称
 
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
 - **类型**: 数据层 / 接口层 / UI层 / 测试
-- **依赖**: 无
+- **implements**: DES-<CAPABILITY>-NNN
+- **covers**: STMT-<CAPABILITY>-NNN
+- **dependsOn**: 无
 - **状态**: [ ] 未完成
 
 #### 任务描述
@@ -146,10 +156,16 @@
 
 ---
 
-### [TASK-XXX-02] 任务名称
+### [TASK-<CAPABILITY>-NNN] 任务名称
 
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
 - **类型**: 数据层 / 接口层 / UI层 / 测试
-- **依赖**: 无
+- **implements**: DES-<CAPABILITY>-NNN
+- **covers**: STMT-<CAPABILITY>-NNN
+- **dependsOn**: 无
 - **状态**: [ ] 未完成
 
 #### 任务描述
@@ -173,10 +189,16 @@
 
 ---
 
-### [TASK-XXX-03] 任务名称
+### [TASK-<CAPABILITY>-NNN] 任务名称
 
+- **entity-id**: <UUID>
+- **version-id**: <UUID>
+- **delta-state**: added
+- **predecessor-version**: 无
 - **类型**: 数据层 / 接口层 / UI层 / 测试
-- **依赖**: TASK-XXX-01, TASK-XXX-02
+- **implements**: DES-<CAPABILITY>-NNN
+- **covers**: STMT-<CAPABILITY>-NNN
+- **dependsOn**: TASK-<CAPABILITY>-NNN, TASK-<CAPABILITY>-NNN
 - **状态**: [ ] 未完成
 
 #### 任务描述

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

@@ -107,7 +107,8 @@ node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reas
 
 该命令成功后必须已经完成：
 - 活动目录 `openspec/changes/<name>/` 被移入 `openspec/changes/archive/<日期>-<name>/`。
-- 归档目录写入 `archive-manifest.json`。
+- 归档目录写入 `archive-ontology.json`、`canonical-facts.json`、`conversion-report.json` 和新版 `archive-manifest.json`。
+- 生成知识库可直接消费的 `openspec/changes/archive/<日期>-<name>.zip`，包内文件必须由 manifest 完整列举并通过 SHA-256 校验。
 - Full Spec 的 `specs/<capability>/spec.md` 同步到 `openspec/specs/<capability>/spec.md`。
 - archive 阶段写入 `stage_end`。
 - 未勾选 tasks 被写入 `archive_result.task_completion`。
@@ -132,6 +133,8 @@ node skywalk-sdd/log.cjs end --event-id=<event_id> --command=archive --project=.
 > - 归档目录：`openspec/changes/archive/<日期>-<name>/`
 > - 最终报告（默认同时生成 .md + .html）：`openspec/changes/archive/<日期>-<name>/reports/<name>-report.md`、`openspec/changes/archive/<日期>-<name>/reports/<name>-report.html`
 > - 执行日志：`openspec/changes/archive/<日期>-<name>/logs/execution-log.md`
+> - 知识库归档包：`openspec/changes/archive/<日期>-<name>.zip`
+> - 本体消费入口：`openspec/changes/archive/<日期>-<name>/canonical-facts.json`
 > - 未勾选任务：X 项，已记录到报告，不阻断归档
 > - 正式 specs：`openspec/specs/`
 
@@ -155,6 +158,21 @@ node skywalk-sdd/log.cjs record --type=baseline_record --command=archive --proje
 
 ---
 
+## 本体语义归档门禁
+
+- 归档前必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<变更名称>`，不能只信任文件观察事件。
+- 随后必须运行 `node skywalk-sdd/log.cjs semantic-check --project=. --change=<变更名称>`；有阻断诊断时禁止移动活动 Change。
+- Archive 不负责首次生成 propose/spec/design/tasks 的工作态事实；它重新解析原文核对 pending revision，补充 `OntologySnapshot/project_id/archive_id` 后冻结为 confirmed。
+- `archive-docs` 成功后必须在归档目录生成 `archive-ontology.json`，并将 `review_status` 标记为 `confirmed`。
+- 生产端必须把 confirmed 本体转换为 `canonical-facts.json`；实体固定为 `fact_kind=semantic`、`assertion_type=asserted`、`review_status=confirmed`，关系必须补齐对应语义边界字段。
+- `acceptedBy` 在消费协议中归一化为 `verifiedBy`；inferred 关系必须携带 `rule_id`、`generator` 和 `generator_version`。
+- 每个 canonical 实体和关系的 `source.file` 必须存在于 Archive Package，`source.content_hash` 必须等于该原文文件的 SHA-256。
+- `archive-manifest.json` 必须使用 `kld-sdd-archive-manifest/v2`，并与 canonical facts 的 project/archive/change 身份一致。
+- `conversion-report.json` 必须记录源/目标 schema、转换状态、实体数、关系数和归一化告警。
+- Archive 快照必须固化人工锚点、逻辑实体 UUID、版本 UUID、前序版本 UUID、delta-state 和内容哈希；任一 UUID 冲突或谱系断裂都不得 confirmed。
+- 归档目录已经复制但语义快照失败时，不得删除活动 Change，不得标记 confirmed。
+- unchanged 正文保留在前序 Archive；当前归档只固化差量事实、继承引用和来源锚点。
+
 ## Guardrails
 
 - 归档操作执行前必须让用户确认归档原因。

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

@@ -18,7 +18,11 @@ description: "opsx-archive 前后日志/总结自检清单 — 仅在 archive
 ## B. 归档后自检
 
 - [ ] 归档目录 `openspec/changes/archive/<日期>-<变更名称>/` 存在
-- [ ] `openspec/changes/archive/<日期>-<变更名称>/archive-manifest.json` 存在
+- [ ] `openspec/changes/archive/<日期>-<变更名称>/` 下 `archive-ontology.json`、`canonical-facts.json`、`conversion-report.json` 和 `archive-manifest.json` 均存在
+- [ ] 活动 change 目录下的 `artifacts/*.ontology.json` 与 `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` 定向展开到包内原文
 - [ ] 最终报告 `openspec/changes/archive/<日期>-<变更名称>/reports/<变更名称>-report.md` 存在且含「归档结果」段
 - [ ] `reports/<变更名称>-report.md` 与 `reports/<变更名称>-report.html` 都已生成（md+html 双产物）
 - [ ] html 报告含 `SDD 效果度量报告` 标题与各度量章节（执行摘要/效率/质量/过程/归档结果/说明）

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

@@ -200,6 +200,24 @@ node skywalk-sdd/log.cjs record --type=conformance_review --command=check --proj
 
 ---
 
+## 本体语义关系门禁
+
+在其他质量检查前必须运行：
+
+```bash
+node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<变更名称> --profile=<simple|full|strict>
+node skywalk-sdd/log.cjs semantic-check --project=. --change=<变更名称> --profile=<simple|full|strict>
+```
+
+- `simple` 必须阻断 STMT 无 AC；没有 design/tasks 时跳过对应链路，不得误报。
+- `full` 必须阻断 STMT→AC→Design→Task 任一断链。
+- `strict` 在 full 基础上要求完整来源字段并提升可选警告。
+- 所有 profile 都必须阻断重复人工锚点、UUID 缺失/非法、跨 Change 或 Archive 的实体 UUID 误复用、版本 UUID 重用、版本谱系断裂、悬空引用、非法 domain/range 和 Task 依赖成环。
+- `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`。
+
 ## Guardrails
 
 - Check 是**只读检查**操作，不修改任何文档内容

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

@@ -35,3 +35,5 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
 
 - [ ] 完整性、一致性、算法正确性、可执行性四维均已输出
 - [ ] 报告问题对应修复建议（spec/design/task）
+- [ ] `openspec/changes/<变更名称>/artifact-index.json` 已覆盖当前全部 proposal/spec/design/tasks，且每份 `artifacts/*.ontology.json` 与 `working-ontology.json` revision 一致
+- [ ] 全部语义门禁通过时工作态 JSON 已从 draft 刷新为 pending；check 未修改任何 Markdown 原文

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

@@ -164,6 +164,17 @@ design.md 中若使用 version 正则约束（如格式校验 `^\d+\.\d+\.\d+$`
 
 ---
 
+## 本体语义生成契约
+
+- 写入与当前 spec 一致的 `capability-id`。
+- 每个独立设计单元必须使用 `DES-<CAPABILITY>-NNN`；新增前按当前最大序号 + 1 分配，修改时复用原 ID。
+- 每个 DES 必须同时写 `entity-id`、`version-id`、`delta-state` 和按需的 `predecessor-version`；新增用 `semantic-identity --delta-state=added`，修改时复用实体 UUID 并生成新版本 UUID。
+- 每个 DES 必须通过 `**realizes**: STMT-*` 显式引用一个或多个真实 STMT。
+- 不得仅凭文本相似创建 realizes；没有上游 STMT 时必须标记 unresolved。
+- 生成结束后必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>`。
+- reconcile 必须立即生成 `openspec/changes/<name>/artifacts/.../design.ontology.json`，其中 DES 和 realizes 关系保留原文 source；不得推迟到 check/archive。
+- 阶段 `stage_end` 会在无 Hook 环境下幂等执行同步兜底。
+
 ## Guardrails
 
 > 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：

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

@@ -202,6 +202,18 @@ openspec instructions proposal --change "<name>" --json
 
 ---
 
+## 本体语义生成契约
+
+- 创建 Change 时必须写入 `change-id: CHG-<CHANGE-SLUG>`；重新编辑时不得修改已有 Change ID。
+- 每个新增 Capability 必须写成 `[CAP-<CAPABILITY>] <slug>: <说明>`。
+- 修改既有 Capability 时必须复用已有 CAP ID，不得修改或重新分配已有实体 ID。
+- 分配新 CAP ID 前必须扫描当前 proposal 和归档中的显式编号；不得只凭标题认定跨 Change 同一性。
+- 每个 Change/Capability 同时写人工锚点、`entity-id`、`version-id` 和 `delta-state`。新增时必须调用 `node skywalk-sdd/log.cjs semantic-identity --delta-state=added`，不得手写或复制 UUID。
+- 修改既有 Capability 时调用 `semantic-identity --delta-state=modified --entity-id=<历史实体UUID> --predecessor-version=<直接前序版本UUID>`；复用实体 UUID，但必须生成新版本 UUID。
+- 本阶段只声明 Change 和 Capability，不得提前生成 STMT、AC、DES 或 TASK 事实。
+- proposal.md 写入结束后必须立即运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>`，生成 `openspec/changes/<name>/artifacts/proposal.ontology.json`；不得等到 check 或 archive 才首次生成 JSON。
+- 阶段 `stage_end` 会在无 Hook 环境下幂等执行同一次同步作为兜底，结果中的 `semantic_state.artifact_json_paths` 必须包含 proposal 对应 JSON。
+
 ## Guardrails
 
 > 完整 ⛔ 强制项勾选清单见 `./checklist.md`「Guardrails ⛔ 强制项」。核心红线：

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

@@ -39,6 +39,8 @@ description: opsx-propose 的阶段强制检查点与自检清单。仅在执行
 - [ ] Capabilities 章节是关键：决定后续 specs 文件夹结构
 - [ ] 若跳过此文档，后续 specs 必须补齐影响范围
 - [ ] 文档写入后验证文件确实存在
+- [ ] proposal.md 写入后已运行 `semantic-reconcile`，`openspec/changes/<变更名称>/artifacts/proposal.ontology.json` 已存在
+- [ ] 工作态 JSON 为 `canonical=false`、`review_status=draft`，实体能够通过 `source.file/source.anchor_id/source.content_hash` 展开到 proposal.md 原文
 - [ ] 每次生成都提供文档摘要，等待用户确认后再继续
 - [ ] ⛔ **阶段边界**：本阶段禁止执行任何代码创建/修改操作；用户要求处理代码时回复「当前处于 Propose 阶段，代码操作请在完成文档后使用 `/opsx-apply` 执行。」
 - [ ] ⛔ **单阶段原则**：完成 proposal.md 后必须立即停止；仅提示用户下一步可运行 `/opsx-spec`，绝对禁止自动执行 spec/design/task 等后续阶段。每个阶段必须由用户主动触发。