kld-sdd 2.5.1 → 2.6.0

package/skywalk-sdd/index.cjs

@@ -520,31 +520,119 @@ function syncArchivedSpecs(projectRoot, archiveDir, changeName) {
   return copiedSpecs;
 }
 
+function prepareArchivedSpecSync(projectRoot, archiveDir, changeName, token) {
+  const operations = discoverFullSpecFiles(archiveDir, changeName).map((spec) => {
+    const target = path.join(projectRoot, 'openspec', 'specs', spec.capability, 'spec.md');
+    ensureDir(path.dirname(target));
+    const temp = `${target}.${token}.archive-tmp`;
+    const backup = `${target}.${token}.archive-bak`;
+    fs.copyFileSync(spec.source, temp);
+    if (fs.existsSync(target)) fs.copyFileSync(target, backup);
+    return {
+      capability: spec.capability,
+      source: spec.source,
+      target,
+      temp,
+      backup,
+      had_original: fs.existsSync(target),
+      committed: false,
+    };
+  });
+  return {
+    operations,
+    copiedSpecs: operations.map((operation) => ({
+      capability: operation.capability,
+      source: toProjectRelative(projectRoot, operation.source),
+      target: toProjectRelative(projectRoot, operation.target),
+    })),
+  };
+}
+
+function commitArchivedSpecSync(transaction, failAt = '') {
+  for (const operation of transaction.operations) {
+    if (fs.existsSync(operation.target)) fs.rmSync(operation.target, { force: true });
+    fs.renameSync(operation.temp, operation.target);
+    operation.committed = true;
+    if (failAt === 'during-spec-sync') throw new Error('during-spec-sync');
+  }
+}
+
+function rollbackArchivedSpecSync(transaction) {
+  if (!transaction || !transaction.operations) return;
+  for (const operation of [...transaction.operations].reverse()) {
+    if (fs.existsSync(operation.backup)) {
+      fs.rmSync(operation.target, { force: true });
+      fs.renameSync(operation.backup, operation.target);
+    } else if (operation.committed) {
+      fs.rmSync(operation.target, { force: true });
+    }
+    fs.rmSync(operation.temp, { force: true });
+    fs.rmSync(operation.backup, { force: true });
+  }
+}
+
+function cleanupArchivedSpecSync(transaction) {
+  if (!transaction || !transaction.operations) return;
+  for (const operation of transaction.operations) {
+    fs.rmSync(operation.temp, { force: true });
+    fs.rmSync(operation.backup, { force: true });
+  }
+}
+
+function assertConfirmedArchive(projectRoot, changeName, archiveDir, options = {}) {
+  const { parseChangeArtifacts } = require('./ontology/artifact-parser.cjs');
+  const { normalizeFacts } = require('./ontology/normalizer.cjs');
+  const { validateArchiveCandidate } = require('./ontology/identity-index.cjs');
+  const facts = normalizeFacts(parseChangeArtifacts(projectRoot, changeName, {
+    changeDir: archiveDir,
+    persistStructuralIdentities: false,
+  }));
+  const validation = validateArchiveCandidate({
+    change: path.basename(archiveDir),
+    changeDir: archiveDir,
+    expectedArchiveDir: options.expectedArchiveDir,
+  }, facts);
+  if (!validation.eligible) {
+    const codes = validation.diagnostics.map((item) => item.code).join(', ');
+    throw new Error(`Archive 未通过 confirmed 事实校验: ${codes}`);
+  }
+  return { facts, snapshot: validation.snapshot, manifest: validation.manifest };
+}
+
 function ensureArchiveManifest(projectRoot, changeName, archiveDir, options = {}) {
-  const manifestPath = path.join(archiveDir, 'archive-manifest.json');
-  const copiedSpecs = syncArchivedSpecs(projectRoot, archiveDir, changeName);
+  const copiedSpecs = Array.isArray(options.copiedSpecs)
+    ? options.copiedSpecs
+    : syncArchivedSpecs(projectRoot, archiveDir, changeName);
+  const committedArchiveDir = options.archivePath || archiveDir;
   // U4: 归档时拷 events jsonl 进 archive/evidence/events/，报告可从归档目录重建（源数据与产物不再分离）
   const eventsSrcDir = path.join(getDataDir(projectRoot), 'events', safeChangeName(changeName));
   let evidenceEventsPath = null;
   if (fs.existsSync(eventsSrcDir)) {
     const eventsDstDir = path.join(archiveDir, 'evidence', 'events');
     copyDirSync(eventsSrcDir, eventsDstDir);
-    evidenceEventsPath = toProjectRelative(projectRoot, eventsDstDir);
+    evidenceEventsPath = toProjectRelative(
+      projectRoot,
+      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, archiveDir),
-    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,
   };
 }
