kld-sdd 2.6.12 → 2.6.14

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

@@ -4,9 +4,11 @@ const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const { generateUuidV7 } = require('./id.cjs');
+const { resolveRuntimeMetadata } = require('../runtime-metadata.cjs');
 
-const PRODUCER_VERSION = require('../../package.json').version;
-const PRODUCER = `kld-sdd@${PRODUCER_VERSION}`;
+const RUNTIME_METADATA = resolveRuntimeMetadata();
+const PRODUCER_VERSION = RUNTIME_METADATA.version;
+const PRODUCER = RUNTIME_METADATA.producer;
 const MANIFEST_SCHEMA_VERSION = 'kld-sdd-archive-manifest/v2';
 const CANONICAL_FACTS_SCHEMA_VERSION = 'kld-sdd-canonical-facts/v2';
 const CONVERSION_REPORT_SCHEMA_VERSION = 'kld-sdd-conversion-report/v1';
@@ -15,7 +17,7 @@ const MANIFEST_PATH = 'archive-manifest.json';
 const ONTOLOGY_PATH = 'archive-ontology.json';
 const CANONICAL_FACTS_PATH = 'canonical-facts.json';
 const CONVERSION_REPORT_PATH = 'conversion-report.json';
-const PACKAGE_SUFFIXES = new Set(['.md', '.json', '.jsonl', '.yaml', '.yml']);
+const PACKAGE_SUFFIXES = new Set(['.md', '.html', '.json', '.jsonl', '.yaml', '.yml']);
 
 function sha256(content) {
   return crypto.createHash('sha256').update(content).digest('hex');
@@ -63,10 +65,16 @@ function ensureProjectIdentity(projectRoot) {
     }
     return existing;
   }
+  // 兜底：project-identity.json 未通过 opsx-ontology-query 配置 KB 时创建
+  // 此时 project_id 为随机值，KB 入库时会因 project_id !== spaceKey 而失败
+  console.warn('⚠️  project-identity.json 不存在 — 未通过 opsx-ontology-query 配置 KB。');
+  console.warn('⚠️  将生成临时 project_id，KB 入库时需确保与 Space spaceKey 一致。');
+  console.warn('⚠️  建议在首次使用 opsx-ontology-query 配置 KB 时自动创建正确的 project-identity.json。');
   const identity = {
     schema_version: PROJECT_IDENTITY_SCHEMA_VERSION,
     project_id: `urn:kld:sdd:project:${generateUuidV7()}`,
     created_at: new Date().toISOString(),
+    _warning: 'UNCONFIGURED — 请通过 opsx-ontology-query 配置 KB 后更新 project_id 为 Space spaceKey',
   };
   writeJson(identityPath, identity);
   return identity;
@@ -495,6 +503,77 @@ function writeArchiveZip(archiveDir, packagePath, manifest) {
   return packagePath;
 }
 
