sdd-flow-kit 1.3.15 → 1.3.18

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadRunSession = exports.resolveRunDir = exports.runDeliver = exports.runPropose = exports.runPhaseAdvance = exports.printGateResult = exports.runGate = exports.toRunOptions = exports.parseInvokeText = exports.runDoctor = exports.setupProject = exports.runFlow = exports.startFlowScaffold = void 0;
+exports.loadRunSession = exports.resolveRunDir = exports.tryAutoSyncSourcePrd = exports.syncSourcePrdFromDocs = exports.runSyncSourcePrd = exports.runDeliver = exports.runPropose = exports.runPhaseAdvance = exports.printGateResult = exports.runGate = exports.toRunOptions = exports.parseInvokeText = exports.runDoctor = exports.setupProject = exports.runFlow = exports.startFlowScaffold = void 0;
 var startFlow_1 = require("./steps/startFlow");
 Object.defineProperty(exports, "startFlowScaffold", { enumerable: true, get: function () { return startFlow_1.startFlowScaffold; } });
 var runFlow_1 = require("./steps/runFlow");
@@ -21,6 +21,11 @@ var runPropose_1 = require("./steps/runPropose");
 Object.defineProperty(exports, "runPropose", { enumerable: true, get: function () { return runPropose_1.runPropose; } });
 var runDeliver_1 = require("./steps/runDeliver");
 Object.defineProperty(exports, "runDeliver", { enumerable: true, get: function () { return runDeliver_1.runDeliver; } });
+var runSyncSourcePrd_1 = require("./steps/runSyncSourcePrd");
+Object.defineProperty(exports, "runSyncSourcePrd", { enumerable: true, get: function () { return runSyncSourcePrd_1.runSyncSourcePrd; } });
+var syncSourcePrd_1 = require("./core/syncSourcePrd");
+Object.defineProperty(exports, "syncSourcePrdFromDocs", { enumerable: true, get: function () { return syncSourcePrd_1.syncSourcePrdFromDocs; } });
+Object.defineProperty(exports, "tryAutoSyncSourcePrd", { enumerable: true, get: function () { return syncSourcePrd_1.tryAutoSyncSourcePrd; } });
 var resolveRun_1 = require("./steps/resolveRun");
 Object.defineProperty(exports, "resolveRunDir", { enumerable: true, get: function () { return resolveRun_1.resolveRunDir; } });
 Object.defineProperty(exports, "loadRunSession", { enumerable: true, get: function () { return resolveRun_1.loadRunSession; } });

package/dist/steps/runGate.js

@@ -7,11 +7,14 @@ exports.runGate = runGate;
 exports.printGateResult = printGateResult;
 const path_1 = __importDefault(require("path"));
 const prdArtifacts_1 = require("../core/prdArtifacts");
+const syncSourcePrd_1 = require("../core/syncSourcePrd");
 const prdCoverage_1 = require("../core/prdCoverage");
 const gitDiffGuard_1 = require("../core/gitDiffGuard");
 const acMatrix_1 = require("../core/acMatrix");
 const projectRoots_1 = require("../core/projectRoots");
 const openspecGate_1 = require("../core/openspecGate");
