kld-sdd 2.6.3 → 2.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.6.3",
+  "version": "2.6.4",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
     "kld-sdd-init": "bin/kld-sdd-init.js"
   },
   "scripts": {
-    "test": "node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs"
+    "test": "node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs"
   },
   "keywords": [
     "kld",

package/skywalk-sdd/context-client.cjs

@@ -24,12 +24,17 @@ function queryFromArgs(args) {
   if (typeof args['query-file'] === 'string' && args['query-file'].trim()) {
     return fs.readFileSync(args['query-file'], 'utf8').trim();
   }
-  throw new Error('missing --query or --query-file');
+  return '';
 }
 
-function buildEndpoint(apiBase, spaceId) {
+function buildEndpoint(apiBase, spaceId, kbId, mode) {
   const base = String(apiBase || 'http://localhost:8090/api').replace(/\/$/, '');
-  return `${base}/v1/spaces/${encodeURIComponent(spaceId)}/context/match-requirement`;
+  const space = encodeURIComponent(spaceId);
+  const kb = encodeURIComponent(kbId);
+  if (mode === 'resolve') {
+    return `${base}/v1/spaces/${space}/knowledge-bases/${kb}/entities/resolve`;
+  }
+  return `${base}/v1/spaces/${space}/knowledge-bases/${kb}/context/match-requirement`;
 }
 
 function requestJson(url, payload, token, timeoutMs) {
@@ -81,52 +86,85 @@ function requestJson(url, payload, token, timeoutMs) {
   });
 }
 
-function compactContext(data, includeCandidates) {
+function compactContext(data, includeCandidates, mode = 'match') {
   if (includeCandidates) return data;
-  return {
+  const compacted = {
     matchType: data.matchType,
+    resolution: data.resolution,
     inheritanceAllowed: data.inheritanceAllowed,
     reviewRequired: data.reviewRequired,
+    removedBindingCount: data.removedBindingCount,
     advisory: data.advisory,
     degraded: data.degraded,
     degradationReasons: data.degradationReasons,
     targetStage: data.targetStage,
+    reuseMode: data.reuseMode,
     reuseBundles: data.reuseBundles,
     answeredQuestions: data.answeredQuestions,
     warnings: data.warnings,
     clarificationQuestions: data.clarificationQuestions,
     specGenerationContext: data.specGenerationContext,
+    supportEvidence: data.supportEvidence,
+    oppositionEvidence: data.oppositionEvidence,
   };
+  // Continuity resolve 必须透出 candidates；match 默认隐藏内部候选除非 --include-candidates
+  if (mode === 'resolve') {
+    compacted.candidates = data.candidates;
+  }
+  return compacted;
 }
 
-async function retrieveContext(args = parseArgs(process.argv), env = process.env) {
+function buildPayload(args, mode) {
+  const payload = {};
   const query = queryFromArgs(args);
+  if (mode !== 'resolve') {
+    if (!query) {
+      throw new Error('missing --query or --query-file');
+    }
+    payload.query = query;
+    payload.targetStage = args['target-stage'] || 'spec';
+  } else if (query) {
+    payload.query = query;
+  }
+
+  if (args['entity-id']) payload.entityId = args['entity-id'];
+  if (args['previous-version-id']) payload.previousVersionId = args['previous-version-id'];
+  if (args['entity-type']) payload.entityType = args['entity-type'];
+  if (args['external-system']) payload.externalSystem = args['external-system'];
+  if (args['external-object-type']) payload.externalObjectType = args['external-object-type'];
+  if (args['external-id']) payload.externalId = args['external-id'];
+  if (args['canonical-key']) payload.canonicalKey = args['canonical-key'];
+  return payload;
+}
+
+async function retrieveContext(args = parseArgs(process.argv), env = process.env) {
   const spaceId = args['space-id'] || env.ENGINEERING_KB_SPACE_ID || '';
-  if (!spaceId) {
+  const kbId = args['kb-id'] || env.ENGINEERING_KB_KB_ID || '';
+  if (!spaceId || !kbId) {
     return {
       available: false,
       advisory: true,
       degraded: true,
       reason: 'engineering_kb_not_configured',
-      hint: 'set ENGINEERING_KB_SPACE_ID to enable reusable Spec context',
+      hint: 'set ENGINEERING_KB_SPACE_ID and ENGINEERING_KB_KB_ID; do not fall back to local archive/',
     };
   }
 
+  const mode = String(args.mode || 'match').trim().toLowerCase() === 'resolve' ? 'resolve' : 'match';
   const apiBase = args['api-base'] || env.ENGINEERING_KB_API || 'http://localhost:8090/api';
   const token = args.token || env.ENGINEERING_KB_TOKEN || '';
   const timeoutMs = Number(args.timeout || env.ENGINEERING_KB_TIMEOUT_MS || 30000);
+  const payload = buildPayload(args, mode);
   const data = await requestJson(
-    buildEndpoint(apiBase, spaceId),
-    {
-      query,
-      targetStage: args['target-stage'] || 'spec',
-    },
+    buildEndpoint(apiBase, spaceId, kbId, mode),
+    payload,
     token,
     timeoutMs,
   );
   return {
     available: true,
-    ...compactContext(data, Boolean(args['include-candidates'])),
+    mode,
+    ...compactContext(data, Boolean(args['include-candidates']), mode),
   };
 }
 
@@ -141,6 +179,7 @@ async function main() {
       degraded: true,
       reason: 'engineering_kb_unavailable',
       message: error.message,
+      hint: 'KB unavailable: continue degraded; never scan local archive/ for inheritance UUIDs',
     }, null, 2));
     if (args.strict) process.exitCode = 1;
   }
@@ -154,6 +193,7 @@ module.exports = {
   parseArgs,
   queryFromArgs,
   buildEndpoint,
+  buildPayload,
   requestJson,
   compactContext,
   retrieveContext,

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

@@ -8,7 +8,7 @@ const { generateUuidV7 } = require('./id.cjs');
 const PRODUCER_VERSION = require('../../package.json').version;
 const PRODUCER = `kld-sdd@${PRODUCER_VERSION}`;
 const MANIFEST_SCHEMA_VERSION = 'kld-sdd-archive-manifest/v2';
-const CANONICAL_FACTS_SCHEMA_VERSION = 'kld-sdd-canonical-facts/v1';
+const CANONICAL_FACTS_SCHEMA_VERSION = 'kld-sdd-canonical-facts/v2';
 const CONVERSION_REPORT_SCHEMA_VERSION = 'kld-sdd-conversion-report/v1';
 const PROJECT_IDENTITY_SCHEMA_VERSION = 'kld-sdd-project-identity/v1';
 const MANIFEST_PATH = 'archive-manifest.json';
@@ -100,16 +100,42 @@ function requiredText(value, field, owner) {
   return normalized;
 }
 
-function canonicalEntity(archiveDir, entity) {
+function normalizeExternalRefs(refs) {
+  if (!Array.isArray(refs)) return [];
+  const seen = new Set();
+  const result = [];
+  for (const ref of refs) {
+    const system = String(ref.system || ref.system_name || '').trim();
+    const objectType = String(ref.object_type || ref.objectType || '').trim().toLowerCase();
+    const externalId = String(ref.external_id || ref.externalId || '').trim();
+    if (!system || !objectType || !externalId) continue;
+    const key = `${system}\0${objectType}\0${externalId}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push({
+      system,
+      object_type: objectType,
+      external_id: externalId,
+    });
+  }
+  return result;
+}
+
+function canonicalEntity(archiveDir, entity, inheritedRequirementRefs = []) {
   const anchorId = requiredText(entity.anchor_id || entity.id, 'anchor_id', '本体实体').toUpperCase();
   const versionId = requiredText(
     entity.entity_version_id || entity.version_id,
     'entity_version_id/version_id',
     anchorId,
   ).toLowerCase();
+  const entityType = requiredText(entity.type, 'type', anchorId);
+  let externalRefs = normalizeExternalRefs(entity.external_refs || entity.externalRefs || []);
+  if (entityType === 'Capability' && inheritedRequirementRefs.length > 0) {
+    externalRefs = normalizeExternalRefs([...externalRefs, ...inheritedRequirementRefs]);
+  }
   return {
     anchor_id: anchorId,
-    type: requiredText(entity.type, 'type', anchorId),
+    type: entityType,
     name: String(entity.name || anchorId).trim(),
     entity_id: requiredText(entity.entity_id, 'entity_id', anchorId).toLowerCase(),
     entity_version_id: versionId,
@@ -123,6 +149,7 @@ function canonicalEntity(archiveDir, entity) {
     review_status: 'confirmed',
     generation_role: entity.generation_role || 'current',
     ...(entity.inherited_from ? { inherited_from: entity.inherited_from } : {}),
+    ...(externalRefs.length > 0 ? { external_refs: externalRefs } : {}),
     attributes: entity.attributes && typeof entity.attributes === 'object' ? entity.attributes : {},
     source: sourceWithVerifiedHash(archiveDir, entity.source, anchorId, true),
   };
@@ -198,8 +225,11 @@ function buildCanonicalFacts(archiveDir, snapshot, projectId, archiveId) {
     throw new Error('archive-ontology.json 必须是 confirmed 快照');
   }
   const changeId = requiredText(snapshot.change_id, 'change_id', 'archive-ontology.json');
+  const requirementRefs = normalizeExternalRefs(
+    snapshot.requirement_refs || snapshot.requirementRefs || [],
+  ).filter((ref) => ref.object_type === 'requirement');
   const entities = (snapshot.entities || [])
-    .map((entity) => canonicalEntity(archiveDir, entity))
+    .map((entity) => canonicalEntity(archiveDir, entity, requirementRefs))
     .sort((left, right) => (
       left.anchor_id.localeCompare(right.anchor_id)
       || left.entity_version_id.localeCompare(right.entity_version_id)
@@ -241,6 +271,7 @@ function buildCanonicalFacts(archiveDir, snapshot, projectId, archiveId) {
       facts_hash: requiredText(snapshot.facts_hash, 'facts_hash', 'archive-ontology.json'),
       source_revision: snapshot.source_revision,
       snapshot_id: snapshot.snapshot_id,
+      ...(requirementRefs.length > 0 ? { requirement_refs: requirementRefs } : {}),
       entities,
       relations,
     },

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

@@ -7,7 +7,7 @@ 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 IDENTITY_META_PATTERN = /^\s*-\s+\*\*(entity-id|version-id|predecessor-version|delta-state)\*\*\s*[：:]\s*(.*?)\s*$/i;
+const IDENTITY_META_PATTERN = /^\s*-\s+\*\*(entity-id|version-id|predecessor-version|delta-state|external-ref)\*\*\s*[：:]\s*(.*?)\s*$/i;
 
 function toPosix(value) {
   return String(value || '').replace(/\\/g, '/');
@@ -126,6 +126,9 @@ function sourceFor(file, line, anchorId) {
 
 function addEntity(target, type, id, name, file, line, attributes = {}, identity = {}, semanticContent = '') {
   const anchorId = String(id || '').toUpperCase();
+  const externalRefs = Array.isArray(identity.external_refs)
+    ? identity.external_refs.filter(Boolean)
+    : [];
   const entity = {
     id: anchorId,
     anchor_id: anchorId,
@@ -135,6 +138,7 @@ function addEntity(target, type, id, name, file, line, attributes = {}, identity
     version_id: String(identity.version_id || '').trim().toLowerCase() || undefined,
     predecessor_version_id: String(identity.predecessor_version_id || '').trim().toLowerCase() || undefined,
     delta_state: String(identity.delta_state || '').trim().toLowerCase() || undefined,
+    ...(externalRefs.length > 0 ? { external_refs: externalRefs } : {}),
     content_hash: sha256(stripIdentityMetadata(semanticContent || `${type}\n${anchorId}\n${name}`)),
     attributes,
     source: sourceFor(file, line, anchorId),
@@ -162,25 +166,123 @@ function stripIdentityMetadata(value) {
   return String(value || '')
     .split('\n')
     .filter((line) => !IDENTITY_META_PATTERN.test(line))
-    .filter((line) => !/^\s*(?:entity-id|version-id|predecessor-version|delta-state)\s*:/i.test(line))
+    .filter((line) => !/^\s*(?:entity-id|version-id|predecessor-version|delta-state|external-ref)\s*:/i.test(line))
     .filter((line) => !/^\s*-\s+\*\*(?:realizes|implements|covers|dependsOn|constrains|约束对象|实现需求|覆盖需求|依赖)\*\*\s*[：:]/i.test(line))
     .join('\n')
     .trim();
 }
 
+function parseExternalRefValue(value) {
+  const raw = String(value || '').trim();
+  if (!raw || /^(?:无|none|null|-)$/i.test(raw)) return null;
+  const parts = raw.split(':').map((part) => part.trim()).filter(Boolean);
+  if (parts.length < 3) return null;
+  return {
+    system: parts[0],
+    object_type: parts[1].toLowerCase(),
+    external_id: parts.slice(2).join(':'),
+  };
+}
+
 function identityFromValues(values = {}) {
   const optionalValue = (value) => {
     const normalized = String(value || '').trim();
     return /^(?:无|none|null|-)$/i.test(normalized) ? '' : normalized;
   };
+  const externalRef = parseExternalRefValue(values['external-ref']);
   return {
     entity_id: optionalValue(values['entity-id']),
     version_id: optionalValue(values['version-id']),
     predecessor_version_id: optionalValue(values['predecessor-version']),
     delta_state: String(values['delta-state'] || '').trim(),
+    external_refs: externalRef ? [externalRef] : [],
   };
 }
 
+function flushRequirementRef(requirementRefs, currentRef) {
+  if (!currentRef) return null;
+  const system = currentRef.system;
+  const objectType = currentRef['object-type'] || currentRef.object_type;
+  const externalId = currentRef['external-id'] || currentRef.external_id;
+  if (system && objectType && externalId) {
+    requirementRefs.push({
+      system,
+      object_type: String(objectType).toLowerCase(),
+      external_id: externalId,
+    });
+  }
+  return null;
+}
+
+function parseStructuredFrontmatter(lines) {
+  const flat = {};
+  const requirementRefs = [];
+  const continuity = {};
+  if (!lines.length || lines[0].trim() !== '---') {
+    return { flat, requirementRefs, continuity };
+  }
+  let section = null;
+  let currentRef = null;
+  let currentCap = null;
+  for (let index = 1; index < lines.length; index += 1) {
+    const line = lines[index].replace(/\r$/, '');
+    if (line.trim() === '---') break;
+    const topKey = line.match(/^([A-Za-z0-9_-]+):\s*(.*?)\s*$/);
+    const listItem = line.match(/^\s+-\s+([A-Za-z0-9_-]+):\s*(.*?)\s*$/);
+    const nested = line.match(/^\s{2,}([A-Za-z0-9_-]+):\s*(.*?)\s*$/);
+
+    if (topKey && !/^\s/.test(line)) {
+      currentRef = flushRequirementRef(requirementRefs, currentRef);
+      section = topKey[1].toLowerCase();
+      const value = unwrapScalar(stripInlineYamlComment(topKey[2]));
+      flat[section] = value;
+      currentCap = null;
+      if (section === 'continuity' && value) continuity.kind = value;
+      continue;
+    }
+
+    if (section === 'requirement-refs' && listItem) {
+      currentRef = flushRequirementRef(requirementRefs, currentRef) || {};
+      currentRef = { [listItem[1].toLowerCase()]: unwrapScalar(stripInlineYamlComment(listItem[2])) };
+      continue;
+    }
+
+    if (section === 'requirement-refs' && nested) {
+      currentRef = currentRef || {};
+      currentRef[nested[1].toLowerCase()] = unwrapScalar(stripInlineYamlComment(nested[2]));
+      continue;
+    }
+
+    if (section === 'continuity' && nested) {
+      const key = nested[1].toLowerCase().replace(/-/g, '_');
+      const value = unwrapScalar(stripInlineYamlComment(nested[2]));
+      if (key === 'base_capabilities') {
+        continuity.baseCapabilities = continuity.baseCapabilities || [];
+        currentCap = {};
+        continuity.baseCapabilities.push(currentCap);
+      } else if (currentCap && ['anchor', 'entity_id', 'current_version_id'].includes(key)) {
+        currentCap[key] = value;
+      } else {
+        continuity[key] = value;
+      }
+      continue;
+    }
+
+    if (section === 'continuity' && listItem) {
+      continuity.baseCapabilities = continuity.baseCapabilities || [];
+      if (!currentCap || Object.keys(currentCap).length > 0) {
+        currentCap = {};
+        continuity.baseCapabilities.push(currentCap);
+      }
+      currentCap[listItem[1].toLowerCase().replace(/-/g, '_')] = unwrapScalar(
+        stripInlineYamlComment(listItem[2]),
+      );
+    }
+  }
+  flushRequirementRef(requirementRefs, currentRef);
+  return { flat, requirementRefs, continuity };
+}
+
 function parseIdentityBlock(lines, startIndex, endIndex = lines.length) {
   const values = {};
   let started = false;
@@ -217,8 +319,12 @@ function statementContentEnd(lines, startIndex) {
 }
 
 function parseProposal(target, file, lines, frontmatter) {
-  target.proposalMode = String(frontmatter.mode || '').trim().toLowerCase();
-  const changeId = String(frontmatter['change-id'] || '').trim().toUpperCase();
+  const structured = parseStructuredFrontmatter(lines);
+  const mergedFrontmatter = { ...structured.flat, ...frontmatter };
+  target.proposalMode = String(mergedFrontmatter.mode || '').trim().toLowerCase();
+  target.requirementRefs = structured.requirementRefs;
+  target.continuity = structured.continuity;
+  const changeId = String(mergedFrontmatter['change-id'] || '').trim().toUpperCase();
   if (changeId) {
     addEntity(
       target,
@@ -228,7 +334,7 @@ function parseProposal(target, file, lines, frontmatter) {
       file,
       1,
       { change_name: target.changeName },
-      identityFromValues(frontmatter),
+      identityFromValues(mergedFrontmatter),
       file.content,
     );
     target.changeId = changeId;
@@ -248,6 +354,12 @@ function parseProposal(target, file, lines, frontmatter) {
     if (!match) continue;
     const capabilityId = match[1].toUpperCase();
     const identity = parseIdentityBlock(lines, index + 1);
+    if (structured.requirementRefs.length > 0) {
+      identity.external_refs = [
+        ...(identity.external_refs || []),
+        ...structured.requirementRefs,
+      ];
+    }
     const slug = unwrapScalar(match[2]);
     addEntity(target, 'Capability', capabilityId, slug, file, index + 1, {
       slug,
@@ -570,6 +682,8 @@ function parseChangeArtifacts(projectRoot, changeName, options = {}) {
     changeId: '',
     profile: 'simple',
     proposalMode: '',
+    requirementRefs: [],
+    continuity: {},
     artifacts: [],
     files: files.map((file) => ({ path: file.relativePath, content_hash: file.contentHash })),
     entities: [],

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

@@ -142,6 +142,7 @@ function recordsFor(candidate, facts, sourceRevision) {
       delta_state: entity.delta_state,
       content_hash: entity.content_hash,
       source: entity.source,
+      external_refs: Array.isArray(entity.external_refs) ? entity.external_refs : [],
     }));
 }
 
@@ -263,6 +264,15 @@ function buildIdentityCatalog(projectRoot, options = {}) {
     || String(left.message || '').localeCompare(String(right.message || ''))
   ));
 
+  const byExternalRef = new Map();
+  for (const record of records) {
+    for (const ref of record.external_refs || []) {
+      const key = `${ref.system}|${ref.object_type}|${ref.external_id}`;
+      if (!byExternalRef.has(key)) byExternalRef.set(key, []);
+      byExternalRef.get(key).push(record);
+    }
+  }
+
   return {
     records,
     factsByRoot,
@@ -270,6 +280,7 @@ function buildIdentityCatalog(projectRoot, options = {}) {
     byVersionId: groupBy(records, 'version_id'),
     byAnchor: groupBy(records, 'anchor_id'),
     byPredecessor: groupBy(records, 'predecessor_version_id'),
+    byExternalRef,
     diagnostics,
   };
 }

package/skywalk-sdd/ontology/normalizer.cjs

@@ -20,6 +20,13 @@ function normalizeFacts(parsed) {
     version_id: String(entity.version_id || '').trim().toLowerCase() || undefined,
     predecessor_version_id: String(entity.predecessor_version_id || '').trim().toLowerCase() || undefined,
     delta_state: String(entity.delta_state || '').trim().toLowerCase() || undefined,
+    external_refs: Array.isArray(entity.external_refs)
+      ? entity.external_refs.map((ref) => ({
+        system: String(ref.system || '').trim(),
+        object_type: String(ref.object_type || ref.objectType || '').trim().toLowerCase(),
+        external_id: String(ref.external_id || ref.externalId || '').trim(),
+      })).filter((ref) => ref.system && ref.object_type && ref.external_id)
+      : undefined,
   })).sort((left, right) => (
     compareText(left.id, right.id)
     || compareText(left.type, right.type)
@@ -74,6 +81,10 @@ function normalizeFacts(parsed) {
     change_id: parsed.changeId || undefined,
     profile: parsed.profile,
     proposal_mode: parsed.proposalMode || undefined,
+    requirement_refs: Array.isArray(parsed.requirementRefs) ? parsed.requirementRefs : undefined,
+    continuity: parsed.continuity && Object.keys(parsed.continuity).length > 0
+      ? parsed.continuity
+      : undefined,
     artifacts: (parsed.artifacts || []).slice().sort((left, right) => compareText(left.path, right.path)),
     files: (parsed.files || []).slice().sort((left, right) => compareText(left.path, right.path)),
     entities,

package/skywalk-sdd/ontology/runtime.cjs

@@ -271,6 +271,11 @@ function scanChange(projectRoot, changeName, options = {}) {
     profile,
     identityHistory,
     effectiveGraph,
+    projectRoot,
+    continuityResolutionPath: path.join(
+      parsed.changeDir,
+      'continuity-resolution.json',
+    ),
   });
   const reviewStatus = options.markPending && validation.valid ? 'pending' : 'draft';
   const revisionInput = {

package/skywalk-sdd/ontology/schema.cjs

@@ -104,6 +104,11 @@ const DIAGNOSTIC_CODES = Object.freeze({
   ARCHIVE_NOT_CONFIRMED: 'SEM_ARCHIVE_NOT_CONFIRMED',
   ARCHIVE_REVISION_MISMATCH: 'SEM_ARCHIVE_REVISION_MISMATCH',
   INHERITED_RELATION_MISSING: 'SEM_INHERITED_RELATION_MISSING',
+  EXTERNAL_REF_INVALID: 'EXTERNAL_REF_INVALID',
+  EXTERNAL_REF_TYPE_MISMATCH: 'EXTERNAL_REF_TYPE_MISMATCH',
+  EXTERNAL_REF_CONFLICT: 'EXTERNAL_REF_CONFLICT',
+  CONTINUITY_DECISION_REQUIRED: 'CONTINUITY_DECISION_REQUIRED',
+  CONTINUITY_IDENTITY_MISMATCH: 'CONTINUITY_IDENTITY_MISMATCH',
 });
 
 function normalizeProfile(profile, inferredProfile = 'simple') {

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

@@ -340,6 +340,161 @@ function validateInheritedReferences(facts, diagnostics, identityHistory) {
   }
 }
 
+function validateContinuityAndExternalRefs(facts, diagnostics, options = {}) {
+  const allowed = {
+    requirement: new Set(['Capability']),
+    scenario: new Set(['SpecificationStatement', 'AcceptanceCriterion']),
+    feature: new Set(['Capability']),
+  };
+  const continuity = facts.continuity || {};
+  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',
+      )
+      : '');
+  let resolution = null;
+  if (resolutionPath) {
+    try {
+      const fs = require('fs');
+      if (fs.existsSync(resolutionPath)) {
+        resolution = JSON.parse(fs.readFileSync(resolutionPath, 'utf8'));
+      }
+    } catch {
+      resolution = null;
+    }
+  }
+
+  if (kind === 'iteration') {
+    const caps = (facts.entities || []).filter((entity) => entity.type === 'Capability');
+    for (const capability of caps) {
+      if (!capability.entity_id || !capability.version_id) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.CONTINUITY_IDENTITY_MISMATCH,
+          'error',
+          `Continuity=iteration 时 Capability 缺少 KB 回传身份: ${capability.id}`,
+          {
+            ...sourceContext(capability),
+            entity_id: capability.id,
+            suggestion: '在 propose 用 entities/resolve 回填 entity-id / version-id',
+          },
+        ));
+      }
+    }
+    if (!resolution || resolution.status === 'pending') {
+      diagnostics.push(diagnostic(
+        DIAGNOSTIC_CODES.CONTINUITY_DECISION_REQUIRED,
+        'error',
+        'Continuity=iteration 但 continuity-resolution.json 缺失或仍为 pending',
+        {
+          file: resolutionPath || 'continuity-resolution.json',
+          suggestion: '在 propose/spec 完成 A/B/C 决议后再 check',
+        },
+      ));
+    }
+  }
+
+  if (resolution && resolution.status && resolution.status !== 'pending') {
+    const decisions = [
+      ...(Array.isArray(resolution.capabilities) ? resolution.capabilities : []),
+      ...(Array.isArray(resolution.scenarios) ? resolution.scenarios : []),
+    ];
+    const entitiesByAnchor = new Map(
+      (facts.entities || []).map((entity) => [String(entity.anchor_id || entity.id || '').toUpperCase(), entity]),
+    );
+    for (const decision of decisions) {
+      const anchor = String(decision.anchor || '').toUpperCase();
+      if (!anchor) continue;
+      const entity = entitiesByAnchor.get(anchor);
+      if (!entity) continue;
+      const decisionCode = String(decision.decision || '').toLowerCase();
+      const decidedEntityId = String(decision.entityId || decision.entity_id || '').toLowerCase();
+      const actualEntityId = String(entity.entity_id || '').toLowerCase();
+      if (
+        (decisionCode === 'reuse-existing-identity' || decisionCode === 'reuse_existing' || decisionCode === 'a')
+        && decidedEntityId
+        && actualEntityId
+        && decidedEntityId !== actualEntityId
+      ) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.CONTINUITY_IDENTITY_MISMATCH,
+          'error',
+          `决议复用历史身份但产物仍使用新 entity_id: ${anchor}`,
+          {
+            ...sourceContext(entity),
+            entity_id: entity.id,
+            suggestion: '按 continuity-resolution 回填历史 entity-id / version-id',
+          },
+        ));
+      }
+      if (
+        (decisionCode === 'assign-new-anchor' || decisionCode === 'assign_new' || decisionCode === 'b')
+        && decidedEntityId
+        && actualEntityId
+        && decidedEntityId === actualEntityId
+        && String(decision.notes || '').toLowerCase().includes('new-anchor-required')
+      ) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.CONTINUITY_IDENTITY_MISMATCH,
+          'error',
+          `决议为新对象但仍共用旧锚点/身份: ${anchor}`,
+          {
+            ...sourceContext(entity),
+            entity_id: entity.id,
+            suggestion: '更换新锚点并分配新 entity_id 后重跑 check',
+          },
+        ));
+      }
+    }
+  }
+
+  const bindingKeys = new Map();
+  for (const entity of facts.entities || []) {
+    for (const ref of entity.external_refs || []) {
+      const objectType = String(ref.object_type || '').toLowerCase();
+      const allowedTypes = allowed[objectType];
+      if (!allowedTypes) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_REF_INVALID,
+          'error',
+          `未知 external object_type: ${objectType} (${entity.id})`,
+          { ...sourceContext(entity), entity_id: entity.id },
+        ));
+        continue;
+      }
+      if (!allowedTypes.has(entity.type)) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_REF_TYPE_MISMATCH,
+          'error',
+          `external object_type=${objectType} 与实体类型 ${entity.type} 不匹配: ${entity.id}`,
+          { ...sourceContext(entity), entity_id: entity.id },
+        ));
+      }
+      const key = `${ref.system}|${objectType}|${ref.external_id}|${entity.anchor_id || entity.id}`;
+      const prior = bindingKeys.get(key);
+      if (prior && prior !== entity.entity_id) {
+        diagnostics.push(diagnostic(
+          DIAGNOSTIC_CODES.EXTERNAL_REF_CONFLICT,
+          'error',
+          `同外部键+同锚点绑定了不同 entity_id: ${entity.id}`,
+          {
+            ...sourceContext(entity),
+            entity_id: entity.id,
+            suggestion: '复用历史身份或更换新锚点后重开 entity_id',
+          },
+        ));
+      } else if (entity.entity_id) {
+        bindingKeys.set(key, entity.entity_id);
+      }
+    }
+  }
+}
+
 function validateTraceability(facts, options = {}) {
   const profile = normalizeProfile(options.profile || 'auto', facts.profile || 'simple');
   const graphEntities = options.effectiveGraph && options.effectiveGraph.effective_entities
@@ -356,6 +511,7 @@ function validateTraceability(facts, options = {}) {
   const entitiesById = new Map();
 
   validateArtifactPresence(facts, profile, diagnostics);
+  validateContinuityAndExternalRefs(facts, diagnostics, options);
 
   if (profile === 'strict') {
     for (const artifact of facts.artifacts || []) {

package/templates/openspec/continuity-resolution.example.json

@@ -0,0 +1,32 @@
+{
+  "status": "resolved",
+  "updatedAt": "2026-07-23T00:00:00.000Z",
+  "capabilities": [
+    {
+      "anchor": "CAP-ORDER-CANCEL",
+      "externalKey": {
+        "system": "requirement-mgmt",
+        "objectType": "requirement",
+        "externalId": "REQ-FI-2024-001"
+      },
+      "decision": "reuse-existing-identity",
+      "entityId": "00000000-0000-4000-8000-000000000001",
+      "currentVersionId": "00000000-0000-4000-8000-000000000011",
+      "notes": "propose 阶段 A/B/C：复用历史能力"
+    }
+  ],
+  "scenarios": [
+    {
+      "anchor": "AC-ORDER-CANCEL-001",
+      "externalKey": {
+        "system": "requirement-mgmt",
+        "objectType": "scenario",
+        "externalId": "REQ-FI-2024-001:SCN-req-date-empty-002"
+      },
+      "decision": "reuse-existing-identity",
+      "entityId": "00000000-0000-4000-8000-000000000021",
+      "currentVersionId": "00000000-0000-4000-8000-000000000031",
+      "notes": "spec 阶段场景冲突决议"
+    }
+  ]
+}

package/templates/openspec/proposal.md

@@ -7,6 +7,24 @@ delta-state: "added"
 predecessor-version: "" # added 留空；modified/removed 指向直接前序版本
 mode: "" # full=分 Capability 产物，simple=根目录精简产物
 test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
+# 外部需求键（首轮冷启动也建议写入，便于 ingest 种桥）
+requirement-refs:
+  - system: requirement-mgmt
+    object-type: requirement
+    external-id: REQ-<DOMAIN>-<NNN>
+# Continuity：字段一律来自知识库 resolve，禁止本地 archive 文件夹名
+continuity:
+  kind: new # iteration | similar-reference | new
+  kb-space-id: "" # KB space UUID（iteration 时必填）
+  kb-id: "" # KB UUID（iteration 时必填）
+  base-change-id: "" # 可选，来自 KB source/change_id
+  base-archive-id: "" # 可选溯源（KB archive_id），不是本地目录名
+  base-capabilities: []
+  # iteration 示例：
+  # base-capabilities:
+  #   - anchor: CAP-<CAPABILITY>
+  #     entity-id: <uuid>
+  #     current-version-id: <uuid>
 ---
 
 # proposal.md - 业务意图与上下文总览

package/templates/openspec/spec.md

@@ -34,6 +34,7 @@ capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID
 - **version-id**: <UUID>
 - **delta-state**: added
 - **predecessor-version**: 无
+- **external-ref**: requirement-mgmt:scenario:REQ-<DOMAIN>-<NNN>:SCN-<slug>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
@@ -42,6 +43,7 @@ capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID
 - **version-id**: <UUID>
 - **delta-state**: added
 - **predecessor-version**: 无
+- **external-ref**: requirement-mgmt:scenario:REQ-<DOMAIN>-<NNN>:SCN-<slug>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 
@@ -61,6 +63,7 @@ capability-id: "CAP-<CAPABILITY>" # 必须与 proposal.md 中的 Capability ID
 - **version-id**: <新 UUID>
 - **delta-state**: <modified|added>
 - **predecessor-version**: <modified 时填写；added 为无>
+- **external-ref**: requirement-mgmt:scenario:REQ-<DOMAIN>-<NNN>:SCN-<slug>
 - **当** <!-- 触发条件 -->
 - **预期** <!-- 预期结果 -->
 

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

@@ -108,13 +108,17 @@ node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reas
 该命令成功后必须已经完成：
 - 活动目录 `openspec/changes/<name>/` 被移入 `openspec/changes/archive/<日期>-<name>/`。
 - 归档目录写入 `archive-ontology.json`、`canonical-facts.json`、`conversion-report.json` 和新版 `archive-manifest.json`。
-- 生成知识库可直接消费的 `openspec/changes/archive/<日期>-<name>.zip`，包内文件必须由 manifest 完整列举并通过 SHA-256 校验。
+- 生成知识库可直接消费的 `openspec/changes/archive/<日期>-<name>.zip`（canonical-facts **v2**，含 `external_refs`），包内文件必须由 manifest 完整列举并通过 SHA-256 校验。
 - Full Spec 的 `specs/<capability>/spec.md` 同步到 `openspec/specs/<capability>/spec.md`。
 - archive 阶段写入 `stage_end`。
 - 未勾选 tasks 被写入 `archive_result.task_completion`。
 - 最终中文报告生成到 `openspec/changes/archive/<日期>-<name>/reports/<name>-report.md` 及同名 `<name>-report.html`（默认同时生成 .md 与 .html 双产物，默认归档后 archive 目录，可用 --report-output 自定义）。
 - 执行日志 `openspec/changes/archive/<日期>-<name>/logs/execution-log.md` 随归档整目录迁移（人读审计层）。
 
+### 5.5 收尾入库（opsx-kb-ingest）
+
+归档 zip 生成后，提示用户用知识库技能 **`opsx-kb-ingest`** 上传；成功则写 `ingest-receipt.json`。若返回 `EXTERNAL_REF_CONFLICT`，引导回 spec/check 修正后重入，**禁止**在 KB 内现场改绑。
+
 > 注意：`archive-docs` 成功执行后已经在内部写入 `stage_end`，因此**不要在成功的归档后再单独运行 `node skywalk-sdd/log.cjs end --command=archive ...`**。仅在第 5 步归档命令失败时，才需要运行下方的失败分支 `end`。
 
 如果该命令失败，以失败状态结束 telemetry：

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

@@ -216,6 +216,16 @@ node skywalk-sdd/log.cjs record --type=conformance_review --command=check --proj
 
 ---
 
+## Continuity / external_ref 确定性门禁
+
+`opsx-check` **不联网提问**。Agent 应在 propose/spec 已问完；本阶段只验证并入既有 apply 前门禁：
+
+- Continuity=`iteration` 时每个 CAP 具备 KB 回传 `entity-id` / `version-id`
+- 已写 spec 的 Capability：场景 `external-ref` 与 `continuity-resolution.json` 决议一致；同 key+同锚点未偷偷换 entity_id
+- 用户选「原对象」却仍用新 id、或选「新对象」却仍共用旧锚点 → 失败（`CONTINUITY_IDENTITY_MISMATCH` / `EXTERNAL_REF_CONFLICT`）
+- 决议缺失 / pending / 与产物不一致 → `CONTINUITY_DECISION_REQUIRED`
+- CI/非交互：失败即非零退出并打印修复说明，不挂起等待输入
+
 ## 本体语义关系门禁
 
 在其他质量检查前必须运行：

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

@@ -159,6 +159,27 @@ openspec instructions proposal --change "<name>" --json
 
 > 完整性检查（问题描述/目标/模块/约束 4 项）与缺失补充机制见 `./checklist.md`「§6 需求完整性检查」。发现缺失时主动询问用户补充。
 
+### 6.5 【Continuity】需求 / Capability 身份（只到 CAP，不做场景）
+
+在创建变更目录之后、写 proposal 能力列表之前（或紧接 CAP 编号分配前）：
+
+1. 提取 / 询问外部需求号 `REQ-*`（没有则问一次）。
+2. 调用知识库 **`opsx-ontology-query`**（或薄封装）：
+```bash
+node skywalk-sdd/context-client.cjs --mode=resolve \
+  --external-system=requirement-mgmt \
+  --external-object-type=requirement \
+  --external-id="<REQ-...>" \
+  --entity-type=Capability \
+  --space-id="$ENGINEERING_KB_SPACE_ID" \
+  --kb-id="$ENGINEERING_KB_KB_ID"
+```
+3. 按 KB 结果确认 Continuity：`iteration` / `similar-reference` / `new`；勾选本次涉及的 CAP。
+4. 写入 proposal frontmatter：`requirement-refs` + `continuity`（字段来自 KB：`kb-space-id` / `kb-id` / `base-capabilities[].entity-id` / `current-version-id`）。**禁止**写本地 archive 文件夹名作为 `base-archive`。
+5. CAP 级「同 key + 同锚点、不同 entity_id」当场问 A/B/C；决议写入 `openspec/changes/<name>/continuity-resolution.json` 的 `capabilities[]`。
+6. KB 不可用 → `degraded` 继续，**禁止**扫本地 `archive/` 抄 UUID。预期：恢复后同锚点入库可能触发 `EXTERNAL_REF_CONFLICT`。
+7. **不得**在本阶段生成 STMT/AC/场景或裁决场景身份。
+
 ### 7. 【交互引导】文档拆分模式选择
 
 **❗ 必须主动询问用户，不得默认选择**。Full / Simple / Auto 三种模式的目录结构、适用场景与 AskUserQuestion 文案见 `./reference.md`「§7 文档拆分模式选择」。根据用户选择设置 `mode: full | simple`（Auto 按能力域数量判断），记录到 proposal.md 的 YAML frontmatter。

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

@@ -107,21 +107,31 @@ openspec list
 
 > 上下文类型（需求文档 / 代码文件 / API 文档）与用途见 `./reference.md`「§3 上下文类型与用途」。
 
-**【默认尝试】工程 Spec 知识库上下文**：
+**【默认尝试】工程 Spec 知识库上下文（场景身份主战场）**：
 
-从用户输入、proposal.md 中当前 Capability 的名称、业务目标、边界和约束组成一段自然语言查询。不要要求用户提供 `entity_id`。执行：
+读取 proposal Continuity。对**当前 Capability** 各调一次（「全部」= 循环 N 次，不是一次大查询）：
 
 ```bash
-node skywalk-sdd/context-client.cjs --query="<当前 Capability 的自然语言需求>" --target-stage=spec
+node skywalk-sdd/context-client.cjs \
+  --query="<当前 Capability 的自然语言需求>" \
+  --target-stage=spec \
+  --entity-id="<该 CAP 的 entity_id>" \
+  --external-system=requirement-mgmt \
+  --external-object-type=requirement \
+  --external-id="<REQ-...>" \
+  --space-id="$ENGINEERING_KB_SPACE_ID" \
+  --kb-id="$ENGINEERING_KB_KB_ID"
 ```
 
-- 配置项：`ENGINEERING_KB_API`、`ENGINEERING_KB_SPACE_ID`、可选 `ENGINEERING_KB_TOKEN`。
-- 若返回 `available=false` 或 `degraded=true`，记录降级原因并继续 Spec 流程，不得阻塞。
-- 优先消费 `reuseBundles[].statements` 中的历史 STMT、AC、Constraint；`designElements` 只能作为理解上下文，不能写成 Spec 的 How。
-- `answeredQuestions` 表示历史事实已经覆盖的内容，不要对用户重复提问。
-- 只向用户询问 `clarificationQuestions` 中仍与当前 Capability 有关的问题。
-- `reuseMode=REFERENCE` 只能参考复用，不得复制历史 UUID；只有 `reuseMode=INHERIT` 才允许按本体语义生成契约复用历史身份。
-- 所有知识库内容均为 advisory；若与用户输入、proposal.md 或用户确认冲突，以当前用户确认和 proposal.md 为准。
+- 配置项：`ENGINEERING_KB_API`、`ENGINEERING_KB_SPACE_ID`、`ENGINEERING_KB_KB_ID`、可选 `ENGINEERING_KB_TOKEN`。查询权威技能是知识库 **`opsx-ontology-query`**；本脚本只是薄封装。
+- Continuity=`iteration` 时**必须**带 `--entity-id` + external。
+- **禁止**从本地 `archive/` 抄 UUID 当跨迭代继承源；跨迭代只认 KB current。
+- 若返回 `available=false` / `degraded=true`，记录降级并继续，不得扫本地 archive 兜底。
+- `INHERIT`：unchanged 写继承引用；modified 复用 entity-id + predecessor。`REFERENCE`：只参考，新开身份。
+- reuseBundle / 实体上的 `externalRefs` 写入场景 `external-ref`（`requirement-mgmt:scenario:REQ-…:SCN-…`）。
+- 场景级「同 SCN key + 同锚点、不同 entity_id」在写完该 CAP identity 后、确认文档前**当场问** A/B/C；未决不得进入下一 CAP / design。决议追加到 `continuity-resolution.json` 的 `scenarios[]`。
+- 优先消费 `reuseBundles[].statements`；`designElements` 只作理解上下文，不能写成 Spec 的 How。
+- 所有知识库内容均为 advisory；与用户确认 / proposal 冲突时以当前确认与 proposal 为准。
 
 **【可选】业务知识库检索**：
 术语含义不清且可能影响 spec 准确性时，可调用 **opsx-knowledge** skill。
@@ -203,7 +213,7 @@ node skywalk-sdd/context-client.cjs --query="<当前 Capability 的自然语言
 - 新需求、场景和约束分别使用 `STMT-*`、`AC-*`、`CON-*`；分配规则是同前缀同 Capability 当前最大序号 + 1。
 - 修改已有实体必须复用原 ID；删除实体只写 removal 语义，不得把编号分配给新实体。
 - `added` 必须调用 `semantic-identity --delta-state=added` 生成新的实体 UUID 和版本 UUID；禁止通过复制另一需求的 UUID 创建新实体。
-- `modified/removed` 必须从 Archive 读取历史 `entity-id` 和直接前序 `version-id`，调用 `semantic-identity --delta-state=<modified|removed> --entity-id=<UUID> --predecessor-version=<UUID>`；实体 UUID 复用，版本 UUID 新建。
+- `modified/removed` 必须从 **KB**（match-requirement / resolve）取得历史 `entity-id` 和直接前序 `version-id`，调用 `semantic-identity --delta-state=<modified|removed> --entity-id=<UUID> --predecessor-version=<UUID>`；实体 UUID 复用，版本 UUID 新建。禁止把本地 archive 目录当跨迭代继承权威。
 - AC 必须嵌套在所属 STMT 下；CON 必须通过 `**constrains**` 显式引用 STMT。
 - 对 `reuseMode=REFERENCE` 的历史候选必须创建新的实体身份；禁止因为内容相似而复用历史 `entity-id`。
 - 对 `reuseMode=INHERIT` 的历史事实，必须使用返回的实体与版本来源完成 unchanged/modified 身份参数校验。