+function readStoredZipEntries(packagePath) {
+  const bytes = fs.readFileSync(packagePath);
+  const entries = new Map();
+  let offset = 0;
+  while (offset + 4 <= bytes.length && bytes.readUInt32LE(offset) === 0x04034b50) {
+    if (offset + 30 > bytes.length) {
+      throw new Error('Archive Package ZIP local header 不完整');
+    }
+    const flags = bytes.readUInt16LE(offset + 6);
+    const method = bytes.readUInt16LE(offset + 8);
+    const checksum = bytes.readUInt32LE(offset + 14);
+    const compressedSize = bytes.readUInt32LE(offset + 18);
+    const uncompressedSize = bytes.readUInt32LE(offset + 22);
+    const nameLength = bytes.readUInt16LE(offset + 26);
+    const extraLength = bytes.readUInt16LE(offset + 28);
+    const nameStart = offset + 30;
+    const contentStart = nameStart + nameLength + extraLength;
+    const contentEnd = contentStart + compressedSize;
+    if ((flags & 0x0800) !== 0x0800 || method !== 0 || contentEnd > bytes.length) {
+      throw new Error('Archive Package ZIP 只允许完整的 UTF-8 stored entry');
+    }
+    const name = bytes.subarray(nameStart, nameStart + nameLength).toString('utf8');
+    const safeName = safePackagePath(name);
+    if (entries.has(safeName)) {
+      throw new Error(`Archive Package ZIP 包含重复路径: ${safeName}`);
+    }
+    const content = bytes.subarray(contentStart, contentEnd);
+    if (compressedSize !== uncompressedSize || crc32(content) !== checksum) {
+      throw new Error(`Archive Package ZIP entry 校验失败: ${safeName}`);
+    }
+    entries.set(safeName, content);
+    offset = contentEnd;
+  }
+  if (entries.size === 0 || offset + 4 > bytes.length || bytes.readUInt32LE(offset) !== 0x02014b50) {
+    throw new Error('Archive Package ZIP 缺少 central directory');
+  }
+  return entries;
+}
+
+function verifyArchivePackage(archiveDir, packagePath, manifest) {
+  const expectedPaths = [MANIFEST_PATH, ...(manifest.files || []).map((item) => safePackagePath(item.path))];
+  const expectedUnique = new Set(expectedPaths);
+  if (expectedUnique.size !== expectedPaths.length) {
+    throw new Error('Archive Package Manifest 包含重复路径');
+  }
+  const entries = readStoredZipEntries(packagePath);
+  const actualPaths = [...entries.keys()];
+  if (
+    actualPaths.length !== expectedPaths.length
+    || expectedPaths.some((entryPath) => !entries.has(entryPath))
+  ) {
+    throw new Error('Archive Package ZIP 与 Manifest 文件清单不一致');
+  }
+  const manifestBytes = fs.readFileSync(path.join(archiveDir, MANIFEST_PATH));
+  if (!entries.get(MANIFEST_PATH)?.equals(manifestBytes)) {
+    throw new Error('Archive Package ZIP 中的 Manifest 不是最终落盘版本');
+  }
+  for (const item of manifest.files || []) {
+    const content = entries.get(item.path);
+    const expectedHash = `sha256:${sha256(content)}`;
+    if (item.content_hash !== expectedHash) {
+      throw new Error(`Archive Package 内容哈希不一致: ${item.path}`);
+    }
+  }
+  return {
+    entry_count: entries.size,
+    package_hash: `sha256:${sha256(fs.readFileSync(packagePath))}`,
+    paths: actualPaths,
+  };
+}
+
 function materializeArchivePackage(options = {}) {
   const projectRoot = path.resolve(options.projectRoot || process.cwd());
   const archiveDir = path.resolve(requiredText(options.archiveDir, 'archiveDir', 'Archive Package'));
@@ -588,6 +667,41 @@ function materializeArchivePackage(options = {}) {
   };
 }
 
