openxiangda 1.0.138 → 1.0.140

package/lib/sdd.js

@@ -5,23 +5,32 @@ const os = require('os');
 const DEFAULT_SDD_DIR = 'openspec';
 const SDD_CONFIG_FILE = 'config.yaml';
 const CHANGE_META_FILE = 'change.json';
+const COVERAGE_FILE = 'coverage.json';
+const RELEASE_FILE = 'release.json';
 const BYPASS_LOG_FILE = path.join('changes', 'bypass-log.md');
+const SDD_SCHEMA_VERSION = 'openxiangda-sdd-v2';
+const LEGACY_SDD_SCHEMA_VERSION = 'openxiangda-sdd-v1';
 
-const DEFAULT_SPEC_CONTENT = `# OpenXiangda Platform Specification
+const DEFAULT_SPEC_CONTENT = `# Application Specification
 
-This file is the current behavior contract for this application workspace.
+This directory is the source of truth for this application's agreed behavior.
 
-## Requirements
+## Purpose
+
+Record user-facing behavior, data rules, permissions, workflows, automations, and runtime contracts for this OpenXiangda application. Platform governance rules live in OpenXiangda skills and references, not in this application spec.
 
-### Requirement: SDD-governed high-risk changes
-High-risk OpenXiangda changes MUST be attached to an approved change before publishing.
+## Requirements
 
-#### Scenario: AI starts high-risk development
-- **Given** a requested change touches forms, pages, resources, functions, automations, workflows, runtime, or platform contracts
-- **When** the AI prepares implementation or release
-- **Then** it reads \`openxiangda sdd context --json\`, creates or continues a change, and waits for \`openxiangda sdd approve <change>\`
 `;
 
+const PLACEHOLDER_PATTERNS = [
+  /\bTODO\b/i,
+  /\bTBD\b/i,
+  /Describe the behavior/i,
+  /填写|补充|待确认/,
+  /-\s*\*\*(Given|When|Then)\*\*\s*$/im,
+];
+
 function nowIso() {
   return new Date().toISOString();
 }
@@ -47,6 +56,15 @@ function normalizeChangeId(value) {
   return id;
 }
 
+function slug(value, fallback = 'item') {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return normalized || fallback;
+}
+
 function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true });
 }
@@ -98,6 +116,13 @@ function extractSddBlock(configText) {
   return '';
 }
 
