kld-sdd 2.7.8 → 2.8.0

package/skywalk-sdd/lib/test-execution.cjs

@@ -0,0 +1,130 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+function parseCounts(output) {
+  // Prefer runner totals: counting TAP parent suites as tests double-counts nested tests.
+  const value = name => {
+    const matches = [...output.matchAll(new RegExp(`^(?:#|ℹ)\\s+${name}\\s+(\\d+)\\s*$`, 'gm'))];
+    return matches.length ? Number(matches[matches.length - 1][1]) : null;
+  };
+  const total = value('tests'), passed = value('pass'), failed = value('fail');
+  const skipped = value('skipped'), todo = value('todo');
+  if ([total, passed, failed].every(Number.isInteger)
+      && total === passed + failed + (skipped || 0) + (todo || 0)) {
+    return { counts_known: true, passed, failed, skipped: (skipped || 0) + (todo || 0) };
+  }
+  // Surefire/Failsafe print per-class counts and a Results section. Count only
+  // the latter, once per module/execution, to avoid double-counting classes.
+  const summaries = [];
+  let inResults = false;
+  for (const raw of output.replace(/\u001b\[[0-9;]*m/g, '').split(/\r?\n/)) {
+    const line = raw.replace(/^\[(?:INFO|WARNING|ERROR)\]\s*/, '').trim();
+    if (line === 'Results:') { inResults = true; continue; }
+    if (!inResults) continue;
+    const match = /^Tests run:\s*(\d+),\s*Failures:\s*(\d+),\s*Errors:\s*(\d+),\s*Skipped:\s*(\d+)\b/.exec(line);
+    if (!match) continue;
+    const [, count, failures, errors, ignored] = match.map(Number);
+    if (count < failures + errors + ignored) return { counts_known: false };
+    summaries.push({ passed: count - failures - errors - ignored, failed: failures + errors, skipped: ignored });
+    inResults = false;
+  }
+  if (summaries.length) {
+    return summaries.reduce((sum, item) => ({ counts_known: true, passed: sum.passed + item.passed,
+      failed: sum.failed + item.failed, skipped: sum.skipped + item.skipped }),
+    { counts_known: true, passed: 0, failed: 0, skipped: 0 });
+  }
+  return { counts_known: false };
+}
+
+function classifyFailure(output, exitCode, error, signal) {
+  if (error?.code === 'ETIMEDOUT') return 'timeout';
+  if (error || signal) return 'infrastructure';
+  if (exitCode === 0) return 'none';
+  // A missing executable/module/test path is not evidence of a failing business assertion.
+  if (/MODULE_NOT_FOUND|ERR_MODULE_NOT_FOUND|Cannot find module|Could not find|ENOENT|SyntaxError|ERR_TEST_FAILURE.*cancelled/i.test(output)) return 'infrastructure';
+  if (/ERR_ASSERTION|AssertionError|AssertionFailedError|org\.opentest4j\.AssertionFailedError/.test(output)) return 'assertion';
+  return 'infrastructure';
+}
+
+function captureTest(args, projectRoot, change) {
+  let command;
+  try { command = JSON.parse(args['command-json'] || 'null'); } catch { /* validated below */ }
+  if (!Array.isArray(command) || !command.length || command.some(x => typeof x !== 'string' || x.includes('\0')) || !command[0]) {
+    throw new Error('TEST_COMMAND_REQUIRED: --command-json 必须是非空命令参数数组，不通过 shell 执行');
+  }
+  const phase = args['tdd-phase'] || 'regression';
+  if (!['red', 'green', 'refactor', 'regression', 'not-applicable'].includes(phase)) throw new Error('TEST_PHASE_INVALID');
+  const taskIds = [...new Set(String(args['task-ids'] || args['task-id'] || '').split(',').map(x => x.trim()).filter(Boolean))];
+  if (!taskIds.length) throw new Error('TEST_TASKS_REQUIRED: 明确指定 --task-ids，工具不猜测测试覆盖的任务');
+  const timeout = Number(args['timeout-ms'] || 120000);
+  if (!Number.isInteger(timeout) || timeout < 1 || timeout > 3600000) throw new Error('TEST_TIMEOUT_INVALID');
+  const cwd = path.resolve(args.cwd || projectRoot);
+  if (!fs.statSync(cwd).isDirectory()) throw new Error('TEST_CWD_INVALID');
+  const runId = args['run-id'] || crypto.randomUUID();
+  const key = crypto.createHash('sha256').update(`${change}:${runId}`).digest('hex');
+  const dir = path.join(projectRoot, 'skywalk-sdd', 'state', 'test-runs', key);
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  // A run ID identifies one execution. Never re-execute a command under an old receipt.
+  try { fs.mkdirSync(dir); } catch (error) {
+    if (error.code === 'EEXIST') throw new Error('TEST_RUN_EXISTS: 此 run-id 已执行；使用保存的 details.json 重试记录，重新执行须使用新 run-id');
+    throw error;
+  }
+  const startedAt = new Date().toISOString();
+  const started = process.hrtime.bigint();
+  const childEnv = { ...process.env };
+  // The wrapper can itself run inside node:test; its child is a fresh test runner.
+  delete childEnv.NODE_TEST_CONTEXT;
+  const child = spawnSync(command[0], command.slice(1), {
+    cwd, env: childEnv, shell: false, encoding: 'utf8', timeout, maxBuffer: 16 * 1024 * 1024,
+  });
+  const duration = Math.round(Number(process.hrtime.bigint() - started) / 1e6);
+  const stdout = child.stdout || '', stderr = child.stderr || '';
+  const output = stdout + '\n' + stderr;
+  const exitCode = Number.isInteger(child.status) ? child.status : (child.error?.code === 'ETIMEDOUT' ? 124 : 1);
+  const failureType = classifyFailure(output, exitCode, child.error, child.signal);
+  const counts = parseCounts(output);
+  const files = {};
+  for (const [name, content] of Object.entries({ 'stdout.log': stdout, 'stderr.log': stderr })) {
+    fs.writeFileSync(path.join(dir, name), content, { mode: 0o600 });
+    files[name] = crypto.createHash('sha256').update(content).digest('hex');
+  }
+  const execution = {
+    origin: 'command-execution', argv: command, cwd, started_at: startedAt,
+    finished_at: new Date().toISOString(), signal: child.signal || null,
+    error: child.error ? { code: child.error.code, message: child.error.message } : null,
+    output_files: Object.entries(files).map(([name, sha256]) => ({ path: path.join(dir, name), sha256 })),
+    task_association: 'explicit-caller-declaration',
+    receipt_path: path.join(dir, 'execution.json'),
+  };
+  const testResults = {
+    run_id: runId, verified_task_ids: taskIds, tdd_phase: phase,
+    command: JSON.stringify(command), result: exitCode === 0 ? 'success' : 'failure',
+    exit_code: exitCode, duration_ms: duration, ...counts, failure_type: failureType,
+    expected_failure: phase === 'red' && args['expected-failure'] === true,
+    execution,
+  };
+  const receipt = path.join(dir, 'details.json');
+  fs.writeFileSync(execution.receipt_path, JSON.stringify(testResults, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+  fs.writeFileSync(receipt, JSON.stringify({ test_results: testResults }, null, 2) + '\n', { mode: 0o600 });
+  return { testResults, runId, receipt };
+}
+
+function verifyCapture(input, projectRoot) {
+  const base = fs.realpathSync(path.join(projectRoot, 'skywalk-sdd/state/test-runs')) + path.sep;
+  const receiptPath = fs.realpathSync(input.execution.receipt_path);
+  if (input.execution.origin !== 'command-execution' || !receiptPath.startsWith(base)) throw new Error('TEST_CAPTURE_INVALID: 执行回执不在当前项目');
+  const receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
+  for (const key of Object.keys(receipt)) {
+    if (JSON.stringify(receipt[key]) !== JSON.stringify(input[key])) throw new Error(`TEST_CAPTURE_MISMATCH: ${key} 与真实执行回执不一致`);
+  }
+  for (const output of receipt.execution.output_files) {
+    const file = fs.realpathSync(output.path);
+    if (!file.startsWith(base) || crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== output.sha256) throw new Error('TEST_CAPTURE_HASH_MISMATCH: 原始测试输出已变化');
+  }
+}
+
+module.exports = { captureTest, parseCounts, classifyFailure, verifyCapture };

package/skywalk-sdd/lib/usage-reporter.cjs

@@ -23,6 +23,8 @@ const {
   readUserConfig,
 } = require('./user-config.cjs');
 const gitIdentity = require('./git-identity.cjs');
+// kb-state.json 的唯一读取入口（含「必须位于 spec 包裹包根」的位置校验）
+const { loadKbState } = require('./shared.cjs');
 
 const PENDING_FILE_NAME = 'pending-usage.jsonl';
 const PENDING_MAX_BYTES = 1024 * 1024; // 1 MB
@@ -93,6 +95,16 @@ function _resetGitIdentityCache() {
  * 四级解析上报地址：config.server → 项目 kb-state.json api → env KLD_SDD_SERVER → 内置默认。
  * 每级均经 normalizeServerUrl；结果永远非空（默认地址兜底）。
  *
+ * kb-state.json 的读取走 `loadKbState`（唯一 kb-state 读取入口），因此沿用
+ * 其位置校验：只有位于 spec 包裹包根的那份才被采用。位置不符时行为与
+ * 「文件不存在」一致 —— 静默落到下一级（env → 内置默认）。
+ *
+ * 这里刻意**不**把 loadKbState 的 warnings 打到 stderr：上报链路是
+ * 「永不抛错、静默兜底」的后台路径，配置告警应由 KB 技能链路（kb-config /
+ * ontology-query / kb-ingest）呈现，避免每次 log start 都刷屏。
+ * 且宁可上报到默认地址，也不能因为某处残留的陈旧 kb-state.json
+ * 把使用数据发到错误服务器。
+ *
  * @param {{homeDir?:string, projectRoot?:string, env?:object}} [options]
  * @returns {string}
  */
@@ -107,14 +119,11 @@ function resolveReportServer(options = {}) {
   }
   // 2. 项目级 kb-state.json 的 api（kb-state.api 是唯一带 /api 契约的来源，先剥离尾部 /api 再标准化）
   try {
-    const kbStatePath = path.join(projectRoot, 'kb-state.json');
-    if (fs.existsSync(kbStatePath)) {
-      const kbState = JSON.parse(fs.readFileSync(kbStatePath, 'utf8'));
-      if (kbState && typeof kbState.api === 'string') {
-        const stripped = kbState.api.trim().replace(/\/api(\/v\d+)?\/?$/i, '');
-        const normalized = normalizeServerUrl(stripped);
-        if (normalized) return normalized;
-      }
+    const { config: kbState } = loadKbState(projectRoot);
+    if (kbState && typeof kbState.api === 'string') {
+      const stripped = kbState.api.trim().replace(/\/api(\/v\d+)?\/?$/i, '');
+      const normalized = normalizeServerUrl(stripped);
+      if (normalized) return normalized;
     }
   } catch {
     // kb-state 读取失败时静默，继续下一级

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

@@ -4,6 +4,13 @@ const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const { generateUuidV7 } = require('./id.cjs');
+const {
+  SPEC_ONTOLOGY_SCHEMA_VERSION,
+  SPEC_ONTOLOGY_PATH,
+  buildSpecOntology,
+  validateSpecOntology,
+  specOntologyContentSignature,
+} = require('./spec-ontology.cjs');
 const { resolveRuntimeMetadata } = require('../runtime-metadata.cjs');
 const {
   readJson,
@@ -581,6 +588,18 @@ function materializeArchivePackage(options = {}) {
   );
   const canonicalPath = path.join(archiveDir, CANONICAL_FACTS_PATH);
   const canonicalBytes = writeJsonAtomic(canonicalPath, canonicalFacts);
+  const specOntology = buildSpecOntology(snapshot, {
+    projectId: projectIdentity.project_id,
+    archiveId,
+    compatibilityMode: 'ADAPTED_V2',
+    reviewStatus: 'confirmed',
+  });
+  const specOntologyValidation = validateSpecOntology(specOntology);
+  if (!specOntologyValidation.valid) {
+    throw new Error(`Spec 本体事实包校验失败: ${specOntologyValidation.errors.join('; ')}`);
+  }
+  const specOntologyPath = path.join(archiveDir, SPEC_ONTOLOGY_PATH);
+  writeJsonAtomic(specOntologyPath, specOntology);
 
   const conversionReport = {
     schema_version: CONVERSION_REPORT_SCHEMA_VERSION,
@@ -589,6 +608,9 @@ function materializeArchivePackage(options = {}) {
     source_schema: String(snapshot.schema_version || 'unknown'),
     target_file: CANONICAL_FACTS_PATH,
     target_schema: CANONICAL_FACTS_SCHEMA_VERSION,
+    spec_ontology_file: SPEC_ONTOLOGY_PATH,
+    spec_ontology_schema: SPEC_ONTOLOGY_SCHEMA_VERSION,
+    compatibility_mode: specOntology.compatibility_mode,
     status: 'converted',
     entity_count: canonicalFacts.entities.length,
     relation_count: canonicalFacts.relations.length,
@@ -618,6 +640,9 @@ function materializeArchivePackage(options = {}) {
     change_id: changeId,
     content_hash: `sha256:${sha256(canonicalBytes)}`,
     canonical_facts_path: CANONICAL_FACTS_PATH,
+    spec_ontology_path: SPEC_ONTOLOGY_PATH,
+    spec_ontology_schema: SPEC_ONTOLOGY_SCHEMA_VERSION,
+    compatibility_mode: specOntology.compatibility_mode,
     conversion_report_path: CONVERSION_REPORT_PATH,
     created_at: createdAt,
     files,
@@ -647,6 +672,121 @@ function materializeArchivePackage(options = {}) {
     conversion_report: conversionReport,
     manifest_path: existingManifestPath,
     canonical_facts_path: canonicalPath,
+    spec_ontology_path: specOntologyPath,
+    conversion_report_path: path.join(archiveDir, CONVERSION_REPORT_PATH),
+    package_path: packagePath,
+  };
+}
+
+function materializeCompatibilityPackage(options = {}) {
+  const projectRoot = path.resolve(options.projectRoot || process.cwd());
+  const archiveDir = path.resolve(requiredText(options.archiveDir, 'archiveDir', 'Compatibility Package'));
+  const facts = options.facts;
+  if (!facts || !Array.isArray(facts.entities)) {
+    throw new Error('Compatibility Package 缺少已解析 facts');
+  }
+  const projectIdentity = ensureProjectIdentity(projectRoot);
+  const changeName = requiredText(options.changeName || facts.change, 'changeName', 'Compatibility Package');
+  const changeId = String(facts.change_id || `CHG-LEGACY-${sha256(changeName).slice(0, 12)}`).toUpperCase();
+  const publicationVariant = options.specOntology?.review_status === 'confirmed' ? 'reviewed' : 'candidate';
+  const archiveId = `urn:kld:sdd:archive:${sha256(
+    `${projectIdentity.project_id}\n${changeId}\n${facts.facts_hash || sha256(JSON.stringify(facts))}\n${publicationVariant}`,
+  )}`;
+  let specOntology;
+  if (options.specOntology) {
+    specOntology = JSON.parse(JSON.stringify(options.specOntology));
+    if (specOntology.project_id !== projectIdentity.project_id) {
+      throw new Error('已审核 Spec 本体的 project_id 与当前项目不一致，请重新物化并审核');
+    }
+    if (specOntology.compatibility_mode !== 'LEGACY_MATERIALIZED') {
+      throw new Error('兼容包只接受 LEGACY_MATERIALIZED 本体');
+    }
+    if (specOntology.review_status !== 'confirmed' || specOntology.publication_eligible !== true) {
+      throw new Error('历史 Spec 本体尚未审核，不能发布为 current 事实');
+    }
+    const currentOntology = buildSpecOntology({ ...facts, change_id: changeId }, {
+      projectId: projectIdentity.project_id,
+      compatibilityMode: 'LEGACY_MATERIALIZED',
+      reviewStatus: 'pending',
+    });
+    if (specOntologyContentSignature(specOntology) !== specOntologyContentSignature(currentOntology)) {
+      throw new Error('已审核 Spec 本体与当前 Markdown 内容不一致，请重新物化并审核');
+    }
+    specOntology.archive_id = archiveId;
+    specOntology.change = changeName;
+    specOntology.change_id = changeId;
+    delete specOntology.ontology_hash;
+    specOntology.ontology_hash = `sha256:${sha256(JSON.stringify(specOntology))}`;
+  } else {
+    specOntology = buildSpecOntology({ ...facts, change_id: changeId }, {
+      projectId: projectIdentity.project_id,
+      archiveId,
+      compatibilityMode: 'LEGACY_MATERIALIZED',
+      reviewStatus: 'pending',
+    });
+  }
+  const validation = validateSpecOntology(specOntology);
+  if (!validation.valid) {
+    throw new Error(`历史 Spec 本体物化失败: ${validation.errors.join('; ')}`);
+  }
+  const toleratedDiagnostics = (options.toleratedDiagnostics || [])
+    .map((item) => `LEGACY_DIAGNOSTIC_TOLERATED: ${item.code}: ${item.message}`);
+  const specOntologyPath = path.join(archiveDir, SPEC_ONTOLOGY_PATH);
+  const specOntologyBytes = writeJsonAtomic(specOntologyPath, specOntology);
+  const conversionReport = {
+    schema_version: CONVERSION_REPORT_SCHEMA_VERSION,
+    producer: PRODUCER,
+    source_file: 'legacy-markdown',
+    source_schema: String(facts.schema_version || 'legacy-markdown'),
+    target_file: SPEC_ONTOLOGY_PATH,
+    target_schema: SPEC_ONTOLOGY_SCHEMA_VERSION,
+    compatibility_mode: 'LEGACY_MATERIALIZED',
+    status: specOntology.publication_eligible ? 'materialized_reviewed' : 'materialized_pending_review',
+    entity_count: specOntology.entities.length,
+    relation_count: specOntology.relations.length,
+    warnings: [...new Set([...(specOntology.warnings || []), ...toleratedDiagnostics])],
+  };
+  writeJsonAtomic(path.join(archiveDir, CONVERSION_REPORT_PATH), conversionReport);
+
+  const createdAt = options.archivedAt || new Date().toISOString();
+  const filePaths = collectPackageFilePaths(archiveDir);
+  const files = filePaths.map((relativePath) => ({
+    path: relativePath,
+    content_hash: `sha256:${sha256(fs.readFileSync(path.join(archiveDir, relativePath)))}`,
+  }));
+  const manifest = {
+    schema_version: MANIFEST_SCHEMA_VERSION,
+    producer: PRODUCER,
+    project_id: projectIdentity.project_id,
+    archive_id: archiveId,
+    change_id: changeId,
+    content_hash: `sha256:${sha256(specOntologyBytes)}`,
+    canonical_facts_path: null,
+    spec_ontology_path: SPEC_ONTOLOGY_PATH,
+    spec_ontology_schema: SPEC_ONTOLOGY_SCHEMA_VERSION,
+    compatibility_mode: 'LEGACY_MATERIALIZED',
+    conversion_report_path: CONVERSION_REPORT_PATH,
+    created_at: createdAt,
+    files,
+    change: changeName,
+    archived_at: createdAt,
+    reason: options.reason || '历史 Spec 本体兼容入库',
+    method: options.method || 'legacy-spec-ontology-materialization',
+    source_path: options.sourcePath || '',
+    archive_path: toPosix(path.relative(projectRoot, archiveDir)),
+    copied_specs: [],
+    evidence_events_path: null,
+  };
+  const manifestPath = path.join(archiveDir, MANIFEST_PATH);
+  writeJsonAtomic(manifestPath, manifest);
+  const packagePath = path.resolve(options.packagePath || `${archiveDir}.zip`);
+  writeArchiveZip(archiveDir, packagePath, manifest);
+  return {
+    manifest,
+    conversion_report: conversionReport,
+    validation,
+    manifest_path: manifestPath,
+    spec_ontology_path: specOntologyPath,
     conversion_report_path: path.join(archiveDir, CONVERSION_REPORT_PATH),
     package_path: packagePath,
   };
@@ -707,5 +847,6 @@ module.exports = {
   readStoredZipEntries,
   verifyArchivePackage,
   materializeArchivePackage,
+  materializeCompatibilityPackage,
   finalizeArchivePackageAfterReports,
 };

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

@@ -6,7 +6,7 @@ const path = require('path');
 const { DIAGNOSTIC_CODES, entityTypeForId } = require('./schema.cjs');
 const { ensureStructuralIdentities } = require('./structural-identity.cjs');
 
-const ENTITY_ID_PATTERN = /\b(?:CHG|CAP|STMT|AC|CON|DES|TASK|ART|SEC|SNAP)-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/gi;
+const ENTITY_ID_PATTERN = /\b(?:CHG|OBJ|CAP|STMT|AC|CON|DES|TASK|ART|SEC|SNAP)-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/gi;
 const IDENTITY_META_PATTERN = /^\s*-\s+\*\*(entity-id|version-id|predecessor-version|delta-state|external-ref)\*\*\s*[：:]\s*(.*?)\s*$/i;
 
 function toPosix(value) {
@@ -444,7 +444,7 @@ function parseSpec(target, file, lines, frontmatter) {
       });
       continue;
     }
-    const inheritedRelationMatch = line.match(/^\s*-\s+\*\*relation\*\*\s*[：:]\s*`?((?:CHG|CAP|STMT|AC|CON|DES|TASK)-[A-Z0-9-]+)\s+(contains|acceptedBy|constrainedBy|realizes|implements|covers|dependsOn)\s+((?:CHG|CAP|STMT|AC|CON|DES|TASK)-[A-Z0-9-]+)`?\s*$/i);
+    const inheritedRelationMatch = line.match(/^\s*-\s+\*\*relation\*\*\s*[：:]\s*`?((?:CHG|OBJ|CAP|STMT|AC|CON|DES|TASK)-[A-Z0-9-]+)\s+(contains|usesObject|acceptedBy|constrainedBy|realizes|implements|covers|dependsOn)\s+((?:CHG|OBJ|CAP|STMT|AC|CON|DES|TASK)-[A-Z0-9-]+)`?\s*$/i);
     if (inheritedRelationMatch) {
       let source = '';
       for (let offset = index + 1; offset < Math.min(lines.length, index + 6); offset += 1) {
@@ -461,7 +461,28 @@ function parseSpec(target, file, lines, frontmatter) {
       });
       continue;
     }
-    let match = line.match(/^\s*####\s+需求项[：:]\s*[【\[]?(STMT-[A-Z0-9-]+)[】\]]?\s*(.*?)\s*$/i);
+    let match = line.match(/^\s*####\s+业务对象[：:]\s*[【\[]?(OBJ-[A-Z0-9-]+)[】\]]?\s*(.*?)\s*$/i);
+    if (match) {
+      const objectId = match[1].toUpperCase();
+      const endIndex = sectionEnd(lines, index, 4);
+      addEntity(
+        target,
+        'BusinessObject',
+        objectId,
+        match[2],
+        file,
+        index + 1,
+        { capability_id: capabilityId || undefined },
+        parseIdentityBlock(lines, index + 1, endIndex),
+        lines.slice(index, endIndex).join('\n'),
+      );
+      if (capabilityId) {
+        addRelation(target, 'usesObject', capabilityId, objectId, file, index + 1, 'asserted');
+      }
+      continue;
+    }
+
+    match = line.match(/^\s*####\s+需求项[：:]\s*[【\[]?(STMT-[A-Z0-9-]+)[】\]]?\s*(.*?)\s*$/i);
     if (match) {
       currentStatement = match[1].toUpperCase();
       currentConstraint = '';

package/skywalk-sdd/ontology/cli.cjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
 const {
   scanChange,
@@ -18,6 +19,11 @@ const listChanges = require('./list-changes.cjs');
 const sddConfig = require('./sdd-config.cjs');
 const activeChanges = require('./active-changes.cjs');
 const { resolveProjectArg } = require('./resolve-spec-root.cjs');
+const {
+  materializeChangeSpecOntology,
+  validateSpecOntology,
+  approveSpecOntologyFile,
+} = require('./spec-ontology.cjs');
 
 function parseArgs(argv) {
   const result = { _: [] };
@@ -77,6 +83,9 @@ function showHelp() {
   node skywalk-sdd/ontology/cli.cjs status    --project=. --change=<name>
   node skywalk-sdd/ontology/cli.cjs observe   --project=. --change=<name> [--interval=1500]
   node skywalk-sdd/ontology/cli.cjs snapshot  --project=. --change=<name> --archive=<path>
+  node skywalk-sdd/ontology/cli.cjs materialize-ontology --project=. --change=<name> [--output=<path>]
+  node skywalk-sdd/ontology/cli.cjs validate-spec-ontology --file=<spec-ontology.json>
+  node skywalk-sdd/ontology/cli.cjs approve-spec-ontology --file=<spec-ontology.json>
 
 observe 只负责采集和同步；check/archive 前仍必须执行 reconcile。`);
 }
@@ -254,11 +263,55 @@ function main(argv = process.argv.slice(2)) {
     if (!result.ok) process.exitCode = 1;
     return;
   }
+  if (command === 'validate-spec-ontology') {
+    const filePath = path.resolve(args.file || args._[1] || 'spec-ontology.json');
+    const payload = JSON.parse(fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, ''));
+    const result = validateSpecOntology(payload);
+    console.log(JSON.stringify({ file: filePath, ...result }, null, 2));
+    if (!result.valid) process.exitCode = 1;
+    return;
+  }
+  if (command === 'approve-spec-ontology') {
+    const filePath = path.resolve(args.file || args._[1] || 'spec-ontology.json');
+    const result = approveSpecOntologyFile(filePath, {
+      allowCollisions: args['allow-collisions'] === true,
+    });
+    console.log(JSON.stringify({
+      file: result.file,
+      compatibility_mode: result.payload.compatibility_mode,
+      review_status: result.payload.review_status,
+      publication_eligible: result.payload.publication_eligible,
+      validation: result.validation,
+      warnings: result.payload.warnings,
+    }, null, 2));
+    if (!result.validation.valid) process.exitCode = 1;
+    return;
+  }
   const projectRoot = resolveCliProject(args);
   const changeName = args.change;
   if (!changeName) throw new Error('缺少 --change 参数');
   const profile = args.profile || 'auto';
 
+  if (command === 'materialize-ontology' || command === 'materialize') {
+    const result = materializeChangeSpecOntology(projectRoot, changeName, {
+      outputPath: args.output,
+      mappingPath: args.mapping,
+      reviewStatus: args['review-status'],
+    });
+    console.log(JSON.stringify({
+      change: changeName,
+      compatibility_mode: result.payload.compatibility_mode,
+      review_status: result.payload.review_status,
+      publication_eligible: result.payload.publication_eligible,
+      output_path: result.output_path,
+      mapping_path: result.mapping_path,
+      validation: result.validation,
+      warnings: result.payload.warnings,
+    }, null, 2));
+    if (!result.validation.valid) process.exitCode = 1;
+    return;
+  }
+
   if (command === 'scan') {
     const result = scanChange(projectRoot, changeName, { profile });
     console.log(JSON.stringify(summary({ ...result, changed: false, paths: undefined }), null, 2));

package/skywalk-sdd/ontology/id.cjs

@@ -42,7 +42,7 @@ function nextEntityId(prefix, scope, existingIds = []) {
 
 function isValidEntityId(entityId, expectedType = '') {
   const value = String(entityId || '').trim().toUpperCase();
-  if (!/^(?:CHG|CAP|STMT|AC|CON|DES|TASK|ART|SEC|SNAP)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/.test(value)) {
+  if (!/^(?:CHG|OBJ|CAP|STMT|AC|CON|DES|TASK|ART|SEC|SNAP)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/.test(value)) {
     return false;
   }
   if (expectedType && entityTypeForId(value) !== expectedType) {

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

@@ -236,7 +236,11 @@ function buildIdentityCatalog(projectRoot, options = {}) {
 
   for (const candidate of identityRoots(root)) {
     if (excluded && path.resolve(candidate.changeDir) === excluded) continue;
-    const facts = normalizeFacts(parseChangeArtifacts(root, candidate.change, {
+    const snapshot = candidate.scope === 'archive'
+      ? readJson(path.join(candidate.changeDir, 'archive-ontology.json')) : null;
+    // The archive directory gains a date prefix, but facts were frozen with the logical change name.
+    const logicalChange = snapshot && snapshot.change ? snapshot.change : candidate.change;
+    const facts = normalizeFacts(parseChangeArtifacts(root, logicalChange, {
       changeDir: candidate.changeDir,
       persistStructuralIdentities: false,
     }));

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

@@ -4,6 +4,8 @@ const fs = require('fs');
 const path = require('path');
 const sddConfig = require('./sdd-config.cjs');
 const workspaceLayout = require('./workspace-layout.cjs');
+// spec 判据的唯一真相源（spec-detect 对本模块无依赖，不构成循环）
+const specDetect = require('./spec-detect.cjs');
 
 /**
  * 从 anchorRoot 向上遍历目录树，查找 .sdd-spec-root 配置文件。
@@ -28,6 +30,34 @@ function resolveHint(anchorRoot) {
   return null;
 }
 
+/**
+ * 从 `.sdd-workspace.yaml` 的 `spec_path` 解析 spec 根（向上逐级查找）。
+ *
+ * 委托 `spec-detect.resolveWorkspaceYamlUpward` —— 该解析在 spec-detect 中
+ * 同时用于「候选枚举的 tier 0 来源」，两处共用一份实现，避免漂移。
+ */
+function resolveWorkspaceYamlSpecPath(anchorRoot) {
+  return specDetect.resolveWorkspaceYamlUpward(anchorRoot);
+}
+
+/**
+ * 解析 spec 包裹包根目录。
+ *
+ * 优先级（权威声明 → 结构判据 → 回落）：
+ *   1. `.sdd-spec-root` 指针文件（init / 运行时写入）
+ *   2. `.sdd.yaml` layout: mono（单仓，仓内包裹包）
+ *   3. `.sdd-workspace.yaml` spec_path（多仓工作区编排）
+ *   4. 工作区探测：子仓结构判据命中的 spec 包
+ *   5. 非 Git 子目录包裹包
+ *   6. 回落为入参本身（调用方用 isSpecPackageRoot 区分「就是 spec 根」与「解析失败」）
+ *
+ * 第 3 步是**新增**的：多仓工作区根执行文档类命令时，权威链此前不读
+ * `.sdd-workspace.yaml`，只能靠第 4 步的结构判据猜；而 skills 的
+ * `opsx-consistency-check/scripts.cjs` 早已自己解析该文件 —— 两处不一致。
+ * 现由权威链直接支持，该文件成为与 `.sdd.yaml` 同级的显式声明来源。
+ *
+ * 前 3 步均**向上逐级查找**，故从工作区子目录（如某个代码仓内）调用也能命中。
+ */
 function resolveSpecProjectRoot(projectRoot = process.cwd()) {
   const root = path.resolve(projectRoot);
   const hinted = resolveHint(root);
@@ -37,6 +67,9 @@ function resolveSpecProjectRoot(projectRoot = process.cwd()) {
     return sddConfig.resolveMonoSpecRoot(root);
   }
 
+  const fromWorkspaceYaml = resolveWorkspaceYamlSpecPath(root);
+  if (fromWorkspaceYaml) return fromWorkspaceYaml;
+
   const layout = workspaceLayout.detectWorkspaceLayout(root);
   if (layout.specRepo) return layout.specRepo.abs;
 
@@ -50,7 +83,23 @@ function resolveProjectArg(projectArg = '.', cwd = process.cwd()) {
   return resolveSpecProjectRoot(path.resolve(cwd, projectArg));
 }
 
+/**
+ * 判断 dir 本身是否就是一个 SDD spec 包裹包根。
+ *
+ * 用于 `log spec-root` 的 resolved 判定：当 resolveSpecProjectRoot 因找不到
+ * 任何线索而回落为入参本身时，需区分「dir 就是 spec 根」与「解析失败」。
+ *
+ * ⚠️ 判据已收敛到 `spec-detect.cjs#isSpecPackageRoot`（全仓唯一判据入口）。
+ * 该判据比 `isSpecCandidate` 宽一档 —— 额外接受仅含 `openspec/` 的半成品
+ * （`--skip-openspec` 产物），因为本函数的语义是「能否作为 spec 根使用」
+ * 而非「是否是当前项目的 spec 仓」。
+ */
+function isSpecPackageRoot(dir) {
+  return specDetect.isSpecPackageRoot(dir);
+}
+
 module.exports = {
   resolveProjectArg,
   resolveSpecProjectRoot,
+  isSpecPackageRoot,
 };

package/skywalk-sdd/ontology/schema.cjs

@@ -4,6 +4,7 @@ const SCHEMA_VERSION = 'kld-sdd-ontology/v2';
 
 const ENTITY_TYPES = Object.freeze([
   'Change',
+  'BusinessObject',
   'Capability',
   'SpecificationStatement',
   'AcceptanceCriterion',
@@ -17,6 +18,7 @@ const ENTITY_TYPES = Object.freeze([
 
 const ID_PREFIX_TYPES = Object.freeze({
   CHG: 'Change',
+  OBJ: 'BusinessObject',
   CAP: 'Capability',
   STMT: 'SpecificationStatement',
   AC: 'AcceptanceCriterion',
@@ -37,6 +39,10 @@ const RELATION_TYPES = Object.freeze({
       Object.freeze(['Capability', 'SpecificationStatement']),
     ]),
   }),
+  usesObject: Object.freeze({
+    domain: Object.freeze(['Capability']),
+    range: Object.freeze(['BusinessObject']),
+  }),
   acceptedBy: Object.freeze({
     domain: Object.freeze(['SpecificationStatement']),
     range: Object.freeze(['AcceptanceCriterion']),