kld-sdd 2.7.3 → 2.7.8

package/skywalk-sdd/kb-upload.cjs

@@ -33,19 +33,48 @@ const {
   httpGetJson,
 } = require('./lib/shared.cjs');
 
+function resolveUploadTarget(state, options = {}) {
+  if (Boolean(options.spaceId) !== Boolean(options.kbId)) throw new Error('必须同时指定 --space-id 和 --kb-id');
+  const targets = state.targets || [];
+  if (options.spaceId && options.kbId) {
+    return targets.find(t => t.spaceId === options.spaceId && t.kbId === options.kbId) || options;
+  }
+  if (targets.length !== 1) throw new Error('请明确上传目标：配置一个知识库，或同时指定 --space-id 和 --kb-id；不会自动分发到多个 KB');
+  if (!targets[0].spaceId || !targets[0].kbId) throw new Error('知识库目标缺少 spaceId/kbId');
+  return targets[0];
+}
+
+function cacheKey(changeName, context) {
+  if (!context?.api || !context?.spaceId || !context?.kbId) return null;
+  return JSON.stringify([context.api.replace(/\/+$/, ''), context.spaceId, context.kbId, changeName]);
+}
+
+function assertIngestionResult(result) {
+  if (result?.code != null && result.code !== 0) throw new Error(result.message || 'KB API 拒绝入库');
+  const job = result?.data || result;
+  if (!job || !['projecting', 'succeeded'].includes(job.status) || job.relationStatus !== 'committed') {
+    throw new Error(`INGEST_NOT_COMMITTED: ${job?.errorCode || job?.status || 'unknown'} ${job?.errorMessage || ''} job=${job?.jobId || 'unknown'}`);
+  }
+  if (Number(job.report?.version_conflicts || 0) > 0 || job.report?.publication_status === 'needs_review') {
+    throw new Error(`VERSION_CONFLICT: 事实包已保存为候选，当前事实未更新；请合并基线后重新发布。job=${job.jobId}`);
+  }
+  return job;
+}
+
 /**
  * 读取 kb-state.json 中指定 change 的 archive 缓存。
  * @param {string} specRoot
  * @param {string} changeName
  * @returns {object|null} { archive_id, content_hash, uploaded_at }
  */
