kld-sdd 2.5.2 → 2.6.1

package/README.md

@@ -32,8 +32,8 @@ Entity sourcedFrom SEC
 每个本体实体使用双层身份：
 
 - `anchor`：`STMT-ORDER-005` 等人工可读编号，跨迭代保持稳定且删除后不复用。
-- `entity-id`：全局唯一 UUIDv7，同一逻辑实体跨迭代复用。
-- `version-id`：全局唯一 UUIDv7，每次 added/modified/removed 产生新版本；unchanged 复用历史版本。
+- `entity-id`：全局唯一 32 位 ID（8 位十六进制），同一逻辑实体跨迭代复用。
+- `version-id`：全局唯一 32 位 ID，每次 added/modified/removed 产生新版本；unchanged 复用历史版本。
 - `predecessor-version`：modified/removed 指向同一实体的直接前序版本。
 
 UUID 由本地命令生成，不依赖网络、机器号或中央 ID 服务：
@@ -53,7 +53,7 @@ node skywalk-sdd/log.cjs semantic-identity --delta-state=unchanged --entity-id=<
 本地命令：
 
 ```bash
-# 解析与诊断；首次运行会为 Artifact/DocumentSection 分配并持久化结构 UUIDv7 sidecar
+# 解析与诊断；首次运行会为 Artifact/DocumentSection 分配并持久化 32 位结构 ID sidecar
 node skywalk-sdd/log.cjs semantic-scan --project=. --change=<name>
 
 # 文件与工作态本体实例全量对账
@@ -69,6 +69,10 @@ node skywalk-sdd/log.cjs semantic-status --project=. --change=<name>
 node skywalk-sdd/log.cjs semantic-observe --project=. --change=<name>
 ```
 
+`propose/spec/design/task` 在文档写入完成时就必须同步工作态 JSON，不等待 Check 或 Archive。各阶段的 `stage_end` 会自动执行一次 reconcile 作为无 Hook 环境的兜底；Skill 中的显式 `semantic-reconcile` 与该兜底幂等。每份 Markdown 的结构化结果写入 `openspec/changes/<name>/artifacts/<原相对路径>.ontology.json`，`openspec/changes/<name>/artifact-index.json` 与 `working-ontology.json` 提供统一索引与全量工作态视图；这些文件随 change 目录一起提交和归档。`skywalk-sdd/state/ontology/` 仅保留 revision 指针与跨进程锁，默认不提交。
+
+工作态 JSON 使用 `kld-sdd-working-artifact-facts/v1`，明确标记 `canonical=false` 和 `review_status=draft|pending`。它用于当前 Change 的渐进式展开、定向查询和跨文档校验，不能直接入知识库。Check 重新解析原文、校验并在全部通过时生成 pending revision；Archive 再次对账后才确认、转换为 `canonical-facts.json` 并打包。
+
 `semantic-observe` 不是 Hook 替代品：它不能阻止 Cursor、Qoder 或人工编辑，也不能在落盘前控制内容。Observer 启动/重启后会重新对账，暂态失败和锁冲突不会推进文件指纹；Check 和 Archive 始终重新执行 `semantic-reconcile`，以处理重复、乱序或丢失的文件事件。
 
 校验 profile：
@@ -79,9 +83,17 @@ node skywalk-sdd/log.cjs semantic-observe --project=. --change=<name>
 | `full` | 强制 STMT→AC→Design→Task 全链和 Task DAG |
 | `strict` | 在 full 基础上要求完整语义来源 |
 
-同一 Change 的 observe/reconcile/check/archive 共用跨进程事务锁。工作态按 revision 目录一次性提交，再原子切换 `current.json`，读取时会拒绝 working/diagnostics/file-index 的 revision 撕裂。
+同一 Change 的作者阶段同步、observe、reconcile、check 和 archive 共用跨进程事务锁。`working-ontology.json`、diagnostics、file index、artifact index 及所有分文件 JSON 在 change 目录内原子提交，随后切换 `skywalk-sdd/state/ontology/<change>/current.json` 指针；读取时会拒绝任一文件缺失或 revision 撕裂。
+
+Archive 使用两阶段事务：先复制到 staging，从 staging 重新解析正文并生成本体快照、canonical facts、转换报告和 v2 manifest，所有步骤成功后才切换为正式 archive。归档完成后同时生成相邻的 `<日期>-<name>.zip`，其中 `archive-manifest.json` 的文件清单和 SHA-256 必须精确覆盖包内文件，可直接交给知识库消费。语义校验、快照、协议转换、打包或 Spec 同步失败时，活动 Change 会保留或恢复，不留下伪 confirmed 半成品。
+
+生产端归档协议产物：
 
