kld-sdd 2.5.2 → 2.6.1

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/openspec/proposal.md

@@ -1,7 +1,7 @@
 ---
 # 【用户选择配置 - 由 /opsx:propose 引导填写】
 change-id: "CHG-<CHANGE-SLUG>" # 创建时生成，后续不得修改
-entity-id: "<UUID>" # Change 的全局逻辑实体 UUID，added 时生成
+entity-id: "<8位十六进制ID>" # Change 的全局逻辑实体 ID，added 时生成
 version-id: "<UUID>" # 本次 Change 版本 UUID
 delta-state: "added"
 predecessor-version: "" # added 留空；modified/removed 指向直接前序版本

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

@@ -192,11 +192,34 @@ f. **⛔ 立即更新任务状态** — tasks.md `- [ ]`→`- [x]` 与 `**状态
 g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下一层级任务。
 
 **【S2 逐任务红绿节奏】**：每个任务完成后，在编译检查（d）和测试门禁（e）之外，如果 `test-strategy` 为 `tdd`，要求：
-1. 先写/确认该任务相关的测试存在且 RED（失败原因与该任务目标直接相关）
-2. 实现代码使测试 GREEN
-3. 再进入下一个任务
+1. **测试-RED 任务**：编写带真实断言的测试 → 运行测试 → 确认失败（失败原因必须是功能未实现）→ 记录失败原因
+2. **实现-GREEN 任务**：读取对应 RED 的失败原因 → 写最少代码让测试通过 → 运行测试确认通过
+3. **重构-REFACTOR 任务**：在测试全绿状态下重构 → 运行全部测试确认仍绿
+4. 再进入下一个任务
 
-这确保每个任务都有对应的测试保护，而非最后统一跑测试。
+这确保每个行为点都有对应的测试保护，测试真实驱动实现，而非最后统一跑测试。
+
+**【S2.1 RED 测试质量标准】**（test-strategy=tdd 时强制）：
+
+> ⛔ 核心原则：**Mock 边界，不 Mock 行为**
+>
+> 测试应验证**真实行为链路**（输入→输出），而非验证"能否 catch mock 抛的异常"。
+
+1. **禁止 mock 被测行为本身**：测试的 Given 应准备**真实的前置条件**（如真实的 invalid token 字符串），让被测代码自然走完链路；而非直接 mock 出**期望的中间结果**（如 mock parseToken 抛异常）
+   - ❌ `when(jwtUtil.parseToken("invalid")).thenThrow(...)` — mock 了被测行为（token 解析失败），GREEN 只需加 try-catch
+   - ✅ 使用真实 JwtUtil + 真实 invalid token 字符串，让解析自然失败，测试验证完整链路
+
+2. **Mock 仅用于系统边界依赖**：数据库 Mapper、HTTP 客户端、消息队列等外部依赖可 mock；但被测类自身的业务逻辑、实现被测行为的工具类不可 mock
+   - ✅ Mock `BookMapper.countByPublisher()` — 数据库边界，需要真实 DB 环境才能验证
+   - ❌ Mock `JwtUtil.parseToken()` — 这是被测行为的实现，mock 它等于跳过了被测逻辑
+
+3. **RED 测试的 Given 必须是真实输入**：传入真实的数据（如 `"invalid"` 字符串、`null`、空对象），让被测代码自行处理；不能 mock 出"这个输入会导致什么结果"
+   - ❌ `when(parseToken("invalid")).thenThrow()` — 预定了"invalid 会导致抛异常"这个结论
+   - ✅ 传入 `"invalid"` 字符串，让真实的 parseToken 自行决定是否失败
+
+4. **GREEN 实现后测试不应需要修改**：测试描述行为契约（输入→期望输出），GREEN 只写让契约满足的最少代码。如果 GREEN 后需要改测试才能通过，说明 RED 测试有问题
+
+5. **判断标准**：如果删掉被测类的实现（方法体清空），测试是否仍然因为 mock 而通过？如果是，说明测试是假的——真实测试应该在实现缺失时失败
 
 ### 5f. 【S3 apply 结束前 checkbox 全量自检】
 

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

@@ -34,10 +34,37 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 
 ### §5e 测试执行门禁（按 `proposal.md` 的 `test-strategy`）
 
-- [ ] `tdd` → **⛔ 强制执行**：运行相关测试，测试失败禁止继续，必须修复
+- [ ] `tdd` → **⛔ 强制执行**：
+  - 测试-RED 任务：运行测试确认**失败**，失败原因必须是功能未实现（非编译错误）
+  - 实现-GREEN 任务：运行测试确认**通过**
+  - 重构-REFACTOR 任务：运行**全部测试**确认仍绿
+  - 测试失败禁止继续，必须修复
 - [ ] `impl-first` → **⚠️ 警告模式**：运行测试，失败时显示警告但允许继续
 - [ ] `none` → **跳过**：不执行测试门禁
 
+### §5e.1 TDD 执行合规自检（仅 test-strategy=tdd 时）
+
+- [ ] RED 任务执行后已运行测试并确认失败
+- [ ] RED 任务失败原因是"功能未实现"而非编译错误
+- [ ] GREEN 任务执行后已运行测试确认通过
+- [ ] GREEN 任务未提前实现没有测试要求的功能
+- [ ] REFACTOR 任务执行后已运行全部测试确认仍绿
+- [ ] 未出现"先写生产代码再补测试"的情况
+
+### §5e.2 RED 测试质量门禁（仅 test-strategy=tdd 时，RED 任务完成后强制检查）
+
+> ⛔ 核心原则：**Mock 边界，不 Mock 行为**
+
+- [ ] **未 mock 被测行为本身**：测试的 Given 准备的是真实前置条件（如真实 invalid token 字符串），让被测代码自然走完链路；而非直接 mock 出期望的中间结果
+  - ❌ `when(jwtUtil.parseToken("invalid")).thenThrow(...)` — mock 了被测行为（解析失败），GREEN 只需加 try-catch
+  - ✅ 使用真实 JwtUtil + 真实 invalid token，让解析自然失败
+- [ ] **Mock 仅用于系统边界依赖**：数据库 Mapper、HTTP 客户端等外部依赖可 mock；被测类自身的业务逻辑、实现被测行为的工具类不可 mock
+  - ✅ Mock `BookMapper.countByPublisher()` — 数据库边界
+  - ❌ Mock `JwtUtil.parseToken()` — 被测行为的实现
+- [ ] **RED 测试的 Given 是真实输入**：传入真实数据让被测代码自行处理，不 mock 出"这个输入会导致什么结果"
+- [ ] **删掉实现后测试仍因 mock 而通过？** 如果是 → 测试是假的，必须重写
+- [ ] **GREEN 后测试不需要修改**：如果 GREEN 后需要改测试才能通过 → RED 测试有问题
+
 ### 任务状态实时更新
 
 - [ ] tasks.md：`- [ ]` → `- [x]`（拓扑图和任务详情中的复选框）
@@ -81,6 +108,7 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] ⛔ **DAG 依赖拦截**：执行任务前必须检查依赖，前置未完成必须拦截
 - [ ] ⛔ **编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成
 - [ ] ⛔ **测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry，`sdd-apply-test-gate` 校验非占位数据
+- [ ] ⛔ **RED 测试质量门禁**：Mock 边界不 Mock 行为；未 mock 被测行为本身；Mock 仅用于系统边界依赖；RED 测试 Given 是真实输入
 - [ ] ⛔ **必须实时更新任务状态**：每完成一个任务立即改 tasks.md，两种格式（`- [ ]`→`- [x]` 与 `**状态**: [ ]`→`[x]`）同步
 - [ ] **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目用 `vcs_mode=no-git` 继续执行
 - [ ] ⛔ **Step 0.1 隔离校验必做**：建 worktree / 建议分支名前必须完成 proposal + 跨 cap spec 依赖校验并输出报告；未通过不得按 full 并行策略拆 `kld-sdd/<change>/<cap>`