@@ -574,6 +662,8 @@ function ensureArchiveSuccessArtifacts(projectRoot, changeName, details = {}, op
     };
   }
 
+  assertConfirmedArchive(normalizedRoot, changeName, archiveDir);
+
   // 显式 reportOutput 优先；否则默认落归档后 archive 目录的 reports/ 子目录
   const reportPath = options.reportOutput
     ? (path.isAbsolute(options.reportOutput) ? options.reportOutput : path.resolve(normalizedRoot, options.reportOutput))
@@ -587,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,
   };
@@ -632,30 +731,124 @@ function archiveChangeDocs(projectRoot, changeName, options = {}) {
   ensureDir(archiveRoot);
   const archiveDate = options.date || today();
   const archiveDir = nextAvailableDir(archiveRoot, `${archiveDate}-${changeName}`);
+  const { acquireChangeLock, releaseChangeLock } = require('./ontology/change-lock.cjs');
+  const ontologyRuntime = require('./ontology/runtime.cjs');
+  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',
+      markPending: true,
+      lock,
+    });
+    if (!semanticResult.valid) {
+      const codes = [...new Set(semanticResult.diagnostics
+        .filter(item => item.severity === 'error')
+        .map(item => item.code))];
+      throw new Error(`本体语义校验失败: ${codes.join(', ')}`);
+    }
 
-  copyDirSync(sourceDir, archiveDir);
-  // P2-2: 根据 task_completion 调整归档原因，has_incomplete 时不写"已完成实施"
-  const tcForReason = scanTaskCompletionForArchiveDir(normalizedRoot, changeName, archiveDir);
-  let archiveReason = options.reason || '变更已完成实施';
-  if (tcForReason?.has_incomplete) {
-    archiveReason = `部分完成（${tcForReason.incomplete} 项验收未勾选）`;
-  }
-  const manifestInfo = ensureArchiveManifest(normalizedRoot, changeName, archiveDir, {
-    reason: archiveReason,
-    method: 'skywalk-full-spec-archive',
-  });
-  const manifest = manifestInfo.manifest;
+    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');
+
+    ontologyRuntime.createArchiveSnapshot(
+      normalizedRoot,
+      changeName,
+      stagingDir,
+      semanticResult.state,
+    );
+    if (options.failAt === 'after-snapshot') throw new Error('after-snapshot');
+
+    const tcForReason = scanTaskCompletionForArchiveDir(normalizedRoot, changeName, stagingDir);
+    let archiveReason = options.reason || '变更已完成实施';
+    if (tcForReason?.has_incomplete) {
+      archiveReason = `部分完成（${tcForReason.incomplete} 项验收未勾选）`;
+    }
+    specTransaction = prepareArchivedSpecSync(
+      normalizedRoot,
+      stagingDir,
+      changeName,
+      token,
+    );
+    const manifestInfo = ensureArchiveManifest(normalizedRoot, changeName, stagingDir, {
+      reason: archiveReason,
+      method: 'skywalk-full-spec-archive',
+      archivePath: archiveDir,
+      packagePath: stagingPackagePath,
+      copiedSpecs: specTransaction.copiedSpecs,
+    });
+    const confirmed = assertConfirmedArchive(normalizedRoot, changeName, stagingDir, {
+      expectedArchiveDir: archiveDir,
+    });
+    if (confirmed.snapshot.source_revision !== semanticResult.revision) {
+      throw new Error('confirmed snapshot 的 source_revision 与工作态 revision 不一致');
+    }
+    if (options.failAt === 'after-manifest') throw new Error('after-manifest');
+    if (typeof options._testBeforeFinalize === 'function') {
+      options._testBeforeFinalize({ sourceDir, stagingDir, archiveDir });
+    }
 
