openxiangda 1.0.159 → 1.0.161

package/lib/sdd.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { readGitSourceBase } = require('./change-baseline');
 
 const DEFAULT_SDD_DIR = 'openspec';
 const SDD_CONFIG_FILE = 'config.yaml';
@@ -11,6 +12,20 @@ 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 CODE_RESOURCE_TARGETS = ['functions', 'automations', 'workflows', 'jsCodeNodes'];
+const SDD_VERIFY_STAGES = ['implementation', 'prepublish', 'postpublish', 'archive'];
+const QUICK_SDD_RISK_TIER = 'L1';
+const QUICK_SDD_ALLOWED_KINDS = ['copy', 'style', 'binding', 'metadata', 'narrow-fix'];
+const QUICK_FUNCTION_SAFETY_FIELDS = [
+  'schema',
+  'permission',
+  'auth',
+  'publicAccess',
+  'dataMigration',
+  'destructive',
+  'crossResource',
+];
+const QUICK_SDD_MAX_TARGETS = 3;
+const QUICK_SDD_MAX_FILES = 12;
 
 const DEFAULT_SPEC_CONTENT = `# Application Specification
 
@@ -311,6 +326,165 @@ function normalizeAffected(input = {}) {
   };
 }
 
+function normalizeQuickScopeFile(value) {
+  const file = String(value || '').trim().replace(/\\/g, '/').replace(/^\.\//, '');
+  if (
+    !file ||
+    path.isAbsolute(file) ||
+    file.split('/').includes('..') ||
+    file.endsWith('/') ||
+    /[*?\[\]{}]/.test(file)
+  ) {
+    return null;
+  }
+  return file;
+}
+
+function normalizeQuickChangeKind(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-');
+}
+
+function normalizeQuickRiskAssessment(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  return {
+    confirmed: value.confirmed === true,
+    schema: value.schema,
+    permission: value.permission ?? value.permissions,
+    auth: value.auth ?? value.authentication,
+    publicAccess: value.publicAccess ?? value.public,
+    dataMigration: value.dataMigration ?? value.migration,
+    destructive: value.destructive,
+    crossResource: value.crossResource ?? value.crossResources,
+  };
+}
+
+function validateQuickSddScope(options = {}) {
+  const affected = normalizeAffected(options);
+  affected.pages = Array.from(new Set(affected.pages));
+  affected.functions = Array.from(new Set(affected.functions));
+  affected.files = Array.from(new Set(affected.files.map(normalizeQuickScopeFile).filter(Boolean))).sort();
+  if (affected.pages.length > 0) affected.runtime = true;
+  const errors = [];
+  const requestedRisk = String(
+    options.riskTier || options.riskLevel || options.risk || QUICK_SDD_RISK_TIER
+  ).trim().toUpperCase();
+  if (!['L1', 'LOW'].includes(requestedRisk)) {
+    errors.push(`quick change 仅允许 ${QUICK_SDD_RISK_TIER}/low，收到 ${requestedRisk || '(empty)'}`);
+  }
+
+  const changeKind = normalizeQuickChangeKind(options.changeKind || options.kind);
+  if (!QUICK_SDD_ALLOWED_KINDS.includes(changeKind)) {
+    errors.push(
+      `quick change 必须声明可解释的 L1 changeKind：${QUICK_SDD_ALLOWED_KINDS.join(', ')}；收到 ${changeKind || '(empty)'}`
+    );
+  }
+  if (
+    affected.forms.length > 0 ||
+    affected.automations.length > 0 ||
+    affected.workflows.length > 0 ||
+    affected.jsCodeNodes.length > 0 ||
+    affected.resources ||
+    affected.backend ||
+    affected.contracts
+  ) {
+    errors.push('quick change 不能覆盖表单、Automation、Workflow、JS_CODE、通用资源、后端或契约变更');
+  }
+  if (affected.runtime && affected.pages.length === 0) {
+    errors.push('quick change 仅允许由精确 page target 引起的 Runtime 发布');
+  }
+
+  const logicalTargets = [...affected.pages, ...affected.functions];
+  if (logicalTargets.length === 0) {
+    errors.push('quick change 至少需要一个精确 page 或 function target');
+  }
+  if (logicalTargets.length > QUICK_SDD_MAX_TARGETS) {
+    errors.push(`quick change 最多允许 ${QUICK_SDD_MAX_TARGETS} 个逻辑 target`);
+  }
+  if (logicalTargets.some(item => !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(item))) {
+    errors.push('quick change target 必须是精确安全 code，不能包含路径或通配符');
+  }
+  if (affected.files.length === 0) {
+    errors.push('quick change 必须声明精确 files');
+  }
+  if (affected.files.length > QUICK_SDD_MAX_FILES) {
+    errors.push(`quick change 最多允许 ${QUICK_SDD_MAX_FILES} 个文件`);
+  }
+
+  const selectedPages = new Set(affected.pages);
+  const selectedFunctions = new Set(affected.functions);
+  const riskAssessment = normalizeQuickRiskAssessment(options.riskAssessment);
+  if (selectedFunctions.size > 0) {
+    if (!riskAssessment?.confirmed) {
+      errors.push('Function quick change 必须提供 riskAssessment.confirmed=true 并逐项排除高风险行为');
+    }
+    for (const field of QUICK_FUNCTION_SAFETY_FIELDS) {
+      if (riskAssessment?.[field] !== false) {
+        errors.push(`Function quick change 必须明确确认 riskAssessment.${field}=false`);
+      }
+    }
+    if (!['metadata', 'narrow-fix'].includes(changeKind)) {
+      errors.push('Function quick change 仅允许 changeKind=metadata 或 narrow-fix');
+    }
+  } else if (changeKind === 'binding' && riskAssessment?.crossResource !== false) {
+    errors.push('binding quick change 必须明确确认 riskAssessment.crossResource=false');
+  }
+  for (const rawFile of normalizeAffected(options).files) {
+    if (!normalizeQuickScopeFile(rawFile)) {
+      errors.push(`quick change file 不是精确安全路径: ${rawFile}`);
+    }
+  }
+  for (const file of affected.files) {
+    const pageCode = file.match(/^src\/pages\/([^/]+)\//)?.[1];
+    const functionCode = file.match(/^src\/functions\/([^/]+)\//)?.[1];
+    const functionManifestCode = file.match(/^src\/resources\/functions\/([^/]+)\.json$/)?.[1];
+    if (pageCode && selectedPages.has(pageCode)) continue;
+    if (functionCode && selectedFunctions.has(functionCode)) continue;
+    if (functionManifestCode && selectedFunctions.has(functionManifestCode)) continue;
+    errors.push(`quick change file 超出精确 page/function scope: ${file}`);
+  }
+  for (const pageCode of selectedPages) {
+    if (!affected.files.some(file => file.startsWith(`src/pages/${pageCode}/`))) {
+      errors.push(`page ${pageCode} 缺少对应精确 file`);
+    }
+  }
+  for (const functionCode of selectedFunctions) {
+    const hasSource = affected.files.some(file => file.startsWith(`src/functions/${functionCode}/`));
+    const hasManifest = affected.files.includes(`src/resources/functions/${functionCode}.json`);
+    if (!hasSource && !hasManifest) {
+      errors.push(`function ${functionCode} 缺少对应源码或 function manifest file`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors: Array.from(new Set(errors)),
+    affected,
+    risk: {
+      tier: QUICK_SDD_RISK_TIER,
+      level: 'low',
+      mode: 'quick',
+      changeKind,
+      assessment: riskAssessment,
+      prohibitedFunctionImpacts: QUICK_FUNCTION_SAFETY_FIELDS,
+      exactScope: true,
+      maxTargets: QUICK_SDD_MAX_TARGETS,
+      maxFiles: QUICK_SDD_MAX_FILES,
+    },
+  };
+}
+
+function assertQuickSddScope(options = {}) {
+  const validation = validateQuickSddScope(options);
+  if (validation.valid) return validation;
+  const error = new Error(`不能创建 quick SDD change: ${validation.errors[0]}`);
+  error.code = 'SDD_QUICK_SCOPE_REJECTED';
+  error.details = validation.errors;
+  throw error;
+}
+
 function extractCodeFromPath(file, prefix) {
   if (!file.startsWith(prefix)) return null;
   const rest = file.slice(prefix.length);
@@ -323,7 +497,7 @@ function coversCodeTarget(normalized, key, code) {
 }
 
 function createChangeMetadata(changeId, options = {}) {
-  return {
+  const metadata = {
     schemaVersion: SDD_SCHEMA_VERSION,
     id: changeId,
     title: options.title || changeId,
@@ -344,6 +518,27 @@ function createChangeMetadata(changeId, options = {}) {
       bypasses: [],
     },
   };
+  if (options.changeMode) metadata.changeMode = options.changeMode;
+  if (options.riskTier) metadata.riskTier = options.riskTier;
+  if (options.changeKind) metadata.changeKind = options.changeKind;
+  if (options.riskMetadata) metadata.riskMetadata = options.riskMetadata;
+  if (options.scopePolicy) metadata.scopePolicy = options.scopePolicy;
+  try {
+    const sourceBase =
+      options.sourceBase ||
+      readGitSourceBase(options.cwd || process.cwd(), options.sourceBaseRef || 'HEAD');
+    if (sourceBase?.baseCommit && sourceBase?.treeHash) {
+      metadata.sourceBase = {
+        repo: sourceBase.repo,
+        baseCommit: sourceBase.baseCommit,
+        treeHash: sourceBase.treeHash,
+      };
+    }
+  } catch {
+    // SDD can still be used before a workspace is initialized as a Git repo.
+    // Release begin will require a reproducible source base for stale-worktree protection.
+  }
+  return metadata;
 }
 
 function formatAffectedList(items) {
@@ -406,18 +601,53 @@ function createDesignContent(meta) {
 `;
 }
 
