kld-sdd 2.5.0 → 2.5.2

package/skywalk-sdd/index.cjs

@@ -520,16 +520,101 @@ 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,
@@ -537,7 +622,7 @@ function ensureArchiveManifest(projectRoot, changeName, archiveDir, options = {}
     reason: options.reason || '变更已完成实施',
     method: options.method || 'skywalk-full-spec-archive',
     source_path: `openspec/changes/${changeName}`,
-    archive_path: toProjectRelative(projectRoot, archiveDir),
+    archive_path: toProjectRelative(projectRoot, committedArchiveDir),
     copied_specs: copiedSpecs,
     evidence_events_path: evidenceEventsPath,
   };
@@ -574,6 +659,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))
@@ -632,30 +719,110 @@ 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 sourceBackup = path.join(path.dirname(sourceDir), `.archive-source-${token}`);
+  let specTransaction = null;
+  let sourceMoved = false;
+  let archiveCommitted = 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 });
+    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,
+      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);
+    if (sourceMoved) fs.rmSync(sourceBackup, { recursive: true, force: true });
+    cleanupArchivedSpecSync(specTransaction);
+
+    return {
+      ...manifestInfo.manifest,
+      project_root: normalizedRoot,
+      archive_path: archiveDir,
+      active_change_exists: fs.existsSync(sourceDir),
+    };
+  } catch (error) {
+    rollbackArchivedSpecSync(specTransaction);
+    if (archiveCommitted) fs.rmSync(archiveDir, { recursive: true, force: true });
+    fs.rmSync(stagingDir, { recursive: true, 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 到事件文件（写入失败时抛出异常） */
@@ -4133,6 +4300,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 +4416,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, {
@@ -4257,6 +4525,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 +4564,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 +4582,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 +4626,12 @@ module.exports = {
   cmdDoctor,
   cmdTasksStatus,
   cmdArchiveDocs,
+  cmdSemanticIdentity,
+  cmdSemanticScan,
+  cmdSemanticReconcile,
+  cmdSemanticCheck,
+  cmdSemanticStatus,
+  cmdSemanticObserve,
   computeChangeMetrics,
   computeOverviewMetrics,
   computeCapabilityMetrics,

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

@@ -0,0 +1,91 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { safeChangeName, scanArtifactFiles } = require('./artifact-parser.cjs');
+const { reconcileChange } = require('./runtime.cjs');
+
+function fingerprint(changeDir) {
+  const files = scanArtifactFiles(changeDir).map((file) => ({
+    path: file.relativePath,
+    content_hash: file.contentHash,
+  }));
+  return crypto.createHash('sha256').update(JSON.stringify(files)).digest('hex');
+}
+
+function observeChangeArtifacts(projectRoot, changeName, options = {}) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const safeName = safeChangeName(changeName);
+  const changeDir = path.join(root, 'openspec', 'changes', safeName);
+  if (!fs.existsSync(changeDir)) {
+    throw new Error(`变更目录不存在: ${changeDir}`);
+  }
+
+  const pollIntervalMs = Math.max(25, Number(options.pollIntervalMs || 1500));
+  const debounceMs = Math.max(0, Number(options.debounceMs || 120));
+  // 启动/重启后先把当前文件集合视为待对账，避免停机期间的变化被当作已处理。
+  let lastFingerprint = '';
+  let debounceTimer = null;
+  let closed = false;
+  let watcher = null;
+
+  function reconcileIfChanged(force = false) {
+    if (closed) return null;
+    const nextFingerprint = fingerprint(changeDir);
+    if (!force && nextFingerprint === lastFingerprint) return null;
+    const result = reconcileChange(root, safeName, { profile: options.profile || 'auto' });
+    lastFingerprint = nextFingerprint;
+    if (typeof options.onReconciled === 'function') options.onReconciled(result);
+    return result;
+  }
+
+  function schedule() {
+    if (closed) return;
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      try {
+        reconcileIfChanged();
+      } catch (error) {
+        if (typeof options.onError === 'function') options.onError(error);
+      }
+    }, debounceMs);
+  }
+
+  try {
+    watcher = fs.watch(changeDir, { recursive: true }, schedule);
+    watcher.on('error', (error) => {
+      if (typeof options.onError === 'function') options.onError(error);
+    });
+  } catch (error) {
+    watcher = null;
+    if (typeof options.onError === 'function') options.onError(error);
+  }
+
+  const poller = setInterval(() => {
+    try {
+      reconcileIfChanged();
+    } catch (error) {
+      if (typeof options.onError === 'function') options.onError(error);
+    }
+  }, pollIntervalMs);
+
+  return {
+    mode: watcher ? 'fs-watch+poll-reconcile' : 'poll-reconcile',
+    changeDir,
+    reconcile: () => reconcileIfChanged(true),
+    close() {
+      if (closed) return;
+      closed = true;
+      if (debounceTimer) clearTimeout(debounceTimer);
+      clearInterval(poller);
+      if (watcher) watcher.close();
+    },
+  };
+}
+
+module.exports = {
+  fingerprint,
+  observeChangeArtifacts,
+};