kld-sdd 2.5.2 → 2.6.0

package/skywalk-sdd/ontology/runtime.cjs

@@ -10,6 +10,11 @@ const { validateTraceability } = require('./traceability-validator.cjs');
 const { buildIdentityCatalog } = require('./identity-index.cjs');
 const { buildEffectiveGraph } = require('./effective-graph.cjs');
 const { generateUuidV7 } = require('./id.cjs');
+const {
+  WORKING_ARTIFACT_SCHEMA_VERSION,
+  ARTIFACT_INDEX_SCHEMA_VERSION,
+  buildWorkingArtifactFacts,
+} = require('./working-artifacts.cjs');
 const {
   acquireChangeLock,
   assertChangeLock,
@@ -20,26 +25,30 @@ function sha256(value) {
   return crypto.createHash('sha256').update(value).digest('hex');
 }
 
-function statePaths(projectRoot, changeName, revision = '') {
+function resolveChangeDir(projectRoot, changeName) {
+  const root = path.resolve(projectRoot || process.cwd());
+  return path.join(root, 'openspec', 'changes', safeChangeName(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'),
+  };
+}
+
+function statePaths(projectRoot, changeName) {
   const root = path.resolve(projectRoot || process.cwd());
   const safeName = safeChangeName(changeName);
   const dir = path.join(root, 'skywalk-sdd', 'state', 'ontology', safeName);
-  const revisions = path.join(dir, 'revisions');
-  const revisionDir = revision ? path.join(revisions, revision) : '';
   return {
     dir,
-    revisions,
     current: path.join(dir, 'current.json'),
-    revisionDir,
-    working: revisionDir
-      ? path.join(revisionDir, 'working-ontology.json')
-      : path.join(dir, 'working-ontology.json'),
-    diagnostics: revisionDir
-      ? path.join(revisionDir, 'diagnostics.json')
-      : path.join(dir, 'diagnostics.json'),
-    fileIndex: revisionDir
-      ? path.join(revisionDir, 'file-index.json')
-      : path.join(dir, 'file-index.json'),
   };
 }
 
@@ -48,7 +57,7 @@ function serialized(value) {
 }
 
 function atomicWriteIfChanged(filePath, value) {
-  const content = serialized(value);
+  const content = typeof value === 'string' ? value : serialized(value);
   if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === content) {
     return false;
   }
@@ -74,7 +83,7 @@ function readJson(filePath, code) {
 }
 
 function readRevisionBundle(paths, expectedRevision) {
-  for (const filePath of [paths.working, paths.diagnostics, paths.fileIndex]) {
+  for (const filePath of [paths.working, paths.diagnostics, paths.fileIndex, paths.artifactIndex]) {
     if (!fs.existsSync(filePath)) {
       throw stateError('SEM_STATE_INCOMPLETE', `revision ${expectedRevision} 缺少 ${path.basename(filePath)}`);
     }
@@ -82,59 +91,161 @@ function readRevisionBundle(paths, expectedRevision) {
   const working = readJson(paths.working, 'SEM_STATE_CORRUPT');
   const diagnostics = readJson(paths.diagnostics, 'SEM_STATE_CORRUPT');
   const fileIndex = readJson(paths.fileIndex, 'SEM_STATE_CORRUPT');
-  const revisions = [working.revision, diagnostics.revision, fileIndex.revision];
+  const artifactIndex = readJson(paths.artifactIndex, 'SEM_STATE_CORRUPT');
+  const revisions = [working.revision, diagnostics.revision, fileIndex.revision, artifactIndex.revision];
   if (revisions.some((revision) => revision !== expectedRevision)) {
     throw stateError(
       'SEM_STATE_REVISION_MISMATCH',
       `current=${expectedRevision}，working/diagnostics/file-index=${revisions.join('/')}`,
     );
   }
-  return { working, diagnostics, fileIndex };
+  for (const artifact of artifactIndex.artifacts || []) {
+    const artifactPath = path.resolve(paths.changeDir, artifact.json_path || '');
+    const artifactRelative = path.relative(paths.changeDir, artifactPath);
+    if (
+      !artifact.json_path
+      || artifactRelative.startsWith('..')
+      || path.isAbsolute(artifactRelative)
+      || !fs.existsSync(artifactPath)
+    ) {
+      throw stateError(
+        'SEM_STATE_INCOMPLETE',
+        `revision ${expectedRevision} 缺少 Artifact JSON: ${artifact.json_path || '(empty)'}`,
+      );
+    }
+    const artifactFacts = readJson(artifactPath, 'SEM_STATE_CORRUPT');
+    if (artifactFacts.revision !== expectedRevision) {
+      throw stateError(
+        'SEM_STATE_REVISION_MISMATCH',
+        `current=${expectedRevision}，artifact=${artifactFacts.revision}`,
+      );
+    }
+  }
+  return { working, diagnostics, fileIndex, artifactIndex };
+}
+
+function pruneStaleArtifacts(changeDir, artifactIndex) {
+  const artifactRoot = path.join(changeDir, 'artifacts');
+  if (!fs.existsSync(artifactRoot)) return;
+  const allowed = new Set((artifactIndex.artifacts || []).map((artifact) => artifact.json_path));
+  const stale = [];
+  (function walk(currentDir, relativePrefix) {
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+      const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
+      const absolutePath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        walk(absolutePath, relativePath);
+        continue;
+      }
+      if (!entry.name.endsWith('.ontology.json')) continue;
+      const jsonPath = `artifacts/${relativePath.replace(/\\/g, '/')}`;
+      if (!allowed.has(jsonPath)) stale.push(absolutePath);
+    }
+  }(artifactRoot, ''));
+  for (const filePath of stale) {
+    fs.rmSync(filePath, { force: true });
+  }
+  (function removeEmptyDirs(currentDir) {
+    if (!fs.existsSync(currentDir) || currentDir === artifactRoot) return;
+    const entries = fs.readdirSync(currentDir);
+    for (const entry of entries) {
+      const child = path.join(currentDir, entry);
+      if (fs.statSync(child).isDirectory()) removeEmptyDirs(child);
+    }
+    if (fs.readdirSync(currentDir).length === 0) fs.rmdirSync(currentDir);
+  }(artifactRoot));
 }
 
 function commitRevision(projectRoot, changeName, result, lock) {
   assertChangeLock(lock);
   const basePaths = statePaths(projectRoot, changeName);
-  const paths = statePaths(projectRoot, changeName, result.revision);
-  fs.mkdirSync(basePaths.revisions, { recursive: true });
+  const paths = changeOntologyPaths(projectRoot, changeName);
+  fs.mkdirSync(basePaths.dir, { recursive: true });
+  fs.mkdirSync(paths.changeDir, { recursive: true });
 
-  if (fs.existsSync(paths.revisionDir)) {
-    readRevisionBundle(paths, result.revision);
-  } else {
-    const stagingDir = path.join(
-      basePaths.revisions,
-      `.${result.revision}.${lock.token}.staging`,
-    );
-    fs.rmSync(stagingDir, { recursive: true, force: true });
-    fs.mkdirSync(stagingDir, { recursive: true });
-    const stagingPaths = {
-      working: path.join(stagingDir, 'working-ontology.json'),
-      diagnostics: path.join(stagingDir, 'diagnostics.json'),
-      fileIndex: path.join(stagingDir, 'file-index.json'),
-    };
-    fs.writeFileSync(stagingPaths.working, serialized(result.state), 'utf8');
-    fs.writeFileSync(stagingPaths.diagnostics, serialized({
-      schema_version: SCHEMA_VERSION,
-      change: changeName,
-      profile: result.profile,
-      valid: result.valid,
-      revision: result.revision,
-      diagnostics: result.diagnostics,
-    }), 'utf8');
-    fs.writeFileSync(stagingPaths.fileIndex, serialized(result.fileIndex), 'utf8');
-    assertChangeLock(lock);
-    fs.renameSync(stagingDir, paths.revisionDir);
+  if (fs.existsSync(paths.working)) {
+    const existing = readJson(paths.working, 'SEM_STATE_CORRUPT');
+    if (existing.revision === result.revision) {
+      readRevisionBundle(paths, result.revision);
+      const artifactIndex = readJson(paths.artifactIndex, 'SEM_STATE_CORRUPT');
+      return {
+        changed: false,
+        paths: {
+          ...paths,
+          current: basePaths.current,
+          artifactFacts: (artifactIndex.artifacts || []).map((artifact) => (
+            path.join(paths.changeDir, artifact.json_path)
+          )),
+        },
+      };
+    }
+  }
+
+  const stagingDir = path.join(basePaths.dir, `.${result.revision}.${lock.token}.staging`);
+  fs.rmSync(stagingDir, { recursive: true, force: true });
+  fs.mkdirSync(stagingDir, { recursive: true });
+  const artifactBundle = buildWorkingArtifactFacts(result);
+  const stagedFiles = {
+    working: path.join(stagingDir, 'working-ontology.json'),
+    diagnostics: path.join(stagingDir, 'diagnostics.json'),
+    fileIndex: path.join(stagingDir, 'file-index.json'),
+    artifactIndex: path.join(stagingDir, 'artifact-index.json'),
+  };
+  fs.writeFileSync(stagedFiles.working, serialized(result.state), 'utf8');
+  fs.writeFileSync(stagedFiles.diagnostics, serialized({
+    schema_version: SCHEMA_VERSION,
+    change: changeName,
+    profile: result.profile,
+    valid: result.valid,
+    revision: result.revision,
+    diagnostics: result.diagnostics,
+  }), 'utf8');
+  fs.writeFileSync(stagedFiles.fileIndex, serialized(result.fileIndex), 'utf8');
+  fs.writeFileSync(stagedFiles.artifactIndex, serialized(artifactBundle.index), 'utf8');
+  for (const artifactFile of artifactBundle.files) {
+    const targetPath = path.join(stagingDir, artifactFile.path);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, serialized(artifactFile.value), 'utf8');
   }
+  assertChangeLock(lock);
+  readRevisionBundle({
+    changeDir: stagingDir,
+    working: stagedFiles.working,
+    diagnostics: stagedFiles.diagnostics,
+    fileIndex: stagedFiles.fileIndex,
+    artifactIndex: stagedFiles.artifactIndex,
+  }, result.revision);
+
+  atomicWriteIfChanged(paths.working, fs.readFileSync(stagedFiles.working, 'utf8'));
+  atomicWriteIfChanged(paths.diagnostics, fs.readFileSync(stagedFiles.diagnostics, 'utf8'));
+  atomicWriteIfChanged(paths.fileIndex, fs.readFileSync(stagedFiles.fileIndex, 'utf8'));
+  atomicWriteIfChanged(paths.artifactIndex, fs.readFileSync(stagedFiles.artifactIndex, 'utf8'));
+  for (const artifactFile of artifactBundle.files) {
+    const stagedPath = path.join(stagingDir, artifactFile.path);
+    atomicWriteIfChanged(path.join(paths.changeDir, artifactFile.path), fs.readFileSync(stagedPath, 'utf8'));
+  }
+  pruneStaleArtifacts(paths.changeDir, artifactBundle.index);
+  fs.rmSync(stagingDir, { recursive: true, force: true });
 
   const pointer = {
     schema_version: 'kld-sdd-state-pointer/v1',
     change: safeChangeName(changeName),
     revision: result.revision,
-    path: `revisions/${result.revision}`,
+    change_dir: path.relative(path.resolve(projectRoot), paths.changeDir).replace(/\\/g, '/'),
+    artifact_index: 'artifact-index.json',
   };
   assertChangeLock(lock);
   const changed = atomicWriteIfChanged(basePaths.current, pointer);
-  return { changed, paths: { ...paths, current: basePaths.current, revisions: basePaths.revisions } };
+  return {
+    changed,
+    paths: {
+      ...paths,
+      current: basePaths.current,
+      artifactFacts: artifactBundle.index.artifacts.map((artifact) => (
+        path.join(paths.changeDir, artifact.json_path)
+      )),
+    },
+  };
 }
 
 function scanChange(projectRoot, changeName, options = {}) {
@@ -164,6 +275,8 @@ function scanChange(projectRoot, changeName, options = {}) {
   const reviewStatus = options.markPending && validation.valid ? 'pending' : 'draft';
   const revisionInput = {
     schema_version: SCHEMA_VERSION,
+    artifact_schema_version: WORKING_ARTIFACT_SCHEMA_VERSION,
+    artifact_index_schema_version: ARTIFACT_INDEX_SCHEMA_VERSION,
     change: changeName,
     profile,
     files: facts.files,
@@ -179,6 +292,8 @@ function scanChange(projectRoot, changeName, options = {}) {
   const revision = sha256(JSON.stringify(revisionInput));
   const state = JSON.parse(JSON.stringify({
     schema_version: SCHEMA_VERSION,
+    artifact_schema_version: WORKING_ARTIFACT_SCHEMA_VERSION,
+    artifact_index_schema_version: ARTIFACT_INDEX_SCHEMA_VERSION,
     change: changeName,
     change_id: facts.change_id,
     profile,
@@ -237,18 +352,18 @@ function reconcileChange(projectRoot, changeName, options = {}) {
 
 function readWorkingState(projectRoot, changeName) {
   const basePaths = statePaths(projectRoot, changeName);
+  const paths = changeOntologyPaths(projectRoot, changeName);
   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(
-      statePaths(projectRoot, changeName, pointer.revision),
-      pointer.revision,
-    ).working;
+    return readRevisionBundle(paths, pointer.revision).working;
   }
-  if (!fs.existsSync(basePaths.working)) return null;
-  return readJson(basePaths.working, 'SEM_STATE_CORRUPT');
+  if (!fs.existsSync(paths.working)) return null;
+  const working = readJson(paths.working, 'SEM_STATE_CORRUPT');
+  readRevisionBundle(paths, working.revision);
+  return working;
 }
 
 function createArchiveSnapshot(projectRoot, changeName, archiveDir, inputState) {
@@ -276,6 +391,14 @@ 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');
+  if (!fs.existsSync(artifactIndexPath)) {
+    throw new Error(`归档目录缺少 artifact-index.json: ${targetDir}`);
+  }
+  const artifactIndex = readJson(artifactIndexPath, 'SEM_STATE_CORRUPT');
+  if (artifactIndex.revision !== state.revision) {
+    throw new Error(`归档 artifact-index 与待确认 revision 不一致: ${changeName}`);
+  }
   const snapshotId = `SNAP-${sha256(`${changeName}:${state.revision}`).slice(0, 16).toUpperCase()}`;
   const targetPath = path.join(targetDir, 'archive-ontology.json');
   const previous = fs.existsSync(targetPath)
@@ -330,6 +453,8 @@ function createArchiveSnapshot(projectRoot, changeName, archiveDir, inputState)
 }
 
 module.exports = {
+  resolveChangeDir,
+  changeOntologyPaths,
   statePaths,
   atomicWriteIfChanged,
   readRevisionBundle,

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

@@ -0,0 +1,243 @@
+'use strict';
+
+const crypto = require('crypto');
+const path = require('path');
+
+const WORKING_ARTIFACT_SCHEMA_VERSION = 'kld-sdd-working-artifact-facts/v1';
+const ARTIFACT_INDEX_SCHEMA_VERSION = 'kld-sdd-working-artifact-index/v1';
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function prefixedHash(value) {
+  const normalized = String(value || '').trim().toLowerCase().replace(/^sha256:/, '');
+  return normalized ? `sha256:${normalized}` : '';
+}
+
+function safeRelativePath(value) {
+  const input = String(value || '').trim().replace(/\\/g, '/');
+  const normalized = path.posix.normalize(input);
+  if (
+    !input
+    || input.startsWith('/')
+    || normalized !== input
+    || normalized === '..'
+    || normalized.startsWith('../')
+    || input.includes('\0')
+  ) {
+    throw new Error(`工作态 Artifact 路径不安全: ${value}`);
+  }
+  return normalized;
+}
+
+function artifactJsonPath(sourcePath) {
+  const normalized = safeRelativePath(sourcePath);
+  const extension = path.posix.extname(normalized);
+  const withoutExtension = extension
+    ? normalized.slice(0, -extension.length)
+    : normalized;
+  return `artifacts/${withoutExtension}.ontology.json`;
+}
+
+function normalizedSource(source, fallbackAnchor) {
+  const input = source && typeof source === 'object' ? source : {};
+  const line = Number(input.line || 0);
+  return {
+    artifact_type: String(input.artifact_type || 'unknown').trim().toLowerCase(),
+    file: safeRelativePath(input.file),
+    ...(Number.isInteger(line) && line > 0 ? { line } : {}),
+    anchor_id: String(input.anchor_id || fallbackAnchor || '').trim().toUpperCase(),
+    content_hash: prefixedHash(input.content_hash),
+  };
+}
+
+function workingEntity(entity, reviewStatus) {
+  const anchorId = String(entity.anchor_id || entity.id || '').trim().toUpperCase();
+  return {
+    anchor_id: anchorId,
+    type: entity.type,
+    name: String(entity.name || anchorId).trim(),
+    entity_id: String(entity.entity_id || '').trim().toLowerCase(),
+    entity_version_id: String(entity.entity_version_id || entity.version_id || '').trim().toLowerCase(),
+    predecessor_version_id: entity.predecessor_version_id
+      ? String(entity.predecessor_version_id).trim().toLowerCase()
+      : null,
+    delta_state: String(entity.delta_state || 'unresolved').trim().toLowerCase(),
+    content_hash: String(entity.content_hash || '').trim().toLowerCase(),
+    fact_kind: 'semantic',
+    assertion_type: 'asserted',
+    review_status: reviewStatus,
+    generation_role: entity.generation_role || 'current',
+    ...(entity.inherited_from ? { inherited_from: entity.inherited_from } : {}),
+    attributes: entity.attributes && typeof entity.attributes === 'object' ? entity.attributes : {},
+    source: normalizedSource(entity.source, anchorId),
+  };
+}
+
+function normalizeRelationDirection(relation, entityByAnchor) {
+  const originalType = String(relation.type || '').trim();
+  const originalFrom = String(relation.from || '').trim().toUpperCase();
+  const originalTo = String(relation.to || '').trim().toUpperCase();
+  if (originalType === 'acceptedBy') {
+    return { type: 'verifiedBy', from: originalFrom, to: originalTo };
+  }
+  if (originalType !== 'constrains') {
+    return { type: originalType, from: originalFrom, to: originalTo };
+  }
+  const fromType = entityByAnchor.get(originalFrom)?.type;
+  const toType = entityByAnchor.get(originalTo)?.type;
+  if (fromType === 'Constraint' && toType === 'SpecificationStatement') {
+    return { type: 'constrainedBy', from: originalTo, to: originalFrom };
+  }
+  return { type: 'constrainedBy', from: originalFrom, to: originalTo };
+}
+
+function workingRelation(relation, entityByAnchor, reviewStatus, producerVersion) {
+  const normalized = normalizeRelationDirection(relation, entityByAnchor);
+  const fromEntity = entityByAnchor.get(normalized.from);
+  const toEntity = entityByAnchor.get(normalized.to);
+  const assertionType = String(relation.assertion_type || 'asserted').trim().toLowerCase();
+  const output = {
+    type: normalized.type,
+    from_anchor_id: normalized.from,
+    to_anchor_id: normalized.to,
+    from_entity_id: String(fromEntity?.entity_id || '').trim().toLowerCase(),
+    to_entity_id: String(toEntity?.entity_id || '').trim().toLowerCase(),
+    assertion_type: assertionType,
+    fact_kind: 'semantic',
+    review_status: assertionType === 'suggested' ? 'pending' : reviewStatus,
+    generation_role: relation.generation_role || 'current',
+    ...(relation.inherited_from ? { inherited_from: relation.inherited_from } : {}),
+    source: normalizedSource(
+      relation.source,
+      `${normalized.from}-${normalized.type}-${normalized.to}`,
+    ),
+  };
+  if (assertionType === 'inferred') {
+    output.rule_id = String(relation.rule_id || '').trim();
+    output.generator = relation.generator || 'kld-sdd';
+    output.generator_version = relation.generator_version || producerVersion;
+  } else if (relation.rule_id) {
+    output.rule_id = relation.rule_id;
+  }
+  if (assertionType === 'suggested') {
+    output.generator = relation.generator;
+    output.generator_version = relation.generator_version;
+    output.confidence = relation.confidence;
+    output.support_evidence = Array.isArray(relation.support_evidence) ? relation.support_evidence : [];
+    output.opposition_evidence = Array.isArray(relation.opposition_evidence) ? relation.opposition_evidence : [];
+  }
+  return output;
+}
+
+function compareFacts(left, right) {
+  return (
+    String(left.anchor_id || left.type || '').localeCompare(String(right.anchor_id || right.type || ''))
+    || String(left.from_entity_id || '').localeCompare(String(right.from_entity_id || ''))
+    || String(left.to_entity_id || '').localeCompare(String(right.to_entity_id || ''))
+  );
+}
+
+function buildWorkingArtifactFacts(result, options = {}) {
+  const state = result.state || {};
+  const producerVersion = String(options.producerVersion || require('../../package.json').version);
+  const reviewStatus = state.review_status === 'pending' ? 'pending' : 'draft';
+  const rawEntities = Array.isArray(state.entities) ? state.entities : [];
+  const entityByAnchor = new Map(rawEntities.map((entity) => [
+    String(entity.anchor_id || entity.id || '').trim().toUpperCase(),
+    entity,
+  ]));
+  const artifactFiles = [];
+  const artifactIndex = [];
+
+  for (const artifact of state.artifacts || []) {
+    const sourcePath = safeRelativePath(artifact.path);
+    const jsonPath = artifactJsonPath(sourcePath);
+    const artifactDiagnostics = (result.diagnostics || []).filter((diagnostic) => (
+      !diagnostic.file || String(diagnostic.file).replace(/\\/g, '/') === sourcePath
+    ));
+    const artifactEntities = rawEntities
+      .filter((entity) => (
+        entity.source && String(entity.source.file).replace(/\\/g, '/') === sourcePath
+      ))
+      .map((entity) => workingEntity(entity, reviewStatus))
+      .sort(compareFacts);
+    const artifactRelations = (state.relations || [])
+      .filter((relation) => (
+        relation.source && String(relation.source.file).replace(/\\/g, '/') === sourcePath
+      ))
+      .map((relation) => workingRelation(relation, entityByAnchor, reviewStatus, producerVersion))
+      .sort(compareFacts);
+    const inheritedReferences = (state.inherited_references || []).filter((reference) => (
+      reference.source && String(reference.source.file).replace(/\\/g, '/') === sourcePath
+    ));
+    const inheritedRelations = (state.inherited_relations || []).filter((relation) => (
+      relation.source && String(relation.source.file).replace(/\\/g, '/') === sourcePath
+    ));
+    const semanticFacts = {
+      entities: artifactEntities,
+      relations: artifactRelations,
+      inherited_references: inheritedReferences,
+      inherited_relations: inheritedRelations,
+    };
+    const artifactFacts = {
+      schema_version: WORKING_ARTIFACT_SCHEMA_VERSION,
+      producer: `kld-sdd@${producerVersion}`,
+      canonical: false,
+      change: state.change,
+      change_id: state.change_id,
+      profile: state.profile,
+      stage: artifact.type,
+      review_status: reviewStatus,
+      valid: !artifactDiagnostics.some((diagnostic) => diagnostic.severity === 'error'),
+      revision: result.revision,
+      source: {
+        artifact_type: artifact.type,
+        path: sourcePath,
+        capability_id: artifact.capability_id || null,
+        content_hash: prefixedHash(artifact.content_hash),
+      },
+      facts_hash: sha256(JSON.stringify(semanticFacts)),
+      ...semanticFacts,
+      diagnostics: artifactDiagnostics,
+    };
+    artifactFiles.push({ path: jsonPath, value: artifactFacts });
+    artifactIndex.push({
+      artifact_type: artifact.type,
+      source_path: sourcePath,
+      json_path: jsonPath,
+      capability_id: artifact.capability_id || null,
+      source_content_hash: prefixedHash(artifact.content_hash),
+      facts_hash: artifactFacts.facts_hash,
+      entity_count: artifactEntities.length,
+      relation_count: artifactRelations.length,
+      diagnostic_count: artifactDiagnostics.length,
+    });
+  }
+
+  return {
+    index: {
+      schema_version: ARTIFACT_INDEX_SCHEMA_VERSION,
+      producer: `kld-sdd@${producerVersion}`,
+      canonical: false,
+      change: state.change,
+      change_id: state.change_id,
+      profile: state.profile,
+      review_status: reviewStatus,
+      valid: Boolean(result.valid),
+      revision: result.revision,
+      working_ontology_path: 'working-ontology.json',
+      artifacts: artifactIndex,
+    },
+    files: artifactFiles,
+  };
+}
+
+module.exports = {
+  WORKING_ARTIFACT_SCHEMA_VERSION,
+  ARTIFACT_INDEX_SCHEMA_VERSION,
+  safeRelativePath,
+  artifactJsonPath,
+  buildWorkingArtifactFacts,
+};

package/templates/skills/kld-sdd/opsx-archive/SKILL.md

@@ -107,7 +107,8 @@ node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reas
 
 该命令成功后必须已经完成：
 - 活动目录 `openspec/changes/<name>/` 被移入 `openspec/changes/archive/<日期>-<name>/`。
-- 归档目录写入 `archive-manifest.json`。
+- 归档目录写入 `archive-ontology.json`、`canonical-facts.json`、`conversion-report.json` 和新版 `archive-manifest.json`。
+- 生成知识库可直接消费的 `openspec/changes/archive/<日期>-<name>.zip`，包内文件必须由 manifest 完整列举并通过 SHA-256 校验。
 - Full Spec 的 `specs/<capability>/spec.md` 同步到 `openspec/specs/<capability>/spec.md`。
 - archive 阶段写入 `stage_end`。
 - 未勾选 tasks 被写入 `archive_result.task_completion`。
@@ -132,6 +133,8 @@ node skywalk-sdd/log.cjs end --event-id=<event_id> --command=archive --project=.
 > - 归档目录：`openspec/changes/archive/<日期>-<name>/`
 > - 最终报告（默认同时生成 .md + .html）：`openspec/changes/archive/<日期>-<name>/reports/<name>-report.md`、`openspec/changes/archive/<日期>-<name>/reports/<name>-report.html`
 > - 执行日志：`openspec/changes/archive/<日期>-<name>/logs/execution-log.md`
+> - 知识库归档包：`openspec/changes/archive/<日期>-<name>.zip`
+> - 本体消费入口：`openspec/changes/archive/<日期>-<name>/canonical-facts.json`
 > - 未勾选任务：X 项，已记录到报告，不阻断归档
 > - 正式 specs：`openspec/specs/`
 
@@ -159,7 +162,13 @@ node skywalk-sdd/log.cjs record --type=baseline_record --command=archive --proje
 
 - 归档前必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<变更名称>`，不能只信任文件观察事件。
 - 随后必须运行 `node skywalk-sdd/log.cjs semantic-check --project=. --change=<变更名称>`；有阻断诊断时禁止移动活动 Change。
+- Archive 不负责首次生成 propose/spec/design/tasks 的工作态事实；它重新解析原文核对 pending revision，补充 `OntologySnapshot/project_id/archive_id` 后冻结为 confirmed。
 - `archive-docs` 成功后必须在归档目录生成 `archive-ontology.json`，并将 `review_status` 标记为 `confirmed`。
+- 生产端必须把 confirmed 本体转换为 `canonical-facts.json`；实体固定为 `fact_kind=semantic`、`assertion_type=asserted`、`review_status=confirmed`，关系必须补齐对应语义边界字段。
+- `acceptedBy` 在消费协议中归一化为 `verifiedBy`；inferred 关系必须携带 `rule_id`、`generator` 和 `generator_version`。
+- 每个 canonical 实体和关系的 `source.file` 必须存在于 Archive Package，`source.content_hash` 必须等于该原文文件的 SHA-256。
+- `archive-manifest.json` 必须使用 `kld-sdd-archive-manifest/v2`，并与 canonical facts 的 project/archive/change 身份一致。
+- `conversion-report.json` 必须记录源/目标 schema、转换状态、实体数、关系数和归一化告警。
 - Archive 快照必须固化人工锚点、逻辑实体 UUID、版本 UUID、前序版本 UUID、delta-state 和内容哈希；任一 UUID 冲突或谱系断裂都不得 confirmed。
 - 归档目录已经复制但语义快照失败时，不得删除活动 Change，不得标记 confirmed。
 - unchanged 正文保留在前序 Archive；当前归档只固化差量事实、继承引用和来源锚点。

package/templates/skills/kld-sdd/opsx-archive/checklist.md

@@ -18,7 +18,11 @@ description: "opsx-archive 前后日志/总结自检清单 — 仅在 archive
 ## B. 归档后自检
 
 - [ ] 归档目录 `openspec/changes/archive/<日期>-<变更名称>/` 存在
-- [ ] `openspec/changes/archive/<日期>-<变更名称>/archive-manifest.json` 存在
+- [ ] `openspec/changes/archive/<日期>-<变更名称>/` 下 `archive-ontology.json`、`canonical-facts.json`、`conversion-report.json` 和 `archive-manifest.json` 均存在
+- [ ] 活动 change 目录下的 `artifacts/*.ontology.json` 与 `artifact-index.json` 已随归档目录一并迁移
+- [ ] `archive-manifest.json` 为 `kld-sdd-archive-manifest/v2`，且 `files` 精确覆盖 ZIP 内除 manifest 自身外的全部文件
+- [ ] `openspec/changes/archive/<日期>-<变更名称>.zip` 存在并可由知识库 `ArchivePackageReader` 读取
+- [ ] canonical facts 中每个实体/关系均能通过 `source.file`、`source.anchor_id`、`source.content_hash` 定向展开到包内原文
 - [ ] 最终报告 `openspec/changes/archive/<日期>-<变更名称>/reports/<变更名称>-report.md` 存在且含「归档结果」段
 - [ ] `reports/<变更名称>-report.md` 与 `reports/<变更名称>-report.html` 都已生成（md+html 双产物）
 - [ ] html 报告含 `SDD 效果度量报告` 标题与各度量章节（执行摘要/效率/质量/过程/归档结果/说明）

package/templates/skills/kld-sdd/opsx-check/SKILL.md

@@ -215,6 +215,8 @@ node skywalk-sdd/log.cjs semantic-check --project=. --change=<变更名称> --pr
 - 所有 profile 都必须阻断重复人工锚点、UUID 缺失/非法、跨 Change 或 Archive 的实体 UUID 误复用、版本 UUID 重用、版本谱系断裂、悬空引用、非法 domain/range 和 Task 依赖成环。
 - `added` 必须使用全新实体/版本 UUID；`modified/removed` 必须复用实体 UUID并指向直接前序版本；`unchanged` 必须复用历史实体和版本 UUID且不得复制历史正文。
 - 文件观察结果只能作为快速上下文，check 必须重新全量 semantic-reconcile。
+- propose/spec/design/task 对应工作态 JSON 应已在各作者阶段生成；check 不负责首次生成业务事实，只重新解析 Markdown、核对各 JSON 与同一 revision，并在全部通过时把派生 revision 更新为 `review_status=pending`。
+- Check 只读是指不修改 proposal/spec/design/tasks 原文；允许原子刷新 `openspec/changes/<变更名称>/` 下可再生的 `working-ontology.json`、`artifact-index.json` 与 `artifacts/*.ontology.json`。
 
 ## Guardrails
 

package/templates/skills/kld-sdd/opsx-check/checklist.md

@@ -35,3 +35,5 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
 
 - [ ] 完整性、一致性、算法正确性、可执行性四维均已输出
 - [ ] 报告问题对应修复建议（spec/design/task）
+- [ ] `openspec/changes/<变更名称>/artifact-index.json` 已覆盖当前全部 proposal/spec/design/tasks，且每份 `artifacts/*.ontology.json` 与 `working-ontology.json` revision 一致
+- [ ] 全部语义门禁通过时工作态 JSON 已从 draft 刷新为 pending；check 未修改任何 Markdown 原文

package/templates/skills/kld-sdd/opsx-design/SKILL.md

@@ -172,6 +172,8 @@ design.md 中若使用 version 正则约束（如格式校验 `^\d+\.\d+\.\d+$`
 - 每个 DES 必须通过 `**realizes**: STMT-*` 显式引用一个或多个真实 STMT。
 - 不得仅凭文本相似创建 realizes；没有上游 STMT 时必须标记 unresolved。
 - 生成结束后必须运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>`。
+- reconcile 必须立即生成 `openspec/changes/<name>/artifacts/.../design.ontology.json`，其中 DES 和 realizes 关系保留原文 source；不得推迟到 check/archive。
+- 阶段 `stage_end` 会在无 Hook 环境下幂等执行同步兜底。
 
 ## Guardrails
 

package/templates/skills/kld-sdd/opsx-propose/SKILL.md

@@ -211,6 +211,8 @@ openspec instructions proposal --change "<name>" --json
 - 每个 Change/Capability 同时写人工锚点、`entity-id`、`version-id` 和 `delta-state`。新增时必须调用 `node skywalk-sdd/log.cjs semantic-identity --delta-state=added`，不得手写或复制 UUID。
 - 修改既有 Capability 时调用 `semantic-identity --delta-state=modified --entity-id=<历史实体UUID> --predecessor-version=<直接前序版本UUID>`；复用实体 UUID，但必须生成新版本 UUID。
 - 本阶段只声明 Change 和 Capability，不得提前生成 STMT、AC、DES 或 TASK 事实。
+- proposal.md 写入结束后必须立即运行 `node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>`，生成 `openspec/changes/<name>/artifacts/proposal.ontology.json`；不得等到 check 或 archive 才首次生成 JSON。
+- 阶段 `stage_end` 会在无 Hook 环境下幂等执行同一次同步作为兜底，结果中的 `semantic_state.artifact_json_paths` 必须包含 proposal 对应 JSON。
 
 ## Guardrails