-  if (!options.keepActive) {
-    fs.rmSync(sourceDir, { recursive: true, force: true });
-  }
+    const activeFacts = require('./ontology/normalizer.cjs').normalizeFacts(
+      require('./ontology/artifact-parser.cjs').parseChangeArtifacts(
+        normalizedRoot,
+        changeName,
+        { changeDir: sourceDir, persistStructuralIdentities: false },
+      ),
+    );
+    if (activeFacts.facts_hash !== semanticResult.state.facts_hash) {
+      throw new Error('活动 Change 在归档事务期间发生变化');
+    }
 
-  return {
-    ...manifest,
-    project_root: normalizedRoot,
-    archive_path: archiveDir,
-    active_change_exists: fs.existsSync(sourceDir),
-  };
+    if (!options.keepActive) {
+      fs.renameSync(sourceDir, sourceBackup);
+      sourceMoved = true;
+    }
+    if (options.failAt === 'after-source-move') throw new Error('after-source-move');
+    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);
+
+    return {
+      ...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);
+    }
+    const wrapped = new Error(`归档事务失败，活动 Change 保持不变: ${error.message}`);
+    wrapped.code = error.code || 'SEM_ARCHIVE_TRANSACTION_FAILED';
+    wrapped.cause = error;
+    throw wrapped;
+  } finally {
+    releaseChangeLock(lock);
+  }
 }
 
 /** 追加一行 JSONL 到事件文件（写入失败时抛出异常） */
@@ -3340,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: 记录阶段结束
  */
@@ -3422,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;
@@ -3565,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) {
@@ -4133,6 +4382,106 @@ function cmdTasksStatus(args) {
   }
 }
 
+function semanticCommandContext(args) {
+  const projectRoot = normalizeProjectRoot(args.project || args['project-root'] || process.cwd());
+  const changeName = args.change || args['change-name'];
+  if (!changeName) {
+    throw new Error('缺少 --change 参数');
+  }
+  return {
+    projectRoot,
+    changeName,
+    profile: args.profile || 'auto',
+  };
+}
+
+function cmdSemanticIdentity(args) {
+  const identity = require('./ontology/id.cjs').allocateIdentity(args);
+  console.log(JSON.stringify(identity, null, 2));
+  return identity;
+}
+
+function semanticResultPayload(result) {
+  return {
+    change: result.state.change,
+    profile: result.profile,
+    valid: result.valid,
+    review_status: result.state.review_status,
+    revision: result.revision,
+    changed: Boolean(result.changed),
+    counts: result.counts,
+    paths: result.paths,
+    diagnostics: result.diagnostics,
+  };
+}
+
+function cmdSemanticScan(args) {
+  const context = semanticCommandContext(args);
+  const result = require('./ontology/runtime.cjs').scanChange(
+    context.projectRoot,
+    context.changeName,
+    { profile: context.profile },
+  );
+  console.log(JSON.stringify(semanticResultPayload({ ...result, changed: false, paths: undefined }), null, 2));
+  if (!result.valid) process.exitCode = 1;
+  return result;
+}
+
+function cmdSemanticReconcile(args, options = {}) {
+  const context = semanticCommandContext(args);
+  const result = require('./ontology/runtime.cjs').reconcileChange(
+    context.projectRoot,
+    context.changeName,
+    { profile: context.profile, markPending: Boolean(options.markPending) },
+  );
+  console.log(JSON.stringify(semanticResultPayload(result), null, 2));
+  if (!result.valid) process.exitCode = 1;
+  return result;
+}
+
+function cmdSemanticCheck(args) {
+  return cmdSemanticReconcile(args, { markPending: true });
+}
+
+function cmdSemanticStatus(args) {
+  const context = semanticCommandContext(args);
+  const state = require('./ontology/runtime.cjs').readWorkingState(context.projectRoot, context.changeName);
+  if (!state) throw new Error(`不存在工作态本体实例: ${context.changeName}`);
+  console.log(JSON.stringify(state, null, 2));
+  return state;
+}
+
+function cmdSemanticObserve(args) {
+  const context = semanticCommandContext(args);
+  const observer = require('./ontology/artifact-observer.cjs').observeChangeArtifacts(
+    context.projectRoot,
+    context.changeName,
+    {
+      profile: context.profile,
+      pollIntervalMs: Number(args.interval || 1500),
+      onReconciled(result) {
+        console.log(JSON.stringify(semanticResultPayload(result)));
+      },
+      onError(error) {
+        console.error(`[ontology-observer] ${error.message}`);
+      },
+    },
+  );
+  console.log(JSON.stringify({
+    change: context.changeName,
+    mode: observer.mode,
+    change_dir: observer.changeDir,
+    boundary: 'observe-and-reconcile-only',
+  }));
+  const close = () => {
+    observer.close();
+    process.exit(0);
+  };
+  process.once('SIGINT', close);
+  process.once('SIGTERM', close);
+  return observer;
+}
+
 /**
  * log archive-docs: 真实归档 Simple/Full spec，结束 archive 阶段并生成最终报告
  */