-Archive 使用两阶段事务：先复制到 staging，从 staging 重新解析正文并生成 manifest、Spec 投影和带 UUIDv7 `OntologySnapshot` 实体的 `archive-ontology.json`，所有步骤成功后才切换为正式 archive。语义校验、快照、manifest 或 Spec 同步失败时，活动 Change 会保留或恢复，不留下伪 confirmed 半成品。
+- `archive-ontology.json`：KLD-SDD 内部 confirmed 本体快照。
+- `canonical-facts.json`：面向知识库的稳定语义事实，实体与关系均带原文来源及内容哈希。
+- `conversion-report.json`：本体快照到 canonical facts 的转换结果、数量和归一化告警。
+- `archive-manifest.json`：`kld-sdd-archive-manifest/v2` 身份、内容哈希及完整文件清单。
+- `openspec/changes/archive/<日期>-<name>.zip`：知识库可直接读取的 Archive Package。
 
 ## 快速开始
 
@@ -251,6 +263,21 @@ kld-sdd-init --tool codex       # 仅配置 Codex
 
 ```
 your-project/
+├── openspec/
+│   └── changes/
+│       └── <name>/
+│           ├── proposal.md
+│           ├── working-ontology.json
+│           ├── artifact-index.json
+│           ├── diagnostics.json
+│           ├── file-index.json
+│           ├── ontology-identities.json
+│           └── artifacts/
+│               ├── proposal.ontology.json
+│               └── specs/<capability>/
+│                   ├── spec.ontology.json
+│                   ├── design.ontology.json
+│                   └── tasks.ontology.json
 ├── openspec-templates/              # openSpec 四文档参考模版
 │   ├── proposal.md
 │   ├── spec.md
@@ -262,11 +289,7 @@ your-project/
 │   └── state/ontology/
 │       ├── .locks/<change>.lock     # observe/reconcile/check/archive 跨进程锁
 │       └── <change>/
-│           ├── current.json         # 当前 revision 原子指针
-│           └── revisions/<revision>/
-│               ├── working-ontology.json
-│               ├── diagnostics.json
-│               └── file-index.json
+│           └── current.json         # 当前 revision 指针（本体 JSON 在 change 目录）
 ├── .cursor/
 │   └── skills/opsx-*/               # SDD skills（扁平一层）
 ├── .claude/

package/lib/init.js

@@ -830,6 +830,15 @@ function deployTelemetryDataDir() {
     console.log(`   ⚠️  Telemetry CLI 源文件缺失: ${telemetrySrc}`);
   }
 
+  const contextClientSrc = path.join(pkgPath, 'skywalk-sdd', 'context-client.cjs');
+  const contextClientDst = path.join(dataDir, 'context-client.cjs');
+  if (fs.existsSync(contextClientSrc)) {
+    fs.copyFileSync(contextClientSrc, contextClientDst);
+    console.log('   ✓ 部署 skywalk-sdd/context-client.cjs（工程 Spec 上下文客户端）');
+  } else {
+    console.log(`   ⚠️  工程 Spec 上下文客户端缺失: ${contextClientSrc}`);
+  }
+
   const ontologySrc = path.join(pkgPath, 'skywalk-sdd', 'ontology');
   const ontologyDst = path.join(dataDir, 'ontology');
   if (fs.existsSync(ontologySrc)) {
@@ -847,6 +856,7 @@ function deployTelemetryDataDir() {
   }
 
   console.log('   ✓ 调用方式: node skywalk-sdd/log.cjs start|end|metrics|semantic-identity|semantic-reconcile|semantic-check');
+  console.log('   ✓ Spec Context: node skywalk-sdd/context-client.cjs --query="<自然语言需求>" --target-stage=spec');
   console.log('   ✓ Apply worktree: record-base 在 §1.5；收尾 apply-worktree-finish.cjs --change=<name>');
   console.log('✅ Telemetry 已就绪（数据存储在 skywalk-sdd/，无需配置 MCP）');
   return true;
@@ -971,7 +981,7 @@ function updateGitignore() {
 .workbuddy/commands/personal-*
 .agents/commands/personal-*
 
-# SDD Telemetry 数据（本地度量，可选提交；最终报告落 openspec/changes/<change>/reports/ 随 change 提交）
+# SDD Telemetry 数据（本地度量，可选提交；本体 JSON 与报告随 openspec/changes/<change>/ 提交）
 skywalk-sdd/events/
 skywalk-sdd/state/
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.5.2",
+  "version": "2.6.1",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
     "kld-sdd-init": "bin/kld-sdd-init.js"
   },
   "scripts": {
-    "test": "node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs"
+    "test": "node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs"
   },
   "keywords": [
     "kld",
@@ -32,6 +32,7 @@
     "templates/",
     "kld-sdd-guide.html",
     "skywalk-sdd/index.cjs",
+    "skywalk-sdd/context-client.cjs",
     "skywalk-sdd/ontology/",
     "skywalk-sdd/apply-worktree-finish.cjs",
     "README.md"

package/skywalk-sdd/context-client.cjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+function parseArgs(argv) {
+  const args = {};
+  for (const item of argv.slice(2)) {
+    if (!item.startsWith('--')) continue;
+    const equal = item.indexOf('=');
+    if (equal < 0) args[item.slice(2)] = true;
+    else args[item.slice(2, equal)] = item.slice(equal + 1);
+  }
+  return args;
+}
+
+function queryFromArgs(args) {
+  if (typeof args.query === 'string' && args.query.trim()) {
+    return args.query.trim();
+  }
+  if (typeof args['query-file'] === 'string' && args['query-file'].trim()) {
+    return fs.readFileSync(args['query-file'], 'utf8').trim();
+  }
+  throw new Error('missing --query or --query-file');
+}
+
+function buildEndpoint(apiBase, spaceId) {
+  const base = String(apiBase || 'http://localhost:8090/api').replace(/\/$/, '');
+  return `${base}/v1/spaces/${encodeURIComponent(spaceId)}/context/match-requirement`;
+}
+
+function requestJson(url, payload, token, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(url);
+    const transport = target.protocol === 'https:' ? https : http;
+    const body = JSON.stringify(payload);
+    const headers = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+    };
+    if (token) headers.Authorization = `Bearer ${token}`;
+
+    const request = transport.request(
+      {
+        hostname: target.hostname,
+        port: target.port || (target.protocol === 'https:' ? 443 : 80),
+        path: target.pathname + target.search,
+        method: 'POST',
+        headers,
+        timeout: timeoutMs,
+      },
+      (response) => {
+        let responseBody = '';
+        response.on('data', (chunk) => {
+          responseBody += chunk;
+        });
+        response.on('end', () => {
+          let parsed;
+          try {
+            parsed = responseBody ? JSON.parse(responseBody) : null;
+          } catch {
+            reject(new Error(`knowledge base returned invalid JSON (HTTP ${response.statusCode})`));
+            return;
+          }
+          if (response.statusCode >= 400 || parsed?.code !== 0) {
+            reject(new Error(parsed?.message || `knowledge base HTTP ${response.statusCode}`));
+            return;
+          }
+          resolve(parsed.data);
+        });
+      },
+    );
+    request.on('timeout', () => request.destroy(new Error(`knowledge base timeout after ${timeoutMs}ms`)));
+    request.on('error', reject);
+    request.write(body);
+    request.end();
+  });
+}
+
+function compactContext(data, includeCandidates) {
+  if (includeCandidates) return data;
+  return {
+    matchType: data.matchType,
+    inheritanceAllowed: data.inheritanceAllowed,
+    reviewRequired: data.reviewRequired,
+    advisory: data.advisory,
+    degraded: data.degraded,
+    degradationReasons: data.degradationReasons,
+    targetStage: data.targetStage,
+    reuseBundles: data.reuseBundles,
+    answeredQuestions: data.answeredQuestions,
+    warnings: data.warnings,
+    clarificationQuestions: data.clarificationQuestions,
+    specGenerationContext: data.specGenerationContext,
+  };
+}
+
+async function retrieveContext(args = parseArgs(process.argv), env = process.env) {
+  const query = queryFromArgs(args);
+  const spaceId = args['space-id'] || env.ENGINEERING_KB_SPACE_ID || '';
+  if (!spaceId) {
+    return {
+      available: false,
+      advisory: true,
+      degraded: true,
+      reason: 'engineering_kb_not_configured',
+      hint: 'set ENGINEERING_KB_SPACE_ID to enable reusable Spec context',
+    };
+  }
+
+  const apiBase = args['api-base'] || env.ENGINEERING_KB_API || 'http://localhost:8090/api';
+  const token = args.token || env.ENGINEERING_KB_TOKEN || '';
+  const timeoutMs = Number(args.timeout || env.ENGINEERING_KB_TIMEOUT_MS || 30000);
+  const data = await requestJson(
+    buildEndpoint(apiBase, spaceId),
+    {
+      query,
+      targetStage: args['target-stage'] || 'spec',
+    },
+    token,
+    timeoutMs,
+  );
+  return {
+    available: true,
+    ...compactContext(data, Boolean(args['include-candidates'])),
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  try {
+    console.log(JSON.stringify(await retrieveContext(args), null, 2));
+  } catch (error) {
+    console.log(JSON.stringify({
+      available: false,
+      advisory: true,
+      degraded: true,
+      reason: 'engineering_kb_unavailable',
+      message: error.message,
+    }, null, 2));
+    if (args.strict) process.exitCode = 1;
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  parseArgs,
+  queryFromArgs,
+  buildEndpoint,
+  requestJson,
+  compactContext,
+  retrieveContext,
+};

package/skywalk-sdd/index.cjs

@@ -600,7 +600,6 @@ function assertConfirmedArchive(projectRoot, changeName, archiveDir, options = {
 }
 
 function ensureArchiveManifest(projectRoot, changeName, archiveDir, options = {}) {
-  const manifestPath = path.join(archiveDir, 'archive-manifest.json');
   const copiedSpecs = Array.isArray(options.copiedSpecs)
     ? options.copiedSpecs
     : syncArchivedSpecs(projectRoot, archiveDir, changeName);
@@ -616,20 +615,24 @@ function ensureArchiveManifest(projectRoot, changeName, archiveDir, options = {}
       path.join(committedArchiveDir, 'evidence', 'events'),
     );
   }
-  const manifest = {
-    change: changeName,
-    archived_at: options.archivedAt || nowISO(),
+  const { materializeArchivePackage } = require('./ontology/archive-package.cjs');
+  const produced = materializeArchivePackage({
+    projectRoot,
+    changeName,
+    archiveDir,
+    archivePath: committedArchiveDir,
+    packagePath: Object.prototype.hasOwnProperty.call(options, 'packagePath')
+      ? options.packagePath
+      : `${committedArchiveDir}.zip`,
+    archivedAt: options.archivedAt,
     reason: options.reason || '变更已完成实施',
     method: options.method || 'skywalk-full-spec-archive',
-    source_path: `openspec/changes/${changeName}`,
-    archive_path: toProjectRelative(projectRoot, committedArchiveDir),
-    copied_specs: copiedSpecs,
-    evidence_events_path: evidenceEventsPath,
-  };
-  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+    sourcePath: `openspec/changes/${changeName}`,
+    copiedSpecs,
+    evidenceEventsPath,
+  });
   return {
-    manifest,
-    manifest_path: manifestPath,
+    ...produced,
     copied_specs: copiedSpecs,
   };
 }
@@ -674,18 +677,27 @@ function ensureArchiveSuccessArtifacts(projectRoot, changeName, details = {}, op
   const manifestInfo = ensureArchiveManifest(normalizedRoot, changeName, archiveDir, {
     reason: archiveReason,
     method: archiveMethod || 'skywalk-full-spec-archive',
-    archivedAt: details.archive_result?.archived_at || nowISO(),
+    archivedAt: details.archive_result?.created_at || details.archive_result?.archived_at,
   });
 
   const archiveResult = {
     reason: archiveReason,
     method: manifestInfo.manifest.method,
+    schema_version: manifestInfo.manifest.schema_version,
+    producer: manifestInfo.manifest.producer,
+    project_id: manifestInfo.manifest.project_id,
+    archive_id: manifestInfo.manifest.archive_id,
+    change_id: manifestInfo.manifest.change_id,
+    created_at: manifestInfo.manifest.created_at,
     archive_path: manifestInfo.manifest.archive_path,
     report_path: toProjectRelative(normalizedRoot, reportPath),
     // report_html_path 为预期路径：由 cmdEnd 落盘阶段写入（try/catch 容错，失败时不阻塞 md 主产物）。
     // 此处无条件派生，html 实际落盘失败时该路径可能不存在；语义为"预期路径"，消费者不应假定文件已存在。
     report_html_path: toProjectRelative(normalizedRoot, reportPath.replace(/\.md$/i, '.html')),
     manifest_path: toProjectRelative(normalizedRoot, manifestInfo.manifest_path),
+    canonical_facts_path: toProjectRelative(normalizedRoot, manifestInfo.canonical_facts_path),
+    conversion_report_path: toProjectRelative(normalizedRoot, manifestInfo.conversion_report_path),
+    package_path: toProjectRelative(normalizedRoot, manifestInfo.package_path),
     task_completion: taskCompletion,
     copied_specs: manifestInfo.copied_specs,
   };
@@ -724,10 +736,13 @@ function archiveChangeDocs(projectRoot, changeName, options = {}) {
   const lock = acquireChangeLock(normalizedRoot, changeName, options.lockOptions);
   const token = lock.token.replace(/-/g, '');
   const stagingDir = path.join(archiveRoot, `.archive-staging-${token}`);
+  const stagingPackagePath = `${stagingDir}.zip`;
+  const finalPackagePath = `${archiveDir}.zip`;
   const sourceBackup = path.join(path.dirname(sourceDir), `.archive-source-${token}`);
   let specTransaction = null;
   let sourceMoved = false;
   let archiveCommitted = false;
+  let packageCommitted = false;
   try {
     const semanticResult = ontologyRuntime.reconcileChange(normalizedRoot, changeName, {
       profile: options.profile || 'auto',
@@ -742,6 +757,7 @@ function archiveChangeDocs(projectRoot, changeName, options = {}) {
     }
 
     fs.rmSync(stagingDir, { recursive: true, force: true });
+    fs.rmSync(stagingPackagePath, { force: true });
     copyDirSync(sourceDir, stagingDir);
     if (options.failAt === 'after-copy') throw new Error('after-copy');
 
@@ -768,6 +784,7 @@ function archiveChangeDocs(projectRoot, changeName, options = {}) {
       reason: archiveReason,
       method: 'skywalk-full-spec-archive',
       archivePath: archiveDir,
+      packagePath: stagingPackagePath,
       copiedSpecs: specTransaction.copiedSpecs,
     });
     const confirmed = assertConfirmedArchive(normalizedRoot, changeName, stagingDir, {
@@ -800,6 +817,9 @@ function archiveChangeDocs(projectRoot, changeName, options = {}) {
     fs.renameSync(stagingDir, archiveDir);
     archiveCommitted = true;
     commitArchivedSpecSync(specTransaction, options.failAt);
+    fs.rmSync(finalPackagePath, { force: true });
+    fs.renameSync(stagingPackagePath, finalPackagePath);
+    packageCommitted = true;
     if (sourceMoved) fs.rmSync(sourceBackup, { recursive: true, force: true });
     cleanupArchivedSpecSync(specTransaction);
 
@@ -807,12 +827,18 @@ function archiveChangeDocs(projectRoot, changeName, options = {}) {
       ...manifestInfo.manifest,
       project_root: normalizedRoot,
       archive_path: archiveDir,
+      manifest_path: path.join(archiveDir, 'archive-manifest.json'),
+      canonical_facts_path: path.join(archiveDir, 'canonical-facts.json'),
+      conversion_report_path: path.join(archiveDir, 'conversion-report.json'),
+      package_path: finalPackagePath,
       active_change_exists: fs.existsSync(sourceDir),
     };
   } catch (error) {
     rollbackArchivedSpecSync(specTransaction);
     if (archiveCommitted) fs.rmSync(archiveDir, { recursive: true, force: true });
+    if (packageCommitted) fs.rmSync(finalPackagePath, { force: true });
     fs.rmSync(stagingDir, { recursive: true, force: true });
+    fs.rmSync(stagingPackagePath, { force: true });
     if (sourceMoved && fs.existsSync(sourceBackup) && !fs.existsSync(sourceDir)) {
       fs.renameSync(sourceBackup, sourceDir);
     }
@@ -3507,6 +3533,37 @@ function cmdStart(args) {
   console.log(JSON.stringify(output, null, 2));
 }
 
+const ONTOLOGY_AUTHORING_STAGES = new Set(['propose', 'spec', 'design', 'task', 'check']);
+
+function syncWorkingOntologyForStage(projectRoot, changeName, command, result) {
+  if (!ONTOLOGY_AUTHORING_STAGES.has(command) || result === 'failure') return null;
+  if (!changeName || changeName === 'general') return null;
+  const changeDir = getChangeDir(projectRoot, changeName);
+  if (!fs.existsSync(changeDir)) return null;
+  const reconciled = require('./ontology/runtime.cjs').reconcileChange(
+    projectRoot,
+    changeName,
+    {
+      profile: 'auto',
+      markPending: command === 'check',
+    },
+  );
+  return {
+    schema_version: reconciled.state.artifact_schema_version,
+    index_schema_version: reconciled.state.artifact_index_schema_version,
+    revision: reconciled.revision,
+    review_status: reconciled.state.review_status,
+    valid: reconciled.valid,
+    changed: Boolean(reconciled.changed),
+    working_ontology_path: toProjectRelative(projectRoot, reconciled.paths.working),
+    artifact_index_path: toProjectRelative(projectRoot, reconciled.paths.artifactIndex),
+    artifact_json_paths: reconciled.paths.artifactFacts.map((filePath) => (
+      toProjectRelative(projectRoot, filePath)
+    )),
+    diagnostics: reconciled.diagnostics,
+  };
+}
+
 /**
  * log end: 记录阶段结束
  */
@@ -3589,6 +3646,30 @@ function cmdEnd(args, options = {}) {
     fail(`details JSON 解析失败: ${err.message}`);
   }
 
+  let semanticState = null;
+  try {
+    semanticState = syncWorkingOntologyForStage(projectRoot, change, command, result);
+    if (semanticState) {
+      details = {
+        ...details,
+        semantic_state: semanticState,
+      };
+    }
+  } catch (error) {
+    if (ONTOLOGY_AUTHORING_STAGES.has(command) && result !== 'failure') {
+      result = 'partial';
+      summary = `${summary}（工作态本体 JSON 同步失败：${error.message}）`.trim();
+      semanticState = {
+        status: 'failed',
+        error: error.message,
+      };
+      details = {
+        ...details,
+        semantic_state: semanticState,
+      };
+    }
+  }
+
   const durationMs = startEvent
     ? new Date(timestamp).getTime() - new Date(startEvent.timestamp).getTime()
     : null;
@@ -3732,6 +3813,7 @@ function cmdEnd(args, options = {}) {
     duration_ms: durationMs,
     recorded_at: timestamp,
     report_output: resolvedReportOutput || undefined,
+    semantic_state: semanticState || undefined,
     message: `SDD ${event.command} 阶段结束（${result}，耗时 ${durationMs ? (durationMs / 1000).toFixed(1) + 's' : '未知'}）`,
   };
   if (!options.silent) {
@@ -4463,6 +4545,28 @@ function cmdArchiveDocs(args) {
       }, { silent: true });
     }
 
+    const archiveDir = path.resolve(result.archive_path);
+    const finalPackage = ensureArchiveManifest(projectRoot, changeName, archiveDir, {
+      reason: result.reason || args.reason || '',
+      method: result.method || 'skywalk-full-spec-archive',
+      archivePath: archiveDir,
+      archivedAt: result.created_at || result.archived_at,
+      copiedSpecs: result.copied_specs,
+    });
+    result = {
+      ...result,
+      schema_version: finalPackage.manifest.schema_version,
+      producer: finalPackage.manifest.producer,
+      project_id: finalPackage.manifest.project_id,
+      archive_id: finalPackage.manifest.archive_id,
+      change_id: finalPackage.manifest.change_id,
+      created_at: finalPackage.manifest.created_at,
+      manifest_path: finalPackage.manifest_path,
+      canonical_facts_path: finalPackage.canonical_facts_path,
+      conversion_report_path: finalPackage.conversion_report_path,
+      package_path: finalPackage.package_path,
+    };
+
     console.log(JSON.stringify({
       ...result,
       report_output: stageEnd ? stageEnd.report_output : reportOutput,
@@ -4582,7 +4686,7 @@ SDD Telemetry CLI - 流程度量采集工具
   tasks-status 扫描 Full/Simple 模式 tasks.md 勾选状态
   check-task 扫描变更目录 tasks.md 并勾选指定 task_id
   archive-docs 将 Simple/Full spec 变更真实移动到 openspec/changes/archive/，并可结束 archive 阶段生成报告
-  semantic-identity 生成或复用实体/版本 UUID；无需网络和中央 ID 服务
+  semantic-identity 生成或复用实体/版本 ID（8 位十六进制）；无需网络和中央 ID 服务
   semantic-scan 只读解析并校验当前 Change
   semantic-reconcile 全量对账文件与本地工作态本体实例
   semantic-check 全量对账并在通过时标记 pending