+function finalizeArchivePackageAfterReports(options = {}) {
+  const projectRoot = path.resolve(options.projectRoot || process.cwd());
+  const changeName = requiredText(options.changeName, 'changeName', 'Archive finalizer');
+  const runIdentity = requiredText(options.runIdentity, 'runIdentity', 'Archive finalizer');
+  const { withChangeLock } = require('./change-lock.cjs');
+  return withChangeLock(projectRoot, changeName, options.lockOptions || {}, (lock) => {
+    const prepared = typeof options.prepare === 'function'
+      ? options.prepare(lock)
+      : {};
+    const produced = materializeArchivePackage({
+      ...options,
+      ...prepared,
+      projectRoot,
+      changeName,
+    });
+    if (!produced.package_path) {
+      throw new Error('Archive finalizer 必须生成 ZIP');
+    }
+    const verification = verifyArchivePackage(
+      path.resolve(prepared.archiveDir || options.archiveDir),
+      produced.package_path,
+      produced.manifest,
+    );
+    return {
+      ...produced,
+      finalizer: {
+        run_identity: runIdentity,
+        lock_token: lock.token,
+        verified: true,
+        ...verification,
+      },
+    };
+  });
+}
+
 module.exports = {
   PRODUCER_VERSION,
   PRODUCER,
@@ -605,5 +719,8 @@ module.exports = {
   buildCanonicalFacts,
   collectPackageFilePaths,
   writeArchiveZip,
+  readStoredZipEntries,
+  verifyArchivePackage,
   materializeArchivePackage,
+  finalizeArchivePackageAfterReports,
 };

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

@@ -5,6 +5,10 @@ const path = require('path');
 const { parseChangeArtifacts } = require('./artifact-parser.cjs');
 const { normalizeFacts } = require('./normalizer.cjs');
 const { DIAGNOSTIC_CODES } = require('./schema.cjs');
+const {
+  ONTOLOGY_STATE_FILES,
+  resolveOntologyStateFile,
+} = require('./ontology-paths.cjs');
 
 function catalogDiagnostic(code, message, context = {}) {
   return {
@@ -97,11 +101,14 @@ function validateArchiveCandidate(candidate, facts) {
     return { eligible: false, snapshot, manifest, diagnostics };
   }
 
-  const artifactIndexPath = path.join(candidate.changeDir, 'artifact-index.json');
+  const artifactIndexPath = resolveOntologyStateFile(
+    candidate.changeDir,
+    ONTOLOGY_STATE_FILES.artifactIndex,
+  );
   if (!fs.existsSync(artifactIndexPath)) {
     diagnostics.push(catalogDiagnostic(
       DIAGNOSTIC_CODES.ARCHIVE_NOT_CONFIRMED,
-      `Archive 缺少 change 目录下的 artifact-index.json: ${candidate.change}`,
+      `Archive 缺少 change 目录下的 ontology/artifact-index.json: ${candidate.change}`,
       { file: artifactIndexPath, suggestion: '通过 KLD-SDD reconcile/archive 在 change 目录生成工作态 JSON 后再归档' },
     ));
     return { eligible: false, snapshot, manifest, diagnostics };

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

@@ -0,0 +1,73 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ONTOLOGY_STATE_DIR = 'ontology';
+
+const ONTOLOGY_STATE_FILES = {
+  working: 'working-ontology.json',
+  diagnostics: 'diagnostics.json',
+  fileIndex: 'file-index.json',
+  artifactIndex: 'artifact-index.json',
+  identities: 'ontology-identities.json',
+  continuityResolution: 'continuity-resolution.json',
+};
+
+function ontologyStateRelative(basename) {
+  return `${ONTOLOGY_STATE_DIR}/${basename}`;
+}
+
+function changeOntologyFilePaths(changeDir) {
+  const resolved = path.resolve(changeDir);
+  const ontologyDir = path.join(resolved, ONTOLOGY_STATE_DIR);
+  return {
+    changeDir: resolved,
+    ontologyDir,
+    working: path.join(ontologyDir, ONTOLOGY_STATE_FILES.working),
+    diagnostics: path.join(ontologyDir, ONTOLOGY_STATE_FILES.diagnostics),
+    fileIndex: path.join(ontologyDir, ONTOLOGY_STATE_FILES.fileIndex),
+    artifactIndex: path.join(ontologyDir, ONTOLOGY_STATE_FILES.artifactIndex),
+    continuityResolution: path.join(ontologyDir, ONTOLOGY_STATE_FILES.continuityResolution),
+    identities: path.join(ontologyDir, ONTOLOGY_STATE_FILES.identities),
+    artifactDir: path.join(resolved, 'artifacts'),
+  };
+}
+
+function resolveOntologyStateFile(changeDir, basename) {
+  const resolved = path.resolve(changeDir);
+  const modern = path.join(resolved, ONTOLOGY_STATE_DIR, basename);
+  if (fs.existsSync(modern)) return modern;
+  const legacy = path.join(resolved, basename);
+  if (fs.existsSync(legacy)) return legacy;
+  return modern;
+}
+
+function resolveRevisionBundlePaths(changeDir) {
+  const preferred = changeOntologyFilePaths(changeDir);
+  return {
+    ...preferred,
+    working: resolveOntologyStateFile(changeDir, ONTOLOGY_STATE_FILES.working),
+    diagnostics: resolveOntologyStateFile(changeDir, ONTOLOGY_STATE_FILES.diagnostics),
+    fileIndex: resolveOntologyStateFile(changeDir, ONTOLOGY_STATE_FILES.fileIndex),
+    artifactIndex: resolveOntologyStateFile(changeDir, ONTOLOGY_STATE_FILES.artifactIndex),
+  };
+}
+
+function removeLegacyOntologyStateFiles(changeDir) {
+  const resolved = path.resolve(changeDir);
+  for (const basename of Object.values(ONTOLOGY_STATE_FILES)) {
+    const legacy = path.join(resolved, basename);
+    if (fs.existsSync(legacy)) fs.rmSync(legacy, { force: true });
+  }
+}
+
+module.exports = {
+  ONTOLOGY_STATE_DIR,
+  ONTOLOGY_STATE_FILES,
+  ontologyStateRelative,
+  changeOntologyFilePaths,
+  resolveOntologyStateFile,
+  resolveRevisionBundlePaths,
+  removeLegacyOntologyStateFiles,
+};

package/skywalk-sdd/ontology/resolve-spec-root.cjs

@@ -5,98 +5,38 @@ const path = require('path');
 const sddConfig = require('./sdd-config.cjs');
 const workspaceLayout = require('./workspace-layout.cjs');
 
-function isSpecPackageRoot(dir) {
-  const root = path.resolve(dir);
-  return (
-    fs.existsSync(path.join(root, 'openspec', 'changes'))
-    || fs.existsSync(path.join(root, 'modules.yaml'))
-    || fs.existsSync(path.join(root, 'sdd.config.yaml'))
-  );
+function resolveHint(anchorRoot) {
+  const hintPath = path.join(anchorRoot, '.sdd-spec-root');
+  if (!fs.existsSync(hintPath)) return null;
+  const hint = fs.readFileSync(hintPath, 'utf8').trim();
+  if (!hint) return null;
+  const resolved = path.resolve(anchorRoot, hint);
+  return fs.existsSync(resolved) ? resolved : null;
 }
 
-/**
- * 解析 SDD 文档根（*-sdd-specs 包裹包或旧平铺 spec 根）。
- * openspec CLI 只认 cwd 下的 openspec/；本函数供 log.cjs / ontology cli 自动定位包裹包。
- *
- * 解析顺序：
- * 1. start 本身已是 spec 包根
- * 2. KLD_SDD_SPEC_ROOT（绝对或相对 start）
- * 3. 单仓 layout: mono → spec_path / 子目录 *-sdd-specs
- * 4. 工作区 layout → specRepo
- * 5. start 下嵌套包裹包
- * 6. 代码仓 git config sdd.specPath（含仓内 nested 包裹）
- * 7. 向上最多 3 层找 mono / 嵌套包（Git 根、工作区根常见）
- * 8. 回退 start
- */
-function resolveSpecProjectRoot(startDir = process.cwd(), options = {}) {
-  const start = path.resolve(startDir || process.cwd());
-  if (options.skipResolve || options.forCodeRepo) return start;
-  if (isSpecPackageRoot(start)) return start;
+function resolveSpecProjectRoot(projectRoot = process.cwd()) {
+  const root = path.resolve(projectRoot);
+  const hinted = resolveHint(root);
+  if (hinted) return hinted;
 
-  const envRoot = process.env.KLD_SDD_SPEC_ROOT && String(process.env.KLD_SDD_SPEC_ROOT).trim();
-  if (envRoot) {
-    const candidate = path.isAbsolute(envRoot) ? envRoot : path.resolve(start, envRoot);
-    if (fs.existsSync(candidate)) return candidate;
+  if (sddConfig.isMonoLayout(root)) {
+    return sddConfig.resolveMonoSpecRoot(root);
   }
 
-  if (sddConfig.isMonoLayout(start)) {
-    const monoRoot = sddConfig.resolveMonoSpecRoot(start);
-    if (fs.existsSync(monoRoot)) return monoRoot;
-  }
-
-  const layout = workspaceLayout.detectWorkspaceLayout(start);
-  if (layout.specRepo && fs.existsSync(layout.specRepo.abs)) {
-    return layout.specRepo.abs;
-  }
+  const layout = workspaceLayout.detectWorkspaceLayout(root);
+  if (layout.specRepo) return layout.specRepo.abs;
 
-  const nested = workspaceLayout.findNestedSpecPackage(start);
+  const nested = workspaceLayout.findNestedSpecPackage(root);
   if (nested) return nested.abs;
 
-  const specPathResult = sddConfig.resolveSpecPath(start);
-  if (specPathResult.ok) {
-    const valid = sddConfig.validateSpecPath(specPathResult.path, { allowNestedPackage: true });
-    if (valid.ok) return valid.path;
-  }
-
-  let dir = start;
-  for (let depth = 0; depth < 3; depth += 1) {
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    if (sddConfig.isMonoLayout(parent)) {
-      const monoRoot = sddConfig.resolveMonoSpecRoot(parent);
-      if (fs.existsSync(monoRoot)) return monoRoot;
-    }
-    const parentNested = workspaceLayout.findNestedSpecPackage(parent);
-    if (parentNested) return parentNested.abs;
-    const parentLayout = workspaceLayout.detectWorkspaceLayout(parent);
-    if (parentLayout.specRepo && fs.existsSync(parentLayout.specRepo.abs)) {
-      return parentLayout.specRepo.abs;
-    }
-    dir = parent;
-  }
-
-  return start;
+  return root;
 }
 
-/**
- * CLI / skills 用：解析 --project 参数。
- * '.' 或未显式绝对 spec 根时走 resolve；link-spec 等代码仓命令传 forCodeRepo:true。
- */
-function resolveProjectArg(projectArg, startDir = process.cwd(), options = {}) {
-  const raw = projectArg == null || projectArg === '' ? '.' : String(projectArg);
-  const resolved = path.resolve(startDir, raw);
-  if (options.forCodeRepo) return resolved;
-  if (raw !== '.' && raw !== './' && path.isAbsolute(raw)) {
-    return isSpecPackageRoot(resolved) ? resolved : resolveSpecProjectRoot(resolved, options);
-  }
-  if (raw !== '.' && raw !== './') {
-    if (isSpecPackageRoot(resolved)) return resolved;
-  }
-  return resolveSpecProjectRoot(startDir, options);
+function resolveProjectArg(projectArg = '.', cwd = process.cwd()) {
+  return resolveSpecProjectRoot(path.resolve(cwd, projectArg));
 }
 
 module.exports = {
-  isSpecPackageRoot,
-  resolveSpecProjectRoot,
   resolveProjectArg,
+  resolveSpecProjectRoot,
 };

package/skywalk-sdd/ontology/runtime.cjs

@@ -20,6 +20,14 @@ const {
   assertChangeLock,
   releaseChangeLock,
 } = require('./change-lock.cjs');
+const {
+  ONTOLOGY_STATE_FILES,
+  ontologyStateRelative,
+  changeOntologyFilePaths,
+  resolveOntologyStateFile,
+  resolveRevisionBundlePaths,
+  removeLegacyOntologyStateFiles,
+} = require('./ontology-paths.cjs');
 
 function sha256(value) {
   return crypto.createHash('sha256').update(value).digest('hex');
@@ -31,15 +39,7 @@ function resolveChangeDir(projectRoot, changeName) {
 }
 
 function changeOntologyPaths(projectRoot, changeName) {
-  const changeDir = resolveChangeDir(projectRoot, changeName);
-  return {
-    changeDir,
-    working: path.join(changeDir, 'working-ontology.json'),
-    diagnostics: path.join(changeDir, 'diagnostics.json'),
-    fileIndex: path.join(changeDir, 'file-index.json'),
-    artifactIndex: path.join(changeDir, 'artifact-index.json'),
-    artifactDir: path.join(changeDir, 'artifacts'),
-  };
+  return changeOntologyFilePaths(resolveChangeDir(projectRoot, changeName));
 }
 
 function statePaths(projectRoot, changeName) {
@@ -160,14 +160,16 @@ function commitRevision(projectRoot, changeName, result, lock) {
   assertChangeLock(lock);
   const basePaths = statePaths(projectRoot, changeName);
   const paths = changeOntologyPaths(projectRoot, changeName);
+  const readablePaths = resolveRevisionBundlePaths(paths.changeDir);
   fs.mkdirSync(basePaths.dir, { recursive: true });
   fs.mkdirSync(paths.changeDir, { recursive: true });
+  fs.mkdirSync(paths.ontologyDir, { recursive: true });
 
-  if (fs.existsSync(paths.working)) {
-    const existing = readJson(paths.working, 'SEM_STATE_CORRUPT');
+  if (fs.existsSync(readablePaths.working)) {
+    const existing = readJson(readablePaths.working, 'SEM_STATE_CORRUPT');
     if (existing.revision === result.revision) {
-      readRevisionBundle(paths, result.revision);
-      const artifactIndex = readJson(paths.artifactIndex, 'SEM_STATE_CORRUPT');
+      readRevisionBundle(readablePaths, result.revision);
+      const artifactIndex = readJson(readablePaths.artifactIndex, 'SEM_STATE_CORRUPT');
       return {
         changed: false,
         paths: {
@@ -225,6 +227,7 @@ function commitRevision(projectRoot, changeName, result, lock) {
     atomicWriteIfChanged(path.join(paths.changeDir, artifactFile.path), fs.readFileSync(stagedPath, 'utf8'));
   }
   pruneStaleArtifacts(paths.changeDir, artifactBundle.index);
+  removeLegacyOntologyStateFiles(paths.changeDir);
   fs.rmSync(stagingDir, { recursive: true, force: true });
 
   const pointer = {
@@ -232,7 +235,7 @@ function commitRevision(projectRoot, changeName, result, lock) {
     change: safeChangeName(changeName),
     revision: result.revision,
     change_dir: path.relative(path.resolve(projectRoot), paths.changeDir).replace(/\\/g, '/'),
-    artifact_index: 'artifact-index.json',
+    artifact_index: ontologyStateRelative(ONTOLOGY_STATE_FILES.artifactIndex),
   };
   assertChangeLock(lock);
   const changed = atomicWriteIfChanged(basePaths.current, pointer);
@@ -272,9 +275,9 @@ function scanChange(projectRoot, changeName, options = {}) {
     identityHistory,
     effectiveGraph,
     projectRoot,
-    continuityResolutionPath: path.join(
+    continuityResolutionPath: resolveOntologyStateFile(
       parsed.changeDir,
-      'continuity-resolution.json',
+      ONTOLOGY_STATE_FILES.continuityResolution,
     ),
   });
   const reviewStatus = options.markPending && validation.valid ? 'pending' : 'draft';
@@ -358,16 +361,17 @@ function reconcileChange(projectRoot, changeName, options = {}) {
 function readWorkingState(projectRoot, changeName) {
   const basePaths = statePaths(projectRoot, changeName);
   const paths = changeOntologyPaths(projectRoot, changeName);
+  const readablePaths = resolveRevisionBundlePaths(paths.changeDir);
   if (fs.existsSync(basePaths.current)) {
     const pointer = readJson(basePaths.current, 'SEM_STATE_POINTER_CORRUPT');
     if (!pointer.revision || pointer.change !== safeChangeName(changeName)) {
       throw stateError('SEM_STATE_POINTER_CORRUPT', `current.json 不属于 Change ${changeName}`);
     }
-    return readRevisionBundle(paths, pointer.revision).working;
+    return readRevisionBundle(readablePaths, pointer.revision).working;
   }
-  if (!fs.existsSync(paths.working)) return null;
-  const working = readJson(paths.working, 'SEM_STATE_CORRUPT');
-  readRevisionBundle(paths, working.revision);
+  if (!fs.existsSync(readablePaths.working)) return null;
+  const working = readJson(readablePaths.working, 'SEM_STATE_CORRUPT');
+  readRevisionBundle(readablePaths, working.revision);
   return working;
 }
 
@@ -396,9 +400,12 @@ function createArchiveSnapshot(projectRoot, changeName, archiveDir, inputState)
   if (!state.facts_hash || state.facts_hash !== actualFacts.facts_hash) {
     throw new Error(`归档正文与待确认本体事实不一致: ${changeName}`);
   }
-  const artifactIndexPath = path.join(targetDir, 'artifact-index.json');
+  const artifactIndexPath = resolveOntologyStateFile(
+    targetDir,
+    ONTOLOGY_STATE_FILES.artifactIndex,
+  );
   if (!fs.existsSync(artifactIndexPath)) {
-    throw new Error(`归档目录缺少 artifact-index.json: ${targetDir}`);
+    throw new Error(`归档目录缺少 ontology/artifact-index.json: ${targetDir}`);
   }
   const artifactIndex = readJson(artifactIndexPath, 'SEM_STATE_CORRUPT');
   if (artifactIndex.revision !== state.revision) {
@@ -468,4 +475,7 @@ module.exports = {
   reconcileChange,
   readWorkingState,
   createArchiveSnapshot,
+  resolveOntologyStateFile,
+  resolveRevisionBundlePaths,
+  ONTOLOGY_STATE_FILES,
 };

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

@@ -4,15 +4,20 @@ const fs = require('fs');
 const path = require('path');
 const { SCHEMA_VERSION } = require('./schema.cjs');
 const { generateUuidV7, isValidUuidV7 } = require('./id.cjs');
+const {
+  ONTOLOGY_STATE_FILES,
+  ontologyStateRelative,
+  resolveOntologyStateFile,
+} = require('./ontology-paths.cjs');
 
-const REGISTRY_FILE = 'ontology-identities.json';
+const REGISTRY_FILE = ontologyStateRelative(ONTOLOGY_STATE_FILES.identities);
 
 function registryPath(changeDir) {
   return path.join(path.resolve(changeDir), REGISTRY_FILE);
 }
 
 function readRegistry(changeDir) {
-  const filePath = registryPath(changeDir);
+  const filePath = resolveOntologyStateFile(changeDir, ONTOLOGY_STATE_FILES.identities);
   if (!fs.existsSync(filePath)) {
     return { schema_version: SCHEMA_VERSION, identities: {} };
   }
@@ -35,6 +40,10 @@ function writeRegistry(changeDir, registry) {
   const tempPath = `${filePath}.${process.pid}.tmp`;
   fs.writeFileSync(tempPath, content, 'utf8');
   fs.renameSync(tempPath, filePath);
+  const legacy = path.join(path.resolve(changeDir), ONTOLOGY_STATE_FILES.identities);
+  if (legacy !== filePath && fs.existsSync(legacy)) {
+    fs.rmSync(legacy, { force: true });
+  }
   return true;
 }
 

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

@@ -1,11 +1,18 @@
 'use strict';
 
+const path = require('path');
+const fs = require('fs');
 const {
   DIAGNOSTIC_CODES,
   normalizeProfile,
   relationDefinition,
 } = require('./schema.cjs');
 const { isValidEntityId, isValidUuid } = require('./id.cjs');
+const {
+  ONTOLOGY_STATE_FILES,
+  ontologyStateRelative,
+  resolveOntologyStateFile,
+} = require('./ontology-paths.cjs');
 
 function diagnostic(code, severity, message, context = {}) {
   return {
@@ -350,18 +357,19 @@ function validateContinuityAndExternalRefs(facts, diagnostics, options = {}) {
   const kind = String(continuity.kind || '').toLowerCase();
   const resolutionPath = options.continuityResolutionPath
     || (facts.change
-      ? require('path').join(
-        options.projectRoot || process.cwd(),
-        'openspec',
-        'changes',
-        facts.change,
-        'continuity-resolution.json',
+      ? resolveOntologyStateFile(
+        path.join(
+          options.projectRoot || process.cwd(),
+          'openspec',
+          'changes',
+          facts.change,
+        ),
+        ONTOLOGY_STATE_FILES.continuityResolution,
       )
       : '');
   let resolution = null;
   if (resolutionPath) {
     try {
-      const fs = require('fs');
       if (fs.existsSync(resolutionPath)) {
         resolution = JSON.parse(fs.readFileSync(resolutionPath, 'utf8'));
       }
@@ -392,7 +400,7 @@ function validateContinuityAndExternalRefs(facts, diagnostics, options = {}) {
         'error',
         'Continuity=iteration 但 continuity-resolution.json 缺失或仍为 pending',
         {
-          file: resolutionPath || 'continuity-resolution.json',
+          file: resolutionPath || ontologyStateRelative(ONTOLOGY_STATE_FILES.continuityResolution),
           suggestion: '在 propose/spec 完成 A/B/C 决议后再 check',
         },
       ));

package/skywalk-sdd/ontology/working-artifacts.cjs

@@ -2,6 +2,8 @@
 
 const crypto = require('crypto');
 const path = require('path');
+const { resolveRuntimeMetadata } = require('../runtime-metadata.cjs');
+const { ontologyStateRelative, ONTOLOGY_STATE_FILES } = require('./ontology-paths.cjs');
 
 const WORKING_ARTIFACT_SCHEMA_VERSION = 'kld-sdd-working-artifact-facts/v1';
 const ARTIFACT_INDEX_SCHEMA_VERSION = 'kld-sdd-working-artifact-index/v1';
@@ -141,7 +143,7 @@ function compareFacts(left, right) {
 
 function buildWorkingArtifactFacts(result, options = {}) {
   const state = result.state || {};
-  const producerVersion = String(options.producerVersion || require('../../package.json').version);
+  const producerVersion = String(options.producerVersion || resolveRuntimeMetadata().version);
   const reviewStatus = state.review_status === 'pending' ? 'pending' : 'draft';
   const rawEntities = Array.isArray(state.entities) ? state.entities : [];
   const entityByAnchor = new Map(rawEntities.map((entity) => [
@@ -227,7 +229,7 @@ function buildWorkingArtifactFacts(result, options = {}) {
       review_status: reviewStatus,
       valid: Boolean(result.valid),
       revision: result.revision,
-      working_ontology_path: 'working-ontology.json',
+      working_ontology_path: ontologyStateRelative(ONTOLOGY_STATE_FILES.working),
       artifacts: artifactIndex,
     },
     files: artifactFiles,