+const demoImplementationCoverage_1 = require("../core/demoImplementationCoverage");
+const techDocQuality_1 = require("../core/techDocQuality");
 const resolveRun_1 = require("./resolveRun");
 const fs_1 = require("../core/fs");
 function fail(checks, expect, runId) {
@@ -73,7 +76,7 @@ async function resolveImplRoots(projectRoot) {
  * 脚本门禁：失败时 process.exitCode=1，成功 exit 0。
  */
 async function runGate(options) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e, _f, _g;
     const loaded = await (0, resolveRun_1.loadRunSession)(options.projectRoot, options.runId);
     const checks = [];
     if (!loaded || !loaded.resolved) {
@@ -85,7 +88,27 @@ async function runGate(options) {
     const runId = resolved.runId;
     const implRoots = await resolveImplRoots(options.projectRoot);
     if (options.expect === "prd-fetched") {
-        const prd = await (0, prdArtifacts_1.isPrdFetched)(outputRoot);
+        let prd = await (0, prdArtifacts_1.isPrdFetched)(outputRoot);
+        if (!prd.ok) {
+            const product = (_b = (_a = session === null || session === void 0 ? void 0 : session.product) !== null && _a !== void 0 ? _a : runId.split("-")[1]) !== null && _b !== void 0 ? _b : "ADI";
+            const version = (_d = (_c = session === null || session === void 0 ? void 0 : session.version) !== null && _c !== void 0 ? _c : runId.split("-").slice(2).join("-")) !== null && _d !== void 0 ? _d : "";
+            const sync = await (0, syncSourcePrd_1.tryAutoSyncSourcePrd)({
+                projectRoot: options.projectRoot,
+                outputRoot,
+                product,
+                version,
+            });
+            if (sync.attempted) {
+                checks.push({
+                    name: "source-prd-sync",
+                    ok: sync.ok,
+                    detail: sync.detail,
+                });
+            }
+            if (sync.ok) {
+                prd = await (0, prdArtifacts_1.isPrdFetched)(outputRoot);
+            }
+        }
         checks.push({ name: "prd-fetched", ...prd });
         return pass(checks, options.expect, runId);
     }
@@ -105,6 +128,14 @@ async function runGate(options) {
         checks.push({ name: "questions-closed", ...closed });
         const docs = await (0, prdArtifacts_1.areAnalysisDocsReady)(outputRoot);
         checks.push({ name: "analysis-docs", ...docs });
+        const techRaw = await (0, fs_1.readFileIfExists)(path_1.default.join(outputRoot, "04-技术文档草稿.md"));
+        if (process.env.OPSX_SKIP_TECH_DOC_QUALITY !== "1") {
+            const techStruct = (0, techDocQuality_1.checkTechDocStructure)(techRaw !== null && techRaw !== void 0 ? techRaw : "");
+            checks.push({ name: "tech-doc-structure", ok: techStruct.ok, detail: techStruct.detail });
+        }
+        else {
+            checks.push({ name: "tech-doc-structure", ok: true, detail: "OPSX_SKIP_TECH_DOC_QUALITY=1 已跳过" });
+        }
         const acDefined = await (0, prdArtifacts_1.isAcceptanceChecklistDefined)(outputRoot);
         checks.push({ name: "acceptance-checklist-defined", ...acDefined });
         if (session && session.docModeOnly === false) {
@@ -173,6 +204,11 @@ async function runGate(options) {
                 detail: `openspec/changes/${changeName} 不存在，无法校验 AC 映射`,
             });
         }
+        const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
+        const demoArtifactChecks = await (0, demoImplementationCoverage_1.checkDemoReferenceArtifacts)(pkgRoot, changeName);
+        for (const c of demoArtifactChecks) {
+            checks.push({ name: c.name, ok: c.ok, detail: c.detail });
+        }
         return pass(checks, options.expect, runId);
     }
     if (options.expect === "ac-signed") {
@@ -183,7 +219,10 @@ async function runGate(options) {
     if (options.expect === "prd-coverage") {
         const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
         const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
-        const coverage = await (0, prdCoverage_1.checkPrdCoverage)(outputRoot, pkgRoot);
+        const changeName = await readActiveChange(options.projectRoot, session, options.change);
+        const coverage = await (0, prdCoverage_1.checkPrdCoverage)(outputRoot, pkgRoot, {
+            changeName: changeName !== null && changeName !== void 0 ? changeName : undefined,
+        });
         for (const c of coverage.checks) {
             checks.push({ name: c.name, ok: c.ok, detail: c.detail });
         }
@@ -211,6 +250,11 @@ async function runGate(options) {
                 found = true;
                 const st = (0, openspecGate_1.checkOpenspecApplyReady)(root, changeName);
                 checks.push({ name: "openspec-apply-ready", ok: st.applyReady, detail: st.detail });
+                const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
+                const demoArtifactChecks = await (0, demoImplementationCoverage_1.checkDemoReferenceArtifacts)(pkgRoot, changeName);
+                for (const c of demoArtifactChecks) {
+                    checks.push({ name: c.name, ok: c.ok, detail: c.detail });
+                }
                 break;
             }
         }
@@ -330,8 +374,8 @@ async function runGate(options) {
                     name: "validate-report",
                     ok,
                     detail: ok
-                        ? `验收通过 (pipeline=${(_a = j.pipelineShortExitCode) !== null && _a !== void 0 ? _a : "?"}, e2e=${(_b = j.e2eExitCode) !== null && _b !== void 0 ? _b : "?"})`
-                        : `验收结果: ${(_c = j.verdict) !== null && _c !== void 0 ? _c : "unknown"}`,
+                        ? `验收通过 (pipeline=${(_e = j.pipelineShortExitCode) !== null && _e !== void 0 ? _e : "?"}, e2e=${(_f = j.e2eExitCode) !== null && _f !== void 0 ? _f : "?"})`
+                        : `验收结果: ${(_g = j.verdict) !== null && _g !== void 0 ? _g : "unknown"}`,
                 });
             }
             catch {

package/dist/steps/runSyncSourcePrd.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSyncSourcePrd = runSyncSourcePrd;
+const syncSourcePrd_1 = require("../core/syncSourcePrd");
+const resolveRun_1 = require("./resolveRun");
+/**
+ * CLI：将 docs 版本目录 PRD 同步到 openspec run 的 source/。
+ */
+async function runSyncSourcePrd(options) {
+    var _a, _b, _c, _d;
+    const loaded = await (0, resolveRun_1.loadRunSession)(options.projectRoot, options.runId);
+    if (!(loaded === null || loaded === void 0 ? void 0 : loaded.resolved)) {
+        return { ok: false, detail: "未找到 openspec/PRD/<runId> 目录", runId: null };
+    }
+    const { resolved, session } = loaded;
+    const parts = resolved.runId.split("-");
+    const product = (_b = (_a = session === null || session === void 0 ? void 0 : session.product) !== null && _a !== void 0 ? _a : parts[1]) !== null && _b !== void 0 ? _b : "ADI";
+    const version = (_d = (_c = session === null || session === void 0 ? void 0 : session.version) !== null && _c !== void 0 ? _c : parts.slice(2).join("-")) !== null && _d !== void 0 ? _d : "";
+    if (options.dryRun) {
+        return {
+            ok: true,
+            detail: `dry-run: 将把 docs 版本 PRD 同步到 ${resolved.outputRoot}/source/`,
+            runId: resolved.runId,
+        };
+    }
+    const result = await (0, syncSourcePrd_1.syncSourcePrdFromDocs)({
+        projectRoot: options.projectRoot,
+        outputRoot: resolved.outputRoot,
+        product,
+        version,
+    });
+    return {
+        ok: result.ok,
+        detail: result.detail,
+        runId: resolved.runId,
+        imageCount: result.imageCount,
+    };
+}

package/dist/steps/runValidate.js

@@ -114,7 +114,9 @@ async function runValidate(options) {
     if (remediateLoop.escalated) {
         needUserConfirmFromRemediate = true;
     }
-    let prdCoverage = await (0, prdCoverage_1.checkPrdCoverage)(loaded.resolved.outputRoot, pkgRoot);
+    let prdCoverage = await (0, prdCoverage_1.checkPrdCoverage)(loaded.resolved.outputRoot, pkgRoot, {
+        changeName: options.change,
+    });
     if (!prdCoverage.ok) {
         const failed = prdCoverage.checks.filter((c) => !c.ok).map((c) => `${c.name}: ${c.detail}`);
         const payload = {
@@ -210,7 +212,7 @@ async function runValidate(options) {
     }
     return {
         ok: true,
-        detail: "验收通过（prd-coverage + lint+type+unit + 强制 e2e），可进入交付",
+        detail: "验收通过（prd-coverage 含 E2E 深度与 API 契约 + lint+type+unit + 强制 e2e），可进入交付",
         needUserConfirm: false,
     };
 }

package/dist/steps/setupProject.js

@@ -134,6 +134,7 @@ async function installAgentSkill(projectRoot, projectKind) {
         return;
     const template = await (0, templates_1.loadTemplateText)("artifacts/06-agent-skill.template.md");
     const layered = await (0, templates_1.loadTemplateText)("skills/layered-testing-strategy.md");
+    const demoRef = await (0, templates_1.loadTemplateText)("skills/demo-reference-mandatory-workflow.md");
     for (const target of targets) {
         const agentName = target.includes("/.cursor/")
             ? "cursor"
@@ -150,6 +151,8 @@ async function installAgentSkill(projectRoot, projectKind) {
         await (0, fs_1.writeTextFileEnsuredDir)(target, content);
         const layeredPath = path_1.default.join(path_1.default.dirname(target), "LAYERED-TESTING.md");
         await (0, fs_1.writeTextFileEnsuredDir)(layeredPath, layered);
+        const demoRefPath = path_1.default.join(path_1.default.dirname(target), "DEMO-REFERENCE-WORKFLOW.md");
+        await (0, fs_1.writeTextFileEnsuredDir)(demoRefPath, demoRef);
     }
 }
 async function installSddVersionTriggerRule(projectRoot, agent) {

package/dist/steps/startFlow.js

@@ -10,6 +10,7 @@ const utils_1 = require("../core/utils");
 const fs_1 = require("../core/fs");
 const templates_1 = require("../core/templates");
 const inferProject_1 = require("../core/inferProject");
+const syncSourcePrd_1 = require("../core/syncSourcePrd");
 const sessionState_1 = require("../core/sessionState");
 const projectRoots_1 = require("../core/projectRoots");
 const writeNext_1 = require("../core/writeNext");
@@ -30,12 +31,14 @@ async function startFlowScaffold(options) {
     // 1) Step1: doc-skill 指引（按产品解析脚本路径，支持 monorepo frontend）
     const kind = (0, inferProject_1.productToKind)(options.product);
     const docSkill = await (0, inferProject_1.resolveDocSkillDir)(options.projectRoot, kind);
+    const syncSourceDirRel = await (0, syncSourcePrd_1.resolveSyncSourceDirRel)(options.projectRoot, sourceDir, options.product);
     const step1Template = await (0, templates_1.loadTemplateText)("artifacts/01-adi-doc-skill-指引.template.md");
     const step1 = renderTemplate(step1Template, {
         PRODUCT: options.product,
         PRODUCT_PREFIX: inferProject_1.PRODUCT_PREFIX_BY_KIND[kind],
         DOC_SKILL_REL: docSkill.relFromRoot.replace(/\\/g, "/"),
         VERSION_EXAMPLE: options.version,
+        SYNC_SOURCE_DIR_REL: syncSourceDirRel,
     });
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "01-获取需求文档指引.md"), step1);
     // source 占位：让第 2 步提示词在任何工具里都能直接读
@@ -74,9 +77,11 @@ async function startFlowScaffold(options) {
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "02-改动点清单.md"), file02Template);
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "03-待确认问题清单.md"), file03Template);
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "05-验收清单.md"), file05Template);
-    // 4) Step4 技术文档入口（草稿）
+    // 4) Step4 技术文档入口（完整模板 + 填写指引）
     const techDocTemplate = await (0, templates_1.loadTemplateText)("artifacts/04-技术文档.template.md");
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "04-技术文档草稿.md"), techDocTemplate);
+    const techDocFillGuide = await (0, templates_1.loadTemplateText)("prompts/04-tech-doc-fill-prompt.md");
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "04-技术文档生成指引.md"), techDocFillGuide);
     // 5) Step5 openspec 提案入口（草稿）
     const openspecEntryTemplate = await (0, templates_1.loadTemplateText)("artifacts/06-openspec-提案草稿.template.md");
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "06-openspec-提案草稿.md"), openspecEntryTemplate);
@@ -118,7 +123,7 @@ async function startFlowScaffold(options) {
         "用户确认后产出（顺序重要）：",
         "- `03-待确认问题清单.md`（已闭合）",
         "- `05-验收清单.md`（从 `source/PRD.md` 逐条抽取 AC，标注「定义状态：已定义」）",
-        "- `04-技术文档草稿.md`（引用 AC-ID）",
+        "- `04-技术文档草稿.md`（**在脚手架模板原文件上逐节填写**，见 `04-技术文档生成指引.md`；禁止摘要替换）",
         "- `01-需求分析报告.md`（业务概述，非验收 SSOT）",
         "- `02-改动点清单.md`",
         "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "1.3.15",
+  "version": "1.3.18",
   "private": false,
   "description": "Cross-agent SDD automated development workflow kit (ADI/ADI-like).",
   "license": "MIT",
@@ -12,6 +12,7 @@
   "files": [
     "dist",
     "src/templates",
+    "scripts",
     "README.md"
   ],
   "bin": {

package/scripts/assert-active-openspec-change.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# 校验：改动 src/ 或 e2e/ 时必须绑定活跃 OpenSpec change（见 AGENTS.md）
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+WATCH_PATHS=('src/' 'e2e/')
+CHANGE_DIR_PREFIX="openspec/changes"
+ACTIVE_CHANGE_FILES=('.opsx-active-change' '.poquan-active-change')
+
+log() { printf '[opsx:gate] %s\n' "$*"; }
+die() { log "ERROR: $*"; exit 1; }
+
+path_is_watched() {
+  local path="$1"
+  local prefix
+  for prefix in "${WATCH_PATHS[@]}"; do
+    if [[ "$path" == "$prefix"* ]] || [[ "$path" == */"$prefix"* ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+collect_candidate_files() {
+  CANDIDATE_FILES=()
+  if [[ "${1:-}" == "--ci" ]]; then
+    local base="${GITHUB_BASE_REF:-main}"
+    base="${base#origin/}"
+    git fetch origin "$base" --depth=1 2>/dev/null || true
+    local merge_base
+    merge_base="$(git merge-base "origin/${base}" HEAD 2>/dev/null || git merge-base "${base}" HEAD 2>/dev/null || echo "")"
+    [[ -n "$merge_base" ]] || merge_base="HEAD~1"
+    while IFS= read -r line; do
+      [[ -n "$line" ]] && CANDIDATE_FILES+=("$line")
+    done < <(git diff --name-only "$merge_base"...HEAD 2>/dev/null || git diff --name-only HEAD~1 HEAD)
+  else
+    while IFS= read -r line; do
+      [[ -n "$line" ]] && CANDIDATE_FILES+=("$line")
+    done < <(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
+    if [[ ${#CANDIDATE_FILES[@]} -eq 0 ]]; then
+      while IFS= read -r line; do
+        [[ -n "$line" ]] && CANDIDATE_FILES+=("$line")
+      done < <(git diff --name-only --diff-filter=ACMR HEAD 2>/dev/null || true)
+    fi
+  fi
+}
+
+has_watched_changes() {
+  local file
+  for file in "${CANDIDATE_FILES[@]}"; do
+    if path_is_watched "$file"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+resolve_change_name() {
+  if [[ -n "${OPSX_ACTIVE_CHANGE:-}" ]]; then
+    echo "$OPSX_ACTIVE_CHANGE"
+    return 0
+  fi
+  if [[ -n "${POQUAN_ACTIVE_CHANGE:-}" ]]; then
+    echo "$POQUAN_ACTIVE_CHANGE"
+    return 0
+  fi
+  local file name
+  for file in "${ACTIVE_CHANGE_FILES[@]}"; do
+    if [[ -f "$file" ]]; then
+      name="$(tr -d '[:space:]' <"$file")"
+      [[ -n "$name" ]] && { echo "$name"; return 0; }
+    fi
+  done
+  local branch
+  branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")"
+  if [[ "$branch" =~ ^change/([^/]+) ]]; then
+    echo "${BASH_REMATCH[1]}"
+    return 0
+  fi
+  return 1
+}
+
+validate_change_dir() {
+  local name="$1"
+  local dir="${CHANGE_DIR_PREFIX}/${name}"
+  [[ -d "$dir" ]] || die "change 目录不存在: ${dir}（请先 Propose 或设置 OPSX_ACTIVE_CHANGE）"
+  [[ "$dir" != *"/archive/"* ]] || die "change 已归档，请新建 change: ${name}"
+  if [[ -f "${dir}/tasks.md" ]] && grep -q '^- \[ \]' "${dir}/tasks.md" 2>/dev/null; then
+    log "WARN: tasks.md 仍有未完成项；合码前建议全部勾选并跑 delivery-pipeline"
+  fi
+}
+
+main() {
+  if [[ "${OPSX_SKIP_OPSX:-}" == "1" ]] || [[ "${POQUAN_SKIP_OPSX:-}" == "1" ]]; then
+    log "已跳过（OPSX_SKIP_OPSX 或 POQUAN_SKIP_OPSX=1）"
+    exit 0
+  fi
+
+  collect_candidate_files "${1:-}"
+  if ! has_watched_changes; then
+    log "无 src/ 或 e2e/ 改动，跳过"
+    exit 0
+  fi
+
+  local change_name
+  change_name="$(resolve_change_name)" || die "改动 src/e2e 但未绑定 OpenSpec change。请先 Propose，或设置 OPSX_ACTIVE_CHANGE / .opsx-active-change / 分支 change/<name>。详见 AGENTS.md"
+
+  validate_change_dir "$change_name"
+  log "OK — 活跃 change: ${change_name}"
+}
+
+main "$@"

package/scripts/assess-api-field-contract.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * API 字段契约门禁：change 引用的 config/api/modules 须含 snake/camel normalize（防 SNAKE_CASE 漏映射）。
+ *
+ * 用法: node scripts/assess-api-field-contract.mjs --change <change-name>
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const NORMALIZE_MARKERS =
+  /snakeToCamel|camelToSnake|normalizeFinanceApiResult|normalize\w*Api|caseTransform|toCamelCase|toSnakeCase/i;
+const API_CLIENT_CALL_RE = /\b(?:apiClient|request|post|get)\s*[.(]/i;
+
+function parseArgs(argv) {
+  let change = "";
+  for (let i = 2; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--change" && argv[i + 1]) change = argv[++i];
+    else if (!a.startsWith("-") && !change) change = a;
+  }
+  return { change };
+}
+
+function readChangeBlob(changeDir) {
+  let blob = "";
+  for (const f of ["tasks.md", "proposal.md", "design.md"]) {
+    const fp = path.join(changeDir, f);
+    if (!fs.existsSync(fp)) continue;
+    blob += fs.readFileSync(fp, "utf8");
+  }
+  return blob;
+}
+
+function resolveModuleFile(mod) {
+  const candidates = [
+    path.join(ROOT, "src/config/api/modules", mod, "index.ts"),
+    path.join(ROOT, "frontend/src/config/api/modules", mod, "index.ts"),
+    path.join(ROOT, "src/config/api/modules", `${mod}.ts`),
+    path.join(ROOT, "frontend/src/config/api/modules", `${mod}.ts`),
+  ];
+  for (const fp of candidates) {
+    if (fs.existsSync(fp)) return fp;
+  }
+  return null;
+}
+
+function fail(messages) {
+  console.error("[assess-api-field-contract] FAIL");
+  for (const msg of messages) console.error(`  - ${msg}`);
+  console.error(
+    "  修复: 在 config/api/modules/<domain> 对请求体 camelToSnake、响应 data snakeToCamel；参考 finance/caseTransform.ts",
+  );
+  process.exit(1);
+}
+
+function main() {
+  const skip =
+    process.env.POQUAN_SKIP_API_FIELD_CONTRACT ||
+    process.env.OPSX_SKIP_API_FIELD_CONTRACT;
+  if (skip === "1") {
+    console.warn("[assess-api-field-contract] SKIP");
+    process.exit(0);
+  }
+
+  const { change } = parseArgs(process.argv);
+  if (!change) {
+    console.error("[assess-api-field-contract] 缺少 --change <name>");
+    process.exit(2);
+  }
+
+  const changeDir = path.join(ROOT, "openspec/changes", change);
+  if (!fs.existsSync(changeDir)) {
+    console.error(`[assess-api-field-contract] change 不存在: openspec/changes/${change}`);
+    process.exit(2);
+  }
+
+  const blob = readChangeBlob(changeDir);
+  const moduleRefs = new Set();
+  const modRe = /config\/api\/modules\/([\w/-]+)/g;
+  let m;
+  while ((m = modRe.exec(blob)) !== null) {
+    moduleRefs.add(m[1].replace(/\/index$/, ""));
+  }
+
+  if (moduleRefs.size === 0) {
+    console.log(`[assess-api-field-contract] PASS（无 API 模块引用） change=${change}`);
+    process.exit(0);
+  }
+
+  const errors = [];
+  const passed = [];
+  for (const mod of moduleRefs) {
+    const fp = resolveModuleFile(mod);
+    if (!fp) {
+      errors.push(`config/api/modules/${mod} 引用但文件不存在`);
+      continue;
+    }
+    const rel = path.relative(ROOT, fp).replace(/\\/g, "/");
+    const content = fs.readFileSync(fp, "utf8");
+    if (!API_CLIENT_CALL_RE.test(content)) {
+      passed.push(`${rel}（无 HTTP 调用）`);
+      continue;
+    }
+    if (!NORMALIZE_MARKERS.test(content)) {
+      errors.push(`${rel} 含 API 调用但未发现字段 normalize`);
+    } else {
+      passed.push(rel);
+    }
+  }
+
+  if (errors.length > 0) fail(errors);
+  console.log(
+    `[assess-api-field-contract] PASS change=${change} modules=${passed.join(", ")}`,
+  );
+}
+
+main();