@@ -4149,6 +4498,7 @@ function cmdArchiveDocs(args) {
         reason: args.reason || '',
         date: args.date,
         keepActive: Boolean(args['keep-active']),
+        profile: args.profile || 'auto',
       });
     } else {
       const repaired = ensureArchiveSuccessArtifacts(projectRoot, changeName, {
@@ -4195,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,
@@ -4257,6 +4629,24 @@ function main() {
     case 'archive-docs':
       cmdArchiveDocs(flags);
       break;
+    case 'semantic-scan':
+      cmdSemanticScan(flags);
+      break;
+    case 'semantic-identity':
+      cmdSemanticIdentity(flags);
+      break;
+    case 'semantic-reconcile':
+      cmdSemanticReconcile(flags);
+      break;
+    case 'semantic-check':
+      cmdSemanticCheck(flags);
+      break;
+    case 'semantic-status':
+      cmdSemanticStatus(flags);
+      break;
+    case 'semantic-observe':
+      cmdSemanticObserve(flags);
+      break;
     case 'check-task':
       cmdCheckTask(flags);
       break;
@@ -4278,6 +4668,13 @@ SDD Telemetry CLI - 流程度量采集工具
   node skywalk-sdd/log.cjs tasks-status --project=<path> --change=<name> [--require-complete]
   node skywalk-sdd/log.cjs check-task --project=<path> --change=<name> --task-id=<id>
   node skywalk-sdd/log.cjs archive-docs --project=<path> --change=<name> [--reason=<text>] [--event-id=<id>] [--report-output=<file>]
+  node skywalk-sdd/log.cjs semantic-identity --delta-state=added
+  node skywalk-sdd/log.cjs semantic-identity --delta-state=modified --entity-id=<uuid> --predecessor-version=<uuid>
+  node skywalk-sdd/log.cjs semantic-identity --delta-state=unchanged --entity-id=<uuid> --version-id=<uuid>
+  node skywalk-sdd/log.cjs semantic-reconcile --project=<path> --change=<name> [--profile=auto|simple|full|strict]
+  node skywalk-sdd/log.cjs semantic-check --project=<path> --change=<name> [--profile=...]
+  node skywalk-sdd/log.cjs semantic-status --project=<path> --change=<name>
+  node skywalk-sdd/log.cjs semantic-observe --project=<path> --change=<name> [--interval=1500]
 
 子命令:
   start    记录 SDD 阶段开始，返回 event_id
@@ -4289,6 +4686,12 @@ 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-scan 只读解析并校验当前 Change
+  semantic-reconcile 全量对账文件与本地工作态本体实例
+  semantic-check 全量对账并在通过时标记 pending
+  semantic-status 读取当前工作态本体实例
+  semantic-observe 观察文件变化并同步；不提供 Hook 式控制，Check/Archive 仍会全量对账
 
 示例:
   node skywalk-sdd/log.cjs start --command=propose --project=/my/project --change=user-auth --agent=cursor
@@ -4327,6 +4730,12 @@ module.exports = {
   cmdDoctor,
   cmdTasksStatus,
   cmdArchiveDocs,
+  cmdSemanticIdentity,
+  cmdSemanticScan,
+  cmdSemanticReconcile,
+  cmdSemanticCheck,
+  cmdSemanticStatus,
+  cmdSemanticObserve,
   computeChangeMetrics,
   computeOverviewMetrics,
   computeCapabilityMetrics,