kld-sdd 2.7.8 → 2.8.1

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
@@ -28,18 +33,34 @@ const {
   ensureDir,
   copyDirRecursive,
   resolveSpecRootFast,
-  loadKbState,
+  KB_STATE_FILENAME,
+  isKbStateHostDir,
   uploadFile,
   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 || [];
+  const targets = Array.isArray(state?.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');
+
+  const configured = state?.uploadTarget;
+  if (configured != null) {
+    if (!configured.spaceId || !configured.kbId) {
+      throw new Error('kb-state.json 的 uploadTarget 不完整，请在 SDD 助手中重新选择 Spec 上传知识库');
+    }
+    const selected = targets.find(t => t.spaceId === configured.spaceId && t.kbId === configured.kbId);
+    if (!selected) {
+      throw new Error('kb-state.json 的 uploadTarget 已不在 targets 读取范围中，请在 SDD 助手中重新选择 Spec 上传知识库');
+    }
+    return selected;
+  }
+
+  if (targets.length !== 1) {
+    throw new Error('请明确上传目标：在 SDD 助手中选择“Spec 上传知识库”，或同时指定 --space-id 和 --kb-id；不会自动分发到多个 KB');
+  }
   if (!targets[0].spaceId || !targets[0].kbId) throw new Error('知识库目标缺少 spaceId/kbId');
   return targets[0];
 }
@@ -49,18 +70,33 @@ function cacheKey(changeName, context) {
   return JSON.stringify([context.api.replace(/\/+$/, ''), context.spaceId, context.kbId, changeName]);
 }
 
-function assertIngestionResult(result) {
+function assertIngestionResult(result, options = {}) {
   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') {
+  if (Number(job.report?.version_conflicts || 0) > 0) {
     throw new Error(`VERSION_CONFLICT: 事实包已保存为候选，当前事实未更新；请合并基线后重新发布。job=${job.jobId}`);
   }
+  if (job.report?.publication_status === 'needs_review' && !options.allowNeedsReview) {
+    throw new Error(`REVIEW_REQUIRED: 事实包已保存为候选，当前事实未更新；请审核本体后重新发布。job=${job.jobId}`);
+  }
   return job;
 }
 
+/**
+ * 解析 kb-state.json 的权威路径：`<specRoot>/kb-state.json`。
+ *
+ * 位置校验已由 `resolveSpecRoot` 在入口完成（本函数只做路径拼接）。
+ *
+ * @param {string} specRoot spec 包裹包根目录
+ * @returns {string} kb-state.json 绝对路径
+ */
+function resolveKbStatePath(specRoot) {
+  return path.join(path.resolve(specRoot), KB_STATE_FILENAME);
+}
+
 /**
  * 读取 kb-state.json 中指定 change 的 archive 缓存。
  * @param {string} specRoot
@@ -68,9 +104,7 @@ function assertIngestionResult(result) {
  * @returns {object|null} { archive_id, content_hash, uploaded_at }
  */
 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 statePath = resolveKbStatePath(specRoot);
   const state = readJsonSafe(statePath);
   if (!state || !state.archiveCache) return null;
   const key = cacheKey(changeName, context);
@@ -85,9 +119,7 @@ function readArchiveCache(specRoot, changeName, context) {
  * @param {string} 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 statePath = resolveKbStatePath(specRoot);
   const state = readJsonSafe(statePath) || {};
   if (!state.archiveCache) state.archiveCache = {};
   const key = cacheKey(changeName, context);
@@ -116,8 +148,18 @@ const DEFAULT_LEVEL = 'propose-spec';
 // ── 工具函数 ──────────────────────────────────────────
 
 function resolveSpecRoot(explicit) {
-  if (explicit) return path.resolve(explicit);
-  return resolveSpecRootFast(__dirname);
+  const root = explicit ? path.resolve(explicit) : resolveSpecRootFast(__dirname);
+  // 位置校验前移：specRoot 必须是 spec 包裹包根，后续所有 kb-state.json /
+  // project-identity.json 读取都建立在它之上。在此 fail-fast，避免流程走到
+  // 中途才因「文件不存在」报出误导性错误（真正原因是路径指错了地方）。
+  if (!isKbStateHostDir(root)) {
+    throw new Error(
+      `kb-state.json 位置校验失败：${root} 不是 spec 包裹包根目录。\n` +
+      'kb-state.json 只允许位于 spec 包裹包根（由 /opsx-kb-config 写入）。\n' +
+      '请确认 --project 指向 *-sdd-specs 包裹包，或运行 /opsx-kb-config 重新配置。'
+    );
+  }
+  return root;
 }
 
 /**
@@ -139,36 +181,28 @@ function resolveProjectId(specRoot) {
 }
 
 /**
- * 读取 KB 配置（api, apiKey, tenantKey, targets）
- * 使用 shared.cjs 的 loadKbState，支持 BOM 剥离和多路径搜索
+ * 读取 KB 配置（api, apiKey, tenantKey, targets）。
+ *
+ * 位置校验：只读 `<specRoot>/kb-state.json`（specRoot 的 spec 根身份已由
+ * resolveSpecRoot 在入口校验）。
  */
 function readKbState(specRoot) {
-  // 优先尝试 specRoot 根目录下的 kb-state.json（新路径）
-  const directPath = path.join(specRoot, 'kb-state.json');
-  // 兼容旧路径：specRoot 同级 .shared/kb-state.json
-  const legacyPath = path.join(specRoot, '..', '.shared', 'kb-state.json');
-  if (fs.existsSync(directPath)) {
-    try {
-      return readJson(directPath);
-    } catch (e) {
-      throw new Error(
-        `KB 配置解析失败 (${directPath}): ${e.message}\n` +
-        '请运行 /opsx-kb-config 重新配置知识库。'
-      );
-    }
-  }
-  // 退回到多路径搜索（从 specRoot 向上查找）
-  const { config, path: foundPath, warnings } = loadKbState(specRoot);
-  if (warnings.length > 0) {
-    for (const w of warnings) console.warn(`⚠️  ${w}`);
-  }
-  if (!config) {
+  const statePath = resolveKbStatePath(specRoot);
+  if (!fs.existsSync(statePath)) {
     throw new Error(
       'KB 配置不存在（kb-state.json 缺失）。\n' +
+      `期望位置: ${statePath}\n` +
       '请运行 /opsx-kb-config 配置知识库。'
     );
   }
-  return config;
+  try {
+    return readJson(statePath);
+  } catch (e) {
+    throw new Error(
+      `KB 配置解析失败 (${statePath}): ${e.message}\n` +
+      '请运行 /opsx-kb-config 重新配置知识库。'
+    );
+  }
 }
 
 /**
@@ -204,7 +238,7 @@ function preCheckProjectId(projectId, state, selectedTarget) {
   }
   const spaceKey = (selectedTarget || resolveUploadTarget(state)).spaceKey;
   if (!spaceKey) {
-    console.warn('⚠️  kb-state.json targets[0].spaceKey 为空，跳过本地预检');
+    console.warn('⚠️  kb-state.json 的上传目标缺少 spaceKey，跳过本地预检');
     return;
   }
   if (projectId !== spaceKey) {
@@ -229,9 +263,65 @@ function preCheckProjectId(projectId, state, selectedTarget) {
  *   5. materializeArchivePackage（生成 manifest + canonical-facts + conversion-report + zip）
  *   6. 返回 zip 路径
  */
-function buildPackageFromFolder(specRoot, changeName, options) {
+/**
+ * 历史产物的 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)...');
@@ -239,13 +329,20 @@ function buildPackageFromFolder(specRoot, changeName, options) {
     profile: 'auto',
     markPending: true,
   });
+  const legacy = classifyLegacyDiagnostics(semanticResult.diagnostics);
+  const legacyIdentityOnly = legacy.legacyCompatible;
   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')}`);
+    if (!legacyIdentityOnly) {
+      const errors = legacy.blocking.map(d => `${d.code}: ${d.message}`);
+      throw new Error(`语义校验失败:\n${errors.join('\n')}`);
+    }
+    console.warn('⚠️  检测到历史产物缺少身份标识，将生成旁路映射与本体包，不改写 Markdown。');
+    for (const item of legacy.tolerated) {
+      console.warn(`   ↳ 兼容放行 ${item.code}: ${item.message}`);
+    }
+  } else {
+    console.log(`✓ 语义校验通过 (profile: ${semanticResult.profile}, revision: ${semanticResult.revision})`);
   }
-  console.log(`✓ 语义校验通过 (profile: ${semanticResult.profile}, revision: ${semanticResult.revision})`);
 
   // 2. 创建临时 staging 目录
   const stagingDir = path.join(
@@ -258,28 +355,63 @@ function buildPackageFromFolder(specRoot, changeName, options) {
     const changeDir = path.join(specRoot, 'openspec', 'changes', changeName);
     copyDirRecursive(changeDir, stagingDir);
 
-    // 4. 创建 archive snapshot（生成 archive-ontology.json）
-    runtime.createArchiveSnapshot(specRoot, changeName, stagingDir, semanticResult.state);
-    console.log('✓ 已生成 archive-ontology.json');
-
-    // 5. 生成 manifest + canonical-facts + conversion-report + zip
-    const projectIdentity = archivePackage.ensureProjectIdentity(specRoot);
-    const result = archivePackage.materializeArchivePackage({
-      projectRoot: specRoot,
-      archiveDir: stagingDir,
-      archivePath: stagingDir,
-      changeName: changeName,
-      packagePath: zipPath,
-      reason: options.reason || '随时入库（文件夹上传）',
-      method: 'kb-upload-folder',
-    });
+    let result;
+    let legacyStatus = null;
+    if (legacyIdentityOnly) {
+      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: resolved.approved,
+        toleratedDiagnostics: legacy.tolerated,
+        packagePath: zipPath,
+        reason: options.reason || '历史 Spec 兼容入库',
+        method: 'kb-upload-legacy-folder',
+      });
+      console.log(resolved.approved
+        ? '✓ 已生成审核通过的 LEGACY_MATERIALIZED 发布包'
+        : '✓ 已生成 LEGACY_MATERIALIZED 本体候选包');
+    } else {
+      // 严格产物继续生成 confirmed snapshot 和双协议事实包。
+      runtime.createArchiveSnapshot(specRoot, changeName, stagingDir, semanticResult.state);
+      console.log('✓ 已生成 archive-ontology.json');
+      archivePackage.ensureProjectIdentity(specRoot);
+      result = archivePackage.materializeArchivePackage({
+        projectRoot: specRoot,
+        archiveDir: stagingDir,
+        archivePath: stagingDir,
+        changeName: changeName,
+        packagePath: zipPath,
+        reason: options.reason || '随时入库（文件夹上传）',
+        method: 'kb-upload-folder',
+      });
+    }
 
     console.log(`✓ Archive Package 已生成`);
     console.log(`  archive_id: ${result.manifest.archive_id}`);
     console.log(`  project_id: ${result.manifest.project_id}`);
     console.log(`  files: ${result.manifest.files.length}`);
 
-    return { zipPath, manifest: result.manifest, stagingDir };
+    return {
+      zipPath,
+      manifest: result.manifest,
+      stagingDir,
+      requiresReview: result.conversion_report?.status === 'materialized_pending_review',
+      legacyStatus,
+      toleratedDiagnostics: legacyIdentityOnly ? legacy.tolerated : [],
+    };
   } catch (err) {
     // 出错时清理 staging
     fs.rmSync(stagingDir, { recursive: true, force: true });
@@ -302,7 +434,7 @@ async function uploadZip(zipPath, state, options) {
 
   try {
     const result = await uploadFile(uploadUrl, zipPath, state.apiKey);
-    assertIngestionResult(result);
+    assertIngestionResult(result, options);
     return result;
   } catch (err) {
     throw new Error(`上传失败: ${err.message}`);
@@ -319,6 +451,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);
   }
 
@@ -332,6 +465,7 @@ async function main() {
   try {
     // ── Zip 模式 ──
     if (args.package) {
+      if (args['validate-only']) throw new Error('--validate-only 仅支持 --folder/--change 本地语义校验；未执行归档上传');
       const zipPath = path.resolve(args.package);
       if (!fs.existsSync(zipPath)) {
         throw new Error(`zip 文件不存在: ${zipPath}`);
@@ -370,9 +504,12 @@ 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 指定归档包');
+    const changesRoot = fs.realpathSync(path.resolve(specRoot, 'openspec', 'changes'));
+    const expectedPath = path.resolve(changesRoot, changeName);
+    const expectedFolder = fs.existsSync(expectedPath) ? fs.realpathSync(expectedPath) : expectedPath;
+    const suppliedFolder = fs.existsSync(folderPath) ? fs.realpathSync(folderPath) : path.resolve(folderPath);
+    if (suppliedFolder !== expectedFolder || !expectedFolder.startsWith(changesRoot + path.sep)) {
+      throw new Error('文件夹上传仅接受当前 Spec 仓 openspec/changes/<change>；已归档内容请用 --package 指定归档包');
     }
 
     if (!fs.existsSync(folderPath)) {
@@ -389,19 +526,6 @@ async function main() {
     // 1. 校验必需文件
     validateRequiredFiles(folderPath, minimumLevel);
 
-    // 2. 解析 project_id
-    const projectId = resolveProjectId(specRoot);
-    console.log(`✓ project_id: ${projectId}`);
-
-    // 3. 读取 KB 配置 + 预检
-    const state = readKbState(specRoot);
-    if (!state.apiKey) {
-      throw new Error('KB 配置中无 apiKey，请运行 /opsx-kb-config 配置知识库。');
-    }
-    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']) {
       const runtime = require('./ontology/runtime.cjs');
@@ -411,20 +535,39 @@ 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，未上传）');
+      console.log('\n✓ 本地语义校验完成（--validate-only，未联网；不代表权限、发布基线或入库已验证）');
       return;
     }
 
+    // 2. 解析 project_id
+    const projectId = resolveProjectId(specRoot);
+    console.log(`✓ project_id: ${projectId}`);
+
+    // 3. 读取 KB 配置 + 预检
+    const state = readKbState(specRoot);
+    if (!state.apiKey) {
+      throw new Error('KB 配置中无 apiKey，请运行 /opsx-kb-config 配置知识库。');
+    }
+    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 };
+
     // 5. 构建 Archive Package
     console.log('');
-    const { zipPath, manifest, stagingDir } = buildPackageFromFolder(specRoot, changeName, {
+    const { zipPath, manifest, stagingDir, requiresReview, legacyStatus } = buildPackageFromFolder(specRoot, changeName, {
       reason: args.reason,
+      requireReview: Boolean(args['require-review']),
     });
 
     try {
@@ -477,6 +620,7 @@ async function main() {
       const result = await uploadZip(zipPath, state, {
         spaceId: target.spaceId,
         kbId: target.kbId,
+        allowNeedsReview: requiresReview,
       });
 
       console.log('\n── 上传结果 ──');
@@ -489,8 +633,21 @@ async function main() {
       console.log(`  change_id:  ${manifest.change_id}`);
       console.log(`  files:      ${manifest.files.length}`);
 
-      // Canonical commit has been verified; a receipt does not imply projection completion.
-      updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);
+      const publicationStatus = result?.data?.report?.publication_status
+        || result?.report?.publication_status
+        || '';
+      if (publicationStatus === 'needs_review') {
+        console.log('\n⚠️  历史 Spec 已安全保存为候选，尚未进入 current 召回');
+        console.log(`  → 审核 ${path.join(folderPath, 'ontology', 'spec-ontology.json')}`);
+        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);
+      }
 
       // === 投影状态提示 ===
       // 上传成功后，KB 后端异步执行 vector embedding + AGE graph 投影。

package/skywalk-sdd/lib/check-review.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+const CATEGORIES = ['completeness', 'consistency', 'executability', 'tdd_compliance'];
+
+function assembleReview(review, taskCompletion, options = {}) {
+  if (!review || !Array.isArray(review.items) || !review.items.length) throw new Error('CHECK_ITEMS_REQUIRED: 提供实际评审项，不能提交空模板');
+  const categories = Object.fromEntries(CATEGORIES.map(key => [key, { passed: 0, total: 0 }]));
+  const warnings = [], suggestions = [], ids = new Set();
+  for (const item of review.items) {
+    if (!item.id || ids.has(item.id)) throw new Error('CHECK_ITEM_ID_INVALID: 检查项必须有唯一 ID');
+    ids.add(item.id);
+    if (!CATEGORIES.includes(item.category) || !['passed', 'error', 'warning', 'suggestion', 'na'].includes(item.status)) throw new Error('CHECK_ITEM_STATUS_INVALID');
+    if (typeof item.evidence !== 'string' || !item.evidence.trim()) throw new Error(`CHECK_ITEM_EVIDENCE_REQUIRED: ${item.id} 缺少来源证据或不适用原因`);
+    if (item.status === 'na') continue;
+    categories[item.category].total++;
+    if (item.status !== 'error') categories[item.category].passed++;
+    if (item.status === 'warning') warnings.push({ category: item.category, warning: item.id, description: item.description || item.evidence, target: item.evidence });
+    if (item.status === 'suggestion') suggestions.push(item);
+  }
+  const total = Object.values(categories).reduce((n, c) => n + c.total, 0);
+  const passed = Object.values(categories).reduce((n, c) => n + c.passed, 0);
+  if (!total) throw new Error('CHECK_ITEMS_REQUIRED: 至少有一个实际适用的评审项');
+  if (taskCompletion.has_incomplete) warnings.push({ category: 'task_completion', warning: 'TASKS_INCOMPLETE', description: `${taskCompletion.incomplete} 个任务尚未完成`, target: 'tasks.md' });
+  const result = total !== passed ? 'failure' : (warnings.length ? 'partial' : 'success');
+  return {
+    result,
+    details: { check_results: {
+      ...review.reviewer,
+      total, errors: total - passed, warnings: warnings.length, suggestions: suggestions.length,
+      categories, warning_items: warnings, warning_dispositions: review.warning_dispositions || [],
+      // This field means items satisfied before implementation, not defect fixes.
+      fixed_before_apply: options.beforeApply ? passed : Math.min(total, options.previousBeforeApply || 0),
+      consistency_score: null,
+      task_completion: { ...taskCompletion, checked_for_archive_readiness: !options.beforeApply },
+      review_items: review.items,
+      review_revision: options.revision,
+    } },
+  };
+}
+
+module.exports = { assembleReview };