openxiangda 1.0.134 → 1.0.136

package/lib/sdd.js

@@ -0,0 +1,777 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DEFAULT_SDD_DIR = 'openspec';
+const SDD_CONFIG_FILE = 'config.yaml';
+const CHANGE_META_FILE = 'change.json';
+const BYPASS_LOG_FILE = path.join('changes', 'bypass-log.md');
+
+const DEFAULT_SPEC_CONTENT = `# OpenXiangda Platform Specification
+
+This file is the current behavior contract for this application workspace.
+
+## Requirements
+
+### Requirement: SDD-governed high-risk changes
+High-risk OpenXiangda changes MUST be attached to an approved change before publishing.
+
+#### 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>\`
+`;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function normalizeRelPath(value) {
+  const input = String(value || '').trim();
+  if (!input) return DEFAULT_SDD_DIR;
+  const normalized = input.replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/, '');
+  if (!normalized || normalized.includes('..') || path.isAbsolute(normalized)) {
+    throw new Error(`非法 SDD 目录: ${value}`);
+  }
+  return normalized;
+}
+
+function normalizeChangeId(value) {
+  const raw = String(value || '').trim();
+  if (!raw) throw new Error('缺少 change id');
+  const id = raw
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (!id) throw new Error(`非法 change id: ${value}`);
+  return id;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeFileIfMissing(file, content, operations, force = false) {
+  const existed = fs.existsSync(file);
+  if (existed && !force) {
+    operations.push({ path: file, action: 'unchanged' });
+    return;
+  }
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, content);
+  operations.push({ path: file, action: existed && force ? 'overwrite' : 'create' });
+}
+
+function readJsonFile(file, fallback = null) {
+  if (!fs.existsSync(file)) return fallback;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    return {
+      __invalid: true,
+      error: error.message,
+      file,
+    };
+  }
+}
+
+function writeJsonFile(file, value) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function extractSddBlock(configText) {
+  const governanceIndex = String(configText || '').indexOf('governance');
+  const sddIndex = String(configText || '').indexOf('sdd', governanceIndex >= 0 ? governanceIndex : 0);
+  if (sddIndex < 0) return '';
+  const start = String(configText).indexOf('{', sddIndex);
+  if (start < 0) return '';
+  let depth = 0;
+  for (let index = start; index < configText.length; index += 1) {
+    const char = configText[index];
+    if (char === '{') depth += 1;
+    if (char === '}') {
+      depth -= 1;
+      if (depth === 0) return configText.slice(start, index + 1);
+    }
+  }
+  return '';
+}
+
+function getSddGovernanceConfig(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const configText = options.configText || '';
+  const block = extractSddBlock(configText);
+  const configured = Boolean(block);
+  const enabled =
+    configured && /enabled\s*:\s*false/.test(block)
+      ? false
+      : configured
+        ? true
+        : fs.existsSync(path.join(cwd, DEFAULT_SDD_DIR));
+  const strictHighRisk =
+    configured && /strictHighRisk\s*:\s*false/.test(block)
+      ? false
+      : enabled;
+  const pathMatch = block.match(/path\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'));
+  return {
+    enabled,
+    strictHighRisk,
+    path: sddPath,
+    rootDir,
+    initialized,
+    configured,
+    source: configured ? 'app-workspace.config.ts' : initialized ? 'openspec' : 'none',
+  };
+}
+
+function buildDefaultConfigYaml() {
+  return [
+    'schema: openxiangda-sdd-v1',
+    'description: OpenXiangda native SDD workspace records inspired by OpenSpec.',
+    'artifacts:',
+    '  proposal: proposal.md',
+    '  design: design.md',
+    '  tasks: tasks.md',
+    '  evidence: evidence.md',
+    '  metadata: change.json',
+    'rules:',
+    '  requireApprovalForHighRisk: true',
+    '  requireAffectedCoverage: true',
+    '  archiveMergesDeltaSpecs: true',
+    '',
+  ].join('\n');
+}
+
+function initSddWorkspace(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const sddPath = normalizeRelPath(options.path || DEFAULT_SDD_DIR);
+  const rootDir = path.join(cwd, sddPath);
+  const operations = [];
+  const force = Boolean(options.force);
+
+  ensureDir(rootDir);
+  ensureDir(path.join(rootDir, 'changes'));
+  ensureDir(path.join(rootDir, 'changes', 'archive'));
+  ensureDir(path.join(rootDir, 'specs', 'platform'));
+  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, 'changes', '.gitkeep'), '', operations, false);
+  writeFileIfMissing(path.join(rootDir, 'changes', 'archive', '.gitkeep'), '', operations, false);
+  writeFileIfMissing(
+    path.join(rootDir, 'templates', 'change', 'README.md'),
+    [
+      '# Change Artifact Template',
+      '',
+      'Create changes with `openxiangda sdd propose <change-id>`.',
+      'High-risk implementation starts only after `openxiangda sdd approve <change-id>`.',
+      '',
+    ].join('\n'),
+    operations,
+    false
+  );
+
+  return {
+    cwd,
+    path: sddPath,
+    rootDir,
+    initialized: true,
+    operations: operations.map(item => ({
+      path: path.relative(cwd, item.path).replace(/\\/g, '/'),
+      action: item.action,
+    })),
+  };
+}
+
+function listMarkdownFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const result = [];
+  const visit = current => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const entryPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        visit(entryPath);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        result.push(entryPath);
+      }
+    }
+  };
+  visit(dir);
+  return result.sort();
+}
+
+function listChangeDirs(rootDir, includeArchive = false) {
+  const changesDir = path.join(rootDir, 'changes');
+  if (!fs.existsSync(changesDir)) return [];
+  const dirs = [];
+  for (const entry of fs.readdirSync(changesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === 'archive') {
+      if (!includeArchive) continue;
+      const archiveDir = path.join(changesDir, entry.name);
+      for (const archived of fs.readdirSync(archiveDir, { withFileTypes: true })) {
+        if (archived.isDirectory()) dirs.push(path.join(archiveDir, archived.name));
+      }
+      continue;
+    }
+    dirs.push(path.join(changesDir, entry.name));
+  }
+  return dirs.sort();
+}
+
+function readChange(changeDir) {
+  const meta = readJsonFile(path.join(changeDir, CHANGE_META_FILE), null);
+  const id = meta?.id || path.basename(changeDir);
+  return {
+    id,
+    dir: changeDir,
+    relativeDir: changeDir.split(path.sep).slice(-2).join('/'),
+    metadata: meta,
+    valid: Boolean(meta && !meta.__invalid),
+  };
+}
+
+function listChanges(rootDir, options = {}) {
+  return listChangeDirs(rootDir, Boolean(options.includeArchive)).map(readChange);
+}
+
+function splitList(value) {
+  if (value === undefined || value === null || value === false) return [];
+  if (Array.isArray(value)) return value.flatMap(splitList);
+  if (value === true) return ['*'];
+  return String(value)
+    .split(',')
+    .map(item => item.trim())
+    .filter(Boolean);
+}
+
+function normalizeAffected(input = {}) {
+  const affected = input.affected || input;
+  return {
+    forms: splitList(affected.forms || affected.form),
+    pages: splitList(affected.pages || affected.page),
+    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',
+    contracts: affected.contracts === true || affected.contracts === 'true',
+  };
+}
+
+function createChangeMetadata(changeId, options = {}) {
+  return {
+    id: changeId,
+    title: options.title || changeId,
+    status: 'proposed',
+    riskLevel: options.riskLevel || options.risk || 'medium',
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+    approvedAt: null,
+    approvedBy: null,
+    approvalSummary: null,
+    affected: normalizeAffected(options),
+    release: {
+      plannedCommands: [],
+      lastVerifiedAt: null,
+    },
+    evidence: {
+      files: ['evidence.md'],
+      bypasses: [],
+    },
+  };
+}
+
+function createProposalContent(meta) {
+  return `# Proposal: ${meta.title}
+
+## Why
+
+- 
+
+## What Changes
+
+- 
+
+## Out Of Scope
+
+- 
+
+## Risks
+
+- 
+`;
+}
+
+function createDesignContent(meta) {
+  return `# Design: ${meta.title}
+
+## OpenXiangda Resource Impact
+
+- Forms: ${meta.affected.forms.join(', ') || '(none)'}
+- Pages: ${meta.affected.pages.join(', ') || '(none)'}
+- 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'}
+
+## Data And Contract Notes
+
+- 
+
+## Publish Plan
+
+- Run \`openxiangda workspace plan --changed\` before publish.
+`;
+}
+
+function createTasksContent() {
+  return [
+    '# Tasks',
+    '',
+    '- [ ] Confirm proposal and affected scope',
+    '- [ ] Implement changes',
+    '- [ ] Run `openxiangda sdd verify <change>`',
+    '- [ ] Run release plan/check commands',
+    '- [ ] Archive the change after release',
+    '',
+  ].join('\n');
+}
+
+function createEvidenceContent() {
+  return [
+    '# Evidence',
+    '',
+    '## Verification',
+    '',
+    '- ',
+    '',
+    '## Release',
+    '',
+    '- ',
+    '',
+    '## Bypass Log',
+    '',
+    '- None',
+    '',
+  ].join('\n');
+}
+
+function createDeltaSpecContent(meta, domain) {
+  return `# ${domain} Delta Spec
+
+## ADDED Requirements
+
+### Requirement: ${meta.title}
+Describe the behavior that will be true after this change.
+
+#### Scenario: Main path
+- **Given** 
+- **When** 
+- **Then** 
+`;
+}
+
+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 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'));
+  const meta = createChangeMetadata(changeId, options);
+  writeJsonFile(path.join(changeDir, CHANGE_META_FILE), meta);
+  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')
+  );
+  return {
+    change: meta,
+    dir: path.relative(options.cwd || process.cwd(), changeDir).replace(/\\/g, '/'),
+  };
+}
+
+function loadSddChange(options = {}) {
+  const governance = getSddGovernanceConfig(options);
+  const changeId = normalizeChangeId(options.changeId);
+  const changeDir = path.join(governance.rootDir, 'changes', changeId);
+  if (!fs.existsSync(changeDir)) throw new Error(`change 不存在: ${changeId}`);
+  const metaFile = path.join(changeDir, CHANGE_META_FILE);
+  const meta = readJsonFile(metaFile, null);
+  if (!meta || meta.__invalid) {
+    throw new Error(`change metadata 无效: ${metaFile}`);
+  }
+  return { governance, changeId, changeDir, meta, metaFile };
+}
+
+function approveSddChange(options = {}) {
+  const loaded = loadSddChange(options);
+  const meta = {
+    ...loaded.meta,
+    status: 'approved',
+    approvedAt: nowIso(),
+    approvedBy: options.approvedBy || os.userInfo().username || 'unknown',
+    approvalSummary: options.summary || options.note || loaded.meta.approvalSummary || '',
+    updatedAt: nowIso(),
+  };
+  writeJsonFile(loaded.metaFile, meta);
+  return {
+    change: meta,
+    dir: path.relative(options.cwd || process.cwd(), loaded.changeDir).replace(/\\/g, '/'),
+  };
+}
+
+function includesAll(list, required) {
+  if (!required || required.length === 0) return true;
+  if (list.includes('*')) return true;
+  return required.every(item => list.includes(item));
+}
+
+function hasHighRiskTargets(targets = {}) {
+  return (
+    (targets.forms || []).length > 0 ||
+    (targets.pages || []).length > 0 ||
+    Boolean(targets.resources) ||
+    Boolean(targets.runtime)
+  );
+}
+
+function classifyHighRiskFiles(files = []) {
+  const highRisk = [];
+  for (const file of files || []) {
+    if (
+      file === 'app-workspace.config.ts' ||
+      file.startsWith('src/forms/') ||
+      file.startsWith('src/pages/') ||
+      file.startsWith('src/resources/') ||
+      file.startsWith('src/functions/') ||
+      file.startsWith('src/automations/') ||
+      file.startsWith('src/workflows/') ||
+      file.startsWith('src/js-code-nodes/') ||
+      file.startsWith('src/runtime/')
+    ) {
+      highRisk.push(file);
+    }
+  }
+  return highRisk;
+}
+
+function affectedCoversTargets(affected, targets = {}) {
+  const normalized = normalizeAffected(affected);
+  const missing = [];
+  if (!includesAll(normalized.forms, targets.forms || [])) {
+    missing.push(`forms:${(targets.forms || []).filter(item => !normalized.forms.includes(item)).join(',')}`);
+  }
+  if (!includesAll(normalized.pages, targets.pages || [])) {
+    missing.push(`pages:${(targets.pages || []).filter(item => !normalized.pages.includes(item)).join(',')}`);
+  }
+  if (targets.resources && !normalized.resources && !normalized.backend) missing.push('resources');
+  if (targets.runtime && !normalized.runtime) missing.push('runtime');
+  return {
+    covered: missing.length === 0,
+    missing,
+  };
+}
+
+function affectedCoversHighRiskFiles(affected, files = []) {
+  const normalized = normalizeAffected(affected);
+  const missing = [];
+  for (const file of files) {
+    if (file === 'app-workspace.config.ts' && !normalized.contracts && !normalized.runtime) {
+      missing.push(file);
+    } else if (file.startsWith('src/forms/')) {
+      const formCode = file.split('/')[2];
+      if (!includesAll(normalized.forms, [formCode])) missing.push(file);
+    } else if (file.startsWith('src/pages/')) {
+      const pageCode = file.split('/')[2];
+      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/runtime/') && !normalized.runtime) {
+      missing.push(file);
+    }
+  }
+  return {
+    covered: missing.length === 0,
+    missing,
+  };
+}
+
+function getApprovedActiveChanges(rootDir) {
+  return listChanges(rootDir)
+    .filter(item => item.valid && item.metadata.status === 'approved' && item.metadata.approvedAt)
+    .map(item => item.metadata);
+}
+
+function buildSddGovernanceReport(options = {}) {
+  const governance = getSddGovernanceConfig(options);
+  const targets = options.targets || {};
+  const files = options.files || [];
+  const highRiskFiles = classifyHighRiskFiles(files);
+  const checks = [];
+  const warnings = [];
+  const errors = [];
+  let activeChanges = [];
+
+  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 };
+  }
+
+  if (!governance.initialized) {
+    const message = `SDD 已配置但未初始化: ${governance.path}。运行 openxiangda sdd init`;
+    if (governance.strictHighRisk && (hasHighRiskTargets(targets) || highRiskFiles.length > 0)) {
+      errors.push({ name: 'sdd-not-initialized', message });
+      checks.push({ name: 'sdd', status: 'error', message });
+    } else {
+      warnings.push(message);
+      checks.push({ name: 'sdd', status: 'warn', message });
+    }
+    return { governance, highRiskFiles, activeChanges, checks, warnings, errors };
+  }
+
+  activeChanges = listChanges(governance.rootDir).filter(
+    item => item.valid && !['archived', 'rejected'].includes(item.metadata.status)
+  );
+  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 };
+  }
+
+  if (approved.length === 0) {
+    errors.push({
+      name: 'sdd-approved-change-required',
+      message: '高风险变更发布前必须存在 approved SDD change；先运行 openxiangda sdd propose <change> 并经 openxiangda sdd approve <change> 确认。',
+    });
+  } 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 未覆盖本次高风险文件变更。',
+      });
+    }
+  }
+
+  checks.push({
+    name: 'sdd',
+    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 };
+}
+
+function readUncheckedTasks(changeDir) {
+  const file = path.join(changeDir, 'tasks.md');
+  if (!fs.existsSync(file)) return ['tasks.md 缺失'];
+  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}`);
+}
+
+function verifySddChange(options = {}) {
+  const loaded = loadSddChange(options);
+  const targets = options.targets || options.releasePlan?.targets || {};
+  const highRiskFiles = classifyHighRiskFiles(options.files || options.releasePlan?.changedFiles || []);
+  const errors = [];
+  const warnings = [];
+  if (loaded.meta.status !== 'approved' || !loaded.meta.approvedAt) {
+    errors.push({ name: 'sdd-change-not-approved', message: `change ${loaded.changeId} 未 approve` });
+  }
+  const targetCoverage = affectedCoversTargets(loaded.meta.affected, targets);
+  if (!targetCoverage.covered) {
+    errors.push({
+      name: 'sdd-change-targets-uncovered',
+      message: `affected 未覆盖发布目标: ${targetCoverage.missing.join(', ')}`,
+    });
+  }
+  const fileCoverage = affectedCoversHighRiskFiles(loaded.meta.affected, highRiskFiles);
+  if (!fileCoverage.covered) {
+    errors.push({
+      name: 'sdd-change-files-uncovered',
+      message: `affected 未覆盖高风险文件: ${fileCoverage.missing.join(', ')}`,
+    });
+  }
+  const uncheckedTasks = readUncheckedTasks(loaded.changeDir);
+  if (uncheckedTasks.length > 0) {
+    errors.push({
+      name: 'sdd-unfinished-tasks',
+      message: `${uncheckedTasks.length} 个 tasks.md 任务未完成`,
+      details: uncheckedTasks,
+    });
+  }
+  const evidenceFile = path.join(loaded.changeDir, 'evidence.md');
+  if (!fs.existsSync(evidenceFile)) {
+    warnings.push({ name: 'sdd-evidence-missing', message: 'evidence.md 缺失' });
+  }
+  const verifiedMeta = {
+    ...loaded.meta,
+    release: {
+      ...(loaded.meta.release || {}),
+      plannedCommands: options.releasePlan?.commands || loaded.meta.release?.plannedCommands || [],
+      lastVerifiedAt: nowIso(),
+    },
+    updatedAt: nowIso(),
+  };
+  if (options.writeMetadata) writeJsonFile(loaded.metaFile, verifiedMeta);
+  return {
+    change: verifiedMeta,
+    errors,
+    warnings,
+    passed: errors.length === 0,
+    targets,
+    highRiskFiles,
+  };
+}
+
+function appendBypassLog(options = {}) {
+  const governance = getSddGovernanceConfig(options);
+  if (!governance.initialized) {
+    throw new Error('SDD bypass 需要已初始化 openspec；先运行 openxiangda sdd init');
+  }
+  const reason = String(options.reason || '').trim();
+  if (!reason) throw new Error('--sdd-bypass 需要同时提供 --reason "..."');
+  const file = path.join(governance.rootDir, BYPASS_LOG_FILE);
+  ensureDir(path.dirname(file));
+  const lines = [
+    `## ${nowIso()}`,
+    '',
+    `- command: ${options.command || '-'}`,
+    `- reason: ${reason}`,
+    `- targets: ${JSON.stringify(options.targets || {})}`,
+    `- user: ${os.userInfo().username || 'unknown'}`,
+    '',
+  ];
+  fs.appendFileSync(file, lines.join('\n'));
+  return {
+    file: path.relative(options.cwd || process.cwd(), file).replace(/\\/g, '/'),
+    reason,
+  };
+}
+
+function buildSddStatus(options = {}) {
+  const governance = getSddGovernanceConfig(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}`)) : [];
+  return {
+    cwd: options.cwd || process.cwd(),
+    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, '/'),
+    })),
+    archivedChanges: archived.slice(-10).map(item => ({
+      id: item.id,
+      dir: path.relative(options.cwd || process.cwd(), item.dir).replace(/\\/g, '/'),
+    })),
+    bypassLog: governance.initialized && fs.existsSync(path.join(governance.rootDir, BYPASS_LOG_FILE))
+      ? path.join(governance.path, BYPASS_LOG_FILE).replace(/\\/g, '/')
+      : null,
+  };
+}
+
+function syncSddChange(options = {}) {
+  const loaded = loadSddChange(options);
+  const specFiles = listMarkdownFiles(path.join(loaded.changeDir, 'specs'));
+  const synced = [];
+  for (const deltaFile of specFiles) {
+    const rel = path.relative(path.join(loaded.changeDir, 'specs'), deltaFile);
+    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, '/'));
+  }
+  return { change: loaded.meta, synced };
+}
+
+function archiveSddChange(options = {}) {
+  const verify = verifySddChange(options);
+  if (!verify.passed && !options.force) {
+    const first = verify.errors[0];
+    throw new Error(`change 不能归档: ${first.message}`);
+  }
+  const loaded = loadSddChange(options);
+  const sync = syncSddChange(options);
+  const archiveName = `${new Date().toISOString().slice(0, 10)}-${loaded.changeId}`;
+  const archiveDir = path.join(loaded.governance.rootDir, 'changes', 'archive', archiveName);
+  ensureDir(path.dirname(archiveDir));
+  if (fs.existsSync(archiveDir)) throw new Error(`archive 已存在: ${archiveName}`);
+  const meta = {
+    ...loaded.meta,
+    status: 'archived',
+    archivedAt: nowIso(),
+    updatedAt: nowIso(),
+  };
+  writeJsonFile(loaded.metaFile, meta);
+  fs.renameSync(loaded.changeDir, archiveDir);
+  return {
+    change: meta,
+    archiveDir: path.relative(options.cwd || process.cwd(), archiveDir).replace(/\\/g, '/'),
+    synced: sync.synced,
+  };
+}
+
+module.exports = {
+  DEFAULT_SDD_DIR,
+  appendBypassLog,
+  archiveSddChange,
+  buildSddGovernanceReport,
+  buildSddStatus,
+  getSddGovernanceConfig,
+  initSddWorkspace,
+  normalizeAffected,
+  proposeSddChange,
+  approveSddChange,
+  syncSddChange,
+  verifySddChange,
+};