+function readConfigYamlSchema(rootDir) {
+  const file = path.join(rootDir, SDD_CONFIG_FILE);
+  if (!fs.existsSync(file)) return null;
+  const content = fs.readFileSync(file, 'utf8');
+  return content.match(/^\s*schema\s*:\s*([^\s#]+)/m)?.[1] || null;
+}
+
 function getSddGovernanceConfig(options = {}) {
   const cwd = options.cwd || process.cwd();
   const configText = options.configText || '';
@@ -114,12 +139,17 @@ function getSddGovernanceConfig(options = {}) {
       ? false
       : enabled;
   const pathMatch = block.match(/path\s*:\s*['"]([^'"]+)['"]/);
+  const schemaMatch = block.match(/schemaVersion\s*:\s*['"]([^'"]+)['"]/);
   const sddPath = normalizeRelPath(pathMatch?.[1] || DEFAULT_SDD_DIR);
   const rootDir = path.join(cwd, sddPath);
   const initialized =
     fs.existsSync(path.join(rootDir, SDD_CONFIG_FILE)) ||
     fs.existsSync(path.join(rootDir, 'specs')) ||
     fs.existsSync(path.join(rootDir, 'changes'));
+  const schemaVersion =
+    schemaMatch?.[1] ||
+    readConfigYamlSchema(rootDir) ||
+    (initialized ? LEGACY_SDD_SCHEMA_VERSION : SDD_SCHEMA_VERSION);
   return {
     enabled,
     strictHighRisk,
@@ -127,23 +157,29 @@ function getSddGovernanceConfig(options = {}) {
     rootDir,
     initialized,
     configured,
+    schemaVersion,
     source: configured ? 'app-workspace.config.ts' : initialized ? 'openspec' : 'none',
   };
 }
 
 function buildDefaultConfigYaml() {
   return [
-    'schema: openxiangda-sdd-v1',
+    `schema: ${SDD_SCHEMA_VERSION}`,
     'description: OpenXiangda native SDD workspace records inspired by OpenSpec.',
     'artifacts:',
     '  proposal: proposal.md',
+    '  specs: specs/**/*.md',
     '  design: design.md',
     '  tasks: tasks.md',
     '  evidence: evidence.md',
+    '  coverage: coverage.json',
+    '  release: release.json',
     '  metadata: change.json',
     'rules:',
     '  requireApprovalForHighRisk: true',
     '  requireAffectedCoverage: true',
+    '  requireCoverageManifest: true',
+    '  requireScenarioEvidence: true',
     '  archiveMergesDeltaSpecs: true',
     '',
   ].join('\n');
@@ -154,16 +190,16 @@ function initSddWorkspace(options = {}) {
   const sddPath = normalizeRelPath(options.path || DEFAULT_SDD_DIR);
   const rootDir = path.join(cwd, sddPath);
   const operations = [];
-  const force = Boolean(options.force);
+  const force = Boolean(options.force || options.upgrade);
 
   ensureDir(rootDir);
   ensureDir(path.join(rootDir, 'changes'));
   ensureDir(path.join(rootDir, 'changes', 'archive'));
-  ensureDir(path.join(rootDir, 'specs', 'platform'));
+  ensureDir(path.join(rootDir, 'specs', 'app'));
   ensureDir(path.join(rootDir, 'templates', 'change'));
 
   writeFileIfMissing(path.join(rootDir, SDD_CONFIG_FILE), buildDefaultConfigYaml(), operations, force);
-  writeFileIfMissing(path.join(rootDir, 'specs', 'platform', 'spec.md'), DEFAULT_SPEC_CONTENT, operations, false);
+  writeFileIfMissing(path.join(rootDir, 'specs', 'app', 'spec.md'), DEFAULT_SPEC_CONTENT, operations, false);
   writeFileIfMissing(path.join(rootDir, 'changes', '.gitkeep'), '', operations, false);
   writeFileIfMissing(path.join(rootDir, 'changes', 'archive', '.gitkeep'), '', operations, false);
   writeFileIfMissing(
@@ -173,10 +209,11 @@ function initSddWorkspace(options = {}) {
       '',
       'Create changes with `openxiangda sdd propose <change-id>`.',
       'High-risk implementation starts only after `openxiangda sdd approve <change-id>`.',
+      'Before release, `coverage.json`, `release.json`, `tasks.md`, delta specs, and `evidence.md` must pass `openxiangda sdd verify <change> --changed`.',
       '',
     ].join('\n'),
     operations,
-    false
+    force
   );
 
   return {
@@ -184,6 +221,7 @@ function initSddWorkspace(options = {}) {
     path: sddPath,
     rootDir,
     initialized: true,
+    schemaVersion: SDD_SCHEMA_VERSION,
     operations: operations.map(item => ({
       path: path.relative(cwd, item.path).replace(/\\/g, '/'),
       action: item.action,
@@ -230,11 +268,13 @@ function listChangeDirs(rootDir, includeArchive = false) {
 function readChange(changeDir) {
   const meta = readJsonFile(path.join(changeDir, CHANGE_META_FILE), null);
   const id = meta?.id || path.basename(changeDir);
+  const coverage = readJsonFile(path.join(changeDir, COVERAGE_FILE), null);
   return {
     id,
     dir: changeDir,
     relativeDir: changeDir.split(path.sep).slice(-2).join('/'),
     metadata: meta,
+    coverage,
     valid: Boolean(meta && !meta.__invalid),
   };
 }
@@ -258,6 +298,11 @@ function normalizeAffected(input = {}) {
   return {
     forms: splitList(affected.forms || affected.form),
     pages: splitList(affected.pages || affected.page),
+    functions: splitList(affected.functions || affected.function),
+    automations: splitList(affected.automations || affected.automation),
+    workflows: splitList(affected.workflows || affected.workflow),
+    jsCodeNodes: splitList(affected.jsCodeNodes || affected.jsCode || affected['js-code-nodes']),
+    files: splitList(affected.files || affected.file),
     resources: affected.resources === true || affected.resources === 'true' || splitList(affected.resources).includes('*'),
     runtime: affected.runtime === true || affected.runtime === 'true',
     backend: affected.backend === true || affected.backend === 'true',
@@ -267,6 +312,7 @@ function normalizeAffected(input = {}) {
 
 function createChangeMetadata(changeId, options = {}) {
   return {
+    schemaVersion: SDD_SCHEMA_VERSION,
     id: changeId,
     title: options.title || changeId,
     status: 'proposed',
@@ -288,24 +334,35 @@ function createChangeMetadata(changeId, options = {}) {
   };
 }
 
+function formatAffectedList(items) {
+  return items.length ? items.join(', ') : '(none)';
+}
+
 function createProposalContent(meta) {
   return `# Proposal: ${meta.title}
 
-## Why
+## Intent
 
-- 
+Deliver "${meta.title}" as one focused OpenXiangda application change.
 
-## What Changes
+## Scope
 
-- 
+- Forms: ${formatAffectedList(meta.affected.forms)}
+- Pages: ${formatAffectedList(meta.affected.pages)}
+- Resources: ${meta.affected.resources ? 'yes' : 'no'}
+- Runtime: ${meta.affected.runtime ? 'yes' : 'no'}
+- Backend logic: ${meta.affected.backend ? 'yes' : 'no'}
 
 ## Out Of Scope
 
-- 
+- Platform-level governance changes.
+- Unrelated application behavior outside the affected resources above.
 
-## Risks
+## Acceptance
 
-- 
+- Requirements in \`specs/**/spec.md\` describe the user-visible behavior.
+- \`coverage.json\` maps requirements and scenarios to affected resources.
+- \`evidence.md\` records verification commands before release.
 `;
 }
 
@@ -314,20 +371,26 @@ function createDesignContent(meta) {
 
 ## OpenXiangda Resource Impact
 
-- Forms: ${meta.affected.forms.join(', ') || '(none)'}
-- Pages: ${meta.affected.pages.join(', ') || '(none)'}
+- Forms: ${formatAffectedList(meta.affected.forms)}
+- Pages: ${formatAffectedList(meta.affected.pages)}
+- Functions: ${formatAffectedList(meta.affected.functions)}
+- Automations: ${formatAffectedList(meta.affected.automations)}
+- Workflows: ${formatAffectedList(meta.affected.workflows)}
+- JS_CODE nodes: ${formatAffectedList(meta.affected.jsCodeNodes)}
 - Resources: ${meta.affected.resources ? 'yes' : 'no'}
 - Runtime: ${meta.affected.runtime ? 'yes' : 'no'}
-- Backend/App Function/Automation logic: ${meta.affected.backend ? 'yes' : 'no'}
-- Contracts: ${meta.affected.contracts ? 'yes' : 'no'}
+- Contracts/config: ${meta.affected.contracts ? 'yes' : 'no'}
 
 ## Data And Contract Notes
 
-- 
+- Keep application specs focused on observable behavior; implementation details stay here or in source code.
+- Resource IDs remain profile-local under \`.openxiangda/state.json\`.
 
 ## Publish Plan
 
-- Run \`openxiangda workspace plan --changed\` before publish.
+- Run \`openxiangda sdd verify ${meta.id} --changed\`.
+- Run \`openxiangda workspace check --changed\`.
+- Publish with the commands recorded in \`release.json\`.
 `;
 }
 
@@ -336,8 +399,11 @@ function createTasksContent() {
     '# Tasks',
     '',
     '- [ ] Confirm proposal and affected scope',
+    '- [ ] Sharpen delta specs into behavior-first requirements and scenarios',
     '- [ ] Implement changes',
-    '- [ ] Run `openxiangda sdd verify <change>`',
+    '- [ ] Update coverage.json if affected resources change',
+    '- [ ] Record verification evidence',
+    '- [ ] Run `openxiangda sdd verify <change> --changed`',
     '- [ ] Run release plan/check commands',
     '- [ ] Archive the change after release',
     '',
@@ -350,11 +416,12 @@ function createEvidenceContent() {
     '',
     '## Verification',
     '',
-    '- ',
+    '- [ ] Record `openxiangda sdd verify <change> --changed` result',
+    '- [ ] Record workspace/resource/runtime check or dry-run output',
     '',
     '## Release',
     '',
-    '- ',
+    '- [ ] Record publish/deploy command output or explain why this change was not released',
     '',
     '## Bypass Log',
     '',
@@ -369,39 +436,118 @@ function createDeltaSpecContent(meta, domain) {
 ## ADDED Requirements
 
 ### Requirement: ${meta.title}
-Describe the behavior that will be true after this change.
+The application SHALL provide the approved "${meta.title}" behavior for the affected OpenXiangda resources.
 
 #### Scenario: Main path
-- **Given** 
-- **When** 
-- **Then** 
+- **Given** an authorized user is using the affected application area
+- **When** the user follows the approved ${meta.title} workflow
+- **Then** the application produces the expected business result without relying on mock data or frontend-only authorization
 `;
 }
 
+function createCoverageManifest(meta, domain) {
+  const reqId = `req-${slug(meta.title || meta.id, meta.id)}`;
+  return {
+    schemaVersion: SDD_SCHEMA_VERSION,
+    changeId: meta.id,
+    generatedAt: nowIso(),
+    resources: {
+      forms: meta.affected.forms,
+      pages: meta.affected.pages,
+      functions: meta.affected.functions,
+      automations: meta.affected.automations,
+      workflows: meta.affected.workflows,
+      jsCodeNodes: meta.affected.jsCodeNodes,
+      resources: meta.affected.resources,
+      runtime: meta.affected.runtime,
+      backend: meta.affected.backend,
+      contracts: meta.affected.contracts,
+      files: meta.affected.files,
+    },
+    requirements: [
+      {
+        id: reqId,
+        title: meta.title,
+        spec: `specs/${domain}/spec.md`,
+        scenarios: [
+          {
+            id: 'main-path',
+            title: 'Main path',
+            evidence: [],
+          },
+        ],
+        covers: {
+          forms: meta.affected.forms,
+          pages: meta.affected.pages,
+          functions: meta.affected.functions,
+          automations: meta.affected.automations,
+          workflows: meta.affected.workflows,
+          jsCodeNodes: meta.affected.jsCodeNodes,
+          resources: meta.affected.resources,
+          runtime: meta.affected.runtime,
+          backend: meta.affected.backend,
+          contracts: meta.affected.contracts,
+          files: meta.affected.files,
+        },
+      },
+    ],
+  };
+}
+
+function createReleaseManifest(meta) {
+  return {
+    schemaVersion: SDD_SCHEMA_VERSION,
+    changeId: meta.id,
+    targets: {
+      forms: meta.affected.forms,
+      pages: meta.affected.pages,
+      resources: meta.affected.resources,
+      runtime: meta.affected.runtime,
+      other: [],
+    },
+    changedFiles: [],
+    commands: [],
+    verifiedAt: null,
+  };
+}
+
 function proposeSddChange(options = {}) {
   const governance = getSddGovernanceConfig(options);
   if (!governance.initialized) initSddWorkspace({ cwd: options.cwd, path: governance.path });
   const changeId = normalizeChangeId(options.changeId);
   const rootDir = governance.rootDir;
+  const domain = options.domain || 'app';
   const changeDir = path.join(rootDir, 'changes', changeId);
   if (fs.existsSync(changeDir) && !options.force) {
     throw new Error(`change 已存在: ${changeId}`);
   }
   ensureDir(changeDir);
-  ensureDir(path.join(changeDir, 'specs', options.domain || 'app'));
+  ensureDir(path.join(changeDir, 'specs', domain));
   const meta = createChangeMetadata(changeId, options);
+  const coverage = createCoverageManifest(meta, domain);
+  const release = createReleaseManifest(meta);
   writeJsonFile(path.join(changeDir, CHANGE_META_FILE), meta);
+  writeJsonFile(path.join(changeDir, COVERAGE_FILE), coverage);
+  writeJsonFile(path.join(changeDir, RELEASE_FILE), release);
   fs.writeFileSync(path.join(changeDir, 'proposal.md'), createProposalContent(meta));
   fs.writeFileSync(path.join(changeDir, 'design.md'), createDesignContent(meta));
   fs.writeFileSync(path.join(changeDir, 'tasks.md'), createTasksContent());
   fs.writeFileSync(path.join(changeDir, 'evidence.md'), createEvidenceContent());
   fs.writeFileSync(
-    path.join(changeDir, 'specs', options.domain || 'app', 'spec.md'),
-    createDeltaSpecContent(meta, options.domain || 'app')
+    path.join(changeDir, 'specs', domain, 'spec.md'),
+    createDeltaSpecContent(meta, domain)
   );
   return {
+    schemaVersion: SDD_SCHEMA_VERSION,
     change: meta,
+    coverage,
+    release,
     dir: path.relative(options.cwd || process.cwd(), changeDir).replace(/\\/g, '/'),
+    nextActions: [
+      `Review openspec/changes/${changeId}/proposal.md`,
+      `Sharpen openspec/changes/${changeId}/specs/${domain}/spec.md`,
+      `Run openxiangda sdd approve ${changeId} after user confirmation`,
+    ],
   };
 }
 
@@ -415,13 +561,28 @@ function loadSddChange(options = {}) {
   if (!meta || meta.__invalid) {
     throw new Error(`change metadata 无效: ${metaFile}`);
   }
-  return { governance, changeId, changeDir, meta, metaFile };
+  const coverageFile = path.join(changeDir, COVERAGE_FILE);
+  const releaseFile = path.join(changeDir, RELEASE_FILE);
+  const coverage = readJsonFile(coverageFile, null);
+  const release = readJsonFile(releaseFile, null);
+  return {
+    governance,
+    changeId,
+    changeDir,
+    meta,
+    metaFile,
+    coverage,
+    coverageFile,
+    release,
+    releaseFile,
+  };
 }
 
 function approveSddChange(options = {}) {
   const loaded = loadSddChange(options);
   const meta = {
     ...loaded.meta,
+    schemaVersion: loaded.meta.schemaVersion || loaded.governance.schemaVersion || LEGACY_SDD_SCHEMA_VERSION,
     status: 'approved',
     approvedAt: nowIso(),
     approvedBy: options.approvedBy || os.userInfo().username || 'unknown',
@@ -430,15 +591,22 @@ function approveSddChange(options = {}) {
   };
   writeJsonFile(loaded.metaFile, meta);
   return {
+    schemaVersion: meta.schemaVersion,
     change: meta,
+    coverage: loaded.coverage,
     dir: path.relative(options.cwd || process.cwd(), loaded.changeDir).replace(/\\/g, '/'),
+    nextActions: [
+      `Implement only the approved scope in openspec/changes/${loaded.changeId}`,
+      `Complete tasks.md and evidence.md`,
+      `Run openxiangda sdd verify ${loaded.changeId} --changed before release`,
+    ],
   };
 }
 
 function includesAll(list, required) {
   if (!required || required.length === 0) return true;
-  if (list.includes('*')) return true;
-  return required.every(item => list.includes(item));
+  if ((list || []).includes('*')) return true;
+  return required.every(item => (list || []).includes(item));
 }
 
 function hasHighRiskTargets(targets = {}) {
@@ -491,6 +659,7 @@ function affectedCoversHighRiskFiles(affected, files = []) {
   const normalized = normalizeAffected(affected);
   const missing = [];
   for (const file of files) {
+    if (includesAll(normalized.files, [file])) continue;
     if (file === 'app-workspace.config.ts' && !normalized.contracts && !normalized.runtime) {
       missing.push(file);
     } else if (file.startsWith('src/forms/')) {
@@ -501,15 +670,18 @@ function affectedCoversHighRiskFiles(affected, files = []) {
       if (!normalized.runtime && !includesAll(normalized.pages, [pageCode])) missing.push(file);
     } else if (file.startsWith('src/resources/') && !normalized.resources) {
       missing.push(file);
-    } else if (
-      (file.startsWith('src/functions/') ||
-        file.startsWith('src/automations/') ||
-        file.startsWith('src/workflows/') ||
-        file.startsWith('src/js-code-nodes/')) &&
-      !normalized.backend &&
-      !normalized.resources
-    ) {
-      missing.push(file);
+    } else if (file.startsWith('src/functions/')) {
+      const code = file.split('/')[2];
+      if (!normalized.backend && !normalized.resources && !includesAll(normalized.functions, [code])) missing.push(file);
+    } else if (file.startsWith('src/automations/')) {
+      const code = file.split('/')[2];
+      if (!normalized.backend && !normalized.resources && !includesAll(normalized.automations, [code])) missing.push(file);
+    } else if (file.startsWith('src/workflows/')) {
+      const code = file.split('/')[2];
+      if (!normalized.backend && !normalized.resources && !includesAll(normalized.workflows, [code])) missing.push(file);
+    } else if (file.startsWith('src/js-code-nodes/')) {
+      const code = file.split('/')[2];
+      if (!normalized.backend && !normalized.resources && !includesAll(normalized.jsCodeNodes, [code])) missing.push(file);
     } else if (file.startsWith('src/runtime/') && !normalized.runtime) {
       missing.push(file);
     }
@@ -520,10 +692,137 @@ function affectedCoversHighRiskFiles(affected, files = []) {
   };
 }
 
+function normalizeCoverageResources(coverage, fallbackAffected = {}, options = {}) {
+  const fallback = options.allowFallback ? normalizeAffected(fallbackAffected) : normalizeAffected({});
+  const resources = coverage?.resources || {};
+  const requirementCovers = Array.isArray(coverage?.requirements)
+    ? coverage.requirements.map(item => item.covers || {})
+    : [];
+  const mergeList = key => [
+    ...splitList(resources[key]),
+    ...requirementCovers.flatMap(item => splitList(item[key])),
+    ...fallback[key],
+  ];
+  const hasBool = key =>
+    resources[key] === true ||
+    resources[key] === 'true' ||
+    requirementCovers.some(item => item[key] === true || item[key] === 'true') ||
+    Boolean(fallback[key]);
+  return {
+    forms: Array.from(new Set(mergeList('forms'))),
+    pages: Array.from(new Set(mergeList('pages'))),
+    functions: Array.from(new Set(mergeList('functions'))),
+    automations: Array.from(new Set(mergeList('automations'))),
+    workflows: Array.from(new Set(mergeList('workflows'))),
+    jsCodeNodes: Array.from(new Set(mergeList('jsCodeNodes'))),
+    files: Array.from(new Set(mergeList('files'))),
+    resources: hasBool('resources'),
+    runtime: hasBool('runtime'),
+    backend: hasBool('backend'),
+    contracts: hasBool('contracts'),
+  };
+}
+
+function coverageCoversTargets(coverage, affected, targets = {}, options = {}) {
+  return affectedCoversTargets(normalizeCoverageResources(coverage, affected, options), targets);
+}
+
+function coverageCoversHighRiskFiles(coverage, affected, files = [], options = {}) {
+  return affectedCoversHighRiskFiles(normalizeCoverageResources(coverage, affected, options), files);
+}
+
 function getApprovedActiveChanges(rootDir) {
   return listChanges(rootDir)
     .filter(item => item.valid && item.metadata.status === 'approved' && item.metadata.approvedAt)
-    .map(item => item.metadata);
+    .map(item => ({
+      ...item.metadata,
+      coverage: item.coverage,
+    }));
+}
+
+function summarizeSpecFile(rootDir, file) {
+  const content = fs.readFileSync(file, 'utf8');
+  const rel = path.relative(path.join(rootDir, 'specs'), file).replace(/\\/g, '/');
+  const title = content.match(/^#\s+(.+)$/m)?.[1] || rel;
+  const purposeIndex = content.indexOf('## Purpose');
+  let purpose = '';
+  if (purposeIndex >= 0) {
+    purpose = content
+      .slice(purposeIndex)
+      .split(/\r?\n/)
+      .slice(1)
+      .find(line => line.trim() && !line.startsWith('#')) || '';
+  }
+  return {
+    path: `specs/${rel}`,
+    title,
+    purpose: purpose.trim(),
+    requirementCount: (content.match(/^### Requirement:/gm) || []).length,
+  };
+}
+
+function summarizeChange(cwd, item) {
+  return {
+    id: item.id,
+    status: item.metadata?.status || 'invalid',
+    approvedAt: item.metadata?.approvedAt || null,
+    schemaVersion: item.metadata?.schemaVersion || LEGACY_SDD_SCHEMA_VERSION,
+    affected: item.metadata?.affected || null,
+    coverage: summarizeCoverage(item.coverage),
+    dir: path.relative(cwd, item.dir).replace(/\\/g, '/'),
+  };
+}
+
+function summarizeCoverage(coverage) {
+  if (!coverage || coverage.__invalid) return null;
+  const resources = normalizeCoverageResources(coverage, {});
+  return {
+    requirements: Array.isArray(coverage.requirements) ? coverage.requirements.length : 0,
+    forms: resources.forms,
+    pages: resources.pages,
+    functions: resources.functions,
+    automations: resources.automations,
+    workflows: resources.workflows,
+    jsCodeNodes: resources.jsCodeNodes,
+    resources: resources.resources,
+    runtime: resources.runtime,
+  };
+}
+
+function chooseActiveChange(changes, targets = {}, highRiskFiles = []) {
+  const candidates = changes
+    .filter(item => item.valid && !['archived', 'rejected'].includes(item.metadata.status))
+    .filter(item => item.metadata.status === 'approved' && item.metadata.approvedAt);
+  return (
+    candidates.find(item => {
+      const legacyMode = (item.metadata?.schemaVersion || LEGACY_SDD_SCHEMA_VERSION) !== SDD_SCHEMA_VERSION;
+      const allowFallback = legacyMode && (!item.coverage || item.coverage.__invalid);
+      return (
+        coverageCoversTargets(item.coverage, item.metadata.affected, targets, { allowFallback }).covered &&
+        coverageCoversHighRiskFiles(item.coverage, item.metadata.affected, highRiskFiles, { allowFallback }).covered
+      );
+    }) || candidates[0] || null
+  );
+}
+
+function buildNextActions(governance, activeChanges, activeChange, targets, highRiskFiles) {
+  if (!governance.enabled) return ['Enable SDD governance or run without SDD for low-risk work.'];
+  if (!governance.initialized) return ['Run `openxiangda sdd init --upgrade`.'];
+  if (hasHighRiskTargets(targets) || highRiskFiles.length > 0) {
+    if (!activeChanges.length) return ['Run `openxiangda sdd propose <change>` before editing high-risk files.'];
+    if (!activeChange) return ['Approve or create an SDD change whose coverage matches the changed resources.'];
+    if (activeChange.metadata?.status !== 'approved') {
+      return [`Run \`openxiangda sdd approve ${activeChange.id}\` after user confirmation.`];
+    }
+    return [
+      `Complete openspec/changes/${activeChange.id}/tasks.md and evidence.md`,
+      `Run openxiangda sdd verify ${activeChange.id} --changed`,
+      `Archive with openxiangda sdd archive ${activeChange.id} after release`,
+    ];
+  }
+  return activeChanges.length
+    ? ['Continue or archive active SDD changes when finished.']
+    : ['No high-risk SDD action required for the current release target.'];
 }
 
 function buildSddGovernanceReport(options = {}) {
@@ -535,15 +834,30 @@ function buildSddGovernanceReport(options = {}) {
   const warnings = [];
   const errors = [];
   let activeChanges = [];
+  let activeChange = null;
+  let coverage = null;
 
   if (!governance.enabled) {
     warnings.push('未启用 SDD governance；运行 openxiangda sdd init 可开启高风险变更记录。');
     checks.push({ name: 'sdd', status: 'warn', message: warnings[0] });
-    return { governance, highRiskFiles, activeChanges, checks, warnings, errors };
+    return {
+      schemaVersion: governance.schemaVersion,
+      governance,
+      releaseTargets: targets,
+      highRiskFiles,
+      activeChange,
+      coverage,
+      activeChanges,
+      checks,
+      warnings,
+      errors,
+      blockingErrors: errors,
+      nextActions: buildNextActions(governance, activeChanges, activeChange, targets, highRiskFiles),
+    };
   }
 
   if (!governance.initialized) {
-    const message = `SDD 已配置但未初始化: ${governance.path}。运行 openxiangda sdd init`;
+    const message = `SDD 已配置但未初始化: ${governance.path}。运行 openxiangda sdd init --upgrade`;
     if (governance.strictHighRisk && (hasHighRiskTargets(targets) || highRiskFiles.length > 0)) {
       errors.push({ name: 'sdd-not-initialized', message });
       checks.push({ name: 'sdd', status: 'error', message });
@@ -551,16 +865,45 @@ function buildSddGovernanceReport(options = {}) {
       warnings.push(message);
       checks.push({ name: 'sdd', status: 'warn', message });
     }
-    return { governance, highRiskFiles, activeChanges, checks, warnings, errors };
+    return {
+      schemaVersion: governance.schemaVersion,
+      governance,
+      releaseTargets: targets,
+      highRiskFiles,
+      activeChange,
+      coverage,
+      activeChanges,
+      checks,
+      warnings,
+      errors,
+      blockingErrors: errors,
+      nextActions: buildNextActions(governance, activeChanges, activeChange, targets, highRiskFiles),
+    };
   }
 
-  activeChanges = listChanges(governance.rootDir).filter(
+  const changes = listChanges(governance.rootDir);
+  activeChanges = changes.filter(
     item => item.valid && !['archived', 'rejected'].includes(item.metadata.status)
   );
+  activeChange = chooseActiveChange(activeChanges, targets, highRiskFiles);
+  coverage = activeChange?.coverage || null;
   const approved = getApprovedActiveChanges(governance.rootDir);
   if (!governance.strictHighRisk || (!hasHighRiskTargets(targets) && highRiskFiles.length === 0)) {
     checks.push({ name: 'sdd', status: 'ok', message: `${activeChanges.length} active changes` });
-    return { governance, highRiskFiles, activeChanges, checks, warnings, errors };
+    return {
+      schemaVersion: governance.schemaVersion,
+      governance,
+      releaseTargets: targets,
+      highRiskFiles,
+      activeChange: activeChange ? summarizeChange(options.cwd || process.cwd(), activeChange) : null,
+      coverage: summarizeCoverage(coverage),
+      activeChanges: activeChanges.map(item => summarizeChange(options.cwd || process.cwd(), item)),
+      checks,
+      warnings,
+      errors,
+      blockingErrors: errors,
+      nextActions: buildNextActions(governance, activeChanges, activeChange, targets, highRiskFiles),
+    };
   }
 
   if (approved.length === 0) {
@@ -568,20 +911,27 @@ function buildSddGovernanceReport(options = {}) {
       name: 'sdd-approved-change-required',
       message: '高风险变更发布前必须存在 approved SDD change；先运行 openxiangda sdd propose <change> 并经 openxiangda sdd approve <change> 确认。',
     });
+  } else if (!activeChange) {
+    errors.push({
+      name: 'sdd-coverage-required',
+      message: 'approved SDD change 的 coverage.json 未覆盖本次发布目标或高风险文件。',
+    });
   } else {
-    const targetCovered = approved.some(change => affectedCoversTargets(change.affected, targets).covered);
-    const fileCovered = approved.some(change => affectedCoversHighRiskFiles(change.affected, highRiskFiles).covered);
-    if (hasHighRiskTargets(targets) && !targetCovered) {
-      errors.push({
-        name: 'sdd-affected-targets-missing',
-        message: 'approved SDD change 的 affected 未覆盖本次发布目标。',
-      });
-    }
-    if (highRiskFiles.length > 0 && !fileCovered) {
-      errors.push({
-        name: 'sdd-affected-files-missing',
-        message: 'approved SDD change 的 affected 未覆盖本次高风险文件变更。',
-      });
+    const verify = verifySddChange({
+      cwd: options.cwd,
+      configText: options.configText,
+      changeId: activeChange.id,
+      targets,
+      files,
+      releasePlan: {
+        targets,
+        changedFiles: files,
+        commands: options.commands || [],
+      },
+    });
+    if (!verify.passed) {
+      errors.push(...verify.errors);
+      warnings.push(...verify.warnings.map(item => `${item.name}: ${item.message}`));
     }
   }
 
@@ -590,24 +940,232 @@ function buildSddGovernanceReport(options = {}) {
     status: errors.length > 0 ? 'error' : 'ok',
     message: errors.length > 0 ? `${errors.length} 个 SDD gate 错误` : `${approved.length} approved active changes`,
   });
-  return { governance, highRiskFiles, activeChanges, checks, warnings, errors };
+  return {
+    schemaVersion: governance.schemaVersion,
+    governance,
+    releaseTargets: targets,
+    highRiskFiles,
+    activeChange: activeChange ? summarizeChange(options.cwd || process.cwd(), activeChange) : null,
+    coverage: summarizeCoverage(coverage),
+    activeChanges: activeChanges.map(item => summarizeChange(options.cwd || process.cwd(), item)),
+    checks,
+    warnings,
+    errors,
+    blockingErrors: errors,
+    nextActions: buildNextActions(governance, activeChanges, activeChange, targets, highRiskFiles),
+  };
 }
 
-function readUncheckedTasks(changeDir) {
-  const file = path.join(changeDir, 'tasks.md');
-  if (!fs.existsSync(file)) return ['tasks.md 缺失'];
+function readUncheckedChecklist(file, missingMessage) {
+  if (!fs.existsSync(file)) return [missingMessage || `${path.basename(file)} 缺失`];
   return fs
     .readFileSync(file, 'utf8')
     .split(/\r?\n/)
     .map((line, index) => ({ line, index: index + 1 }))
     .filter(item => /^-\s*\[\s\]/.test(item.line))
-    .map(item => `tasks.md:${item.index} ${item.line}`);
+    .map(item => `${path.basename(file)}:${item.index} ${item.line}`);
+}
+
+function readUncheckedTasks(changeDir) {
+  return readUncheckedChecklist(path.join(changeDir, 'tasks.md'), 'tasks.md 缺失');
+}
+
+function validateCoverageManifest(coverage, meta, targets, highRiskFiles, legacyMode = false) {
+  const errors = [];
+  const warnings = [];
+  if (!coverage || coverage.__invalid) {
+    const message = coverage?.__invalid
+      ? `coverage.json 无效: ${coverage.error}`
+      : 'coverage.json 缺失';
+    if (legacyMode) warnings.push({ name: 'sdd-coverage-missing', message });
+    else errors.push({ name: 'sdd-coverage-missing', message });
+    return { errors, warnings };
+  }
+  if (coverage.schemaVersion && coverage.schemaVersion !== SDD_SCHEMA_VERSION) {
+    warnings.push({
+      name: 'sdd-coverage-schema-version',
+      message: `coverage schemaVersion=${coverage.schemaVersion}，建议升级为 ${SDD_SCHEMA_VERSION}`,
+    });
+  }
+  if (!Array.isArray(coverage.requirements) || coverage.requirements.length === 0) {
+    errors.push({ name: 'sdd-coverage-empty', message: 'coverage.json 必须包含 requirements 映射' });
+  } else {
+    for (const requirement of coverage.requirements) {
+      if (!requirement.id || !requirement.title || !requirement.spec) {
+        errors.push({ name: 'sdd-coverage-requirement-invalid', message: 'coverage requirement 缺少 id/title/spec' });
+        break;
+      }
+      if (!Array.isArray(requirement.scenarios) || requirement.scenarios.length === 0) {
+        errors.push({ name: 'sdd-coverage-scenarios-missing', message: `coverage requirement ${requirement.id} 缺少 scenarios` });
+        break;
+      }
+    }
+  }
+  const targetCoverage = coverageCoversTargets(coverage, meta.affected, targets);
+  if (!targetCoverage.covered) {
+    errors.push({
+      name: 'sdd-change-targets-uncovered',
+      message: `coverage 未覆盖发布目标: ${targetCoverage.missing.join(', ')}`,
+    });
+  }
+  const fileCoverage = coverageCoversHighRiskFiles(coverage, meta.affected, highRiskFiles);
+  if (!fileCoverage.covered) {
+    errors.push({
+      name: 'sdd-change-files-uncovered',
+      message: `coverage 未覆盖高风险文件: ${fileCoverage.missing.join(', ')}`,
+    });
+  }
+  return { errors, warnings };
+}
+
+function splitDeltaSections(content) {
+  const sections = [];
+  const regex = /^##\s+(ADDED|MODIFIED|REMOVED)\s+Requirements\b.*$/gim;
+  const matches = [...content.matchAll(regex)];
+  for (let index = 0; index < matches.length; index += 1) {
+    const match = matches[index];
+    const start = match.index + match[0].length;
+    const end = matches[index + 1]?.index ?? content.length;
+    sections.push({
+      type: match[1].toUpperCase(),
+      body: content.slice(start, end),
+    });
+  }
+  return sections;
+}
+
+function parseRequirementBlocks(sectionBody) {
+  const regex = /^###\s+Requirement:\s*(.+)$/gim;
+  const matches = [...sectionBody.matchAll(regex)];
+  const blocks = [];
+  for (let index = 0; index < matches.length; index += 1) {
+    const match = matches[index];
+    const start = match.index;
+    const end = matches[index + 1]?.index ?? sectionBody.length;
+    blocks.push({
+      title: match[1].trim(),
+      content: sectionBody.slice(start, end).trim(),
+    });
+  }
+  return blocks;
+}
+
+function parseDeltaSpec(content) {
+  const sections = splitDeltaSections(content);
+  const result = { added: [], modified: [], removed: [] };
+  for (const section of sections) {
+    const key = section.type.toLowerCase();
+    result[key].push(...parseRequirementBlocks(section.body));
+  }
+  return result;
+}
+
+function validateDeltaSpecFile(file, rootDir) {
+  const rel = path.relative(rootDir, file).replace(/\\/g, '/');
+  const content = fs.readFileSync(file, 'utf8');
+  const errors = [];
+  const warnings = [];
+  const sections = splitDeltaSections(content);
+  if (sections.length === 0) {
+    errors.push({ name: 'sdd-delta-section-missing', message: `${rel} 缺少 ADDED/MODIFIED/REMOVED Requirements 段落` });
+    return { errors, warnings };
+  }
+  const delta = parseDeltaSpec(content);
+  const all = [...delta.added, ...delta.modified, ...delta.removed];
+  if (all.length === 0) {
+    errors.push({ name: 'sdd-delta-requirement-missing', message: `${rel} 缺少 Requirement` });
+  }
+  for (const requirement of [...delta.added, ...delta.modified]) {
+    if (!/####\s+Scenario:/i.test(requirement.content)) {
+      errors.push({ name: 'sdd-scenario-missing', message: `${rel} requirement "${requirement.title}" 缺少 Scenario` });
+      continue;
+    }
+    if (!/\bGiven\b|\*\*Given\*\*/i.test(requirement.content) || !/\bWhen\b|\*\*When\*\*/i.test(requirement.content) || !/\bThen\b|\*\*Then\*\*/i.test(requirement.content)) {
+      errors.push({ name: 'sdd-scenario-unverifiable', message: `${rel} requirement "${requirement.title}" 场景必须包含 Given/When/Then` });
+    }
+    if (PLACEHOLDER_PATTERNS.some(pattern => pattern.test(requirement.content))) {
+      errors.push({ name: 'sdd-spec-placeholder', message: `${rel} requirement "${requirement.title}" 仍包含占位内容` });
+    }
+  }
+  for (const requirement of delta.removed) {
+    if (!/because|reason|原因|废弃|移除/i.test(requirement.content)) {
+      warnings.push({ name: 'sdd-removed-reason-missing', message: `${rel} removed requirement "${requirement.title}" 建议写明原因` });
+    }
+  }
+  return { errors, warnings };
+}
+
+function validateDeltaSpecs(changeDir) {
+  const specRoot = path.join(changeDir, 'specs');
+  const files = listMarkdownFiles(specRoot);
+  const errors = [];
+  const warnings = [];
+  if (files.length === 0) {
+    errors.push({ name: 'sdd-delta-specs-missing', message: 'change 缺少 specs/**/*.md delta spec' });
+    return { errors, warnings, files: [] };
+  }
+  for (const file of files) {
+    const validation = validateDeltaSpecFile(file, changeDir);
+    errors.push(...validation.errors);
+    warnings.push(...validation.warnings);
+  }
+  return {
+    errors,
+    warnings,
+    files: files.map(file => path.relative(changeDir, file).replace(/\\/g, '/')),
+  };
+}
+
+function updateReleaseManifest(loaded, releasePlan) {
+  const release = {
+    schemaVersion: SDD_SCHEMA_VERSION,
+    changeId: loaded.changeId,
+    ...(loaded.release && !loaded.release.__invalid ? loaded.release : {}),
+    targets: releasePlan?.targets || loaded.release?.targets || {},
+    changedFiles: releasePlan?.changedFiles || loaded.release?.changedFiles || [],
+    commands: releasePlan?.commands || loaded.release?.commands || [],
+    verifiedAt: nowIso(),
+  };
+  writeJsonFile(loaded.releaseFile, release);
+  return release;
+}
+
+function validateReleaseManifest(release, releasePlan, legacyMode = false) {
+  const errors = [];
+  const warnings = [];
+  if (!release || release.__invalid) {
+    const issue = {
+      name: 'sdd-release-invalid',
+      message: release?.__invalid ? `release.json 无效: ${release.error}` : 'release.json 缺失',
+    };
+    if (legacyMode) warnings.push(issue);
+    else errors.push(issue);
+    return { errors, warnings };
+  }
+  const targets = releasePlan?.targets || release.targets || {};
+  if (releasePlan?.targets) {
+    const releaseTargetCoverage = affectedCoversTargets(release.targets || {}, releasePlan.targets);
+    if (!releaseTargetCoverage.covered) {
+      errors.push({
+        name: 'sdd-release-targets-uncovered',
+        message: `release.json targets 未覆盖发布目标: ${releaseTargetCoverage.missing.join(', ')}`,
+      });
+    }
+  }
+  if (hasHighRiskTargets(targets) && !Array.isArray(release.commands)) {
+    errors.push({ name: 'sdd-release-commands-missing', message: 'release.json commands 必须是数组' });
+  }
+  if (releasePlan?.commands?.length && (!Array.isArray(release.commands) || release.commands.length === 0)) {
+    errors.push({ name: 'sdd-release-commands-empty', message: 'release.json 未记录发布命令' });
+  }
+  return { errors, warnings };
 }
 
 function verifySddChange(options = {}) {
   const loaded = loadSddChange(options);
   const targets = options.targets || options.releasePlan?.targets || {};
   const highRiskFiles = classifyHighRiskFiles(options.files || options.releasePlan?.changedFiles || []);
+  const legacyMode = (loaded.meta.schemaVersion || LEGACY_SDD_SCHEMA_VERSION) !== SDD_SCHEMA_VERSION;
   const errors = [];
   const warnings = [];
   if (loaded.meta.status !== 'approved' || !loaded.meta.approvedAt) {
@@ -627,6 +1185,12 @@ function verifySddChange(options = {}) {
       message: `affected 未覆盖高风险文件: ${fileCoverage.missing.join(', ')}`,
     });
   }
+  const coverageValidation = validateCoverageManifest(loaded.coverage, loaded.meta, targets, highRiskFiles, legacyMode);
+  errors.push(...coverageValidation.errors);
+  warnings.push(...coverageValidation.warnings);
+  const deltaValidation = validateDeltaSpecs(loaded.changeDir);
+  errors.push(...deltaValidation.errors);
+  warnings.push(...deltaValidation.warnings);
   const uncheckedTasks = readUncheckedTasks(loaded.changeDir);
   if (uncheckedTasks.length > 0) {
     errors.push({
@@ -636,29 +1200,52 @@ function verifySddChange(options = {}) {
     });
   }
   const evidenceFile = path.join(loaded.changeDir, 'evidence.md');
-  if (!fs.existsSync(evidenceFile)) {
-    warnings.push({ name: 'sdd-evidence-missing', message: 'evidence.md 缺失' });
+  const uncheckedEvidence = readUncheckedChecklist(evidenceFile, 'evidence.md 缺失');
+  if (uncheckedEvidence.length > 0) {
+    errors.push({
+      name: 'sdd-evidence-incomplete',
+      message: `${uncheckedEvidence.length} 个 evidence.md 证据项未完成`,
+      details: uncheckedEvidence,
+    });
   }
+  const release =
+    options.writeMetadata && options.releasePlan && loaded.release && !loaded.release.__invalid
+      ? updateReleaseManifest(loaded, options.releasePlan)
+      : loaded.release;
+  const releaseValidation = validateReleaseManifest(release, options.releasePlan, legacyMode);
+  errors.push(...releaseValidation.errors);
+  warnings.push(...releaseValidation.warnings);
   const verifiedMeta = {
     ...loaded.meta,
     release: {
       ...(loaded.meta.release || {}),
-      plannedCommands: options.releasePlan?.commands || loaded.meta.release?.plannedCommands || [],
+      plannedCommands: options.releasePlan?.commands || loaded.meta.release?.plannedCommands || release.commands || [],
       lastVerifiedAt: nowIso(),
     },
     updatedAt: nowIso(),
   };
   if (options.writeMetadata) writeJsonFile(loaded.metaFile, verifiedMeta);
   return {
+    schemaVersion: loaded.meta.schemaVersion || loaded.governance.schemaVersion || LEGACY_SDD_SCHEMA_VERSION,
     change: verifiedMeta,
+    coverage: loaded.coverage,
+    release,
+    deltaSpecs: deltaValidation.files,
     errors,
     warnings,
+    blockingErrors: errors,
     passed: errors.length === 0,
     targets,
     highRiskFiles,
   };
 }
 
+function appendToEvidence(changeDir, lines) {
+  const file = path.join(changeDir, 'evidence.md');
+  ensureDir(path.dirname(file));
+  fs.appendFileSync(file, `\n${lines.join('\n')}\n`);
+}
+
 function appendBypassLog(options = {}) {
   const governance = getSddGovernanceConfig(options);
   if (!governance.initialized) {
@@ -668,19 +1255,33 @@ function appendBypassLog(options = {}) {
   if (!reason) throw new Error('--sdd-bypass 需要同时提供 --reason "..."');
   const file = path.join(governance.rootDir, BYPASS_LOG_FILE);
   ensureDir(path.dirname(file));
-  const lines = [
+  const entry = [
     `## ${nowIso()}`,
     '',
     `- command: ${options.command || '-'}`,
     `- reason: ${reason}`,
     `- targets: ${JSON.stringify(options.targets || {})}`,
+    `- followUp: 补齐对应 change 的 evidence.md，并在发布后 archive`,
     `- user: ${os.userInfo().username || 'unknown'}`,
     '',
   ];
-  fs.appendFileSync(file, lines.join('\n'));
+  fs.appendFileSync(file, entry.join('\n'));
+
+  const approved = listChanges(governance.rootDir).find(
+    item => item.valid && item.metadata.status === 'approved' && item.metadata.approvedAt
+  );
+  if (approved) {
+    appendToEvidence(approved.dir, [
+      '## SDD Bypass',
+      '',
+      `- ${nowIso()} ${options.command || '-'} bypassed SDD gate: ${reason}`,
+    ]);
+  }
+
   return {
     file: path.relative(options.cwd || process.cwd(), file).replace(/\\/g, '/'),
     reason,
+    evidenceChange: approved?.id || null,
   };
 }
 
@@ -689,17 +1290,28 @@ function buildSddStatus(options = {}) {
   const specsDir = path.join(governance.rootDir, 'specs');
   const changes = governance.initialized ? listChanges(governance.rootDir) : [];
   const archived = governance.initialized ? listChanges(governance.rootDir, { includeArchive: true }).filter(item => item.dir.includes(`${path.sep}archive${path.sep}`)) : [];
+  const releasePlan = options.releasePlan || {};
+  const highRiskFiles = classifyHighRiskFiles(releasePlan.changedFiles || []);
+  const activeChange = chooseActiveChange(changes, releasePlan.targets || {}, highRiskFiles);
+  const report = buildSddGovernanceReport({
+    cwd: options.cwd,
+    configText: options.configText,
+    targets: releasePlan.targets || {},
+    files: releasePlan.changedFiles || [],
+    commands: releasePlan.commands || [],
+  });
   return {
     cwd: options.cwd || process.cwd(),
+    schemaVersion: governance.schemaVersion,
     governance,
     specs: listMarkdownFiles(specsDir).map(file => path.relative(governance.rootDir, file).replace(/\\/g, '/')),
-    activeChanges: changes.map(item => ({
-      id: item.id,
-      status: item.metadata?.status || 'invalid',
-      approvedAt: item.metadata?.approvedAt || null,
-      affected: item.metadata?.affected || null,
-      dir: path.relative(options.cwd || process.cwd(), item.dir).replace(/\\/g, '/'),
-    })),
+    specSummaries: governance.initialized
+      ? listMarkdownFiles(specsDir).map(file => summarizeSpecFile(governance.rootDir, file))
+      : [],
+    activeChange: activeChange ? summarizeChange(options.cwd || process.cwd(), activeChange) : null,
+    releaseTargets: releasePlan.targets || {},
+    coverage: summarizeCoverage(activeChange?.coverage),
+    activeChanges: changes.map(item => summarizeChange(options.cwd || process.cwd(), item)),
     archivedChanges: archived.slice(-10).map(item => ({
       id: item.id,
       dir: path.relative(options.cwd || process.cwd(), item.dir).replace(/\\/g, '/'),
@@ -707,31 +1319,97 @@ function buildSddStatus(options = {}) {
     bypassLog: governance.initialized && fs.existsSync(path.join(governance.rootDir, BYPASS_LOG_FILE))
       ? path.join(governance.path, BYPASS_LOG_FILE).replace(/\\/g, '/')
       : null,
+    nextActions: report.nextActions,
+    blockingErrors: report.blockingErrors,
   };
 }
 
+function findRequirementBlock(content, title) {
+  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const regex = new RegExp(`^###\\s+Requirement:\\s*${escaped}\\s*$`, 'mi');
+  const match = content.match(regex);
+  if (!match || match.index === undefined) return null;
+  const start = match.index;
+  const next = content.slice(start + match[0].length).search(/^###\s+Requirement:/mi);
+  const end = next >= 0 ? start + match[0].length + next : content.length;
+  return { start, end };
+}
+
+function mergeDeltaIntoSpec(current, delta, targetRel) {
+  let content = current.trimEnd();
+  const errors = [];
+  const warnings = [];
+  if (!content) {
+    const domain = targetRel.replace(/\/spec\.md$/, '') || 'app';
+    content = `# ${domain} Specification\n\n## Purpose\n\nCurrent behavior for ${domain}.\n\n## Requirements\n`;
+  }
+  if (!/##\s+Requirements/i.test(content)) {
+    content += '\n\n## Requirements\n';
+  }
+  for (const requirement of delta.added) {
+    const existing = findRequirementBlock(content, requirement.title);
+    if (existing) {
+      warnings.push({ name: 'sdd-added-existing-requirement', message: `${targetRel} 已存在 requirement "${requirement.title}"，跳过 ADDED` });
+      continue;
+    }
+    content = `${content.trimEnd()}\n\n${requirement.content}\n`;
+  }
+  for (const requirement of delta.modified) {
+    const existing = findRequirementBlock(content, requirement.title);
+    if (!existing) {
+      errors.push({ name: 'sdd-modified-requirement-missing', message: `${targetRel} 不存在要修改的 requirement "${requirement.title}"` });
+      continue;
+    }
+    content = `${content.slice(0, existing.start).trimEnd()}\n\n${requirement.content}\n\n${content.slice(existing.end).trimStart()}`;
+  }
+  for (const requirement of delta.removed) {
+    const existing = findRequirementBlock(content, requirement.title);
+    if (!existing) {
+      warnings.push({ name: 'sdd-removed-requirement-missing', message: `${targetRel} 不存在要移除的 requirement "${requirement.title}"` });
+      continue;
+    }
+    content = `${content.slice(0, existing.start).trimEnd()}\n\n${content.slice(existing.end).trimStart()}`;
+  }
+  return { content: `${content.trimEnd()}\n`, errors, warnings };
+}
+
 function syncSddChange(options = {}) {
   const loaded = loadSddChange(options);
-  const specFiles = listMarkdownFiles(path.join(loaded.changeDir, 'specs'));
+  const specRoot = path.join(loaded.changeDir, 'specs');
+  const specFiles = listMarkdownFiles(specRoot);
   const synced = [];
+  const errors = [];
+  const warnings = [];
+  const plannedWrites = [];
   for (const deltaFile of specFiles) {
-    const rel = path.relative(path.join(loaded.changeDir, 'specs'), deltaFile);
+    const rel = path.relative(specRoot, deltaFile).replace(/\\/g, '/');
     const target = path.join(loaded.governance.rootDir, 'specs', rel);
-    ensureDir(path.dirname(target));
-    const delta = fs.readFileSync(deltaFile, 'utf8').trim();
-    const entry = [
-      '',
-      `## Archived Change: ${loaded.changeId}`,
-      '',
-      `Archived at: ${nowIso()}`,
-      '',
-      delta,
-      '',
-    ].join('\n');
-    fs.appendFileSync(target, fs.existsSync(target) ? entry : `${entry.trimStart()}\n`);
-    synced.push(path.relative(loaded.governance.rootDir, target).replace(/\\/g, '/'));
+    const deltaContent = fs.readFileSync(deltaFile, 'utf8');
+    const delta = parseDeltaSpec(deltaContent);
+    const current = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
+    const merged = mergeDeltaIntoSpec(current, delta, rel);
+    errors.push(...merged.errors);
+    warnings.push(...merged.warnings);
+    if (merged.errors.length === 0) {
+      plannedWrites.push({ target, content: merged.content });
+    }
   }
-  return { change: loaded.meta, synced };
+  if (errors.length > 0 && !options.force) {
+    const first = errors[0];
+    throw new Error(`SDD sync 失败: ${first.message}`);
+  }
+  for (const item of plannedWrites) {
+    ensureDir(path.dirname(item.target));
+    fs.writeFileSync(item.target, item.content);
+    synced.push(path.relative(loaded.governance.rootDir, item.target).replace(/\\/g, '/'));
+  }
+  return {
+    schemaVersion: loaded.meta.schemaVersion || loaded.governance.schemaVersion,
+    change: loaded.meta,
+    synced,
+    warnings,
+    errors,
+  };
 }
 
 function archiveSddChange(options = {}) {
@@ -750,19 +1428,23 @@ function archiveSddChange(options = {}) {
     ...loaded.meta,
     status: 'archived',
     archivedAt: nowIso(),
+    syncedSpecs: sync.synced,
     updatedAt: nowIso(),
   };
   writeJsonFile(loaded.metaFile, meta);
   fs.renameSync(loaded.changeDir, archiveDir);
   return {
+    schemaVersion: meta.schemaVersion || loaded.governance.schemaVersion,
     change: meta,
     archiveDir: path.relative(options.cwd || process.cwd(), archiveDir).replace(/\\/g, '/'),
     synced: sync.synced,
+    warnings: [...verify.warnings, ...sync.warnings],
   };
 }
 
 module.exports = {
   DEFAULT_SDD_DIR,
+  SDD_SCHEMA_VERSION,
   appendBypassLog,
   archiveSddChange,
   buildSddGovernanceReport,