kld-sdd 2.7.8-6 → 2.7.8-7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.7.8-6",
+  "version": "2.7.8-7",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "lib/init.js",
   "bin": {

package/skywalk-sdd/index.cjs

@@ -7706,7 +7706,11 @@ function cmdCheckRecord(args) {
   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
+  const { splitCheckDiagnostics } = require('./ontology/spec-ontology.cjs');
+  const preflightBlocked = preflight.product_valid === false
+    || (preflight.product_valid == null && !splitCheckDiagnostics(preflight.diagnostics).product_valid);
+  const stateBlocked = !splitCheckDiagnostics(state.diagnostics).product_valid;
+  if (preflightBlocked || stateBlocked || 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: 文档或历史身份已变化，重新预检并评审受影响内容');
@@ -8239,16 +8243,20 @@ function cmdSemanticIdentity(args) {
 }
 
 function semanticResultPayload(result) {
+  const split = require('./ontology/spec-ontology.cjs').splitCheckDiagnostics(result.diagnostics);
   return {
     change: result.state.change,
     profile: result.profile,
     valid: result.valid,
+    product_valid: split.product_valid,
     review_status: result.state.review_status,
     revision: result.revision,
     changed: Boolean(result.changed),
     counts: result.counts,
     paths: result.paths,
     diagnostics: result.diagnostics,
+    tool_diagnostics: split.tool_diagnostics,
+    product_diagnostics: split.product_diagnostics,
   };
 }
 
@@ -8290,13 +8298,32 @@ function cmdSemanticReconcile(args, options = {}) {
       total: Number(finished - started) / 1e6,
     };
   }
+  if (options.productGate && payload.tool_diagnostics.length > 0) {
+    try {
+      const repair = require('./ontology/spec-ontology.cjs').materializeChangeSpecOntology(
+        context.projectRoot,
+        context.changeName,
+      );
+      payload.tool_repair = {
+        repaired: repair.validation.valid,
+        output_path: repair.output_path,
+        mapping_path: repair.mapping_path,
+      };
+    } catch (error) {
+      payload.tool_repair = { repaired: false };
+    }
+  }
   console.log(JSON.stringify(payload, null, 2));
-  if (!result.valid) process.exitCode = 1;
+  if (options.productGate) {
+    if (!payload.product_valid) process.exitCode = 1;
+  } else if (!result.valid) {
+    process.exitCode = 1;
+  }
   return result;
 }
 
 function cmdSemanticCheck(args) {
-  return cmdSemanticReconcile(args, { markPending: true, includeTasks: Boolean(args['include-tasks']) });
+  return cmdSemanticReconcile(args, { markPending: true, includeTasks: Boolean(args['include-tasks']), productGate: true });
 }
 
 function cmdSemanticStatus(args) {

package/skywalk-sdd/kb-upload.cjs

@@ -12,6 +12,11 @@
  *   node skywalk-sdd/kb-upload.cjs --folder=<path> [--minimum-level=propose-spec] [--validate-only]
  *   node skywalk-sdd/kb-upload.cjs --package=<zip-path>
  *   node skywalk-sdd/kb-upload.cjs --folder=<path> --project=<spec-root> --change=<name>
+ *   node skywalk-sdd/kb-upload.cjs --folder=<path> --require-review
+ *
+ * 历史产物（缺 entity-id / version-id）：
+ *   自动旁路物化 spec-ontology.json，无 semantic_key 冲突时自动确认并发布为 current；
+ *   有冲突或 --require-review 时只上传候选，需人工 approve-spec-ontology 后再上传。
  *
  * project_id 解析：
  *   1. $SPEC_ROOT/skywalk-sdd/project-identity.json 的 project_id
@@ -243,9 +248,65 @@ function preCheckProjectId(projectId, state, selectedTarget) {
  *   5. materializeArchivePackage（生成 manifest + canonical-facts + conversion-report + zip）
  *   6. 返回 zip 路径
  */
+/**
+ * 历史产物的 Spec 本体解析：
+ *   - 已审核且与当前 Markdown 一致 → 直接复用
+ *   - 否则重新物化。重复锚点、非法 UUID、身份冲突由物化自动改写为稳定身份并确认发布
+ *   - 只有显式 requireReview，或正文没有结构化事实时，才保留候选
+ * 全程不改写 Markdown，只读写 <change>/ontology/spec-ontology.json 与 legacy-mapping.json。
+ */
+function resolveLegacySpecOntology(specRoot, changeName, changeDir, facts, options = {}) {
+  const {
+    buildSpecOntology,
+    materializeChangeSpecOntology,
+    approveSpecOntologyFile,
+    specOntologyContentSignature,
+  } = require('./ontology/spec-ontology.cjs');
+  const { ensureProjectIdentity } = require('./ontology/archive-package.cjs');
+  const identity = ensureProjectIdentity(specRoot);
+  const ontologyPath = path.join(changeDir, 'ontology', 'spec-ontology.json');
+
+  const fresh = buildSpecOntology(facts, {
+    projectId: identity.project_id,
+    compatibilityMode: 'LEGACY_MATERIALIZED',
+    reviewStatus: 'pending',
+  });
+  const freshSignature = specOntologyContentSignature(fresh);
+  const existing = readJsonSafe(ontologyPath);
+  const existingApproved = existing
+    && existing.compatibility_mode === 'LEGACY_MATERIALIZED'
+    && existing.review_status === 'confirmed'
+    && existing.publication_eligible === true
+    && existing.project_id === identity.project_id;
+  if (existingApproved && specOntologyContentSignature(existing) === freshSignature) {
+    return { approved: existing, status: 'reused', path: ontologyPath, collisions: [] };
+  }
+
+  const materialized = materializeChangeSpecOntology(specRoot, changeName, {
+    changeDir,
+    projectId: identity.project_id,
+    compatibilityMode: 'LEGACY_MATERIALIZED',
+    reviewStatus: 'pending',
+  });
+  if (!materialized.validation.valid) {
+    throw new Error(`历史 Spec 本体物化失败: ${materialized.validation.errors.join('; ')}`);
+  }
+  const repairs = (materialized.payload.warnings || [])
+    .filter((warning) => warning.startsWith('LEGACY_DUPLICATE_ANCHOR:') || warning.startsWith('LEGACY_IDENTITY_REPAIRED:'));
+  if (options.requireReview) {
+    return { approved: null, status: 'pending_review', path: ontologyPath, collisions: repairs };
+  }
+  if (materialized.payload.entities.length === 0) {
+    return { approved: null, status: 'needs_review', path: ontologyPath, collisions: repairs };
+  }
+  const approved = approveSpecOntologyFile(materialized.output_path, { allowCollisions: true });
+  return { approved: approved.payload, status: 'auto_approved', path: ontologyPath, collisions: repairs };
+}
+
 function buildPackageFromFolder(specRoot, changeName, options = {}) {
   const runtime = require('./ontology/runtime.cjs');
   const archivePackage = require('./ontology/archive-package.cjs');
+  const { classifyLegacyDiagnostics } = require('./ontology/spec-ontology.cjs');
 
   // 1. 语义管线
   console.log('→ 运行语义管线 (semantic-reconcile)...');
@@ -253,15 +314,17 @@ function buildPackageFromFolder(specRoot, changeName, options = {}) {
     profile: 'auto',
     markPending: true,
   });
-  const blockingDiagnostics = semanticResult.diagnostics.filter(d => d.severity === 'error');
-  const legacyIdentityOnly = blockingDiagnostics.length > 0
-    && blockingDiagnostics.every(d => d.code === 'SEM_UUID_MISSING');
+  const legacy = classifyLegacyDiagnostics(semanticResult.diagnostics);
+  const legacyIdentityOnly = legacy.legacyCompatible;
   if (!semanticResult.valid) {
-    const errors = blockingDiagnostics.map(d => `${d.code}: ${d.message}`);
     if (!legacyIdentityOnly) {
+      const errors = legacy.blocking.map(d => `${d.code}: ${d.message}`);
       throw new Error(`语义校验失败:\n${errors.join('\n')}`);
     }
-    console.warn('⚠️  检测到历史产物缺少身份标识，将生成旁路映射和待审核本体包，不改写 Markdown。');
+    console.warn('⚠️  检测到历史产物缺少身份标识，将生成旁路映射与本体包，不改写 Markdown。');
+    for (const item of legacy.tolerated) {
+      console.warn(`   ↳ 兼容放行 ${item.code}: ${item.message}`);
+    }
   } else {
     console.log(`✓ 语义校验通过 (profile: ${semanticResult.profile}, revision: ${semanticResult.revision})`);
   }
@@ -278,25 +341,31 @@ function buildPackageFromFolder(specRoot, changeName, options = {}) {
     copyDirRecursive(changeDir, stagingDir);
 
     let result;
+    let legacyStatus = null;
     if (legacyIdentityOnly) {
-      const approvedPath = path.join(changeDir, 'ontology', 'spec-ontology.json');
-      const approvedOntology = readJsonSafe(approvedPath);
-      const useApproved = approvedOntology?.review_status === 'confirmed'
-        && approvedOntology?.publication_eligible === true;
-      if (useApproved) {
-        console.log('✓ 已发现审核通过的历史 Spec 本体，将校验内容一致性后发布');
-      }
+      const resolved = resolveLegacySpecOntology(specRoot, changeName, changeDir, semanticResult.state, {
+        requireReview: Boolean(options.requireReview),
+      });
+      legacyStatus = resolved.status;
+      const messages = {
+        reused: '✓ 已发现审核通过且与当前 Markdown 一致的历史 Spec 本体，直接发布',
+        auto_approved: '✓ 历史 Spec 本体已自动物化并确认，身份和重复锚点已在旁路改写，将发布为 current 事实',
+        needs_review: '⚠️  历史正文没有可发布的结构化事实，仅保留为证据候选',
+        pending_review: 'ℹ️  按 --require-review 要求，历史 Spec 本体保留为待审核候选',
+      };
+      console.log(messages[resolved.status]);
       result = archivePackage.materializeCompatibilityPackage({
         projectRoot: specRoot,
         archiveDir: stagingDir,
         changeName,
         facts: semanticResult.state,
-        specOntology: useApproved ? approvedOntology : null,
+        specOntology: resolved.approved,
+        toleratedDiagnostics: legacy.tolerated,
         packagePath: zipPath,
         reason: options.reason || '历史 Spec 兼容入库',
         method: 'kb-upload-legacy-folder',
       });
-      console.log(useApproved
+      console.log(resolved.approved
         ? '✓ 已生成审核通过的 LEGACY_MATERIALIZED 发布包'
         : '✓ 已生成 LEGACY_MATERIALIZED 本体候选包');
     } else {
@@ -325,6 +394,8 @@ function buildPackageFromFolder(specRoot, changeName, options = {}) {
       manifest: result.manifest,
       stagingDir,
       requiresReview: result.conversion_report?.status === 'materialized_pending_review',
+      legacyStatus,
+      toleratedDiagnostics: legacyIdentityOnly ? legacy.tolerated : [],
     };
   } catch (err) {
     // 出错时清理 staging
@@ -365,6 +436,7 @@ async function main() {
     console.error('  node skywalk-sdd/kb-upload.cjs --folder=<path> [--minimum-level=propose-spec] [--validate-only]');
     console.error('  node skywalk-sdd/kb-upload.cjs --package=<zip-path>');
     console.error('  node skywalk-sdd/kb-upload.cjs --folder=<path> --project=<spec-root> --change=<name>');
+    console.error('  node skywalk-sdd/kb-upload.cjs --folder=<path> --require-review   # 历史产物只上传候选，不自动确认本体');
     process.exit(1);
   }
 
@@ -448,12 +520,17 @@ async function main() {
         markPending: true,
       });
       if (!semanticResult.valid) {
-        const errors = semanticResult.diagnostics
-          .filter(d => d.severity === 'error')
-          .map(d => `${d.code}: ${d.message}`);
-        throw new Error(`语义校验失败:\n${errors.join('\n')}`);
+        const { classifyLegacyDiagnostics } = require('./ontology/spec-ontology.cjs');
+        const legacy = classifyLegacyDiagnostics(semanticResult.diagnostics);
+        if (!legacy.legacyCompatible) {
+          const errors = legacy.blocking.map(d => `${d.code}: ${d.message}`);
+          throw new Error(`语义校验失败:\n${errors.join('\n')}`);
+        }
+        console.log('⚠️  历史产物缺少身份标识，正式上传时将走 LEGACY_MATERIALIZED 旁路物化，不改写 Markdown');
+        for (const item of legacy.tolerated) console.log(`   ↳ 兼容放行 ${item.code}: ${item.message}`);
+      } else {
+        console.log(`✓ 语义校验通过 (profile: ${semanticResult.profile}, revision: ${semanticResult.revision})`);
       }
-      console.log(`✓ 语义校验通过 (profile: ${semanticResult.profile}, revision: ${semanticResult.revision})`);
       console.log('\n✓ 本地语义校验完成（--validate-only，未联网；不代表权限、发布基线或入库已验证）');
       return;
     }
@@ -473,8 +550,9 @@ async function main() {
 
     // 5. 构建 Archive Package
     console.log('');
-    const { zipPath, manifest, stagingDir, requiresReview } = buildPackageFromFolder(specRoot, changeName, {
+    const { zipPath, manifest, stagingDir, requiresReview, legacyStatus } = buildPackageFromFolder(specRoot, changeName, {
       reason: args.reason,
+      requireReview: Boolean(args['require-review']),
     });
 
     try {
@@ -546,7 +624,11 @@ async function main() {
       if (publicationStatus === 'needs_review') {
         console.log('\n⚠️  历史 Spec 已安全保存为候选，尚未进入 current 召回');
         console.log(`  → 审核 ${path.join(folderPath, 'ontology', 'spec-ontology.json')}`);
-        console.log('  → 运行 approve-spec-ontology 后再次上传即可发布');
+        if (legacyStatus === 'needs_review') {
+          console.log('  → 正文没有足够的结构化事实，只能作为证据保留');
+        } else {
+          console.log('  → 运行 approve-spec-ontology 后再次上传即可发布；不带 --require-review 上传则自动确认');
+        }
       } else {
         // Published commit has been verified; a receipt does not imply projection completion.
         updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);

package/skywalk-sdd/ontology/archive-package.cjs

@@ -9,6 +9,7 @@ const {
   SPEC_ONTOLOGY_PATH,
   buildSpecOntology,
   validateSpecOntology,
+  specOntologyContentSignature,
 } = require('./spec-ontology.cjs');
 const { resolveRuntimeMetadata } = require('../runtime-metadata.cjs');
 const {
@@ -708,14 +709,7 @@ function materializeCompatibilityPackage(options = {}) {
       compatibilityMode: 'LEGACY_MATERIALIZED',
       reviewStatus: 'pending',
     });
-    const entityContentSignature = (payload) => (payload.entities || [])
-      .map((entity) => `${entity.anchor_id}:${entity.content_hash}`)
-      .sort();
-    const relationContentSignature = (payload) => (payload.relations || [])
-      .map((relation) => `${relation.type}:${relation.source?.anchor_id || ''}:${relation.source?.content_hash || ''}`)
-      .sort();
-    if (JSON.stringify(entityContentSignature(specOntology)) !== JSON.stringify(entityContentSignature(currentOntology))
-        || JSON.stringify(relationContentSignature(specOntology)) !== JSON.stringify(relationContentSignature(currentOntology))) {
+    if (specOntologyContentSignature(specOntology) !== specOntologyContentSignature(currentOntology)) {
       throw new Error('已审核 Spec 本体与当前 Markdown 内容不一致，请重新物化并审核');
     }
     specOntology.archive_id = archiveId;
@@ -735,6 +729,8 @@ function materializeCompatibilityPackage(options = {}) {
   if (!validation.valid) {
     throw new Error(`历史 Spec 本体物化失败: ${validation.errors.join('; ')}`);
   }
+  const toleratedDiagnostics = (options.toleratedDiagnostics || [])
+    .map((item) => `LEGACY_DIAGNOSTIC_TOLERATED: ${item.code}: ${item.message}`);
   const specOntologyPath = path.join(archiveDir, SPEC_ONTOLOGY_PATH);
   const specOntologyBytes = writeJsonAtomic(specOntologyPath, specOntology);
   const conversionReport = {
@@ -748,7 +744,7 @@ function materializeCompatibilityPackage(options = {}) {
     status: specOntology.publication_eligible ? 'materialized_reviewed' : 'materialized_pending_review',
     entity_count: specOntology.entities.length,
     relation_count: specOntology.relations.length,
-    warnings: specOntology.warnings,
+    warnings: [...new Set([...(specOntology.warnings || []), ...toleratedDiagnostics])],
   };
   writeJsonAtomic(path.join(archiveDir, CONVERSION_REPORT_PATH), conversionReport);
 

package/skywalk-sdd/ontology/spec-ontology.cjs

@@ -8,6 +8,8 @@ const { normalizeFacts } = require('./normalizer.cjs');
 const { resolveChangeDir } = require('./runtime.cjs');
 const { resolveRuntimeMetadata } = require('../runtime-metadata.cjs');
 const { ensureDir, readJsonSafe, writeJsonAtomic } = require('../lib/shared.cjs');
+const { DIAGNOSTIC_CODES } = require('./schema.cjs');
+const { isValidUuid } = require('./id.cjs');
 
 const SPEC_ONTOLOGY_SCHEMA_VERSION = 'kld-sdd-spec-ontology/v1';
 const LEGACY_MAPPING_SCHEMA_VERSION = 'kld-sdd-legacy-identity-mapping/v1';
@@ -32,10 +34,92 @@ const RELATION_MAP = Object.freeze({
   constrains: 'constrainedBy',
 });
 
+// 工具升级后新增的身份、归档和任务校验。历史稿上传遇到这些诊断时旁路物化，
+// 由上传流程自动消解，不把整包失败交回给使用者。
+const LEGACY_TOLERATED_CODES = Object.freeze([
+  DIAGNOSTIC_CODES.UUID_MISSING,
+  DIAGNOSTIC_CODES.UUID_INVALID,
+  DIAGNOSTIC_CODES.ID_MISSING,
+  DIAGNOSTIC_CODES.ID_INVALID,
+  DIAGNOSTIC_CODES.ID_DUPLICATE,
+  DIAGNOSTIC_CODES.DELTA_STATE_INVALID,
+  DIAGNOSTIC_CODES.SOURCE_MISSING,
+  DIAGNOSTIC_CODES.VERSION_LINEAGE_MISSING,
+  DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
+  DIAGNOSTIC_CODES.VERSION_IDENTITY_CONFLICT,
+  DIAGNOSTIC_CODES.INHERITED_SOURCE_MISMATCH,
+  DIAGNOSTIC_CODES.INHERITED_RELATION_MISSING,
+  DIAGNOSTIC_CODES.ARCHIVE_NOT_CONFIRMED,
+  DIAGNOSTIC_CODES.ARCHIVE_REVISION_MISMATCH,
+  DIAGNOSTIC_CODES.TASK_DEPENDENCY_CYCLE,
+  DIAGNOSTIC_CODES.TASK_DEPENDENCY_LAYER_GAP,
+  DIAGNOSTIC_CODES.TASK_DEPENDENCY_MISSING_EDGE,
+  DIAGNOSTIC_CODES.STMT_WITHOUT_AC,
+  DIAGNOSTIC_CODES.STMT_WITHOUT_DESIGN,
+  DIAGNOSTIC_CODES.DESIGN_WITHOUT_TASK,
+  DIAGNOSTIC_CODES.AC_WITHOUT_STMT,
+  DIAGNOSTIC_CODES.TASK_WITHOUT_UPSTREAM,
+]);
+
+// Check 对用户隐藏并自行处理的工具诊断。需求、设计、任务之间的覆盖缺口不在此列。
+const CHECK_TOOL_CODES = Object.freeze([
+  DIAGNOSTIC_CODES.UUID_MISSING,
+  DIAGNOSTIC_CODES.UUID_INVALID,
+  DIAGNOSTIC_CODES.ID_MISSING,
+  DIAGNOSTIC_CODES.ID_INVALID,
+  DIAGNOSTIC_CODES.ID_DUPLICATE,
+  DIAGNOSTIC_CODES.DELTA_STATE_INVALID,
+  DIAGNOSTIC_CODES.SOURCE_MISSING,
+  DIAGNOSTIC_CODES.VERSION_LINEAGE_MISSING,
+  DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
+  DIAGNOSTIC_CODES.VERSION_IDENTITY_CONFLICT,
+  DIAGNOSTIC_CODES.INHERITED_SOURCE_MISMATCH,
+  DIAGNOSTIC_CODES.INHERITED_RELATION_MISSING,
+  DIAGNOSTIC_CODES.ARCHIVE_NOT_CONFIRMED,
+  DIAGNOSTIC_CODES.ARCHIVE_REVISION_MISMATCH,
+]);
+
 function sha256(value) {
   return crypto.createHash('sha256').update(value).digest('hex');
 }
 
+function splitCheckDiagnostics(diagnostics = []) {
+  const tool = [];
+  const product = [];
+  for (const item of diagnostics || []) {
+    if (item && item.severity === 'error' && CHECK_TOOL_CODES.includes(item.code)) tool.push(item);
+    else product.push(item);
+  }
+  return {
+    tool_diagnostics: tool,
+    product_diagnostics: product,
+    product_valid: product.every((item) => !item || item.severity !== 'error'),
+  };
+}
+
+function classifyLegacyDiagnostics(diagnostics = []) {
+  const blocking = (diagnostics || []).filter((item) => item && item.severity === 'error');
+  const tolerated = blocking.filter((item) => LEGACY_TOLERATED_CODES.includes(item.code));
+  const rejected = blocking.filter((item) => !LEGACY_TOLERATED_CODES.includes(item.code));
+  return {
+    blocking,
+    tolerated,
+    rejected,
+    legacyCompatible: blocking.length > 0 && rejected.length === 0,
+  };
+}
+
+// 同一份 Markdown 反复物化时用于判断“已审核本体是否仍对应当前正文”。
+function specOntologyContentSignature(payload) {
+  const entities = (payload?.entities || [])
+    .map((entity) => `${entity.anchor_id}:${entity.content_hash}`)
+    .sort();
+  const relations = (payload?.relations || [])
+    .map((relation) => `${relation.type}:${relation.source?.anchor_id || ''}:${relation.source?.content_hash || ''}`)
+    .sort();
+  return JSON.stringify({ entities, relations });
+}
+
 function withOntologyHash(payload) {
   const result = { ...payload };
   delete result.ontology_hash;
@@ -91,16 +175,25 @@ function compatibilityMode(facts, selectedEntities) {
   return 'LEGACY_MATERIALIZED';
 }
 
-function identityFor(entity, projectId, semanticKey) {
+function identityFor(entity, projectId, semanticKey, options = {}) {
   const declaredEntityId = normalizedText(entity.entity_id).toLowerCase();
   const declaredVersionId = normalizedText(entity.entity_version_id || entity.version_id).toLowerCase();
-  const entityId = declaredEntityId || deterministicUuid(`${projectId}\n${semanticKey}`);
+  const declaredUsable = isValidUuid(declaredEntityId) && isValidUuid(declaredVersionId);
   const contentHash = normalizedText(entity.content_hash) || `sha256:${sha256(JSON.stringify(entity))}`;
-  const entityVersionId = declaredVersionId || deterministicUuid(`${entityId}\n${contentHash}`);
+  if (!options.repairLegacy || declaredUsable) {
+    return {
+      entity_id: declaredEntityId || deterministicUuid(`${projectId}\n${semanticKey}`),
+      entity_version_id: declaredVersionId || deterministicUuid(`${declaredEntityId || semanticKey}\n${contentHash}`),
+      identity_origin: declaredUsable ? 'declared' : 'derived_legacy',
+      repaired: false,
+    };
+  }
   return {
-    entity_id: entityId,
-    entity_version_id: entityVersionId,
-    identity_origin: declaredEntityId && declaredVersionId ? 'declared' : 'derived_legacy',
+    entity_id: deterministicUuid(`${projectId}\n${semanticKey}`),
+    entity_version_id: deterministicUuid(`${projectId}\n${semanticKey}\n${contentHash}`),
+    identity_origin: 'derived_legacy',
+    repaired: true,
+    repair_reason: declaredEntityId || declaredVersionId ? 'invalid_declared_uuid' : 'missing_uuid',
   };
 }
 
@@ -124,12 +217,36 @@ function buildSpecOntology(facts, options = {}) {
     const baseKey = baseKeys[index];
     const source = normalizeSource(sourceEntity.source);
     const semanticKey = keyCounts.get(baseKey) > 1
-      ? `${baseKey}@${normalizedText(source.file).toLowerCase() || index + 1}`
+      ? `${baseKey}@${normalizedText(source.file).toLowerCase() || 'source'}#${index + 1}`
       : baseKey;
     if (keyCounts.get(baseKey) > 1) {
-      warnings.push(`SEMANTIC_KEY_COLLISION: ${baseKey} 已按来源路径拆分，需要人工判定是否合并`);
+      warnings.push(`LEGACY_DUPLICATE_ANCHOR: ${baseKey} 已按来源路径拆成独立事实，上传不再等待人工合并`);
+    }
+    const repairLegacy = mode === 'LEGACY_MATERIALIZED';
+    let identity = identityFor(sourceEntity, projectId, semanticKey, { repairLegacy });
+    if (repairLegacy && entities.some((item) => item.entity_id === identity.entity_id)) {
+      identity = {
+        entity_id: deterministicUuid(`${projectId}\n${semanticKey}\n${index}`),
+        entity_version_id: deterministicUuid(`${projectId}\n${semanticKey}\n${index}\nversion`),
+        identity_origin: 'derived_legacy',
+        repaired: true,
+        repair_reason: 'entity_id_conflict',
+      };
     }
-    const identity = identityFor(sourceEntity, projectId, semanticKey);
+    if (repairLegacy && entities.some((item) => item.entity_version_id === identity.entity_version_id)) {
+      identity = {
+        ...identity,
+        entity_version_id: deterministicUuid(`${identity.entity_id}\n${semanticKey}\n${index}\nversion`),
+        identity_origin: 'derived_legacy',
+        repaired: true,
+        repair_reason: identity.repair_reason || 'version_id_conflict',
+      };
+    }
+    if (identity.repaired) {
+      warnings.push(`LEGACY_IDENTITY_REPAIRED: ${anchor} ${identity.repair_reason}`);
+    }
+    const declaredPredecessor = normalizedText(sourceEntity.predecessor_version_id);
+    const predecessor = repairLegacy || !isValidUuid(declaredPredecessor) ? null : declaredPredecessor;
     const ontologyEntity = {
       semantic_key: semanticKey,
       type: TYPE_MAP[sourceEntity.type],
@@ -141,8 +258,10 @@ function buildSpecOntology(facts, options = {}) {
         || anchor,
       ),
       anchor_id: anchor,
-      ...identity,
-      predecessor_version_id: sourceEntity.predecessor_version_id || null,
+      entity_id: identity.entity_id,
+      entity_version_id: identity.entity_version_id,
+      identity_origin: identity.identity_origin,
+      predecessor_version_id: predecessor,
       content_hash: normalizedText(sourceEntity.content_hash),
       review_status: reviewStatus,
       publication_status: reviewStatus === 'confirmed' ? 'publishable' : 'candidate',
@@ -375,8 +494,12 @@ module.exports = {
   SPEC_ONTOLOGY_PATH,
   LEGACY_MAPPING_PATH,
   TYPE_MAP,
+  LEGACY_TOLERATED_CODES,
   deterministicUuid,
   semanticKeyFor,
+  classifyLegacyDiagnostics,
+  splitCheckDiagnostics,
+  specOntologyContentSignature,
   buildSpecOntology,
   validateSpecOntology,
   approveSpecOntologyFile,

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

@@ -47,14 +47,17 @@ node "<spec-package>/skywalk-sdd/log.cjs" start --command=check --project="<spec
 node "<spec-package>/skywalk-sdd/log.cjs" semantic-check --project="<spec-package>" --change=<变更名称> --profile=auto --include-tasks > "<spec-package>/skywalk-sdd/state/<变更名称>-preflight.json"
 ```
 
-输出 `profile / valid / revision / counts / diagnostics`、`review_inputs`（文档路径与哈希、历史身份哈希）、`task_completion` 和 `timings_ms`。程序时间不等于模型评审总耗时。
+输出 `profile / valid / product_valid / revision / counts`、`product_diagnostics`、`tool_diagnostics`、`review_inputs`、`task_completion` 和 `timings_ms`。程序时间不等于模型评审总耗时。
 
-- semantic-check 已包含全量对账、工作态 JSON 原子刷新和 pending 标记；无需再调用 semantic-reconcile。pending 仅表示程序校验通过，不能宣称已完成独立评审或已入库。
+- `product_valid` 只看产物质量。需求没有验收、需求没有设计、设计没有任务、任务没有上游、验收没有归属需求、产物缺失、任务依赖成环，这些进入报告并阻断 Check。
+- `tool_diagnostics` 是工具升级带来的身份、来源、谱系和归档诊断。预检已把可物化的部分写入 `ontology/spec-ontology.json` 与 `ontology/legacy-mapping.json`，不改 Markdown。不要向用户展示这些诊断，不要要求用户补 UUID、改锚点或重做归档。
+- 交给独立评审者的程序诊断只使用 `product_diagnostics`。报告只写产物缺口和 design 与 tasks 之间的覆盖缺失。
+- semantic-check 已包含全量对账、工作态 JSON 原子刷新和 pending 标记；无需再调用 semantic-reconcile。`product_valid=true` 只表示产物结构没有阻断，不能宣称已完成独立评审或已入库。
 - 默认从产物推断 simple/full；用户或项目明确要求 strict 时传 `--profile=strict`，不能为通过而降级。
-- `simple` 阻断 STMT 无 AC，未生成 design/tasks 时跳过对应链路；`full` 阻断 STMT→AC→Design→Task 断链；`strict` 还要求完整来源字段。
-- 所有模式保留身份合法性、重复锚点、跨 Change/Archive 身份误复用、版本谱系、悬空引用、domain/range 和依赖成环门禁。added 使用新身份；modified/removed 复用实体并指向直接前驱；unchanged 引用历史版本且不复制正文。
-- Continuity、external_ref 与 `ontology/continuity-resolution.json` 必须一致。`CONTINUITY_DECISION_REQUIRED` / `CONTINUITY_IDENTITY_MISMATCH` / `EXTERNAL_REF_CONFLICT` 和编号诊断原样进入报告；不得临时改身份来绕过门禁。
-- 文件观察结果只作提示，不复用历史“通过”代替本轮全量校验。命令失败、诊断 error 或 valid=false 时先展示具体问题，在授权内修复后重试；无需模型再读全仓来重复确认确定性错误。若缺业务决定则本轮结束为 failure、说明“预检阻断，尚未独立评审”，保留阶段日志，不伪造 check_result。用户明确要求同时审阅其余问题时可继续独立评审，但总体仍失败。
+- `simple` 阻断 STMT 无 AC，未生成 design/tasks 时跳过对应链路；`full` 阻断 STMT→AC→Design→Task 断链；`strict` 还要求完整来源字段，来源缺失按工具诊断自行旁路处理，不单独向用户追问。
+- 产物门禁保留追溯断链、悬空业务引用、domain/range 和任务依赖成环。身份、重复锚点、归档版本和谱系由工具旁路处理。
+- Continuity、external_ref 与 `ontology/continuity-resolution.json` 仍属于产物决定。`CONTINUITY_DECISION_REQUIRED` / `CONTINUITY_IDENTITY_MISMATCH` / `EXTERNAL_REF_CONFLICT` 进入报告；不得临时改身份来绕过这些业务门禁。
+- 只有 `product_diagnostics` 里的 error 才向用户展示并在授权内修复后重试。仅有工具诊断时继续独立评审，不把本轮记成预检失败。缺业务决定时本轮结束为 failure，说明“预检阻断，尚未独立评审”。
 
 ### 多仓库关联配置
 
@@ -75,7 +78,7 @@ node "<spec-package>/skywalk-sdd/log.cjs" semantic-check --project="<spec-packag
 
 ## 3. 一次独立评审
 
-程序预检后交给评审者：`review_inputs` 对应的最终文件路径、profile/test-strategy、任务状态、程序诊断、用户指定的上下文路径、检查范围和作者会话 ID。只传客观输入，不传作者对话或主 Agent 的结论摘要。主 Agent 从 proposal 元数据确定测试策略即可，无需预读正文。
+程序预检后交给评审者：`review_inputs` 对应的最终文件路径、profile/test-strategy、任务状态、`product_diagnostics`、用户指定的上下文路径、检查范围和作者会话 ID。不传 `tool_diagnostics`，不传作者对话或主 Agent 的结论摘要。评审重点是产物是否完整，以及 spec、design、tasks 之间有没有覆盖缺失。
 
 ${CHECK_REVIEW_DELEGATION_GUIDANCE}
 
@@ -105,6 +108,6 @@ node "<spec-package>/skywalk-sdd/log.cjs" check-record --project="<spec-package>
 
 check-record 按预检的同一 profile 重新核验正文、文件集合和历史身份。输入变化返回 CHECK_REVIEW_STALE，不写本轮通过记录；重新预检并复核受影响内容。成功时仍通过原 strict 校验和阶段结束入口，不另手动执行 end。评审输入始终保留，记录失败可以修复后重试。未真实开展评审时不用此命令，按原 end 命令记录 failure 和原因。
 
-报告输出五维结论、多仓配置、KB 状态、证据与未执行项，说明覆盖范围。只请求检查则结束；已授权实现且无阻断项时进入 apply。修复文档后再检查相关依赖，禁止携带旧结论直接通过；不把 Capability 局部评审写成全 Change 通过。
+报告输出五维结论、多仓配置、KB 状态、产物证据与未执行项。只写需求、设计、任务之间的缺口和质量问题。身份、UUID、归档版本、重复锚点等工具处理结果不写入给用户的报告。只请求检查则结束；已授权实现且没有产物阻断项时进入 apply。修复文档后再检查相关依赖，禁止携带旧结论直接通过；不把 Capability 局部评审写成全 Change 通过。
 
 [checklist.md](checklist.md) 仅供日志异常/自检时读取，正常路径不再完整加载一遍。

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

@@ -7,7 +7,8 @@
 
 - 自己读取完整的相关业务文档正文一次；批量读取相互独立的文件，同一文件同一版本复用，输出截断时补读缺失部分。
 - Simple 支持根目录 `spec.md/design.md/tasks.md`；Full 使用 `specs/<capability>/`。兼容 `propose.md/task.md`。
-- 程序已核验的 UUID、谱系、引用和 DAG 结果直接引用；模型负责语义覆盖、业务矛盾、可行性和测试质量，不能把“结构合法”当作“设计正确”。
+- 程序已核验结构。身份、UUID、谱系和归档诊断由主 Agent 自行处理，不写入给用户的评审结论。
+- 模型负责产物质量：语义覆盖、design 是否覆盖 spec、tasks 是否拆解 design、业务矛盾、可行性和测试质量。不能把“结构合法”当作“设计正确”，也不能用工具诊断代替这些缺口。
 - 代码只读 design/tasks 实际引用的锚点及其必要依赖；不做全仓 diff、不运行测试。用户提供的上下文文件必须读取。
 - 仅指定 Capability 时，补读 proposal 和明确的跨能力依赖；报告覆盖边界，不能宣称全 Change 已独立评审。全 Change 的程序语义门禁仍执行。
 - 不适用的算法、TDD 或实施后检查写 `N/A` 和理由，不能计成通过；仅在 test-strategy=tdd 时加载下面 TDD 资料。

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

@@ -80,7 +80,7 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JO
 上传的 zip 包必须满足以下条件（否则入库会失败）：
 
 - 当前产物包含：`archive-manifest.json`、`canonical-facts.json`、`spec-ontology.json`、`conversion-report.json`
-- 历史兼容包可不带 `canonical-facts.json`，但必须带 `spec-ontology.json`，且 `compatibility_mode=LEGACY_MATERIALIZED`、`review_status=pending`
+- 历史兼容包可不带 `canonical-facts.json`，但必须带 `spec-ontology.json`，且 `compatibility_mode=LEGACY_MATERIALIZED`。重复锚点、非法 UUID、身份冲突、依赖成环、归档版本不一致由上传自动消解；无结构化事实时才是 `pending`。不要让用户处理这些历史诊断。
 - `canonical-facts.json` 支持 `kld-sdd-canonical-facts/v1` 与 **`v2`**（v2 可选实体级 `external_refs`）
 - 所有文件需通过 SHA-256 校验（manifest 中记录每个文件的 `content_hash`）
 - 允许的文件类型：`.md`、`.json`、`.jsonl`、`.yaml`、`.yml`

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

@@ -22,9 +22,10 @@ allowed-tools:
 
 ## 始终遵守
 
-- 不改写历史 Markdown。缺少 `entity-id` / `version-id` 时，身份写入 `ontology/legacy-mapping.json`。
-- 兼容转换不因缺少旧标识失败。无法确定的合并只生成 candidate，不自动发布为 current。
-- 正式发布仍校验证据、哈希、版本和租户边界。
+- 不改写历史 Markdown。缺少、非法或互相冲突的身份由上传写进 `ontology/legacy-mapping.json`，并生成稳定 UUID。
+- 重复锚点、非法 UUID、身份冲突、任务依赖成环、归档版本对不上，都由上传自动消解并继续发布。不要停下来请用户处理，也不要改 Markdown 去“修”这些历史诊断。
+- `opsx-check` 仍会报告这些问题。入库和召回不依赖 Check 通过。
+- 正式发布仍校验证据、哈希、版本和租户边界。正文没有结构化事实时只入证据，不发布本体事实。
 - 当前 `canonical-facts/v2` 与 `spec-ontology/v1` 同包产出，支持新旧知识库过渡。
 
 ## 执行流程
@@ -48,28 +49,29 @@ node skywalk-sdd/ontology/cli.cjs validate-spec-ontology \
   --file=openspec/changes/<change-key>/ontology/spec-ontology.json
 ```
 
-5. 若有 `SEMANTIC_KEY_COLLISION` 或候选合并，展示锚点、来源和建议，让用户只审核这些差异。历史产物默认可以先上传为 candidate，不会进入 current 召回。
-6. 审核语义键、身份映射、实体和关系无误后，显式确认旁路本体：
+5. 上传本身会自动物化并确认。重复锚点按来源拆开，非法或冲突的 UUID 改成稳定派生身份，依赖成环和归档版本不一致只记入转换说明。不要向用户复述这些诊断，不要要求用户选择合并或补 UUID。完成后直接入库并用 spec-generation 召回验证。
+6. 仅当用户明确要求先审阅，或正文没有任何结构化事实时，才保留 candidate。此时再运行：
 
 ```bash
 node skywalk-sdd/ontology/cli.cjs approve-spec-ontology \
   --file=openspec/changes/<change-key>/ontology/spec-ontology.json
 ```
 
-   有 semantic key 冲突时，此命令会拒绝通过；先修正本体 JSON 中的实体、关系和 `identity_map`，再重新校验与确认。不要通过 `--allow-collisions` 跳过真实冲突。
-7. 通过 `opsx-kb-ingest` 打包上传。上传脚本会复核已确认本体与当前 Markdown 的事实哈希；内容已变化时拒绝发布，并要求重新物化和审核。
-8. 通过 `context-client.cjs --mode=spec-generation` 执行一次召回验证，报告是否命中能力、场景、规则和 Spec 模式。
+   用户没有要求审阅时不要执行这一步。上传已经自动确认，不要因为重复锚点或身份改写再停下来。
+7. 通过 `opsx-kb-ingest` 打包上传。正文变化时重新物化并自动确认。已确认本体与当前 Markdown 不一致时不沿用旧确认。
+8. 通过 `context-client.cjs --mode=spec-generation` 执行一次召回验证。向用户只报告是否入库、是否召回到 current 事实。自动改写过的身份、拆开的重复锚点、忽略的成环和归档差异写在命令输出里，不单独向用户确认。
 
-## 历史产物审核输出
+## 完成后的简报
 
-只展示需要人判断的项：
+只向用户说明入库和召回结果。下面这些由工具自动处理，不列入需要用户决定的事项：
 
 ```text
 兼容模式：LEGACY_MATERIALIZED
-可直接物化：12
-需审核合并：2
-仅证据：1
-原文改动：0
+已发布事实：12
+自动改写身份：3
+重复锚点已拆分：1
+归档/成环已忽略：2
+仅证据：0
 ```
 
 若 KB 不可用，保留已物化产物并标记 `remoteContextVerified=false`；本地编写可继续，入库与发布状态明确为未完成。