@chenmk/superflow 0.4.0 → 0.5.1

package/assets/scripts/superflow-managed-work-check.mjs

@@ -18,7 +18,14 @@ const task = JSON.parse(fs.readFileSync(taskFile, 'utf8'));
 verifyContract(task);
 const runsDir = path.join(taskDir, 'runs');
 const runs = fs.existsSync(runsDir)
-  ? fs.readdirSync(runsDir).filter((entry) => fs.statSync(path.join(runsDir, entry)).isDirectory())
+  ? fs.readdirSync(runsDir).filter((entry) => {
+      const candidate = path.join(runsDir, entry);
+      return (
+        entry.startsWith('run-') &&
+        fs.statSync(candidate).isDirectory() &&
+        fs.existsSync(path.join(candidate, 'run-state.json'))
+      );
+    })
   : [];
 if (runs.length !== 1) fail(`首版要求一个活动 run，实际 ${runs.length}`);
 
@@ -31,39 +38,68 @@ for (const file of [stateFile, journalFile, reportFile]) {
 }
 const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
 
-assertMax('reviewRound', state.reviewRound, 5);
-assertMax('executorInvocations', state.executorInvocations, 7);
-assertMax('totalAgentInvocations', state.totalAgentInvocations, 12);
-assertMax('reviewInvocations', state.reviewInvocations, 5);
+if (task.budgets?.unlimitedAgentInvocations !== true) {
+  assertMax('reviewRound', state.reviewRound, 10);
+  assertMax(
+    'executorInvocations',
+    state.executorInvocations,
+    20 + (state.executorInvocationCredits ?? 0),
+  );
+  assertMax(
+    'totalAgentInvocations',
+    state.totalAgentInvocations,
+    30 + (state.totalAgentInvocationCredits ?? 0),
+  );
+  assertMax('reviewInvocations', state.reviewInvocations, 10);
+}
 if (state.contractHash !== task.contractHash) fail('任务合同哈希与运行状态不一致');
 if (state.status !== task.status) fail('任务合同状态与运行状态不一致');
 if (state.executorInvocations > 0 && !state.executorSession?.sessionId) {
   fail('已有执行调用但缺少执行会话编号');
 }
-if (state.reviewInvocations > 0 && !state.supervisorSession?.sessionId) {
-  fail('已有正式检查但缺少监督会话编号');
-}
 const events = verifyJournal(journalFile);
 