-function createTasksContent() {
+function createTasksContent(meta = {}) {
+  if (meta.changeMode === 'quick') {
+    return [
+      '# Tasks',
+      '',
+      '## Implementation',
+      '',
+      '- [x] Record exact L1 scope and explicit approval basis',
+      '- [ ] Implement the focused change',
+      '',
+      '## Prepublish',
+      '',
+      '- [ ] Record implementation checks and dry-run evidence',
+      '- [ ] Confirm the exact release plan',
+      '',
+      '## Postpublish',
+      '',
+      '- [ ] Record publish/deploy result',
+      '',
+      '## Archive',
+      '',
+      '- [ ] Confirm the released change is ready to archive',
+      '',
+    ].join('\n');
+  }
   return [
     '# Tasks',
     '',
+    '## Implementation',
+    '',
     '- [ ] Confirm proposal and affected scope',
     '- [ ] Sharpen delta specs into behavior-first requirements and scenarios',
     '- [ ] Implement changes',
     '- [ ] Update coverage.json if affected resources change',
+    '',
+    '## Prepublish',
+    '',
     '- [ ] Record verification evidence',
-    '- [ ] Run `openxiangda sdd verify <change> --changed`',
     '- [ ] Run release plan/check commands',
-    '- [ ] Archive the change after release',
+    '',
+    '## Postpublish',
+    '',
+    '- [ ] Record publish/deploy result',
+    '',
+    '## Archive',
+    '',
+    '- [ ] Confirm the released change is ready to archive',
     '',
   ].join('\n');
 }
@@ -428,7 +658,7 @@ function createEvidenceContent() {
     '',
     '## Verification',
     '',
-    '- [ ] Record `openxiangda sdd verify <change> --changed` result',
+    '- [ ] Record implementation test/check output',
     '- [ ] Record workspace/resource/runtime check or dry-run output',
     '',
     '## Release',
@@ -547,7 +777,7 @@ function proposeSddChange(options = {}) {
   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, 'tasks.md'), createTasksContent(meta));
   fs.writeFileSync(path.join(changeDir, 'evidence.md'), createEvidenceContent());
   fs.writeFileSync(
     path.join(changeDir, 'specs', domain, 'spec.md'),
@@ -603,6 +833,8 @@ function approveSddChange(options = {}) {
     approvedAt: nowIso(),
     approvedBy: options.approvedBy || os.userInfo().username || 'unknown',
     approvalSummary: options.summary || options.note || loaded.meta.approvalSummary || '',
+    ...(options.approvalMode ? { approvalMode: options.approvalMode } : {}),
+    ...(options.approvalBasis ? { approvalBasis: options.approvalBasis } : {}),
     updatedAt: nowIso(),
   };
   writeJsonFile(loaded.metaFile, meta);
@@ -619,6 +851,85 @@ function approveSddChange(options = {}) {
   };
 }
 
+function proposeQuickSddChange(options = {}) {
+  const validation = assertQuickSddScope(options);
+  return proposeSddChange({
+    ...options,
+    affected: validation.affected,
+    riskLevel: validation.risk.level,
+    riskTier: validation.risk.tier,
+    changeMode: validation.risk.mode,
+    changeKind: validation.risk.changeKind,
+    riskMetadata: {
+      tier: validation.risk.tier,
+      level: validation.risk.level,
+      classification: 'explicit-l1-quick',
+      changeKind: validation.risk.changeKind,
+      exactScope: true,
+      assessment: validation.risk.assessment,
+      prohibitedFunctionImpacts: validation.risk.prohibitedFunctionImpacts,
+    },
+    scopePolicy: {
+      exact: true,
+      allowedTargets: ['pages', 'functions'],
+      maxTargets: validation.risk.maxTargets,
+      maxFiles: validation.risk.maxFiles,
+    },
+  });
+}
+
+function approveQuickSddChange(options = {}) {
+  const loaded = loadSddChange(options);
+  if (loaded.meta.changeMode !== 'quick' || loaded.meta.riskTier !== QUICK_SDD_RISK_TIER) {
+    throw new Error(`change ${loaded.changeId} 不是可 quick approve 的 L1 change`);
+  }
+  assertQuickSddScope({
+    affected: loaded.meta.affected,
+    riskTier: loaded.meta.riskTier,
+    changeKind: loaded.meta.changeKind,
+    riskAssessment: loaded.meta.riskMetadata?.assessment,
+  });
+  const summary = String(
+    options.summary || options.note || options.userIntent || ''
+  ).trim();
+  if (!summary) {
+    throw new Error('quick approve 需要 summary/userIntent 记录用户的明确变更意图');
+  }
+  return approveSddChange({
+    ...options,
+    summary,
+    approvalMode: 'quick-explicit-intent',
+    approvalBasis: 'explicit-user-request',
+  });
+}
+
+function createQuickSddChange(options = {}) {
+  const summary = String(
+    options.approvalSummary || options.summary || options.note || options.userIntent || ''
+  ).trim();
+  if (!summary) {
+    throw new Error('quick change 需要 approvalSummary/summary/userIntent 才能创建并批准');
+  }
+  assertQuickSddScope(options);
+  const proposed = proposeQuickSddChange(options);
+  const approved = approveQuickSddChange({
+    cwd: options.cwd,
+    configText: options.configText,
+    changeId: proposed.change.id,
+    summary,
+    approvedBy: options.approvedBy,
+  });
+  return {
+    ...proposed,
+    change: approved.change,
+    approved: true,
+    nextActions: [
+      `Implement only the exact L1 scope in openspec/changes/${proposed.change.id}`,
+      `Run staged verification: implementation -> prepublish -> postpublish -> archive`,
+    ],
+  };
+}
+
 function includesAll(list, required) {
   if (!required || required.length === 0) return true;
   if ((list || []).includes('*')) return true;
@@ -693,13 +1004,25 @@ function affectedCoversHighRiskFiles(affected, files = []) {
       if (!normalized.runtime && !includesAll(normalized.pages, [pageCode])) missing.push(file);
     } else if (file.startsWith('src/resources/functions/')) {
       const code = extractCodeFromPath(file, 'src/resources/functions/');
-      if (code && !coversCodeTarget(normalized, 'functions', code)) missing.push(file);
+      const isScopedContainer =
+        normalized.resources || normalized.backend || normalized.functions.length > 0;
+      if (code && !isScopedContainer && !coversCodeTarget(normalized, 'functions', code)) {
+        missing.push(file);
+      }
     } else if (file.startsWith('src/resources/automations/')) {
       const code = extractCodeFromPath(file, 'src/resources/automations/');
-      if (code && !coversCodeTarget(normalized, 'automations', code)) missing.push(file);
+      const isScopedContainer =
+        normalized.resources || normalized.backend || normalized.automations.length > 0;
+      if (code && !isScopedContainer && !coversCodeTarget(normalized, 'automations', code)) {
+        missing.push(file);
+      }
     } else if (file.startsWith('src/resources/workflows/')) {
       const code = extractCodeFromPath(file, 'src/resources/workflows/');
-      if (code && !coversCodeTarget(normalized, 'workflows', code)) missing.push(file);
+      const isScopedContainer =
+        normalized.resources || normalized.backend || normalized.workflows.length > 0;
+      if (code && !isScopedContainer && !coversCodeTarget(normalized, 'workflows', code)) {
+        missing.push(file);
+      }
     } else if (file.startsWith('src/resources/js-code-nodes/')) {
       const code = extractCodeFromPath(file, 'src/resources/js-code-nodes/');
       if (code && !coversCodeTarget(normalized, 'jsCodeNodes', code)) missing.push(file);
@@ -824,10 +1147,14 @@ function summarizeCoverage(coverage) {
   };
 }
 
-function chooseActiveChange(changes, targets = {}, highRiskFiles = []) {
+function chooseActiveChange(changes, targets = {}, highRiskFiles = [], options = {}) {
+  const requestedChangeId = options.changeId
+    ? normalizeChangeId(options.changeId)
+    : null;
   const candidates = changes
     .filter(item => item.valid && !['archived', 'rejected'].includes(item.metadata.status))
-    .filter(item => item.metadata.status === 'approved' && item.metadata.approvedAt);
+    .filter(item => item.metadata.status === 'approved' && item.metadata.approvedAt)
+    .filter(item => !requestedChangeId || item.id === requestedChangeId);
   return (
     candidates.find(item => {
       const legacyMode = (item.metadata?.schemaVersion || LEGACY_SDD_SCHEMA_VERSION) !== SDD_SCHEMA_VERSION;
@@ -836,10 +1163,55 @@ function chooseActiveChange(changes, targets = {}, highRiskFiles = []) {
         coverageCoversTargets(item.coverage, item.metadata.affected, targets, { allowFallback }).covered &&
         coverageCoversHighRiskFiles(item.coverage, item.metadata.affected, highRiskFiles, { allowFallback }).covered
       );
-    }) || candidates[0] || null
+    }) || null
   );
 }
 
+function getSddChangeScope(options = {}) {
+  const loaded = loadSddChange(options);
+  const affected = normalizeAffected(loaded.meta.affected || {});
+  const coverage = normalizeCoverageResources(loaded.coverage, {});
+  const releaseTargets = loaded.release && !loaded.release.__invalid
+    ? loaded.release.targets || {}
+    : {};
+  const mergeList = key => Array.from(new Set([
+    ...splitList(releaseTargets[key]),
+    ...splitList(coverage[key]),
+    ...splitList(affected[key]),
+  ])).sort();
+  const targets = {
+    forms: mergeList('forms'),
+    pages: mergeList('pages'),
+    functions: mergeList('functions'),
+    automations: mergeList('automations'),
+    workflows: mergeList('workflows'),
+    jsCodeNodes: mergeList('jsCodeNodes'),
+    resources: Boolean(releaseTargets.resources || coverage.resources || affected.resources),
+    runtime: Boolean(releaseTargets.runtime || coverage.runtime || affected.runtime),
+    other: Array.from(new Set(splitList(releaseTargets.other))).sort(),
+  };
+  const recordedChangedFiles = splitList(loaded.release?.changedFiles);
+  const ownedFiles = Array.from(new Set([
+    ...splitList(coverage.files),
+    ...splitList(affected.files),
+  ])).sort();
+  const changedFiles = Array.from(new Set([
+    ...recordedChangedFiles,
+    ...ownedFiles,
+  ])).sort();
+  return {
+    changeId: loaded.changeId,
+    change: loaded.meta,
+    coverage: loaded.coverage,
+    release: loaded.release,
+    targets,
+    changedFiles,
+    recordedChangedFiles,
+    ownedFiles,
+    commands: Array.isArray(loaded.release?.commands) ? loaded.release.commands : [],
+  };
+}
+
 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`.'];
@@ -916,13 +1288,21 @@ function buildSddGovernanceReport(options = {}) {
     };
   }
 
+  const requestedChangeId = options.changeId
+    ? normalizeChangeId(options.changeId)
+    : null;
   const changes = listChanges(governance.rootDir);
   activeChanges = changes.filter(
     item => item.valid && !['archived', 'rejected'].includes(item.metadata.status)
   );
-  activeChange = chooseActiveChange(activeChanges, targets, highRiskFiles);
+  activeChange = chooseActiveChange(activeChanges, targets, highRiskFiles, {
+    changeId: requestedChangeId,
+  });
   coverage = activeChange?.coverage || null;
-  const approved = getApprovedActiveChanges(governance.rootDir);
+  const approvedAll = getApprovedActiveChanges(governance.rootDir);
+  const approved = requestedChangeId
+    ? approvedAll.filter(item => item.id === requestedChangeId)
+    : approvedAll;
   if (!governance.strictHighRisk || (!hasHighRiskTargets(targets) && highRiskFiles.length === 0)) {
     checks.push({ name: 'sdd', status: 'ok', message: `${activeChanges.length} active changes` });
     return {
@@ -941,7 +1321,20 @@ function buildSddGovernanceReport(options = {}) {
     };
   }
 
-  if (approved.length === 0) {
+  const requestedChange = requestedChangeId
+    ? activeChanges.find(item => item.id === requestedChangeId)
+    : null;
+  if (requestedChangeId && !requestedChange) {
+    errors.push({
+      name: 'sdd-change-not-found',
+      message: `指定的 SDD change 不存在或已归档: ${requestedChangeId}`,
+    });
+  } else if (requestedChangeId && approved.length === 0) {
+    errors.push({
+      name: 'sdd-change-not-approved',
+      message: `指定的 SDD change 尚未 approve: ${requestedChangeId}`,
+    });
+  } else if (approved.length === 0) {
     errors.push({
       name: 'sdd-approved-change-required',
       message: '高风险变更发布前必须存在 approved SDD change；先运行 openxiangda sdd propose <change> 并经 openxiangda sdd approve <change> 确认。',
@@ -949,7 +1342,9 @@ function buildSddGovernanceReport(options = {}) {
   } else if (!activeChange) {
     errors.push({
       name: 'sdd-coverage-required',
-      message: 'approved SDD change 的 coverage.json 未覆盖本次发布目标或高风险文件。',
+      message: requestedChangeId
+        ? `指定 change ${requestedChangeId} 的 coverage.json 未覆盖本次发布目标或高风险文件。`
+        : 'approved SDD change 的 coverage.json 未覆盖本次发布目标或高风险文件。',
     });
   } else {
     const verify = verifySddChange({
@@ -958,6 +1353,7 @@ function buildSddGovernanceReport(options = {}) {
       changeId: activeChange.id,
       targets,
       files,
+      stage: options.stage || options.verifyStage,
       releasePlan: {
         targets,
         changedFiles: files,
@@ -1001,8 +1397,96 @@ function readUncheckedChecklist(file, missingMessage) {
     .map(item => `${path.basename(file)}:${item.index} ${item.line}`);
 }
 
-function readUncheckedTasks(changeDir) {
-  return readUncheckedChecklist(path.join(changeDir, 'tasks.md'), 'tasks.md 缺失');
+function normalizeSddVerifyStage(value) {
+  const stage = String(value || 'default').trim().toLowerCase();
+  if (['default', 'legacy', 'all'].includes(stage)) return 'default';
+  if (stage === 'pre-publish') return 'prepublish';
+  if (stage === 'post-publish') return 'postpublish';
+  if (!SDD_VERIFY_STAGES.includes(stage)) {
+    throw new Error(
+      `未知 SDD verify stage: ${value}。可选 implementation, prepublish, postpublish, archive`
+    );
+  }
+  return stage;
+}
+
+function getSddVerifyStagePolicy(stageValue) {
+  const stage = normalizeSddVerifyStage(stageValue);
+  if (stage === 'default') {
+    return {
+      stage,
+      taskStages: new Set(SDD_VERIFY_STAGES),
+      evidenceStages: new Set(SDD_VERIFY_STAGES),
+      requireRelease: true,
+    };
+  }
+  const rank = SDD_VERIFY_STAGES.indexOf(stage);
+  return {
+    stage,
+    taskStages: new Set(SDD_VERIFY_STAGES.slice(0, rank + 1)),
+    evidenceStages:
+      stage === 'implementation'
+        ? new Set()
+        : new Set(SDD_VERIFY_STAGES.slice(1, rank + 1)),
+    requireRelease: stage !== 'implementation',
+  };
+}
+
+function inferChecklistStage(kind, section, line) {
+  const explicit = line.match(/sdd-stage\s*:\s*(implementation|prepublish|postpublish|archive)/i)?.[1];
+  if (explicit) return explicit.toLowerCase();
+  const normalizedSection = String(section || '').toLowerCase().replace(/[^a-z]/g, '');
+  if (normalizedSection.includes('implementation')) return 'implementation';
+  if (normalizedSection.includes('prepublish') || normalizedSection.includes('verification')) {
+    return 'prepublish';
+  }
+  if (normalizedSection.includes('postpublish') || normalizedSection === 'release') {
+    return 'postpublish';
+  }
+  if (normalizedSection.includes('archive')) return 'archive';
+  if (/archive|归档/i.test(line)) return 'archive';
+  if (/publish\/deploy result|publish output|release output|发布结果|上线结果/i.test(line)) {
+    return 'postpublish';
+  }
+  if (
+    kind === 'evidence' ||
+    /verification evidence|release plan|workspace\/resource\/runtime check|dry-run|发布计划|验证证据/i.test(line)
+  ) {
+    return 'prepublish';
+  }
+  return 'implementation';
+}
+
+function readUncheckedChecklistForStages(file, options = {}) {
+  const requiredStages = options.requiredStages || new Set(SDD_VERIFY_STAGES);
+  if (requiredStages.size === 0) return [];
+  if (!fs.existsSync(file)) {
+    return [options.missingMessage || `${path.basename(file)} 缺失`];
+  }
+  const result = [];
+  let section = '';
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const heading = line.match(/^##\s+(.+)$/);
+    if (heading) {
+      section = heading[1].trim();
+      continue;
+    }
+    if (!/^-\s*\[\s\]/.test(line)) continue;
+    const stage = inferChecklistStage(options.kind || 'tasks', section, line);
+    if (!requiredStages.has(stage)) continue;
+    result.push(`${path.basename(file)}:${index + 1} [${stage}] ${line}`);
+  }
+  return result;
+}
+
+function readUncheckedTasks(changeDir, stagePolicy = getSddVerifyStagePolicy('default')) {
+  return readUncheckedChecklistForStages(path.join(changeDir, 'tasks.md'), {
+    kind: 'tasks',
+    requiredStages: stagePolicy.taskStages,
+    missingMessage: 'tasks.md 缺失',
+  });
 }
 
 function validateCoverageManifest(coverage, meta, targets, highRiskFiles, legacyMode = false) {
@@ -1151,7 +1635,8 @@ function validateDeltaSpecs(changeDir) {
   };
 }
 
-function buildUpdatedReleaseManifest(loaded, releasePlan) {
+function buildUpdatedReleaseManifest(loaded, releasePlan, verificationStage = 'default') {
+  const verifiedAt = nowIso();
   return {
     schemaVersion: SDD_SCHEMA_VERSION,
     changeId: loaded.changeId,
@@ -1159,12 +1644,17 @@ function buildUpdatedReleaseManifest(loaded, releasePlan) {
     targets: releasePlan?.targets || loaded.release?.targets || {},
     changedFiles: releasePlan?.changedFiles || loaded.release?.changedFiles || [],
     commands: releasePlan?.commands || loaded.release?.commands || [],
-    verifiedAt: nowIso(),
+    verifiedAt,
+    verificationStage,
+    verificationStages: {
+      ...(loaded.release?.verificationStages || {}),
+      [verificationStage]: { verifiedAt },
+    },
   };
 }
 
-function updateReleaseManifest(loaded, releasePlan) {
-  const release = buildUpdatedReleaseManifest(loaded, releasePlan);
+function updateReleaseManifest(loaded, releasePlan, verificationStage = 'default') {
+  const release = buildUpdatedReleaseManifest(loaded, releasePlan, verificationStage);
   writeJsonFile(loaded.releaseFile, release);
   return release;
 }
@@ -1202,6 +1692,8 @@ function validateReleaseManifest(release, releasePlan, legacyMode = false) {
 
 function verifySddChange(options = {}) {
   const loaded = loadSddChange(options);
+  const stagePolicy = getSddVerifyStagePolicy(options.stage || options.phase);
+  const verificationStage = stagePolicy.stage;
   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;
@@ -1230,7 +1722,7 @@ function verifySddChange(options = {}) {
   const deltaValidation = validateDeltaSpecs(loaded.changeDir);
   errors.push(...deltaValidation.errors);
   warnings.push(...deltaValidation.warnings);
-  const uncheckedTasks = readUncheckedTasks(loaded.changeDir);
+  const uncheckedTasks = readUncheckedTasks(loaded.changeDir, stagePolicy);
   if (uncheckedTasks.length > 0) {
     errors.push({
       name: 'sdd-unfinished-tasks',
@@ -1239,7 +1731,11 @@ function verifySddChange(options = {}) {
     });
   }
   const evidenceFile = path.join(loaded.changeDir, 'evidence.md');
-  const uncheckedEvidence = readUncheckedChecklist(evidenceFile, 'evidence.md 缺失');
+  const uncheckedEvidence = readUncheckedChecklistForStages(evidenceFile, {
+    kind: 'evidence',
+    requiredStages: stagePolicy.evidenceStages,
+    missingMessage: 'evidence.md 缺失',
+  });
   if (uncheckedEvidence.length > 0) {
     errors.push({
       name: 'sdd-evidence-incomplete',
@@ -1249,25 +1745,35 @@ function verifySddChange(options = {}) {
   }
   const release =
     options.writeMetadata && options.releasePlan && loaded.release && !loaded.release.__invalid
-      ? buildUpdatedReleaseManifest(loaded, options.releasePlan)
+      ? buildUpdatedReleaseManifest(loaded, options.releasePlan, verificationStage)
       : loaded.release;
-  const releaseValidation = validateReleaseManifest(release, options.releasePlan, legacyMode);
-  errors.push(...releaseValidation.errors);
-  warnings.push(...releaseValidation.warnings);
+  if (stagePolicy.requireRelease) {
+    const releaseValidation = validateReleaseManifest(release, options.releasePlan, legacyMode);
+    errors.push(...releaseValidation.errors);
+    warnings.push(...releaseValidation.warnings);
+  }
   const passed = errors.length === 0;
+  const verifiedAt = nowIso();
   const verifiedMeta = {
     ...loaded.meta,
     release: {
       ...(loaded.meta.release || {}),
-      plannedCommands: options.releasePlan?.commands || loaded.meta.release?.plannedCommands || release.commands || [],
-      lastVerifiedAt: nowIso(),
+      plannedCommands: options.releasePlan?.commands || loaded.meta.release?.plannedCommands || release?.commands || [],
+      lastVerifiedAt: verifiedAt,
     },
-    updatedAt: nowIso(),
+    verification: {
+      ...(loaded.meta.verification || {}),
+      [verificationStage]: {
+        passed,
+        verifiedAt,
+      },
+    },
+    updatedAt: verifiedAt,
   };
   let metadataWritten = false;
   if (options.writeMetadata && passed) {
     if (options.releasePlan && loaded.release && !loaded.release.__invalid) {
-      updateReleaseManifest(loaded, options.releasePlan);
+      updateReleaseManifest(loaded, options.releasePlan, verificationStage);
     }
     writeJsonFile(loaded.metaFile, verifiedMeta);
     metadataWritten = true;
@@ -1285,6 +1791,12 @@ function verifySddChange(options = {}) {
     metadataWritten,
     targets,
     highRiskFiles,
+    stage: verificationStage,
+    stageRequirements: {
+      tasks: Array.from(stagePolicy.taskStages),
+      evidence: Array.from(stagePolicy.evidenceStages),
+      release: stagePolicy.requireRelease,
+    },
   };
 }
 
@@ -1315,8 +1827,13 @@ function appendBypassLog(options = {}) {
   ];
   fs.appendFileSync(file, entry.join('\n'));
 
+  const requestedChangeId = options.changeId ? normalizeChangeId(options.changeId) : null;
   const approved = listChanges(governance.rootDir).find(
-    item => item.valid && item.metadata.status === 'approved' && item.metadata.approvedAt
+    item =>
+      item.valid &&
+      item.metadata.status === 'approved' &&
+      item.metadata.approvedAt &&
+      (!requestedChangeId || item.id === requestedChangeId)
   );
   if (approved) {
     appendToEvidence(approved.dir, [
@@ -1340,13 +1857,17 @@ function buildSddStatus(options = {}) {
   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 activeChange = chooseActiveChange(changes, releasePlan.targets || {}, highRiskFiles, {
+    changeId: options.changeId,
+  });
   const report = buildSddGovernanceReport({
     cwd: options.cwd,
     configText: options.configText,
     targets: releasePlan.targets || {},
     files: releasePlan.changedFiles || [],
     commands: releasePlan.commands || [],
+    changeId: options.changeId,
+    stage: options.stage || options.verifyStage,
   });
   return {
     cwd: options.cwd || process.cwd(),
@@ -1461,7 +1982,7 @@ function syncSddChange(options = {}) {
 }
 
 function archiveSddChange(options = {}) {
-  const verify = verifySddChange(options);
+  const verify = verifySddChange({ ...options, stage: 'archive' });
   if (!verify.passed && !options.force) {
     const first = verify.errors[0];
     throw new Error(`change 不能归档: ${first.message}`);
@@ -1492,16 +2013,27 @@ function archiveSddChange(options = {}) {
 
 module.exports = {
   DEFAULT_SDD_DIR,
+  QUICK_FUNCTION_SAFETY_FIELDS,
+  QUICK_SDD_ALLOWED_KINDS,
+  QUICK_SDD_RISK_TIER,
   SDD_SCHEMA_VERSION,
+  SDD_VERIFY_STAGES,
   appendBypassLog,
+  approveQuickSddChange,
   archiveSddChange,
   buildSddGovernanceReport,
   buildSddStatus,
+  createQuickSddChange,
   getSddGovernanceConfig,
+  getSddChangeScope,
+  getSddVerifyStagePolicy,
   initSddWorkspace,
   normalizeAffected,
+  normalizeSddVerifyStage,
+  proposeQuickSddChange,
   proposeSddChange,
   approveSddChange,
   syncSddChange,
+  validateQuickSddScope,
   verifySddChange,
 };