kld-sdd 2.5.1 → 2.5.2

package/skywalk-sdd/ontology/traceability-validator.cjs

@@ -0,0 +1,610 @@
+'use strict';
+
+const {
+  DIAGNOSTIC_CODES,
+  normalizeProfile,
+  relationDefinition,
+} = require('./schema.cjs');
+const { isValidEntityId, isValidUuid } = require('./id.cjs');
+
+function diagnostic(code, severity, message, context = {}) {
+  return {
+    code,
+    severity,
+    message,
+    file: context.file || '',
+    line: Number(context.line || 0),
+    entity_id: context.entity_id || undefined,
+    relation: context.relation || undefined,
+    suggestion: context.suggestion || undefined,
+  };
+}
+
+function sourceContext(item) {
+  return {
+    file: item && item.source && item.source.file,
+    line: item && item.source && item.source.line,
+  };
+}
+
+function findTaskCycles(relations) {
+  const graph = new Map();
+  for (const relation of relations.filter((item) => item.type === 'dependsOn')) {
+    if (!graph.has(relation.from)) graph.set(relation.from, []);
+    graph.get(relation.from).push(relation.to);
+  }
+  const visiting = new Set();
+  const visited = new Set();
+  const cycles = [];
+
+  function visit(node, path) {
+    if (visiting.has(node)) {
+      const start = path.indexOf(node);
+      cycles.push(path.slice(start).concat(node));
+      return;
+    }
+    if (visited.has(node)) return;
+    visiting.add(node);
+    for (const next of graph.get(node) || []) visit(next, path.concat(node));
+    visiting.delete(node);
+    visited.add(node);
+  }
+
+  for (const node of graph.keys()) visit(node, []);
+  return cycles;
+}
+
+function validateIdentitySemantics(facts, diagnostics, identityHistory) {
+  const entities = facts.entities || [];
+  const currentByEntityId = new Map();
+  const currentByVersionId = new Map();
+
+  for (const entity of entities) {
+    const context = { ...sourceContext(entity), entity_id: entity.id };
+    if (!entity.entity_id || !entity.version_id) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.UUID_MISSING,
+        'error',
+        `实体缺少全局 entity-id 或 version-id: ${entity.id}`,
+        { ...context, suggestion: '使用 semantic-identity 生成 UUID；继承实体必须复用历史 UUID' },
+      ));
+      continue;
+    }
+    if (!isValidUuid(entity.entity_id) || !isValidUuid(entity.version_id)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.UUID_INVALID,
+        'error',
+        `实体 UUID 格式非法: ${entity.id}`,
+        { ...context, suggestion: '重新运行 semantic-identity，禁止手写伪 UUID' },
+      ));
+      continue;
+    }
+    if (!['added', 'modified', 'unchanged', 'removed'].includes(entity.delta_state)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.DELTA_STATE_INVALID,
+        'error',
+        `实体 delta-state 缺失或非法: ${entity.id}`,
+        { ...context, suggestion: '使用 added、modified、unchanged 或 removed' },
+      ));
+    }
+    if (['modified', 'removed'].includes(entity.delta_state)
+      && !isValidUuid(entity.predecessor_version_id)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.VERSION_LINEAGE_MISSING,
+        'error',
+        `${entity.delta_state} 实体缺少有效 predecessor-version: ${entity.id}`,
+        { ...context, suggestion: '指向同一 entity-id 的直接前序 version-id' },
+      ));
+    }
+    if (entity.delta_state === 'added' && entity.predecessor_version_id) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.VERSION_LINEAGE_MISSING,
+        'error',
+        `added 实体不应声明 predecessor-version: ${entity.id}`,
+        context,
+      ));
+    }
+
+    const entityOwner = currentByEntityId.get(entity.entity_id);
+    if (entityOwner && (entityOwner.id !== entity.id || entityOwner.type !== entity.type)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
+        'error',
+        `同一 entity-id 被不同实体复用: ${entityOwner.id} / ${entity.id}`,
+        { ...context, suggestion: '不同逻辑实体必须重新生成 entity-id' },
+      ));
+    } else if (!entityOwner) {
+      currentByEntityId.set(entity.entity_id, entity);
+    }
+
+    const versionOwner = currentByVersionId.get(entity.version_id);
+    if (versionOwner && (versionOwner.entity_id !== entity.entity_id || versionOwner.content_hash !== entity.content_hash)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.VERSION_IDENTITY_CONFLICT,
+        'error',
+        `同一 version-id 对应不同实体或内容: ${entity.version_id}`,
+        { ...context, suggestion: '每个新增、修改或删除版本必须生成新的 version-id' },
+      ));
+    } else if (!versionOwner) {
+      currentByVersionId.set(entity.version_id, entity);
+    }
+  }
+
+  if (!Array.isArray(identityHistory)) return;
+  const historyByEntityId = new Map();
+  const historyByVersionId = new Map();
+  const historyByAnchor = new Map();
+  for (const record of identityHistory) {
+    if (record.entity_id) {
+      if (!historyByEntityId.has(record.entity_id)) historyByEntityId.set(record.entity_id, []);
+      historyByEntityId.get(record.entity_id).push(record);
+    }
+    if (record.version_id && !historyByVersionId.has(record.version_id)) {
+      historyByVersionId.set(record.version_id, record);
+    }
+    if (record.anchor_id) {
+      if (!historyByAnchor.has(record.anchor_id)) historyByAnchor.set(record.anchor_id, []);
+      historyByAnchor.get(record.anchor_id).push(record);
+    }
+  }
+
+  for (const entity of entities) {
+    if (!isValidUuid(entity.entity_id) || !isValidUuid(entity.version_id)) continue;
+    const context = { ...sourceContext(entity), entity_id: entity.id };
+    const priorEntities = historyByEntityId.get(entity.entity_id) || [];
+    const priorAnchors = historyByAnchor.get(entity.anchor_id || entity.id) || [];
+    const priorVersion = historyByVersionId.get(entity.version_id);
+
+    if (priorEntities.some((record) => record.anchor_id !== entity.id || record.type !== entity.type)
+      || priorAnchors.some((record) => record.entity_id !== entity.entity_id)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
+        'error',
+        `entity-id 与历史锚点或类型冲突: ${entity.id}`,
+        { ...context, suggestion: '确认是同一逻辑实体；复制产生的新实体必须生成新 UUID' },
+      ));
+    }
+
+    if (entity.delta_state === 'added') {
+      if (priorEntities.length > 0) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
+          'error',
+          `added 实体复用了历史 entity-id: ${entity.id}`,
+          { ...context, suggestion: 'added 必须生成新的 entity-id；同一实体变化应使用 modified' },
+        ));
+      }
+      if (priorVersion) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.VERSION_IDENTITY_CONFLICT,
+          'error',
+          `added 实体复用了历史 version-id: ${entity.version_id}`,
+          context,
+        ));
+      }
+    }
+
+    if (['modified', 'removed'].includes(entity.delta_state)) {
+      const predecessor = historyByVersionId.get(entity.predecessor_version_id);
+      if (priorEntities.length === 0 || !predecessor || predecessor.entity_id !== entity.entity_id) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.VERSION_LINEAGE_MISSING,
+          'error',
+          `${entity.delta_state} 无法定位同一实体的前序版本: ${entity.id}`,
+          { ...context, suggestion: '从 Archive 读取 entity-id 和直接前序 version-id' },
+        ));
+      }
+      if (priorVersion) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.VERSION_IDENTITY_CONFLICT,
+          'error',
+          `${entity.delta_state} 必须生成新的 version-id: ${entity.id}`,
+          context,
+        ));
+      }
+      const knownSuccessor = priorEntities.find((record) => (
+        ['modified', 'removed'].includes(record.delta_state)
+        && record.predecessor_version_id === entity.predecessor_version_id
+        && record.version_id !== entity.version_id
+      ));
+      if (knownSuccessor) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.VERSION_LINEAGE_CONFLICT,
+          'error',
+          `同一 predecessor 已存在后继版本，禁止并行或陈旧分支: ${entity.id}`,
+          { ...context, suggestion: `以 ${knownSuccessor.change} 的版本为直接前序；不要再次继承已消费的 predecessor` },
+        ));
+      }
+    }
+
+    if (entity.delta_state === 'unchanged') {
+      if (priorEntities.length === 0 || !priorVersion || priorVersion.entity_id !== entity.entity_id) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.VERSION_LINEAGE_MISSING,
+          'error',
+          `unchanged 引用无法定位既有实体版本: ${entity.id}`,
+          { ...context, suggestion: '复用 Archive 中同一实体的 entity-id 和 version-id' },
+        ));
+      } else if (priorVersion.anchor_id !== entity.id
+        || priorVersion.type !== entity.type
+        || priorVersion.content_hash !== entity.content_hash) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.VERSION_IDENTITY_CONFLICT,
+          'error',
+          `unchanged 实体与历史版本内容或锚点不一致: ${entity.id}`,
+          { ...context, suggestion: 'unchanged 必须完整复用历史 anchor、entity/version UUID 和内容；正文变化应使用 modified' },
+        ));
+      }
+    }
+  }
+}
+
+function validateArtifactPresence(facts, profile, diagnostics) {
+  const artifacts = facts.artifacts || [];
+  const hasType = (type) => artifacts.some((artifact) => artifact.type === type);
+  const addMissing = (message, file = '') => diagnostics.push(diagnostic(
+    DIAGNOSTIC_CODES.ARTIFACT_MISSING,
+    'error',
+    message,
+    { file, line: 1 },
+  ));
+
+  if (!hasType('proposal')) addMissing('ontology v2 Change 缺少 proposal.md');
+  if (!hasType('spec')) addMissing(`${profile} Change 缺少 spec.md`);
+  if (profile !== 'full' && profile !== 'strict') return;
+
+  const activeCapabilities = (facts.entities || []).filter((entity) => (
+    entity.type === 'Capability' && entity.delta_state !== 'removed'
+  ));
+  for (const capability of activeCapabilities) {
+    for (const type of ['spec', 'design', 'tasks']) {
+      if (artifacts.some((artifact) => artifact.type === type && artifact.capability_id === capability.id)) continue;
+      addMissing(`Full Capability ${capability.id} 缺少 ${type} 产物`, capability.source && capability.source.file);
+    }
+  }
+}
+
+function validateInheritedReferences(facts, diagnostics, identityHistory) {
+  const declaredAnchors = new Set((facts.entities || []).map((entity) => entity.id));
+  const references = facts.inherited_references || [];
+  const historyByVersionId = new Map();
+  if (Array.isArray(identityHistory)) {
+    for (const record of identityHistory) {
+      if (record.version_id && !historyByVersionId.has(record.version_id)) {
+        historyByVersionId.set(record.version_id, record);
+      }
+    }
+  }
+
+  for (const reference of references) {
+    const context = {
+      ...sourceContext(reference),
+      entity_id: reference.anchor_id,
+      suggestion: 'unchanged 只复用 Archive 中的实体/版本 UUID、来源锚点和内容哈希，不复制正文',
+    };
+    if (!isValidUuid(reference.entity_id) || !isValidUuid(reference.version_id)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.UUID_INVALID,
+        'error',
+        `unchanged 引用缺少有效 UUID: ${reference.anchor_id}`,
+        context,
+      ));
+      continue;
+    }
+    if (reference.delta_state !== 'unchanged') {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.DELTA_STATE_INVALID,
+        'error',
+        `继承引用必须使用 unchanged: ${reference.anchor_id}`,
+        context,
+      ));
+    }
+    if (declaredAnchors.has(reference.anchor_id)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
+        'error',
+        `同一锚点不能同时声明本次实体和 unchanged 引用: ${reference.anchor_id}`,
+        context,
+      ));
+    }
+    if (!reference.source_ref || !/^[a-f0-9]{64}$/i.test(reference.source_version_hash || '')) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.SOURCE_MISSING,
+        'error',
+        `unchanged 引用缺少来源路径或版本内容哈希: ${reference.anchor_id}`,
+        context,
+      ));
+    }
+
+    if (!Array.isArray(identityHistory)) continue;
+    const priorVersion = historyByVersionId.get(reference.version_id);
+    if (!priorVersion
+      || priorVersion.entity_id !== reference.entity_id
+      || priorVersion.anchor_id !== reference.anchor_id) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.VERSION_LINEAGE_MISSING,
+        'error',
+        `unchanged 引用无法定位历史实体版本: ${reference.anchor_id}`,
+        context,
+      ));
+      continue;
+    }
+    if (reference.source_version_hash && priorVersion.content_hash !== reference.source_version_hash) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.INHERITED_SOURCE_MISMATCH,
+        'error',
+        `unchanged 来源内容哈希与 Archive 不一致: ${reference.anchor_id}`,
+        context,
+      ));
+    }
+  }
+}
+
+function validateTraceability(facts, options = {}) {
+  const profile = normalizeProfile(options.profile || 'auto', facts.profile || 'simple');
+  const graphEntities = options.effectiveGraph && options.effectiveGraph.effective_entities
+    ? options.effectiveGraph.effective_entities
+    : (facts.entities || []);
+  const graphRelations = options.effectiveGraph && options.effectiveGraph.effective_relations
+    ? options.effectiveGraph.effective_relations
+    : (facts.relations || []);
+  const diagnostics = (facts.diagnostics || []).map((item) => (
+    profile === 'strict' && item.code === DIAGNOSTIC_CODES.ID_MISSING
+      ? { ...item, severity: 'error' }
+      : item
+  ));
+  const entitiesById = new Map();
+
+  validateArtifactPresence(facts, profile, diagnostics);
+
+  if (profile === 'strict') {
+    for (const artifact of facts.artifacts || []) {
+      if (!['spec', 'design', 'tasks'].includes(artifact.type) || artifact.capability_id) continue;
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.ID_MISSING,
+        'error',
+        `${artifact.type} 产物缺少 capability-id`,
+        {
+          file: artifact.path,
+          line: 1,
+          suggestion: '在 YAML frontmatter 中写入 proposal 已声明的 CAP ID',
+        },
+      ));
+    }
+  }
+
+  for (const entity of facts.entities || []) {
+    if (!isValidEntityId(entity.id, entity.type)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.ID_INVALID,
+        'error',
+        `实体 ID 与类型不匹配: ${entity.id} (${entity.type})`,
+        { ...sourceContext(entity), entity_id: entity.id, suggestion: '使用模板规定的实体前缀和稳定编号格式' },
+      ));
+    }
+    if (!entity.source || !entity.source.file || !entity.source.anchor_id) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.SOURCE_MISSING,
+        'error',
+        `实体缺少可定位来源: ${entity.id}`,
+        { ...sourceContext(entity), entity_id: entity.id },
+      ));
+    }
+    if (!entitiesById.has(entity.id)) entitiesById.set(entity.id, []);
+    entitiesById.get(entity.id).push(entity);
+  }
+
+  validateIdentitySemantics(facts, diagnostics, options.identityHistory);
+  validateInheritedReferences(facts, diagnostics, options.identityHistory);
+
+  for (const [entityId, declarations] of entitiesById.entries()) {
+    if (declarations.length <= 1) continue;
+    const first = declarations[0];
+    diagnostics.push(diagnostic(
+      DIAGNOSTIC_CODES.ID_DUPLICATE,
+      'error',
+      `实体 ID 重复声明: ${entityId}`,
+      { ...sourceContext(first), entity_id: entityId, suggestion: '保留原实体 ID；为真正新增实体分配下一个可用序号' },
+    ));
+  }
+
+  const graphEntitiesById = new Map();
+  for (const entity of graphEntities) {
+    if (!graphEntitiesById.has(entity.id)) graphEntitiesById.set(entity.id, entity);
+  }
+  const entityType = new Map();
+  const removedEntityIds = new Set();
+  for (const [entityId, entity] of graphEntitiesById.entries()) {
+    entityType.set(entityId, entity.type);
+    if (entity.delta_state === 'removed') removedEntityIds.add(entityId);
+  }
+  for (const reference of facts.inherited_references || []) {
+    if (!entityType.has(reference.anchor_id) && reference.type) {
+      entityType.set(reference.anchor_id, reference.type);
+    }
+  }
+
+  for (const relation of graphRelations) {
+    if (relation.assertion_type === 'inferred' && !String(relation.rule_id || '').trim()) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.RELATION_ASSERTION_INVALID,
+        'error',
+        `inferred 关系缺少稳定 rule_id: ${relation.from} -${relation.type}-> ${relation.to}`,
+        { ...sourceContext(relation), relation: relation.id },
+      ));
+    }
+    const definition = relationDefinition(relation.type);
+    if (!definition) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.RELATION_UNKNOWN,
+        'error',
+        `未知关系类型: ${relation.type}`,
+        { ...sourceContext(relation), relation: relation.id },
+      ));
+      continue;
+    }
+    if (!entityType.has(relation.from) || !entityType.has(relation.to)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.RELATION_TARGET_MISSING,
+        'error',
+        `关系引用不存在的实体: ${relation.from} -${relation.type}-> ${relation.to}`,
+        { ...sourceContext(relation), relation: relation.id, suggestion: '修正引用，或先在对应上游产物中声明实体' },
+      ));
+      continue;
+    }
+    if (removedEntityIds.has(relation.from) || removedEntityIds.has(relation.to)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.RELATION_TARGET_REMOVED,
+        'error',
+        `当前有效关系不能引用 removed 实体: ${relation.from} -${relation.type}-> ${relation.to}`,
+        { ...sourceContext(relation), relation: relation.id },
+      ));
+      continue;
+    }
+    const fromType = entityType.get(relation.from);
+    const toType = entityType.get(relation.to);
+    const matchesDomainRange = definition.domain.includes(fromType) && definition.range.includes(toType);
+    const matchesAllowedPair = !definition.pairs
+      || definition.pairs.some(([allowedFrom, allowedTo]) => allowedFrom === fromType && allowedTo === toType);
+    if (!matchesDomainRange || !matchesAllowedPair) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.RELATION_DOMAIN_RANGE,
+        'error',
+        `关系定义域/值域非法: ${fromType} -${relation.type}-> ${toType}`,
+        { ...sourceContext(relation), relation: relation.id, suggestion: '按照本体 Schema 调整关系方向或目标实体类型' },
+      ));
+    }
+  }
+
+  const activeEntities = graphEntities.filter((entity) => entity.delta_state !== 'removed');
+  const statements = activeEntities.filter((entity) => entity.type === 'SpecificationStatement');
+  const acceptances = activeEntities.filter((entity) => entity.type === 'AcceptanceCriterion');
+  const designs = activeEntities.filter((entity) => entity.type === 'DesignElement');
+  const tasks = activeEntities.filter((entity) => entity.type === 'Task');
+  const relations = graphRelations.filter((relation) => (
+    relation.assertion_type === 'asserted'
+    || (relation.assertion_type === 'inferred' && String(relation.rule_id || '').trim())
+  ));
+
+  const capabilityByEntity = new Map();
+  for (const entity of activeEntities) {
+    const capabilityId = entity.type === 'Capability'
+      ? entity.id
+      : entity.attributes && entity.attributes.capability_id;
+    if (capabilityId) capabilityByEntity.set(entity.id, capabilityId);
+  }
+  for (const acceptance of acceptances) {
+    const statementId = acceptance.attributes && acceptance.attributes.statement_id;
+    if (statementId && capabilityByEntity.has(statementId)) {
+      capabilityByEntity.set(acceptance.id, capabilityByEntity.get(statementId));
+    }
+  }
+  for (const relation of relations) {
+    const fromCapability = capabilityByEntity.get(relation.from);
+    const toCapability = capabilityByEntity.get(relation.to);
+    if (fromCapability && toCapability && fromCapability !== toCapability) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.CAPABILITY_BOUNDARY,
+        'error',
+        `关系跨越 Capability 边界: ${relation.from}(${fromCapability}) -${relation.type}-> ${relation.to}(${toCapability})`,
+        { ...sourceContext(relation), relation: relation.id },
+      ));
+    }
+  }
+
+  for (const statement of statements) {
+    if (!relations.some((relation) => relation.type === 'acceptedBy' && relation.from === statement.id)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.STMT_WITHOUT_AC,
+        'error',
+        `STMT 缺少验收条件: ${statement.id}`,
+        { ...sourceContext(statement), entity_id: statement.id, suggestion: '在该需求项下新增带 AC 编号的场景' },
+      ));
+    }
+    if ((profile === 'full' || profile === 'strict') && !relations.some((relation) => relation.type === 'realizes' && relation.to === statement.id)) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.STMT_WITHOUT_DESIGN,
+        'error',
+        `Full 链路中 STMT 缺少 Design: ${statement.id}`,
+        { ...sourceContext(statement), entity_id: statement.id, suggestion: '新增 DES 实体并显式写入 realizes 引用' },
+      ));
+    }
+  }
+
+  for (const acceptance of acceptances) {
+    const owners = relations.filter((relation) => relation.type === 'acceptedBy' && relation.to === acceptance.id);
+    if (owners.length !== 1) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.AC_WITHOUT_STMT,
+        'error',
+        `AC 必须且只能归属一个有效 STMT: ${acceptance.id}`,
+        { ...sourceContext(acceptance), entity_id: acceptance.id },
+      ));
+    }
+  }
+
+  for (const task of tasks) {
+    if (!relations.some((relation) => (
+      relation.from === task.id && (relation.type === 'implements' || relation.type === 'covers')
+    ))) {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.TASK_WITHOUT_UPSTREAM,
+        'error',
+        `Task 缺少 implements 或 covers 上游关系: ${task.id}`,
+        { ...sourceContext(task), entity_id: task.id },
+      ));
+    }
+  }
+
+  if (profile === 'full' || profile === 'strict') {
+    for (const design of designs) {
+      if (!relations.some((relation) => relation.type === 'implements' && relation.to === design.id)) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.DESIGN_WITHOUT_TASK,
+          'error',
+          `Full 链路中 Design 缺少 Task: ${design.id}`,
+          { ...sourceContext(design), entity_id: design.id, suggestion: '新增 TASK 实体并显式写入 implements 引用' },
+        ));
+      }
+    }
+  }
+
+  for (const cycle of findTaskCycles(relations)) {
+    const taskId = cycle[0];
+    const task = graphEntitiesById.get(taskId);
+    diagnostics.push(diagnostic(
+      DIAGNOSTIC_CODES.TASK_DEPENDENCY_CYCLE,
+      'error',
+      `Task 依赖成环: ${cycle.join(' -> ')}`,
+      { ...sourceContext(task), entity_id: taskId, suggestion: '移除至少一条 dependsOn 关系以恢复 DAG' },
+    ));
+  }
+
+  diagnostics.sort((left, right) => (
+    String(left.code).localeCompare(String(right.code))
+    || String(left.file || '').localeCompare(String(right.file || ''))
+    || Number(left.line || 0) - Number(right.line || 0)
+    || String(left.message || '').localeCompare(String(right.message || ''))
+  ));
+
+  return {
+    profile,
+    valid: !diagnostics.some((item) => item.severity === 'error'),
+    diagnostics,
+    counts: {
+      entities: graphEntities.length,
+      relations: graphRelations.length,
+      inherited_references: (facts.inherited_references || []).length,
+      errors: diagnostics.filter((item) => item.severity === 'error').length,
+      warnings: diagnostics.filter((item) => item.severity === 'warning').length,
+    },
+  };
+}
+
+module.exports = {
+  diagnostic,
+  findTaskCycles,
+  validateIdentitySemantics,
+  validateInheritedReferences,
+  validateTraceability,
+};

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 中补齐
-> - [ ] 能力分解章节已明确列出所有能力
+> - [ ] 能力分解章节已明确列出所有能力