-if (state.status === 'awaiting_git_approval') {
+const deliveryStatuses = new Set([
+  'local_delivery_ready',
+  'environment_validation_blocked',
+  'release_ready',
+]);
+if (deliveryStatuses.has(state.status)) {
   if (!state.lastExecutorResult || !fs.existsSync(state.lastExecutorResult)) {
-    fail('等待 Git 批准状态缺少最终执行结果');
+    fail('交付状态缺少最终执行结果');
   }
   if (!state.lastReviewResult || !fs.existsSync(state.lastReviewResult)) {
-    fail('等待 Git 批准状态缺少最终检查结果');
+    fail('交付状态缺少最终检查结果');
   }
   assertInsideRun(state.lastExecutorResult, runDir, '最终执行结果');
   assertInsideRun(state.lastReviewResult, runDir, '最终检查结果');
   const executor = JSON.parse(fs.readFileSync(state.lastExecutorResult, 'utf8'));
-  verifyExecutorEvidence(task, executor);
   const review = JSON.parse(fs.readFileSync(state.lastReviewResult, 'utf8'));
+  const completion = verifyOpenSpecTasksComplete(task, executor);
+  verifyDeliveryStatus(state.status, completion);
+  if (
+    task.source === 'sdd' &&
+    !review.verificationCommands?.some(
+      (item) =>
+        item.exitCode === 0 &&
+        /openspec\s+instructions\s+apply/i.test(item.command),
+    )
+  ) {
+    fail('SDD 最终评审缺少 openspec instructions apply 命令证据');
+  }
   if (review.result !== 'pass' || review.findings?.some((item) => item.blocking)) {
-    fail('等待 Git 批准状态与最终检查结论不一致');
+    fail('交付状态与最终检查结论不一致');
   }
+  verifyExecutorEvidence(task, executor, review, runDir);
   const readyEvents = events.filter((event) => event.eventType === 'run.delivery_ready');
+  const reopenedEvents = events.filter(
+    (event) => event.eventType === 'run.delivery_reopened',
+  );
   const expectedReadyEvents = beforeReadyEvent ? 0 : 1;
-  if (readyEvents.length !== expectedReadyEvents) {
-    fail(`交付就绪事件数量应为 ${expectedReadyEvents}，实际 ${readyEvents.length}`);
+  if (readyEvents.length !== reopenedEvents.length + expectedReadyEvents) {
+    fail(
+      `交付就绪事件应比重新打开事件多 ${expectedReadyEvents} 条，实际就绪 ${readyEvents.length}、重新打开 ${reopenedEvents.length}`,
+    );
   }
 }
 
@@ -77,18 +113,35 @@ function assertMax(name, value, max) {
 
 function verifyContract(contract) {
   const budgets = contract.budgets ?? {};
-  assertPositiveMax('maxReviewRounds', budgets.maxReviewRounds, 5, true);
-  assertPositiveMax('maxExecutorInvocations', budgets.maxExecutorInvocations, 7, true);
-  assertPositiveMax('maxTotalAgentInvocations', budgets.maxTotalAgentInvocations, 12, true);
+  if (
+    budgets.executorPhysicalStopAt !== undefined &&
+    (!Number.isInteger(budgets.executorPhysicalStopAt) ||
+      budgets.executorPhysicalStopAt <= 0)
+  ) {
+    fail('executorPhysicalStopAt 必须是正整数');
+  }
+  assertPositiveMax('maxReviewRounds', budgets.maxReviewRounds, 10, true);
+  assertPositiveMax('maxExecutorInvocations', budgets.maxExecutorInvocations, 20, true);
+  assertPositiveMax('maxTotalAgentInvocations', budgets.maxTotalAgentInvocations, 30, true);
   assertPositiveMax('maxActiveRunHours', budgets.maxActiveRunHours, 24, false);
   assertPositiveMax('maxSingleInvocationHours', budgets.maxSingleInvocationHours, 3, false);
   if (contract.supervisorAgent === contract.executorAgent) {
     fail('监督 Agent 和执行 Agent 不能相同');
   }
+  if (contract.supervisorExecution !== 'external_host') {
+    fail('监督执行模式只允许 external_host');
+  }
   const permissions = contract.permissions ?? {};
   for (const key of ['gitCommit', 'gitPush', 'productionWrites', 'bypassSandbox']) {
     if (permissions[key] !== false) fail(`不可覆盖的权限边界被放宽: ${key}`);
   }
+  const disclosure = permissions.externalModelDataDisclosure;
+  if (!disclosure?.approved || !disclosure.approvedBy || !disclosure.approvedAt) {
+    fail('缺少任务级外部研发 Agent 源码披露授权');
+  }
+  if (!Array.isArray(disclosure.scope) || disclosure.scope.length === 0) {
+    fail('外部研发 Agent 源码披露授权缺少仓库作用域');
+  }
   if (contract.taskPrompt) {
     const expectedSnapshot = path.join(
       path.resolve(contract.projectRoot),
@@ -117,9 +170,16 @@ function verifyContract(contract) {
     ...(contract.language ? { language: contract.language } : {}),
     objective: contract.objective,
     doneCriteria: contract.doneCriteria,
+    ...(contract.mandatoryEngineeringRules?.length
+      ? { mandatoryEngineeringRules: contract.mandatoryEngineeringRules }
+      : {}),
     taskPrompt: contract.taskPrompt,
     supervisorAgent: contract.supervisorAgent,
     executorAgent: contract.executorAgent,
+    ...(contract.supervisorExecution
+      ? { supervisorExecution: contract.supervisorExecution }
+      : {}),
+    ...(contract.executionMode ? { executionMode: contract.executionMode } : {}),
     permissions: contract.permissions,
     budgets: contract.budgets,
   };
@@ -133,20 +193,220 @@ function assertPositiveMax(name, value, max, integer) {
   }
 }
 
-function verifyExecutorEvidence(task, result) {
-  if (result.status !== 'ready_for_review') fail('最终执行结果不是可检查状态');
-  if (!Array.isArray(result.commands) || result.commands.some((item) => item.exitCode !== 0)) {
-    fail('最终执行结果缺少成功命令证据或仍含失败命令');
+function verifyOpenSpecTasksComplete(task, executor) {
+  if (task.source !== 'sdd' || !task.taskPrompt?.originalPath) {
+    return { localPending: [], environmentPending: [], releasePending: [] };
+  }
+  let current = path.dirname(path.resolve(task.taskPrompt.originalPath));
+  const projectRoot = path.resolve(task.projectRoot);
+  while (current.startsWith(projectRoot)) {
+    const tasksFile = path.join(current, 'tasks.md');
+    if (fs.existsSync(tasksFile)) {
+      const tasks = fs.readFileSync(tasksFile, 'utf8')
+        .split(/\r?\n/)
+        .filter((line) => /^\s*- \[[ xX]\]/.test(line))
+        .map((line, index) => parseCompletionTask(line, index));
+      const localPending = tasks.filter(
+        (item) => !item.completed && item.category === 'local_required',
+      );
+      const environmentPending = tasks.filter(
+        (item) => !item.completed && item.category === 'environment_required',
+      );
+      const releasePending = tasks.filter(
+        (item) => !item.completed && item.category === 'release_required',
+      );
+      if (localPending.length > 0) {
+        fail(`OpenSpec tasks.md 仍有 ${localPending.length} 个本地可执行任务未完成`);
+      }
+      const evidence = new Map(
+        (executor.taskEvidence ?? []).map((item) => [item.taskId, item]),
+      );
+      const successfulCommands = (executor.commands ?? []).filter(
+        isAcceptedEvidenceCommand,
+      );
+      const derivedEvidencePaths = [
+        ...(executor.evidence ?? []),
+        tasksFile,
+        path.join(current, 'test-report.md'),
+      ].filter((item) => taskEvidencePathExists(task, item));
+      for (const item of tasks.filter(
+        (taskItem) =>
+          taskItem.completed && taskItem.category === 'local_required',
+      )) {
+        const proof = evidence.get(item.taskId);
+        if (successfulCommands.length > 0 && derivedEvidencePaths.length > 0) {
+          continue;
+        }
+        if (!proof) {
+          fail(`已勾选本地任务 ${item.taskId} 缺少可推导的真实交付证据`);
+        }
+        if (
+          proof.owner !== 'executor' ||
+          !proof.evidencePaths?.length ||
+          !proof.verificationCommands?.length ||
+          !proof.evidencePaths.every((item) => taskEvidencePathExists(task, item)) ||
+          !proof.verificationCommands.every((command) =>
+            executor.commands?.some(
+              (item) =>
+                isAcceptedEvidenceCommand(item) &&
+                verificationCommandCovered(command, item.command),
+            ),
+          ) ||
+          !proof.changedFiles.every((file) => executor.changedFiles?.includes(file))
+        ) {
+          fail(`已勾选本地任务 ${item.taskId} 缺少结构化交付证据`);
+        }
+      }
+      if (
+        environmentPending.length + releasePending.length > 0 &&
+        (!Array.isArray(executor.releasePrerequisites) ||
+          executor.releasePrerequisites.length === 0)
+      ) {
+        fail(
+          `OpenSpec tasks.md 有 ${environmentPending.length + releasePending.length} 个环境/发布前置，但执行结果未记录 releasePrerequisites`,
+        );
+      }
+      return { localPending, environmentPending, releasePending };
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  fail('SDD 托管任务未找到 OpenSpec tasks.md');
+}
+
+function isAcceptedEvidenceCommand(command) {
+  if (command.exitCode === 0) return true;
+  if (command.exitCode !== 1 && command.exitCode !== 2) return false;
+  return (
+    /^(?:\s*)(?:grep|rg|pgrep|lsof|ls|ss|netstat|git\s+(?:status|diff)|find)\b/i.test(
+      command.command,
+    ) &&
+    /(?:none|empty|no\s+(?:match|orphan|process|change|listener|such\s+file)|not found|does not exist|无匹配|无残留|未发现|没有|不存在|空)/i.test(
+      command.result,
+    )
+  );
+}
+
+function verificationCommandCovered(expected, actual) {
+  if (expected === actual) return true;
+  const expectedTests = mavenTestSelectors(expected);
+  const actualTests = mavenTestSelectors(actual);
+  return (
+    expectedTests.length > 0 &&
+    actualTests.length > 0 &&
+    expectedTests.every((test) => actualTests.includes(test))
+  );
+}
+
+function mavenTestSelectors(command) {
+  if (!/(?:^|\s)(?:\.\/)?mvn(?:\s|$)/.test(command)) return [];
+  const match = command.match(/-Dtest=([^\s]+)/);
+  return match?.[1].split(',').filter(Boolean) ?? [];
+}
+
+function taskEvidencePathExists(task, evidencePath) {
+  if (path.isAbsolute(evidencePath)) return fs.existsSync(evidencePath);
+  const bases = [
+    ...(findTaskDirectory(task) ? [findTaskDirectory(task)] : []),
+    ...(task.taskPrompt?.originalPath
+      ? [path.dirname(task.taskPrompt.originalPath)]
+      : []),
+    task.projectRoot,
+    ...(task.relatedProjectRoots ?? []),
+  ];
+  return bases.some((base) => fs.existsSync(path.resolve(base, evidencePath)));
+}
+
+function findTaskDirectory(task) {
+  if (!task.taskPrompt?.originalPath) return null;
+  let current = path.dirname(path.resolve(task.taskPrompt.originalPath));
+  const roots = [task.projectRoot, ...(task.relatedProjectRoots ?? [])].map(
+    (root) => path.resolve(root),
+  );
+  while (roots.some((root) => current.startsWith(root))) {
+    if (fs.existsSync(path.join(current, 'tasks.md'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+function parseCompletionTask(line, index) {
+  const completed = /^\s*- \[[xX]\]/.test(line);
+  const text = line.replace(/^\s*- \[[ xX]\]\s*/, '').trim();
+  const match = text.match(/^([A-Za-z]*\d+(?:\.\d+)*|[A-Z][A-Z0-9_-]+)\b/);
+  const category = /\[environment_required\]/i.test(text)
+    ? 'environment_required'
+    : /\[release_required\]/i.test(text)
+      ? 'release_required'
+      : 'local_required';
+  return { taskId: match?.[1] ?? `task-${index + 1}`, completed, category };
+}
+
+function verifyDeliveryStatus(status, completion) {
+  if (status === 'environment_validation_blocked' && completion.environmentPending.length === 0) {
+    fail('environment_validation_blocked 状态没有待完成环境验收');
+  }
+  if (status === 'local_delivery_ready' && completion.environmentPending.length > 0) {
+    fail('local_delivery_ready 状态仍有环境验收未完成');
   }
-  if (Array.isArray(result.blockers) && result.blockers.length > 0) {
-    fail('最终执行结果仍含阻塞项');
+  if (
+    status === 'release_ready' &&
+    completion.environmentPending.length + completion.releasePending.length > 0
+  ) {
+    fail('release_ready 状态仍有环境或发布任务未完成');
+  }
+}
+
+function verifyExecutorEvidence(task, result, review, runDir) {
+  if (!['ready_for_review', 'blocked'].includes(result.status)) {
+    fail('最终执行结果既不可检查也不是诚实阻塞状态');
+  }
+  if (!Array.isArray(result.commands)) fail('最终执行结果缺少命令证据');
+  if (result.status === 'blocked' && review.result !== 'pass') {
+    fail('执行者阻塞结果未经监督者判定为非阻断发布前置');
+  }
+  if (result.status === 'ready_for_review' && result.blockers?.length > 0) {
+    fail('可检查执行结果仍含阻塞项');
   }
   if (task.profile === 'engineering' || task.profile === 'sdd') {
-    const categories = new Set(result.commands.flatMap((item) => verificationCategories(item.command)));
-    if (categories.size < 2) fail('工程任务缺少至少两类成功验证证据');
+    const successful = loadExecutorCommands(runDir)
+      .filter((item) => item.exitCode === 0);
+    const categories = new Set(
+      successful.flatMap((item) => verificationCategories(item.command)),
+    );
+    const required = requiredVerificationCategories(projectRoot);
+    if (categories.size < required) fail('工程任务缺少至少两类成功验证证据');
   }
 }
 
+function requiredVerificationCategories(root) {
+  const packageFile = path.join(root, 'package.json');
+  if (!fs.existsSync(packageFile)) return 2;
+  try {
+    const scripts = JSON.parse(fs.readFileSync(packageFile, 'utf8')).scripts ?? {};
+    const hasTest = typeof scripts.test === 'string';
+    const hasRunnableTarget = ['build', 'start', 'dev', 'serve']
+      .some((name) => typeof scripts[name] === 'string');
+    return hasTest && !hasRunnableTarget ? 1 : 2;
+  } catch {
+    return 2;
+  }
+}
+
+function loadExecutorCommands(runDir) {
+  return fs.readdirSync(runDir)
+    .filter((entry) => /^executor-result-\d+\.json$/.test(entry))
+    .flatMap((entry) => {
+      const result = JSON.parse(
+        fs.readFileSync(path.join(runDir, entry), 'utf8'),
+      );
+      return Array.isArray(result.commands) ? result.commands : [];
+    });
+}
+
 function verificationCategories(command = '') {
   const value = command.toLowerCase();
   const categories = [];
@@ -155,6 +415,7 @@ function verificationCategories(command = '') {
       || /mvn(?:\s+[^\s]+)*\s+test/.test(value)
       || /gradle\w*\s+test/.test(value)) categories.push('test');
   if (/(?:npm|pnpm|yarn)\s+(?:run\s+)?build/.test(value)
+      || /(?:^|[\s/])(?:vite|vue-cli-service)\s+build(?:\s|$)/.test(value)
       || /(^|\s)(tsc|make|cmake|compile)(\s|$)/.test(value)
       || /mvn(?:\s+[^\s]+)*\s+(?:compile|package|verify)/.test(value)
       || /gradle\w*\s+(?:build|assemble)/.test(value)

package/assets/scripts/superflow-managed-work-guard.sh

@@ -6,98 +6,12 @@ set -u
 ROLE="${SUPERFLOW_MANAGED_ROLE:-}"
 [ -n "$ROLE" ] || exit 0
 
-block() {
-  echo "[Superflow 托管任务门禁] $1" >&2
-  exit 2
-}
-
-case "$ROLE" in
-  supervisor|executor) ;;
-  *) block "检测到非法托管角色，按失败关闭。" ;;
-esac
-
-INPUT=""
-if [ ! -t 0 ]; then
-  INPUT=$(cat 2>/dev/null || true)
-fi
-[ -n "$INPUT" ] || block "Hook 没有收到工具调用数据，按失败关闭。"
-
-VALID_JSON=$(printf '%s' "$INPUT" | python3 -c "
-import json, sys
-try:
-    value = json.load(sys.stdin)
-    print('yes' if isinstance(value, dict) else 'no')
-except Exception:
-    print('no')
-" 2>/dev/null)
-[ "$VALID_JSON" = "yes" ] || block "Hook 输入不是有效 JSON，按失败关闭。"
-
-read_field() {
-  local field="$1"
-  printf '%s' "$INPUT" | python3 -c "
-import json, sys
-try:
-    data = json.load(sys.stdin)
-except Exception:
-    print('')
-    raise SystemExit
-tool_input = data.get('tool_input', {})
-print(tool_input.get('$field') or '')
-" 2>/dev/null
-}
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+GUARD="$SCRIPT_DIR/superflow-managed-command-guard.py"
 
-TOOL_NAME=$(printf '%s' "$INPUT" | python3 -c "
-import json, sys
-try:
-    data = json.load(sys.stdin)
-except Exception:
-    print('')
-    raise SystemExit
-print(data.get('tool_name') or data.get('tool') or '')
-" 2>/dev/null)
-FILE_PATH=$(read_field file_path)
-[ -n "$FILE_PATH" ] || FILE_PATH=$(read_field path)
-[ -n "$FILE_PATH" ] || FILE_PATH=$(read_field file)
-COMMAND=$(read_field command)
-[ -n "$COMMAND" ] || COMMAND=$(read_field cmd)
-
-normalize() {
-  printf '%s' "$1" | sed 's|\\|/|g'
-}
-
-FILE_PATH=$(normalize "$FILE_PATH")
-COMMAND=$(printf '%s' "$COMMAND" | tr '\n' ' ')
-
-if [ "$ROLE" = "supervisor" ]; then
-  case "$TOOL_NAME" in
-    Edit|Write|MultiEdit|NotebookEdit|apply_patch)
-      block "监督角色只允许检查，禁止修改目标文件。"
-      ;;
-  esac
-  if [ -n "$COMMAND" ] && printf '%s' "$COMMAND" | grep -Eiq \
-    '(^|[[:space:]])(rm|mv|cp|mkdir|touch|chmod|chown)([[:space:]]|$)|git[[:space:]]+(add|commit|push|tag|reset|checkout|restore)|npm[[:space:]]+publish|apply_patch|sed[[:space:]]+-i|(^|[^>])>[>|[:space:]]|tee[[:space:]]'; then
-    block "监督角色的 Bash 仅允许只读检查，检测到可能写入的命令。"
-  fi
-fi
-
-if [ "$ROLE" = "executor" ]; then
-  case "$TOOL_NAME" in
-    Edit|Write|MultiEdit|NotebookEdit|apply_patch)
-      [ -n "$FILE_PATH" ] || block "写入工具缺少目标路径，按失败关闭。"
-      ;;
-  esac
-  if [ -n "$FILE_PATH" ] && printf '%s' "$FILE_PATH" | grep -Eq \
-    '(^|/)\.superflow/tasks/'; then
-    block "执行角色禁止修改托管状态、事件、Prompt 和过程报告。"
-  fi
-  if [ -n "$COMMAND" ] && printf '%s' "$COMMAND" | grep -Eq \
-    '\.superflow/tasks/'; then
-    block "执行角色的 Bash 禁止直接访问托管运行目录，请使用提示词中提供的只读证据。"
-  fi
-  if [ -n "$COMMAND" ] && printf '%s' "$COMMAND" | grep -Eiq \
-    'git[[:space:]]+(add|commit|push|tag)|npm[[:space:]]+publish|dangerously-(bypass|skip)|kubectl[[:space:]]+(apply|delete)|helm[[:space:]]+(install|upgrade)|DROP[[:space:]]+(DATABASE|TABLE)|TRUNCATE[[:space:]]+TABLE'; then
-    block "执行角色禁止自动 Git 提交/推送、发布、部署、绕过沙箱或高破坏数据库操作。"
-  fi
+if [ ! -f "$GUARD" ]; then
+  echo "[Superflow 托管任务门禁] 缺少命令门禁脚本，按失败关闭：$GUARD" >&2
+  exit 2
 fi
 
-exit 0
+exec python3 "$GUARD"

package/assets/skills/superflow-clarify/SKILL.md

@@ -23,6 +23,19 @@ any full SDD document or implementation prompt is generated.
 - Do not freeze a feature from product text or understand-anything output alone
   when code impact is relevant. Current source, Mapper/XML, database samples,
   API contracts, or real consumer entry points must confirm the design.
+- 对依赖存量系统行为、表关系或调用链的功能，冻结前必须生成
+  `source-code-audit.md` 的“源码事实冻结卡”：
+  `业务结论 | understand定位 | 数据模型 | 所有写入方 | 真实用户入口 |
+  当前调用方 | 遗留冲突 | DB是否必查 | 结论等级 | owner决策`。
+  understand-anything 只允许作为定位器；每项结论必须回到源码、Mapper/SQL、
+  当前调用方或只读 DB 证据。
+- 证据必须分类为 `current`、`legacy`、`unmounted`、`data-model-only`、
+  `owner-confirmed` 或 `blocked`。看到 `List`、`orderIds`、`batchInsert`、
+  一对多关系表，而真实 UI/小程序/H5 只提交单笔时，必须写“冲突审计”，禁止
+  直接推导为现行批量业务。
+- 向用户提问前，必须在“提问资格门禁”记录源码、Mapper/SQL、前端/小程序/H5
+  调用方、sibling repo 检索以及 DB 核查或跳过原因。能从仓库或只读数据查明的
+  事实不得转嫁给用户；只有 owner 意图决策才允许提问。
 - When the feature depends on existing code relationships, field ownership,
   table joins, data permissions, status transitions, or upstream/downstream
   calls, verify the relationship before freezing with current evidence:
@@ -81,6 +94,7 @@ Create or update these files in the active OpenSpec change directory:
 - `ui-contract.md`: page fields, controls, buttons, list columns, dropdowns, API/DTO/DB mapping.
 - `gap-analysis.md`: UI/document/source gaps and over-design risks.
 - `spec-freeze-review.md`: freeze card for the current feature.
+- `source-code-audit.md`: 源码事实冻结卡、证据分类、冲突审计和提问资格门禁。
 - Platform impact evidence in one of the above documents: discovery method,
   understand-anything index status when available, analyzed platform scope,
   impacted modules/interfaces/tables, regression risks, source/DB/API

package/assets/skills/superflow-design/SKILL.md

@@ -21,6 +21,12 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 
 ## Preconditions
 
+- When the change modifies a database schema, index, constraint, seed data, or
+  historical data, `release-sql.md` must already contain the complete executable
+  release SQL, an exact target `.sql` path, `copy_policy: verbatim`, and a valid
+  `sql_sha256`. Source-level HOW design must not defer SQL design to an
+  implementation prompt.
+
 - `proposal.md`, `api.md`, `design.md`, `tasks.md`, `tests.md`,
   `traceability-matrix.md`, `sdd-quality-gate.md`, and `test-report.md` exist.
 - `.sdd/state.yaml` exists and is in `phase: design`. If still `docs`, run:
@@ -38,15 +44,27 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 
 1. Read `.sdd/handoff/sdd-context.md` plus original `api.md`, `design.md`,
    `tasks.md`, and `tests.md`.
-2. If design discussion is still evolving, maintain
+2. If the change has any schema, index, constraint, seed-data, or historical
+   migration impact, verify `release-sql.md` before source-level HOW design:
+   - front matter sets `database_change: true`, an exact `target_sql_path`,
+     `copy_policy: verbatim`, and the normalized SQL payload `sql_sha256`;
+   - exactly one `sql` block contains the complete executable release script,
+     including prechecks, DDL/DML, and post-verification required by the
+     contract;
+   - `design.md`, `tasks.md`, and `sdd-quality-gate.md` reference the artifact
+     and prohibit implementation agents from editing its SQL;
+   - unresolved SQL types, defaults, indexes, migration rules, or target paths
+     return to `$superflow-docs`. They must not be deferred to
+     `$superflow-implement`.
+3. If design discussion is still evolving, maintain
    `.sdd/handoff/brainstorm-summary.md` with confirmed, candidate, pending, and
    rejected items. Do not create final technical design from memory only.
-3. Use Superpowers `brainstorming` or equivalent deep design reasoning to
+4. Use Superpowers `brainstorming` or equivalent deep design reasoning to
    decide source-level HOW.
-4. Write:
+5. Write:
    `docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md`
    using `../superflow-pipeline/references/superpower-technical-design-template.md`.
-5. Complete `复杂度减法评审` before expanding source-level HOW. For every new
+6. Complete `复杂度减法评审` before expanding source-level HOW. For every new
    table, field, API, Service/component, abstraction, cache, async/MQ/event
    flow, scheduled job, or compatibility layer, prove existing reuse options,
    necessity, and why the simplest direct implementation is insufficient.
@@ -55,7 +73,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    duplicate DTO/API layers, derivable persistence, premature caches, and
    async compensation without measured need. Record the retained and removed
    counts; unresolved simpler alternatives keep the design blocked.
-6. For cross-repository, service-to-service, SDK, MQ, scheduler, device,
+7. For cross-repository, service-to-service, SDK, MQ, scheduler, device,
    callback, third-party, mini-program, gateway, or adapter changes, include
    `Architecture Boundary And Call Direction`. Prove owner module, call
    direction, existing entry/exit points, proposed entry/exit points, evidence
@@ -63,7 +81,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    adapter/protocol translator/device gateway into a business-entry
    orchestrator, stop and return to `$superflow-docs` unless the OpenSpec/SDD
    contract explicitly grants that ownership with approval evidence.
-7. For third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
+8. For third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
    gateways, cloud services, or other external integrations, include
    `External Integration Configuration And Deployment Contract`. Inventory
    every endpoint, app/tenant/project ID, Topic, Tag, Consumer Group,
@@ -75,7 +93,7 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    auto-creation or pre-existing resources must not be treated as proof that
    production will provision them. Missing production provisioning evidence
    blocks design completion.
-8. For concurrent requests, batch issue/activation/renewal, duplicate callbacks,
+9. For concurrent requests, batch issue/activation/renewal, duplicate callbacks,
    duplicate consumption, or repeated external delivery, include
    `Concurrency And Idempotency Ownership`. Use a stable business idempotency
    key and an application-layer atomic claim in a short transaction; persist
@@ -85,17 +103,24 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
    optional fallback with proven natural uniqueness, historical cleanup,
    NULL/soft-delete semantics, and a conflict contract. Check-then-insert,
    process-local locks, and random IDs alone are blocked.
-9. For field/status/enum/sync changes, include `Field And Status Reverse
+   When the selected design is version-based optimistic locking, record the
+   exact database atomic compare-and-set statement and affected-row decision:
+   the update predicate contains both the stable row identity and expected
+   version; a zero-row result distinguishes missing data from version conflict.
+   The TDD plan references the `tests.md` concurrent stale-version case proving
+   one winner, one conflict, and one increment. Do not defer this decision to
+   the managed Executor prompt.
+10. For field/status/enum/sync changes, include `Field And Status Reverse
 Impact` and prove writers, readers, filters, derived sync paths, consumers,
    and tests. Direct setter-only design is blocked.
-10. For third-party, SDK, BEM/parking, payment/refund, financial display,
+11. For third-party, SDK, BEM/parking, payment/refund, financial display,
    source/origin, status sync, or external dictionary fields, include
    `External Enum Binding`. Prove local source fields/enums, external fields,
    external enum values, display/business/financial meaning, source evidence,
    owner confirmation, unresolved handling, and test evidence. A request
    succeeding or a field being non-null is not enough; unconfirmed values are
    blockers and must be returned to `$superflow-docs` or the user.
-11. For amount, fee, discount, deduction, refund, sharing, payment, invoice,
+12. For amount, fee, discount, deduction, refund, sharing, payment, invoice,
    balance, electricity fee, service fee, package settlement, proration,
    allocation, reconciliation, or financial display changes,
    include `Money Precision Boundary`. Prove calculation-state fields,
@@ -114,12 +139,12 @@ Impact` and prove writers, readers, filters, derived sync paths, consumers,
    level and policy source, deterministic residual strategy with stable
    tie-breaker, and positive/zero/negative evidence. For FX changes, freeze the
    directional rate metadata and one canonical conversion path.
-12. Record state:
+13. Record state:
    ```bash
    ../superflow-pipeline/scripts/superflow-state.sh set <change-dir> technical_design docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md
    ../superflow-pipeline/scripts/superflow-state.sh set <change-dir> design_doc design.md
    ```
-13. Update `design.md` with `Superpowers Technical Design Handoff`, update
+14. Update `design.md` with `Superpowers Technical Design Handoff`, update
    `sdd-quality-gate.md` with the technical design path and hash, then run
    `../superflow-pipeline/scripts/superflow-handoff.sh <change-dir> --refresh`.
    If the guard reports a stale or missing hash, record the printed hash in
@@ -127,7 +152,7 @@ Impact` and prove writers, readers, filters, derived sync paths, consumers,
    `--refresh` again. Do not set `design_doc` to the Superpowers document;
    `design_doc` is the OpenSpec/SDD contract design, while `technical_design`
    is the Superpowers HOW document.
-14. Run:
+15. Run:
 
 ```bash
 ../superflow-pipeline/scripts/superflow-yaml-validate.sh <change-dir>