-function readArchiveCache(specRoot, changeName) {
+function readArchiveCache(specRoot, changeName, context) {
   const directPath = path.join(specRoot, 'kb-state.json');
   const legacyPath = path.join(specRoot, '..', '.shared', 'kb-state.json');
   const statePath = fs.existsSync(directPath) ? directPath : legacyPath;
   const state = readJsonSafe(statePath);
   if (!state || !state.archiveCache) return null;
-  return state.archiveCache[changeName] || null;
+  const key = cacheKey(changeName, context);
+  return key ? state.archiveCache[key] || null : null;
 }
 
 /**
@@ -55,16 +84,19 @@ function readArchiveCache(specRoot, changeName) {
  * @param {string} archiveId
  * @param {string} contentHash
  */
-function updateKbStateCache(specRoot, changeName, archiveId, contentHash) {
+function updateKbStateCache(specRoot, changeName, archiveId, contentHash, context) {
   const directPath = path.join(specRoot, 'kb-state.json');
   const legacyPath = path.join(specRoot, '..', '.shared', 'kb-state.json');
   const statePath = fs.existsSync(directPath) ? directPath : legacyPath;
   const state = readJsonSafe(statePath) || {};
   if (!state.archiveCache) state.archiveCache = {};
-  state.archiveCache[changeName] = {
+  const key = cacheKey(changeName, context);
+  if (!key) throw new Error('缓存必须包含 API、Space 和 KB');
+  state.archiveCache[key] = {
     archive_id: archiveId,
     content_hash: contentHash,
     uploaded_at: new Date().toISOString(),
+    target: context,
   };
   writeJsonAtomic(statePath, state);
   console.log(`✓ 已更新本地缓存: ${changeName} → ${archiveId.slice(0, 24)}...`);
@@ -144,7 +176,11 @@ function readKbState(specRoot) {
  */
 function validateRequiredFiles(folderPath, minimumLevel) {
   const required = MINIMUM_LEVELS[minimumLevel] || MINIMUM_LEVELS[DEFAULT_LEVEL];
-  const missing = required.filter(f => !fs.existsSync(path.join(folderPath, f)));
+  const specsDir = path.join(folderPath, 'specs');
+  const capabilityDirs = fs.existsSync(specsDir) ? fs.readdirSync(specsDir, { withFileTypes: true })
+    .filter(e => e.isDirectory()).map(e => path.join(specsDir, e.name)) : [];
+  const missing = required.filter(f => !fs.existsSync(path.join(folderPath, f))
+    && !(f !== 'proposal.md' && capabilityDirs.length > 0 && capabilityDirs.every(d => fs.existsSync(path.join(d, f)))));
   if (missing.length > 0) {
     throw new Error(
       `[${minimumLevel}] 缺少必需文件: ${missing.join(', ')}\n` +
@@ -162,11 +198,11 @@ function validateRequiredFiles(folderPath, minimumLevel) {
 /**
  * 本地预检 project_id === spaceKey
  */
-function preCheckProjectId(projectId, state) {
+function preCheckProjectId(projectId, state, selectedTarget) {
   if (!state.targets || !state.targets[0]) {
     throw new Error('KB 配置中无 targets，请运行 /opsx-kb-config 配置知识库。');
   }
-  const spaceKey = state.targets[0].spaceKey;
+  const spaceKey = (selectedTarget || resolveUploadTarget(state)).spaceKey;
   if (!spaceKey) {
     console.warn('⚠️  kb-state.json targets[0].spaceKey 为空，跳过本地预检');
     return;
@@ -255,15 +291,9 @@ function buildPackageFromFolder(specRoot, changeName, options) {
  * 上传 zip 到 KB（使用 Node.js HTTP，替代 curl）
  */
 async function uploadZip(zipPath, state, options) {
-  const target = options.spaceId && options.kbId
-    ? { spaceId: options.spaceId, kbId: options.kbId }
-    : state.targets[0];
+  const target = resolveUploadTarget(state, options);
 
-  if (!target || !target.spaceId || !target.kbId) {
-    throw new Error('未指定目标 Space/KB，请运行 /opsx-kb-config 配置知识库。');
-  }
-
-  const apiUrl = state.api || 'http://localhost:8090/api';
+  const apiUrl = (state.api || 'http://localhost:8090/api').replace(/\/+$/, '');
   const uploadUrl = `${apiUrl}/v1/spaces/${target.spaceId}/knowledge-bases/${target.kbId}/ingestions`;
 
   console.log(`→ 上传到 KB: ${target.spaceName || target.spaceId}/${target.kbName || target.kbId}`);
@@ -272,6 +302,7 @@ async function uploadZip(zipPath, state, options) {
 
   try {
     const result = await uploadFile(uploadUrl, zipPath, state.apiKey);
+    assertIngestionResult(result);
     return result;
   } catch (err) {
     throw new Error(`上传失败: ${err.message}`);
@@ -339,6 +370,11 @@ async function main() {
       changeName = path.basename(folderPath);
     }
 
+    const expectedFolder = path.resolve(specRoot, 'openspec', 'changes', changeName);
+    if (path.resolve(folderPath) !== expectedFolder || !expectedFolder.startsWith(path.resolve(specRoot, 'openspec', 'changes') + path.sep)) {
+      throw new Error('文件夹上传仅接受当前 Spec 仓 openspec/changes/<change>；已归档内容请用 --zip 指定归档包');
+    }
+
     if (!fs.existsSync(folderPath)) {
       throw new Error(`变更目录不存在: ${folderPath}`);
     }
@@ -362,7 +398,9 @@ async function main() {
     if (!state.apiKey) {
       throw new Error('KB 配置中无 apiKey，请运行 /opsx-kb-config 配置知识库。');
     }
-    preCheckProjectId(projectId, state);
+    const target = resolveUploadTarget(state, { spaceId: args['space-id'], kbId: args['kb-id'] });
+    preCheckProjectId(projectId, state, target);
+    const cacheContext = { api: state.api || 'http://localhost:8090/api', spaceId: target.spaceId, kbId: target.kbId };
 
     // 4. 仅校验模式（含语义校验）
     if (args['validate-only']) {
@@ -390,26 +428,8 @@ async function main() {
     });
 
     try {
-      // === Step 5.1: 本地缓存快速检查 ===
-      const cache = readArchiveCache(specRoot, changeName);
-      if (cache && cache.archive_id === manifest.archive_id) {
-        console.log('\n✓ 内容无变更（archive_id 与上次成功上传一致），跳过上传');
-        console.log(`  cached archive_id: ${cache.archive_id}`);
-        console.log(`  uploaded_at: ${cache.uploaded_at}`);
-        console.log('\n✓ 完成（本地缓存命中）');
-        return;
-      }
-
-      // 解析上传目标
-      const target = (args['space-id'] && args['kb-id'])
-        ? { spaceId: args['space-id'], kbId: args['kb-id'] }
-        : state.targets[0];
-
-      if (!target || !target.spaceId || !target.kbId) {
-        throw new Error('未指定目标 Space/KB，请运行 /opsx-kb-config 配置知识库。');
-      }
-
-      const apiUrl = state.api || 'http://localhost:8090/api';
+      // Local receipts are informational only. Always verify the selected destination remotely.
+      const apiUrl = (state.api || 'http://localhost:8090/api').replace(/\/+$/, '');
 
       // === Step 5.5: KB 预检（网络级幂等确认）===
       const archiveId = manifest.archive_id;
@@ -424,11 +444,13 @@ async function main() {
       try {
         const checkResult = await httpGetJson(checkUrl, state.apiKey);
 
-        if (checkResult && checkResult.data && checkResult.data.idempotent) {
+        if (checkResult?.data?.idempotent && checkResult.data.publicationStatus === 'published') {
           console.log('\n✓ KB 中已存在相同 archive（幂等命中），跳过上传');
           console.log(`  snapshot_id: ${checkResult.data.snapshotId}`);
-          updateKbStateCache(specRoot, changeName, archiveId, contentHash);
-          console.log('\n✓ 完成（KB 预检命中）');
+          updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);
+          console.log(`  publication: ${checkResult.data.publicationStatus}; projection: ${checkResult.data.projectionStatus}`);
+          if (['failed', 'degraded'].includes(checkResult.data.projectionStatus)) console.log('⚠️ 检索准备尚未完成，请在知识库概览重试该任务的投影');
+          console.log('\n✓ 归档已存在（检索状态以上述回执为准）');
           return;
         }
 
@@ -467,8 +489,8 @@ async function main() {
       console.log(`  change_id:  ${manifest.change_id}`);
       console.log(`  files:      ${manifest.files.length}`);
 
-      // === 上传成功后更新本地缓存 ===
-      updateKbStateCache(specRoot, changeName, archiveId, contentHash);
+      // Canonical commit has been verified; a receipt does not imply projection completion.
+      updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);
 
       // === 投影状态提示 ===
       // 上传成功后，KB 后端异步执行 vector embedding + AGE graph 投影。
@@ -479,9 +501,9 @@ async function main() {
       if (projStatus === 'complete') {
         console.log('\n✓ 投影已完成，向量/图检索可用');
       } else if (projStatus === 'degraded') {
-        console.log('\n⚠️  投影完成但有降级（部分通道不可用，FTS 仍可用）');
+        console.log('\n⚠️  投影完成但有降级（部分通道不可用，召回结果会标记降级）');
       } else if (projStatus === 'disabled') {
-        console.log('\nℹ️  投影已禁用（FTS-only 模式）');
+        console.log('\nℹ️  投影已禁用（仅可使用当前已就绪的检索通道）');
       } else if (projStatus && projStatus !== 'complete') {
         console.log(`\nℹ️  投影进行中 (${projStatus})，向量/图检索暂不可用`);
         console.log('  → 正常 SDD 流程中阶段间间隔通常足够投影完成');
@@ -502,4 +524,5 @@ async function main() {
   }
 }
 
-main();
+if (require.main === module) main();
+module.exports = { resolveUploadTarget, readArchiveCache, updateKbStateCache, assertIngestionResult, uploadZip, buildPackageFromFolder, validateRequiredFiles };

package/skywalk-sdd/lib/usage-contract.cjs

@@ -112,7 +112,7 @@ function classifyUsageSubmitResponse(statusCode) {
  *   data: 若为 ApiResponse 信封且 code=0，则为解包后的 data；否则为 undefined
  *   error: 仅在 statusCode=null 时携带 Error；否则为 null
  */
-function postJson(url, payload, options = {}) {
+function postJson(url, payload = {}, options = {}) {
   return new Promise((resolve, reject) => {
     let target;
     try {
@@ -132,7 +132,8 @@ function postJson(url, payload, options = {}) {
 
     let body;
     try {
-      body = JSON.stringify(payload === undefined ? {} : payload);
+      // payload 缺省为 {}（默认参数），null 仍按 "null" 序列化，与原三元行为一致
+      body = JSON.stringify(payload);
     } catch (err) {
       reject(new Error(`payload serialization error: ${err.message}`));
       return;

package/skywalk-sdd/lib/usage-reporter.cjs

@@ -31,6 +31,27 @@ const SHARED_DEADLINE_MS = 3000;
 // 单行事件 JSON 的安全上限（小于 4KB 以保证 appendFileSync 在 POSIX/Windows 都原子）
 const SINGLE_EVENT_MAX_BYTES = 4096;
 
+// drop 警告每进程最多一次的模块级标记
+let dropWarned = false;
+
+/**
+ * drop（含 401）时输出一次 stderr 警告；每进程最多一次，简短带 [kld-sdd] 前缀。
+ */
+function warnUsageDropOnce() {
+  if (dropWarned) return;
+  dropWarned = true;
+  try {
+    process.stderr.write('[kld-sdd] usage 事件上报被拒绝，本次事件已丢弃\n');
+  } catch { /* stderr 不可用时静默 */ }
+}
+
+/**
+ * 测试专用：重置 drop 警告的每进程一次标记。
+ */
+function _resetDropWarned() {
+  dropWarned = false;
+}
+
 function pendingPathFor(homeDir) {
   const envHome = typeof process !== 'undefined' && process && process.env
     ? process.env.KLD_SDD_HOME
@@ -84,13 +105,14 @@ function resolveReportServer(options = {}) {
     const normalized = normalizeServerUrl(config.server);
     if (normalized) return normalized;
   }
-  // 2. 项目级 kb-state.json 的 api
+  // 2. 项目级 kb-state.json 的 api（kb-state.api 是唯一带 /api 契约的来源，先剥离尾部 /api 再标准化）
   try {
     const kbStatePath = path.join(projectRoot, 'kb-state.json');
     if (fs.existsSync(kbStatePath)) {
       const kbState = JSON.parse(fs.readFileSync(kbStatePath, 'utf8'));
       if (kbState && typeof kbState.api === 'string') {
-        const normalized = normalizeServerUrl(kbState.api);
+        const stripped = kbState.api.trim().replace(/\/api(\/v\d+)?\/?$/i, '');
+        const normalized = normalizeServerUrl(stripped);
         if (normalized) return normalized;
       }
     }
@@ -300,6 +322,7 @@ async function flushPendingQueue(server, identity, pendingFile, deadlineStart) {
     }
     if (classification === 'drop') {
       // drop 丢弃该条（含 401），不 retained、不 break，继续下一条
+      warnUsageDropOnce();
       if (ev.id) droppedIds.add(ev.id);
       continue;
     }
@@ -421,6 +444,7 @@ async function reportUsageOnce(options = {}) {
           currentOutcome = 'confirmed';
         } else if (classification === 'drop') {
           // 当前事件 drop（含 401）直接丢弃不入队，不清任何本地状态
+          warnUsageDropOnce();
           currentOutcome = 'dropped';
         } else {
           currentOutcome = 'enqueued';
@@ -453,6 +477,7 @@ module.exports = {
   readGitIdentity,
   resolveReportServer,
   _resetGitIdentityCache,
+  _resetDropWarned,
   PENDING_FILE_NAME,
   PENDING_MAX_BYTES,
   FLUSH_MAX_COUNT,

package/skywalk-sdd/metrics-v3.cjs

@@ -1036,7 +1036,7 @@ function buildSchemeCompliance(input = {}) {
   const semanticParity = input.semantic_parity_status || input.semantic_parity || null;
   const multiFormatStatus = semanticParity === 'pass'
     ? 'implemented'
-    : (['md', 'html', 'json'].every(format => formats.includes(format)) ? 'provisional' : 'provisional');
+    : 'provisional';
   const alertLoopReady = Boolean(
     input.alert_loop
     && input.alert_loop.root_cause
@@ -1050,7 +1050,7 @@ function buildSchemeCompliance(input = {}) {
     || null;
   const reproducibleStatus = eventContractHealth === 'healthy' && Number(input.event_count) > 0
     ? 'implemented'
-    : (Number(input.event_count) > 0 ? 'provisional' : 'provisional');
+    : 'provisional';
   const statusLabel = status => ({
     implemented: '已实现',
     provisional: '部分可用',

package/skywalk-sdd/ontology/active-changes.cjs

@@ -42,7 +42,8 @@ function stripQuotes(value) {
 }
 
 function needsQuotes(value) {
-  return /^[\s]|[:#]|[\s]$/.test(value);
+  // 非捕获分组显式锚定各分支优先级：以空白开头、含 : 或 #、以空白结尾
+  return /(?:^[\s])|(?:[:#])|(?:[\s]$)/.test(value);
 }
 
 function quoteIfNeeded(value) {

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

@@ -571,7 +571,7 @@ function materializeArchivePackage(options = {}) {
   const projectIdentity = ensureProjectIdentity(projectRoot);
   const changeId = requiredText(snapshot.change_id, 'change_id', ONTOLOGY_PATH);
   const archiveId = `urn:kld:sdd:archive:${sha256(
-    `${projectIdentity.project_id}\n${changeId}\n${snapshot.facts_hash}`,
+    `${projectIdentity.project_id}\n${changeId}\n${snapshot.facts_hash}\n${snapshot.source_revision || snapshot.facts_hash}`,
   )}`;
   const { canonicalFacts, warnings } = buildCanonicalFacts(
     archiveDir,

package/skywalk-sdd/ontology/artifact-parser.cjs

@@ -246,7 +246,8 @@ function parseStructuredFrontmatter(lines) {
     const nested = line.match(/^\s{2,}([A-Za-z0-9_-]+):\s*(.*?)\s*$/);
 
     if (topKey && !/^\s/.test(line)) {
-      currentRef = flushRequirementRef(requirementRefs, currentRef);
+      flushRequirementRef(requirementRefs, currentRef);
+      currentRef = null;
       section = topKey[1].toLowerCase();
       const value = unwrapScalar(stripInlineYamlComment(topKey[2]));
       flat[section] = value;
@@ -263,7 +264,7 @@ function parseStructuredFrontmatter(lines) {
     }
 
     if (section === 'requirement-refs' && listItem) {
-      currentRef = flushRequirementRef(requirementRefs, currentRef) || {};
+      flushRequirementRef(requirementRefs, currentRef);
       currentRef = { [listItem[1].toLowerCase()]: unwrapScalar(stripInlineYamlComment(listItem[2])) };
       continue;
     }
@@ -668,7 +669,8 @@ function addStructuralEntities(target, files, options = {}) {
         name: descriptor.file.relativePath,
         entity_id: identity.entity_id,
         version_id: identity.version_id,
-        delta_state: 'added',
+        delta_state: identity.delta_state || 'added',
+        predecessor_version_id: identity.predecessor_version_id || undefined,
         content_hash: descriptor.content_hash,
         attributes: { artifact_type: artifactType(descriptor.file.relativePath), path: descriptor.file.relativePath },
         source: sourceFor(descriptor.file, 1, identity.anchor_id),
@@ -684,7 +686,8 @@ function addStructuralEntities(target, files, options = {}) {
         name: `${owner.source.file}#${owner.id}`,
         entity_id: identity.entity_id,
         version_id: identity.version_id,
-        delta_state: 'added',
+        delta_state: identity.delta_state || 'added',
+        predecessor_version_id: identity.predecessor_version_id || undefined,
         content_hash: descriptor.content_hash,
         attributes: { artifact_path: owner.source.file, entity_anchor: owner.id },
         source: { ...owner.source, anchor_id: identity.anchor_id },

package/skywalk-sdd/ontology/id.cjs

@@ -3,7 +3,7 @@
 const crypto = require('crypto');
 const { ID_PREFIX_TYPES, entityTypeForId } = require('./schema.cjs');
 
-const ID_BYTE_LENGTH = 4;
+const ID_BYTE_LENGTH = 16;
 const ID_HEX_LENGTH = ID_BYTE_LENGTH * 2;
 
 function normalizeSlug(value) {
@@ -52,15 +52,16 @@ function isValidEntityId(entityId, expectedType = '') {
 }
 
 function generateIdentityId() {
-  return crypto.randomBytes(ID_BYTE_LENGTH).toString('hex');
+  return crypto.randomUUID();
 }
 
 function generateUuidV7() {
+  // Compatibility name retained for existing callers; new identities are standard UUIDs.
   return generateIdentityId();
 }
 
 /**
- * Normalize a UUID value to the internal 8-hex short format.
+ * Preserve full UUIDs; collapse only the legacy zero-padded 8-hex representation.
  *
  * KB backend (PostgreSQL) serializes UUID columns as full 36-char format
  * (e.g. "3518f551-0000-0000-0000-000000000000").  The SDD toolchain uses
@@ -69,7 +70,7 @@ function generateUuidV7() {
  */
 function normalizeUuid(value) {
   const v = String(value || '').trim().toLowerCase();
-  const fullUuidMatch = v.match(/^([0-9a-f]{8})-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  const fullUuidMatch = v.match(/^([0-9a-f]{8})-0000-0000-0000-000000000000$/);
   if (fullUuidMatch) {
     return fullUuidMatch[1];
   }

package/skywalk-sdd/ontology/identity-index.cjs

@@ -168,11 +168,11 @@ function buildCatalogDiagnostics(records) {
   const byPredecessor = groupBy(records, 'predecessor_version_id');
 
   for (const [entityId, items] of byEntityId.entries()) {
-    const signatures = new Set(items.map((item) => `${item.anchor_id}|${item.type}`));
+    const signatures = new Set(items.map((item) => item.type));
     if (signatures.size > 1) {
       diagnostics.push(catalogDiagnostic(
         DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
-        `历史集合中同一 entity-id 对应多个锚点或类型: ${entityId}`,
+        `历史集合中同一 entity-id 对应多个类型: ${entityId}`,
         { entity_id: items[0].anchor_id, file: items[0].source && items[0].source.file },
       ));
     }
@@ -206,7 +206,8 @@ function buildCatalogDiagnostics(records) {
       diagnostics.push(catalogDiagnostic(
         DIAGNOSTIC_CODES.VERSION_LINEAGE_CONFLICT,
         `历史集合中同一 predecessor 存在多个后继: ${predecessorId}`,
-        { entity_id: items[0].anchor_id, file: items[0].source && items[0].source.file },
+        { severity: items.every(item => item.scope === "active") ? "warning" : "error",
+          entity_id: items[0].anchor_id, file: items[0].source && items[0].source.file },
       ));
     }
   }

package/skywalk-sdd/ontology/list-changes.cjs

@@ -15,7 +15,7 @@ function listActiveChanges(projectRoot) {
       const full = path.join(changesDir, name);
       return fs.statSync(full).isDirectory();
     })
-    .sort();
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
 function describeChange(projectRoot, changeName, registry) {

package/skywalk-sdd/ontology/runtime.cjs

@@ -417,8 +417,10 @@ function createArchiveSnapshot(projectRoot, changeName, archiveDir, inputState)
   }
   const snapshotId = `SNAP-${sha256(`${changeName}:${state.revision}`).slice(0, 16).toUpperCase()}`;
   const targetPath = path.join(targetDir, 'archive-ontology.json');
-  const previous = fs.existsSync(targetPath)
-    ? JSON.parse(fs.readFileSync(targetPath, 'utf8'))
+  const cachePath = path.join(statePaths(projectRoot, changeName).dir, 'snapshots', `${state.revision}.json`);
+  const previousPath = fs.existsSync(cachePath) ? cachePath : targetPath;
+  const previous = fs.existsSync(previousPath)
+    ? JSON.parse(fs.readFileSync(previousPath, 'utf8'))
     : null;
   const previousEntity = previous && previous.source_revision === state.revision
     ? (previous.entities || []).find((entity) => entity.type === 'OntologySnapshot')
@@ -458,12 +460,14 @@ function createArchiveSnapshot(projectRoot, changeName, archiveDir, inputState)
     snapshot_id: snapshotId,
     snapshot_entity_id: snapshotEntity.entity_id,
     source_revision: state.revision,
-    confirmed_at: new Date().toISOString(),
+    confirmed_at: previous && previous.source_revision === state.revision
+      ? previous.confirmed_at : new Date().toISOString(),
     entities: [
       ...(state.entities || []).filter((entity) => entity.type !== 'OntologySnapshot'),
       snapshotEntity,
     ],
   };
+  atomicWriteIfChanged(cachePath, snapshot);
   atomicWriteIfChanged(targetPath, snapshot);
   return snapshot;
 }

package/skywalk-sdd/ontology/schema.cjs

@@ -114,6 +114,8 @@ const DIAGNOSTIC_CODES = Object.freeze({
   NUMBERING_WAIVER_ACTIVE: 'NUMBERING_WAIVER_ACTIVE',
   CONTINUITY_DECISION_REQUIRED: 'CONTINUITY_DECISION_REQUIRED',
   CONTINUITY_IDENTITY_MISMATCH: 'CONTINUITY_IDENTITY_MISMATCH',
+  TASK_DEPENDENCY_LAYER_GAP: 'SEM_TASK_DEPENDENCY_LAYER_GAP',
+  TASK_DEPENDENCY_MISSING_EDGE: 'SEM_TASK_DEPENDENCY_MISSING_EDGE',
 });
 
 function normalizeProfile(profile, inferredProfile = 'simple') {

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

@@ -113,7 +113,7 @@ function validateIdentitySemantics(facts, diagnostics, identityHistory) {
     }
 
     const entityOwner = currentByEntityId.get(entity.entity_id);
-    if (entityOwner && (entityOwner.id !== entity.id || entityOwner.type !== entity.type)) {
+    if (entityOwner && (entityOwner.type !== entity.type)) {
       diagnostics.push(diagnostic(
         DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
         'error',
@@ -165,7 +165,7 @@ function validateIdentitySemantics(facts, diagnostics, identityHistory) {
     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)
+    if (priorEntities.some((record) => record.type !== entity.type)
       || priorAnchors.some((record) => record.entity_id !== entity.entity_id)) {
       diagnostics.push(diagnostic(
         DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
@@ -220,8 +220,8 @@ function validateIdentitySemantics(facts, diagnostics, identityHistory) {
       if (knownSuccessor) {
         diagnostics.push(diagnostic(
           DIAGNOSTIC_CODES.VERSION_LINEAGE_CONFLICT,
-          'error',
-          `同一 predecessor 已存在后继版本，禁止并行或陈旧分支: ${entity.id}`,
+          knownSuccessor.scope === 'active' ? 'warning' : 'error',
+          `同一 predecessor 存在其他后继；草稿可并行，发布前必须解决基线冲突: ${entity.id}`,
           { ...context, suggestion: `以 ${knownSuccessor.change} 的版本为直接前序；不要再次继承已消费的 predecessor` },
         ));
       }
@@ -922,6 +922,8 @@ function validateTraceability(facts, options = {}) {
     ));
   }
 
+  validateTaskLayerSemantics(graphEntities, graphRelations, diagnostics);
+
   diagnostics.sort((left, right) => (
     String(left.code).localeCompare(String(right.code))
     || String(left.file || '').localeCompare(String(right.file || ''))
@@ -943,10 +945,78 @@ function validateTraceability(facts, options = {}) {
   };
 }
 
+function inferTaskLayer(task) {
+  const attrs = task.attributes || {};
+  if (typeof attrs.layer === 'number') return attrs.layer;
+
+  const id = String(task.id || '').toUpperCase();
+  const desc = String(task.description || task.title || '').toUpperCase();
+  const text = `${id} ${desc}`;
+
+  const patterns = [
+    { layer: 0, keywords: ['DEPS', 'DEPEND', 'CONFIG', 'POM', 'GRADLE', 'CONST'] },
+    { layer: 1, keywords: ['ENTITY', 'DTO', 'ENUM', 'VO', 'MODEL'] },
+    { layer: 2, keywords: ['MAPPER', 'REPO', 'REPOSITORY', 'DAO'] },
+    { layer: 3, keywords: ['SERVICE-IF', 'SERVICE_IF', 'INTERFACE'] },
+    { layer: 4, keywords: ['IMPL', 'SERVICE', 'HANDLER', 'PROCESSOR'] },
+    { layer: 5, keywords: ['CONTROLLER', 'API', 'RESOURCE', 'ENDPOINT'] },
+    { layer: 6, keywords: ['TEST', 'VERIFY', 'VALIDATE', 'SPEC'] },
+  ];
+
+  for (const { layer, keywords } of patterns) {
+    if (keywords.some((kw) => text.includes(kw))) return layer;
+  }
+  return null;
+}
+
+function validateTaskLayerSemantics(graphEntities, graphRelations, diagnostics) {
+  const tasks = graphEntities.filter((entity) => entity.type === 'Task' && entity.delta_state !== 'removed');
+  if (tasks.length === 0) return;
+
+  const taskById = new Map();
+  for (const task of tasks) taskById.set(task.id, task);
+
+  const dependsOnMap = new Map();
+  for (const relation of graphRelations) {
+    if (relation.type !== 'dependsOn') continue;
+    if (!dependsOnMap.has(relation.from)) dependsOnMap.set(relation.from, new Set());
+    dependsOnMap.get(relation.from).add(relation.to);
+  }
+
+  const layerByTask = new Map();
+  for (const task of tasks) {
+    const layer = inferTaskLayer(task);
+    if (layer !== null) layerByTask.set(task.id, layer);
+  }
+
+  for (const [taskId, layer] of layerByTask.entries()) {
+    if (layer <= 0) continue;
+    const deps = dependsOnMap.get(taskId) || new Set();
+
+    for (const [otherId, otherLayer] of layerByTask.entries()) {
+      if (otherId === taskId) continue;
+      if (otherLayer >= layer) continue;
+      if (!deps.has(otherId)) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.TASK_DEPENDENCY_LAYER_GAP,
+          'warning',
+          `Task ${taskId} (Layer ${layer}) 可能缺少对 Layer ${otherLayer} 任务 ${otherId} 的依赖`,
+          {
+            entity_id: taskId,
+            suggestion: `若 ${taskId} 引用或依赖 ${otherId} 的定义，建议添加 dependsOn: ${otherId}`,
+          },
+        ));
+      }
+    }
+  }
+}
+
 module.exports = {
   diagnostic,
   findTaskCycles,
   validateIdentitySemantics,
   validateInheritedReferences,
   validateTraceability,
+  validateTaskLayerSemantics,
+  inferTaskLayer,
 };