@gordon.gan/specflow 1.8.4-beta → 1.8.5-beta

package/dist/cli/commands/document-run.js

@@ -719,11 +719,11 @@ function buildSynthRules(dirs) {
         `1. **统一大纲**：一次生成一份 outline，章节覆盖所有仓，不按仓分章（跨仓对比/汇总放进对应章节）。`,
         `2. **契约单一定义**：同一物理端点（method+path）只定义一个契约实体，用 \`side\`（console/worker/internal）与 \`consumers\`/\`producers\`（仓名）标注面与消费方/生产方；\`<repo>_<id>\` 前缀仅作为追溯别名保留，禁止为不同仓重复定义同一接口（validate 会以 \`duplicate_contract\` 拦截）。`,
         `3. **整体性组织（替代按仓分节）**：每章按主题写成一段整体叙述，仓归属用内联 \`[${repoList.split('、').join('] / [')}]\` 标注或表格「归属」列；**禁止**为无内容的仓写占位小节（如「某仓无 UI」）；若确需 \`### <repo>\` 小节，小节必须有实质内容（validate 会以 \`repo_section_stub\` 拦截空壳）。`,
-        `4. **全局视角**（若所选 profile 包含对应章节）：goal 写多仓总目标与边界；tech-selection 对比各仓技术方案；**接口与数据合并为「接口与数据设计」章**（接口总览 → 逐接口明细 → 数据模型与契约-表映射 → 存量回滚，DDL 就近引用附录），含契约-表映射表（每接口 ↔ 读写表/列）；closed-loop 跨仓统一闭环检查；implementability 跨仓统一可实施性评估。`,
+        `4. **全局视角**（若所选 profile 包含对应章节）：goal 写多仓总目标与边界；tech-selection 对比各仓技术方案；**接口与数据分工**——接口契约内联进「接口与数据设计」章（接口明细），**数据库表必须由「数据模型」章组件承载**（DDL/存量 G3/回滚 G4），契约-表映射写数据模型章，两章按「接口与数据设计 → 数据模型」顺序并列；closed-loop 跨仓统一闭环检查；implementability 跨仓统一可实施性评估。`,
         `5. **跨仓依赖/风险**：涉及仓间依赖（接口调用/数据共享/发布顺序）时显式标注「跨仓依赖」。`,
         `6. **按需加载规约（重要）**：写某个仓的小节时，**只读取该仓**的规约/IDE rules/guidance（该仓的 \`docs/\`、\`.cursor\`、\`.claude\`、\`.agents\` 等），**禁止一次性读取全部仓的规约**；只有写跨仓内容（接口对接/数据共享/发布顺序）时才读取**涉及仓**的规约。未读取的仓规约不得臆测，必要时标注「未读取该仓规约，待确认」。`,
         `7. **输入归属**：每段输入带「来源仓」标记，段 id 携带仓前缀（如 \`seg-repo1-proposal-01\`）；引用原文时按段 id 精确取回对应仓的片段，不整篇重读。`,
-        `8. **完整性骨架**：合成文档必须含术语与约定表、非目标汇总、风险与开放问题、决策记录（ADR，正文用 \`[D#]\` 引用，决策先定义后引用，validate 以 \`forward_decision_ref\` 提示前向引用）。`,
+        `8. **完整性骨架**：合成文档必须含术语与约定表、非目标汇总、风险与开放问题章节。**不设决策记录（ADR）章、不使用 \`[D#]\` 引用**——决策理由沉淀在技术选型（否决/备选列）与风险章。`,
         `9. **示例与字段表**：接口实体必须填 \`request_example\`/\`success_response_example\`/\`failure_response_example\`（真实 JSON body，无请求体方法显式标注「无请求体」）；请求字段与响应字段分列填写；错误表按 \`backend\`（gRPC→HTTP 映射）/ \`guard\`（前端守卫行为）/ \`internal\`（Worker 内部语义）分类。`,
         `10. **主流程必须含图**：主业务流程章输出整体流程图（含失败分支）+ 时序图 + 失败路径决策图，图必须有文字说明（validate 以 diagram 门禁拦截缺图）。`,
     ].join('\n');

package/dist/core/document/engine.js

@@ -17,7 +17,7 @@ import { renderDocument, renderHtml } from './render.js';
 import { runGates } from './gates.js';
 import { resolvePaths, reposPath, chapterPath } from './paths.js';
 import { parseEntitiesLenient } from './schemas.js';
-import { lintNarrative, checkRepoCoverage, checkRepoSectionStub, checkDuplicateContract, checkExamplePresence, checkForwardDecisionRef, checkUnverifiedNumber, checkDataContractMapping } from './lint.js';
+import { lintNarrative, checkRepoCoverage, checkRepoSectionStub, checkDuplicateContract, checkExamplePresence, checkForwardDecisionRef, checkUnverifiedNumber, checkDataContractMapping, checkBareIdentifiers, checkTextHeavyNoDiagram } from './lint.js';
 import { checkStructuredCoverage } from './coverage.js';
 import { resolveProjectConventionPaths } from '../project-conventions.js';
 import { extractContracts, EMPTY_CONTRACTS } from './extract.js';
@@ -708,6 +708,12 @@ export async function validateWork(options) {
         for (const d of checkUnverifiedNumber(chId, narrative)) {
             diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: chId });
         }
+        for (const d of checkBareIdentifiers(chId, narrative)) {
+            diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: chId });
+        }
+        for (const d of checkTextHeavyNoDiagram(chId, narrative)) {
+            diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: chId });
+        }
     }
     if (synthRepos.length >= 2) {
         for (const d of checkDataContractMapping(narrativeMap, allEntities)) {

package/dist/core/document/gates.js

@@ -2,7 +2,7 @@
  * Document Engine — gate orchestration (T10.4).
  * Runs lint → structured coverage → review check → budget → zod, collecting diagnostics.
  */
-import { lintNarrative, checkBudget, checkDiagramPresence, checkNumericPresence, checkGoldenSignals, checkRepoCoverage, checkRepoSectionStub, checkDuplicateContract, checkExamplePresence, checkForwardDecisionRef, checkUnverifiedNumber, checkDataContractMapping, } from './lint.js';
+import { lintNarrative, checkBudget, checkDiagramPresence, checkNumericPresence, checkGoldenSignals, checkRepoCoverage, checkRepoSectionStub, checkDuplicateContract, checkExamplePresence, checkForwardDecisionRef, checkUnverifiedNumber, checkDataContractMapping, checkBareIdentifiers, checkTextHeavyNoDiagram, } from './lint.js';
 import { checkStructuredCoverage } from './coverage.js';
 import { checkReviewResult } from './review.js';
 export async function runGates(input) {
@@ -74,6 +74,12 @@ export async function runGates(input) {
         for (const d of checkUnverifiedNumber(chId, narrative)) {
             diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: chId });
         }
+        for (const d of checkBareIdentifiers(chId, narrative)) {
+            diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: chId });
+        }
+        for (const d of checkTextHeavyNoDiagram(chId, narrative)) {
+            diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: chId });
+        }
     }
     if (input.repos && input.repos.length >= 2) {
         for (const d of checkDataContractMapping(input.chapterNarratives, input.entities)) {

package/dist/core/document/lint.d.ts

@@ -59,7 +59,17 @@ export declare function checkForwardDecisionRef(narratives: ReadonlyMap<string,
 }>): RepoSectionDiagnostic[];
 /** 性能章目标数字必须标注来源/待实测（P10）。 */
 export declare function checkUnverifiedNumber(chapterId: string, narrative: string): RepoSectionDiagnostic[];
-/** 接口与数据整合（P11）：synth 模式下有表实体时，接口章必须含契约-表映射表。 */
+/** 接口与数据对齐（P11）：有表实体时，数据模型章（或接口章）必须含契约-表映射表。 */
 export declare function checkDataContractMapping(narratives: ReadonlyMap<string, string>, entities: {
     tables?: unknown[];
 }): RepoSectionDiagnostic[];
+/**
+ * 正文中文化（warning）：叙述行（非代码块/非表格/非标题）出现裸代码标识符时提示用中文业务术语替代。
+ * 术语与约定章（glossary）放行——那里本就登记标识符。
+ */
+export declare function checkBareIdentifiers(chapterId: string, narrative: string): RepoSectionDiagnostic[];
+/**
+ * 图文结合（warning）：叙述正文（非表格/非标题/非代码块）超过阈值行数但整章无 Mermaid 图 →
+ * 提示补充图（流程/状态/结构类内容必须配图 + 文字说明）。术语表放行。
+ */
+export declare function checkTextHeavyNoDiagram(chapterId: string, narrative: string, minProseLines?: number): RepoSectionDiagnostic[];

package/dist/core/document/lint.js

@@ -247,16 +247,92 @@ export function checkUnverifiedNumber(chapterId, narrative) {
     }
     return [];
 }
-/** 接口与数据整合（P11）：synth 模式下有表实体时，接口章必须含契约-表映射表。 */
+/** 接口与数据对齐（P11）：有表实体时，数据模型章（或接口章）必须含契约-表映射表。 */
 export function checkDataContractMapping(narratives, entities) {
     if ((entities.tables?.length ?? 0) === 0)
         return [];
-    const narrative = narratives.get('api-design') ?? '';
+    const narrative = narratives.get('data-model') ?? narratives.get('api-design') ?? '';
     if (!/契约-表映射|映射表|接口.*表.*映射|表.*接口.*映射/.test(narrative)) {
         return [{
                 code: 'data_contract_mapping_missing',
                 severity: 'warning',
-                message: '接口与数据应整合呈现：api-design 章缺少「契约-表映射」（每接口 ↔ 读写表/列），接口约定与数据库仍游离',
+                message: '接口与数据应通过契约-表映射对齐：数据模型章缺少「契约-表映射」（每接口 ↔ 读写表/列），接口约定与数据库仍游离',
+            }];
+    }
+    return [];
+}
+// ============= 正文中文化 lint（可读性整改：代码标识符只允许出现在术语表/字段表/示例） =============
+/** 正文叙述中禁止裸用代码标识符的清单（术语表/字段表/JSON 示例/代码块除外）。 */
+const BARE_IDENTIFIERS = [
+    'runtime_payload', 'execution_jobs', 'scenario_cases', 'scenario_steps', 'scenario_step_results',
+    'param_overrides', 'lease_epoch', 'ref_type', 'step_count', 'job_type', 'execution_mode',
+    'step_uid', 'step_order', 'schema_version', 'request_id', 'EnsureCaseResult', 'CompileScenario',
+    'ExecuteCase', 'StartDebugExecution', 'SubmitStepResult', 'ListScenarioStepResults', 'ReplaceScenarioSteps',
+    'pollJobUntilTerminal', 'case_result_uid', 'execution_job_uid',
+];
+/**
+ * 正文中文化（warning）：叙述行（非代码块/非表格/非标题）出现裸代码标识符时提示用中文业务术语替代。
+ * 术语与约定章（glossary）放行——那里本就登记标识符。
+ */
+export function checkBareIdentifiers(chapterId, narrative) {
+    if (/term|glossary|约定|术语/i.test(chapterId))
+        return [];
+    const diags = [];
+    let inFence = false;
+    for (const raw of narrative.split('\n')) {
+        const line = raw.trimStart();
+        if (line.startsWith('```')) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        if (line.startsWith('|'))
+            continue; // 表格行（字段表）保留原名
+        if (/^#{1,6}\s/.test(line))
+            continue; // 标题
+        for (const id of BARE_IDENTIFIERS) {
+            if (new RegExp(`\\b${id}\\b`).test(line)) {
+                diags.push({
+                    code: 'bare_identifier',
+                    severity: 'warning',
+                    chapter: chapterId,
+                    message: `Chapter "${chapterId}" 正文出现裸代码标识符「${id}」——正文应用中文业务术语（如「运行时信封」替代 runtime_payload）；标识符只允许在术语表、字段表、JSON/HTTP 示例、代码块中出现`,
+                });
+                break;
+            }
+        }
+    }
+    return diags;
+}
+// ============= 图文结合 lint（可读性整改：叙述多的章节必须有图） =============
+/**
+ * 图文结合（warning）：叙述正文（非表格/非标题/非代码块）超过阈值行数但整章无 Mermaid 图 →
+ * 提示补充图（流程/状态/结构类内容必须配图 + 文字说明）。术语表放行。
+ */
+export function checkTextHeavyNoDiagram(chapterId, narrative, minProseLines = 30) {
+    if (/term|glossary|约定|术语/i.test(chapterId))
+        return [];
+    let prose = 0;
+    let inFence = false;
+    for (const raw of narrative.split('\n')) {
+        const line = raw.trimStart();
+        if (line.startsWith('```')) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        if (line.startsWith('|') || /^#{1,6}\s/.test(line) || line.trim() === '')
+            continue;
+        prose += 1;
+    }
+    if (prose >= minProseLines && !/```mermaid/.test(narrative)) {
+        return [{
+                code: 'text_heavy_no_diagram',
+                severity: 'warning',
+                chapter: chapterId,
+                message: `Chapter "${chapterId}" 叙述较多（${prose} 行）但无图——建议图文结合：流程/状态流转/结构/决策分支用 Mermaid 图（flowchart/sequenceDiagram/stateDiagram-v2）+ 文字说明，叙述分条输出`,
             }];
     }
     return [];

package/dist/core/document/render.d.ts

@@ -16,14 +16,10 @@ export declare function escapeFenceContent(s: string): string;
 export declare function escapeInline(s: string): string;
 export declare function renderInterface(i: InterfaceEntity): string;
 export declare function renderTable(t: TableEntity): string;
-export declare function renderDecisions(decisions: Array<{
-    id: string;
-    text: string;
-    background?: string;
-    alternative?: string;
-}>): string;
-/** 契约实体按「面」分组渲染（Console 面 / 内部与 Worker 面），替代平铺。 */
 export declare function renderEntities(entities: Entities): string;
+/** 契约实体按「面」分组渲染（Console 面 / 内部与 Worker 面），供接口与数据设计章就地展开。 */
+export declare function renderInterfaces(interfaces: InterfaceEntity[]): string;
+export declare function renderTables(tables: TableEntity[]): string;
 export interface RenderDocumentInput {
     outline: Outline;
     entities: Entities;

package/dist/core/document/render.js

@@ -83,22 +83,14 @@ export function renderTable(t) {
         ...(t.rollback ? ['**回滚兼容**', '', t.rollback, ''] : []),
     ].join('\n');
 }
-export function renderDecisions(decisions) {
-    if (decisions.length === 0)
-        return '';
-    return [
-        '## 决策记录（ADR）',
-        '',
-        '| 决策 | 背景 | 结论 | 备选（已否决） |',
-        '|------|------|------|------|',
-        ...decisions.map((d) => `| ${escapeTableCell(d.id)} | ${escapeTableCell(d.background ?? '')} | ${escapeTableCell(d.text)} | ${escapeTableCell(d.alternative ?? '')} |`),
-    ].join('\n');
-}
-/** 契约实体按「面」分组渲染（Console 面 / 内部与 Worker 面），替代平铺。 */
 export function renderEntities(entities) {
+    return [renderInterfaces(entities.interfaces), renderTables(entities.tables)].filter(Boolean).join('\n\n');
+}
+/** 契约实体按「面」分组渲染（Console 面 / 内部与 Worker 面），供接口与数据设计章就地展开。 */
+export function renderInterfaces(interfaces) {
     const parts = [];
     const groups = new Map();
-    for (const i of entities.interfaces) {
+    for (const i of interfaces) {
         const key = i.side ?? 'other';
         if (!groups.has(key))
             groups.set(key, []);
@@ -116,10 +108,11 @@ export function renderEntities(entities) {
             continue;
         parts.push(`### ${sideTitle[key]}`, '', list.map(renderInterface).join('\n\n'));
     }
-    for (const t of entities.tables)
-        parts.push(renderTable(t));
     return parts.join('\n\n');
 }
+export function renderTables(tables) {
+    return tables.map(renderTable).join('\n\n');
+}
 /** Strip engine repair notes (`<!-- review-fix ... -->`) from the FINAL render. The audit trail
  *  stays in `chapters/<id>.md` and `review-result.json`; the deliverable document must not show
  *  internal fix notes. */
@@ -216,44 +209,36 @@ export function renderDocument(input) {
     if (meta.length > 0) {
         body.push('| 项 | 值 |', '|------|------|', ...meta, '');
     }
-    // 目录（P7）：按大纲章节序确定性生成；接口与数据合并时 data-model 不单列。
-    const apiDesignIdx = outline.chapters.findIndex((c) => c.id === 'api-design');
-    const dataModelIdx = outline.chapters.findIndex((c) => c.id === 'data-model');
-    const mergeDataModel = apiDesignIdx >= 0 && dataModelIdx > apiDesignIdx;
+    // 目录（P7）：按大纲章节序确定性生成。
     body.push('## 目录', '');
-    outline.chapters.forEach((ch, idx) => {
-        if (mergeDataModel && ch.id === 'data-model')
-            return;
-        body.push(`${idx + 1}. ${escapeInline(ch.title)}`);
+    let tocNo = 0;
+    outline.chapters.forEach((ch) => {
+        tocNo += 1;
+        body.push(`${tocNo}. ${escapeInline(ch.title)}`);
     });
     body.push('');
-    for (const [idx, ch] of outline.chapters.entries()) {
-        if (mergeDataModel && ch.id === 'data-model')
-            continue; // 已并入「接口与数据设计」章
+    // 契约明细按章节组件落位：
+    //  - 接口实体（请求/响应字段表、示例、错误表）内联进「接口与数据设计」章（接口明细）；
+    //  - 数据库表（DDL/存量填充/回滚）必须由「数据模型」章组件承载（数据表），不并入接口章。
+    const interfacesMd = renderInterfaces(entities.interfaces);
+    const tablesMd = renderTables(entities.tables);
+    const hasApiDesign = outline.chapters.some((c) => c.id === 'api-design');
+    const hasDataModel = outline.chapters.some((c) => c.id === 'data-model');
+    for (const ch of outline.chapters) {
         body.push(`## ${escapeInline(ch.title)}`, '');
         // 依次净化：剥内嵌契约 JSON 块（机器中间格式）→ 剥与章节标题重复的首行 H1 → 剥引擎修复注记，
         // 再把叙述内标题降级一级（章节头已占 H2，叙述小节 H2→H3），保证目录层级正确。
         const narrative = demoteHeadings(stripLeadingTitle(stripEntityJsonBlocks(stripReviewNotes(narratives.get(ch.id) ?? '')), ch.title));
         if (narrative.trim())
             body.push(narrative.trim(), '');
-        // 接口与数据整合（P11）：data-model 紧随 api-design 时并入其下为小节，不再单独成章。
-        if (mergeDataModel && ch.id === 'api-design') {
-            const dm = outline.chapters[dataModelIdx];
-            const dmNarrative = demoteHeadings(stripLeadingTitle(stripEntityJsonBlocks(stripReviewNotes(narratives.get(dm.id) ?? '')), dm.title));
-            if (dmNarrative.trim())
-                body.push('### 数据模型', '', dmNarrative.trim(), '');
-        }
-    }
-    // 决策记录（ADR）独立成节（P6）：不再埋在契约实体末尾。
-    const decisionsMd = renderDecisions(entities.decisions);
-    if (decisionsMd.trim()) {
-        body.push('---', '', decisionsMd, '');
+        if (ch.id === 'api-design' && interfacesMd.trim())
+            body.push('### 接口明细', '', interfacesMd, '');
+        if (ch.id === 'data-model' && tablesMd.trim())
+            body.push('### 数据表', '', tablesMd, '');
     }
-    // Contract entities: append to the chapters that reference them (simplified: append in a
-    // final "附录 A" section, since entities are cross-chapter).
-    const contractMd = renderEntities(entities);
-    if (contractMd.trim()) {
-        body.push('---', '', '## 附录 A：契约实体明细', '', contractMd, '');
+    // 无 api-design / data-model 章时的兜底（如 bugfix 等 profile 的契约实体仍须呈现）。
+    if (!hasApiDesign && !hasDataModel && (interfacesMd.trim() || tablesMd.trim())) {
+        body.push('---', '', '## 附录 A：契约实体明细', '', [interfacesMd, tablesMd].filter(Boolean).join('\n\n'), '');
     }
     // 产物溯源附录（P8）：默认不渲染（synth 下每章来源雷同，属噪声）；--signoff/调试时开启。
     if (includeProvenance) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.8.4-beta",
+  "version": "1.8.5-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [

package/prompts/document/map/api-design.md

@@ -1,20 +1,19 @@
-# 章节填充：api-design（接口与数据设计 · 契约 + 数据模型 + 前端对接）
+# 章节填充：api-design（接口与数据设计 · 接口契约 + 前端对接）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
 - kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
-- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.；**正文中文化**；**叙述分条 + 图文结合**）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
 - **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
 
-## 本章定位：接口与数据整合呈现（P11）
+## 本章定位：接口契约承载（P11/P13）
 
-本章同时承载**接口契约**与**数据模型**，二者不得游离：
+本章承载**接口契约**（渲染为「接口明细」），与「数据模型」章分工：
 
-1. 固定顺序：接口总览（含面/消费方/生产方）→ 请求字段表 → 请求示例 → 响应字段表 → 响应示例 → 失败示例 → 错误表（按类别）→ **数据流总览与契约-表映射**（每接口 ↔ 读写表/列）→ 表结构与 DDL → 存量填充（G3）→ 回滚兼容（G4）。
-2. **契约-表映射表（强制）**：每个接口一行，列 = 契约 / 读写 / 表·列 / 关键说明。例：`step-results → 写 scenario_step_results（幂等键 execution_job_uid+step_order）`。契约字段与表列必须对得上，禁止接口讲接口、表讲表。
-3. DDL 就近：表结构在本章给出说明，完整 CREATE TABLE 可放附录并交叉引用（零 DDL 迭代必须显式声明「零迁移」，并展示现网 DDL 参考，禁止假装不涉及数据库）。
-4. **跨仓合成（≥2 仓）**：接口**单一定义**——同一 method+path 只定义一个实体，用 `side`（console/worker/internal）与 `consumers`/`producers`（仓名）标注；`<repo>_<id>` 仅作追溯别名，禁止按仓重复。仓归属用 `[repo]` 内联标注或表格「归属」列。
+1. 固定顺序：接口总览（含面/消费方/生产方）→ 请求字段表 → 请求示例 → 响应字段表 → 响应示例 → 失败示例 → 错误表（按类别）。
+2. **数据库表不由本章承载**：表结构与 DDL、存量填充（G3）、回滚兼容（G4）、**契约-表映射**全部由「数据模型」章给出；本章在涉及表实体时给一句指引（如"契约-表映射见数据模型章"），**不**在本章写建表语句。
+3. **跨仓合成（≥2 仓）**：接口**单一定义**——同一 method+path 只定义一个实体，用 `side`（console/worker/internal）与 `consumers`/`producers`（仓名）标注；`<repo>_<id>` 仅作追溯别名，禁止按仓重复。仓归属用 `[repo]` 内联标注或表格「归属」列。
 
 ## 接口章节硬规则（借鉴 approval api-guidance + F1/F2 前端对接合并）
 
@@ -24,19 +23,12 @@
 4. **G2 失败示例（强制）**：清单中每个接口（含「不变」）除成功示例外，必须 ≥1 组失败示例（参数校验失败/租约过期/未认证），附完整 HTTP 或等价示例。只有错误码表不合格。
 5. **固定顺序**：元信息（面/消费方/生产方）→ **请求字段表** → **请求示例（真实 JSON body，禁止空壳；无请求体方法显式标注「无请求体」）** → **响应字段表** → **成功响应示例（真实 JSON）** → **失败示例（G2，可附失败响应 body）** → **错误表（backend/guard/internal 分类）**。
 6. **接口清单稳定编号**：`In` 稳定，供页面引用与跨章交叉引用。
-7. **契约-表映射**：见上文「本章定位」第 2 条，接口清单后紧跟映射表。
-
-## 数据模型硬规则（G3/G4）
-
-8. 每张表必须有完整 CREATE TABLE（含 ENGINE/CHARSET）与字段说明。
-9. JSON/新列必须有存量填充策略（G3）；必须有回滚数据兼容说明（G4）。
-10. 零 DDL 迭代仍须展示现网 DDL（禁止假装不涉及数据库），并显式声明「零迁移」。
 
 ## 前端对接维度（O5–O7，F1 §2.2 合并「契约+对接」）
 
-11. **前端请求封装**：统一请求层（拦截器：token 注入/统一错误处理/超时/重试策略/缓存），DTO → VO 映射层。禁止「每个页面自己 fetch + 自己处理错误」。
-12. **前端错误处理统一**：后端错误码 → 前端统一错误态映射（Loading-Empty-Error），禁止前后端各写一套错误码约定。
-13. **接口 Mock 与契约先行**：前端并行开发用 Mock，Mock 的数据结构必须与冻结契约一致（R5）；联调时切换真实接口不改变前端代码结构。
-14. **优先级**：项目约定 + 现网 OpenAPI/proto > SpecFlow 骨架 > LLM。
+7. **前端请求封装**：统一请求层（拦截器：token 注入/统一错误处理/超时/重试策略/缓存），DTO → VO 映射层。禁止「每个页面自己 fetch + 自己处理错误」。
+8. **前端错误处理统一**：后端错误码 → 前端统一错误态映射（Loading-Empty-Error），禁止前后端各写一套错误码约定。
+9. **接口 Mock 与契约先行**：前端并行开发用 Mock，Mock 的数据结构必须与冻结契约一致（R5）；联调时切换真实接口不改变前端代码结构。
+10. **优先级**：项目约定 + 现网 OpenAPI/proto > SpecFlow 骨架 > LLM。
 
 > 前后端契约一致性是本章最高门禁：字段名、错误码、DTO 结构前后端必须对齐，禁止各写各的。

package/prompts/document/map/architecture.md

@@ -18,7 +18,7 @@
 
 3. **C4 分层（AR4）**：按需给 Context（系统上下文，外部系统/用户）/ Container（可部署单元：Web/API/DB/消息）/ Component（模块组件）分层；每层给依赖方向。与 core-flow 的组件层交互时序对接（R5，交叉引用冻结 id）。
 
-4. **ADR 决策记录（AR5）**：把 tech-selection 的关键决策沉淀为 ADR——背景 / 决策 / 后果 / 备选（为什么不用备选）。引用 tech-selection 的 decisions 实体 id，不另起名。
+4. **决策理由就地沉淀（AR5，可读性整改）**：关键取舍（如"为什么不用备选方案"）写在技术选型章的否决/备选列与风险章的缓解列，**不设独立的 ADR/决策记录章节**。
 
 5. **架构一致性自检（AR3）**：对照目标（可扩展/可维护/性能），检查架构是否满足，给出自检结论。
 

package/prompts/document/map/core-logic.md

@@ -1,9 +1,16 @@
-# 章节填充：core-logic
+# 章节填充：core-logic（关键实现规则）
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
-- kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
-- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.；**正文中文化**）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
 - **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
 - 涉及项目规约/DB/API/前端约束时，遵循「项目约定 > SpecFlow guidance > LLM」优先级
+
+## 关键实现规则章节硬规则（可读性整改：承接主流程、只写图中未覆盖的规则）
+
+1. **开头必须承接上下文（禁孤立开头）**：第一段用一两句话说明"本章规则承接主业务流程（核心链路/失败分支），回答'每一步在实现上怎么落地'"。禁止直接从"校验 xxx"开始。
+2. **只写主流程图/时序图未覆盖的细节**：链路、失败分支、幂等并发已在主业务流程章画图并说明的，本章**不得整段重复**——重复内容改用交叉引用（如"失败分叉见主业务流程·失败路径决策图"）。
+3. **按环节分节**：编译规则（排序/展开/校验/信封冻结）→ 执行规则（信封校验/共享变量/失败策略细节）→ 上报规则（写入顺序/幂等键/abort 语义）。每节 1. 2. 3. 编号，一条一句。
+4. **正文中文化**：正文用中文业务术语（如「运行时信封」「步骤序号」「租约世代」），代码标识符只允许在术语表/字段表/示例中（见 artifact-language.md）。
+5. **位置**：本章属于主业务流程的"下一环节"——渲染时紧随主业务流程之后；若你发现本章内容 90% 以上已在别章讲过，则应大幅精简并只保留真正新增的规则。

package/prompts/document/map/data-model.md

@@ -1,6 +1,6 @@
-# 章节填充：data-model（数据结构/数据模型变更）
+# 章节填充：data-model（数据结构/数据模型变更 —— 数据库表的唯一承载章节组件）
 
-> **整合说明（P11）**：跨仓合成（≥2 仓）时，本章内容并入「接口与数据设计」章（api-design）——接口、数据模型与契约-表映射同章呈现，不单独成章。单仓文档可继续独立使用本章。无论哪种形态，**契约-表映射**（每接口 ↔ 读写表/列）都必须给出，禁止接口讲接口、表讲表。
+> **分工说明（P11/P13）**：涉及数据库的表时本组件必选。表结构与 DDL、存量填充（G3）、回滚兼容（G4）、**契约-表映射**全部由本章承载；接口契约本体在「接口与数据设计」章（接口明细）。无论是否跨仓合成，**契约-表映射**（每接口 ↔ 读写表/列）都必须在本章给出，禁止接口讲接口、表讲表。
 
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
 - kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）

package/prompts/document/map/requirement.md

@@ -3,6 +3,11 @@
 你是方案文档撰写员。按大纲要点"填空题"式展开本章，逐要点填充，不自由发挥。
 - kind=entity|mixed 的要点 → 产出结构化契约实体（JSON 块 ```json {"interfaces": [...], "tables": [...], "decisions": [...]} ```）
 - kind=narrative|mixed 的要点 → 产出叙述 Markdown
-- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.）
+- 遵循 prompts/shared/artifact-language.md 的中文叙述规范（简要；怎么做用 1. 2. 3.；**正文中文化**）
 - 禁止 stub（TODO/待补充/此处省略）；禁止含糊词
 - **事实从工程数据源提取，意图向用户询问，推理由你完成**（见 `prompts/document/shared/grounding.md`）：本章涉及的接口字段/表列/组件名/依赖版本必须来自工程，缺失的关键信息列入缺口清单一次性询问用户，禁止编造
+
+## 需求章节硬规则
+
+1. **不写 Given-When-Then 验收小节**：验收标准已从方案文档移除（可读性整改）；验收断言由「测试策略」章承接。本章只写功能需求描述、目标与边界（MVP 范围、跨仓依赖、约束）。
+2. **目标可验证**：每个目标一句"做成什么状态"，但验证落在测试策略章，不在本章列验收表。

package/prompts/document/map/test-strategy.md

@@ -13,7 +13,7 @@
 
 2. **测试环境与数据（T2）**：测试环境地址、测试数据准备（fixture/seed/工厂）、Mock 说明（接口 Mock/第三方 Mock）。
 
-3. **与验收标准映射（T3）**：每条验收标准（GWT）对应到至少一个测试层级，形成可追踪矩阵。
+3. **验收断言承接（T3，可读性整改）**：验收标准不再单独成章——把 Given-When-Then 断言**折叠进本表**，每行测试加「验收依据」列（如「运行 → 恰一个作业（job_count=1）」「非法引用类型 → 报错且不入队」），确保需求章的目标可验证且可追溯。
 
 4. **前端测试金字塔（T4）**：单元 60% / 组件 30% / E2E 10% 的投入比例；组件测试方式写明——Snapshot + 交互（render + fireEvent/userEvent 断言行为），关键组件/页面覆盖率目标。
 

package/prompts/document/outline/general.md

@@ -44,8 +44,11 @@
 5. **source_segments**：要点尽量标注来源段 id（来自全局摘要的段 id）。
 6. **每要点引用 ≤3 个实体**。
 7. **要点数量**：每章 2-5 个要点，覆盖该章必须覆盖的维度。
-8. **接口与数据整合（P11）**：当 `api-design` 与 `data-model` 同时被选中时，合并为单一「接口与数据设计」章（id 用 `api-design`），数据模型作为该章小节（数据流总览 → 契约-表映射 → 表结构/DDL → 存量填充 G3 → 回滚 G4），不再单列 `data-model` 章；DDL 可放附录并交叉引用。
-9. **完整性骨架（P7）**：涉及 ≥2 仓的合成文档必须含 `术语与约定`、`非目标汇总`、`风险与开放问题`、`决策记录（ADR）` 章节位（决策在正文用 `[D#]` 引用，先定义后引用）。
+8. **接口与数据分工（P11/P13）**：`api-design` 与 `data-model` 同时被选中时按「接口与数据设计 → 数据模型」顺序并列两章，**不合并**：
+   - 接口契约（请求/响应字段表、示例、错误表）内联进「接口与数据设计」章（渲染为「接口明细」）；
+   - **数据库表必须由「数据模型」章节组件承载**（表结构与 DDL、字段说明、存量填充 G3、回滚 G4、契约-表映射）——涉及持久化时必须选入 `data-model` 章，禁止把表塞进接口章或忽略；
+   - 契约-表映射（每接口 ↔ 读写表/列）写在「数据模型」章，接口约定与数据库通过映射表对齐。
+9. **完整性骨架（P7）**：涉及 ≥2 仓的合成文档必须含 `术语与约定`、`非目标汇总`、`风险与开放问题` 章节位。**不设决策记录（ADR）章节**——决策理由沉淀在技术选型（否决/备选列）与风险章即可，正文不得使用 `[D#]` 引用。
 10. **实体注册表增强**：接口实体注册时记录 `side`（console/worker/internal）、`consumers`、`producers`（仓名）；同一 method+path 只注册一个实体，`<repo>_<id>` 前缀仅作追溯别名（防 `duplicate_contract`）。
 11. **主流程含图（P12）**：`core-flow` 章必须输出整体流程图（含失败分支）+ 时序图 + 失败路径决策图，图必须有文字说明。
 12. **文档头与目录**：最终文档由引擎确定性渲染元信息头（标题/参与仓/生成时间）与目录；大纲只决定章节序与要点，不写文档头。

package/prompts/document/shared/grounding.md

@@ -85,7 +85,7 @@ OpenAPI（`openapi.yaml`/`swagger.json` 等）、proto3（`*.proto`）、SQL DDL
 
 ## 七、整体性文档写作约定（P9/P11，所有章节通用）
 
-1. **首次定义、后续引用**：术语、决策（`[D#]`）、关键事实（幂等键、零 DDL、禁直连等）只在首次出现处定义，后续一律引用，禁止跨章重复整段（防 P9 重复）。
+1. **首次定义、后续引用**：术语、关键事实（幂等键、零 DDL、禁直连等）只在首次出现处定义，后续一律引用，禁止跨章重复整段（防 P9 重复）。**不设决策记录（ADR）章、不使用 `[D#]` 引用**——决策理由沉淀在技术选型（否决/备选列）与风险章。
 2. **接口与数据同源**：接口字段与表列来自同一工程数据源；写契约-表映射时，字段↔列必须一一对齐，禁止接口讲接口、表讲表（P11）。
 3. **主流程必有图**：涉及多步流程的章节（core-flow 等）必须给出 mermaid 图（整体流程图/时序图），图必须有文字说明（P12）。
 4. **某仓无内容则不出现**：跨仓写作时，某仓在某维度无内容（如后端无 UI 组件）就**不写该仓的占位小节**，只写真实存在的内容（防"无 X"占位）。

package/prompts/shared/artifact-language.md

@@ -45,5 +45,14 @@ When `artifacts.language` is `zh-CN`:
 1. **简要** — 一句一事;禁止套话与大段散文。
 2. **有条理** — 「怎么做 / 怎么走 / 怎么处理」写成 **1. 2. 3.**,每步一句。
 3. **不改结构** — 表格、Mermaid、DDL、HTTP 示例、协议标记保持原样。
+4. **正文中文化（可读性整改）** — 正文叙述必须用**中文业务术语**替代代码标识符：
+   - 接口/表用中文名（如「调试执行接口」「逐步结果上报接口」「场景资产表」「作业表」），编号（I1/T3）只出现在接口总览表与字段表。
+   - 字段/配置用中文（`ref_type`→引用类型、`step_count`→步骤数、`job_type`→作业类型、`runtime_payload`→运行时信封、`param_overrides`→参数覆盖、`lease_epoch`→租约世代、`step_uid`→步骤标识、`step_order`→步骤序号）。
+   - 代码标识符只允许出现在：术语与约定表、接口字段表、JSON/HTTP 示例、代码块内。
+   - 首次出现确需给出原名时用括号注（如「运行时信封（runtime_payload）」）。
+5. **有条理 + 图文结合（可读性整改）**：
+   - 叙述内容多的章节**分条输出**：涉及步骤/规则/流程用 **1. 2. 3.** 编号，一句一条，禁止大段散文堆砌。
+   - 流程 / 状态流转 / 结构 / 决策分支类内容**必须配 Mermaid 图**（flowchart / sequenceDiagram / stateDiagram-v2），图紧跟一段文字说明——**图文成对**，禁止只有图没有文字、也禁止长叙述没有任何图。
+   - 图粒度：一图一事，多流程拆多图。
 
 `en`: keep prose brief; numbered steps for how-to. Same table/diagram exception.

package/skills/specflow-techdoc-synth/SKILL.md

@@ -98,9 +98,9 @@ run [--workspace-root <root>]
 1. **统一大纲**：一次生成一份 outline，章节覆盖所有仓，**不按仓分章**（跨仓对比/汇总放进对应章节）。
 2. **契约单一定义**：同一物理端点（method+path）只定义一个实体，用 `side`（console/worker/internal）与 `consumers`/`producers`（仓名）标注面与消费方/生产方；`<repo>_<id>` 前缀仅作**追溯别名**，禁止不同仓重复定义同一接口（validate 以 `duplicate_contract` 拦截）。
 3. **整体性组织（替代按仓分节）**：每章按主题写成一段整体叙述，仓归属用内联 `[repo]` 标注或表格「归属」列；**禁止**为无内容的仓写占位小节（如「某仓无 UI」，validate 以 `repo_section_stub` 拦截）；validate 以全文级 `repo_coverage_missing` 防某仓被概括掉。
-4. **全局视角**（若所选 profile 包含对应章节）：goal 写多仓总目标与边界；tech-selection 对比各仓技术方案；**接口与数据合并为「接口与数据设计」章**（含契约-表映射表：每接口 ↔ 读写表/列）；closed-loop 跨仓统一闭环检查；implementability 跨仓统一可实施性评估。其他场景章节（如 reproduce/root-cause/fix、requirement/test-strategy、research/poc-demo/benchmark）同样给出跨仓结论。
+4. **全局视角**（若所选 profile 包含对应章节）：goal 写多仓总目标与边界；tech-selection 对比各仓技术方案；**接口与数据分工**——接口契约内联进「接口与数据设计」章（接口明细），**数据库表必须由「数据模型」章组件承载**（DDL/存量 G3/回滚 G4），契约-表映射写数据模型章；closed-loop 跨仓统一闭环检查；implementability 跨仓统一可实施性评估。其他场景章节（如 reproduce/root-cause/fix、requirement/test-strategy、research/poc-demo/benchmark）同样给出跨仓结论。
 5. **跨仓依赖/风险**：涉及仓间依赖（接口调用/数据共享/发布顺序）时显式标注「跨仓依赖」。
-6. **完整性骨架**：合成文档必须含术语与约定表、非目标汇总、风险与开放问题、决策记录（ADR，正文用 `[D#]` 引用且先定义后引用）。
+6. **完整性骨架**：合成文档必须含术语与约定表、非目标汇总、风险与开放问题。**不设决策记录（ADR）章节、不用 `[D#]` 引用**——决策理由沉淀在技术选型（否决/备选列）与风险章。
 7. **契约质量**：接口示例带真实 JSON body（空壳示例拦截）、请求/响应字段分列、错误表按 backend/guard/internal 分类。
 8. **主流程必须含图**：主业务流程章输出整体流程图（含失败分支）+ 时序图 + 失败路径决策图。
 

package/templates/document/chapters/api-design.yaml

@@ -1,10 +1,10 @@
 # 接口与数据设计（候选；依赖架构）
-# 整合呈现：接口契约（分层契约 + 前端对接）与数据模型（DDL/G3/G4）同章，含契约-表映射表。
-# 跨仓合成时遵循 buildSynthRules：接口单一定义（side/consumers/producers）、字段表请求/响应分列、
-# 示例带真实 JSON body、错误表按 backend/guard/internal 分类。
+# 接口契约（分层契约 + 前端对接）在本章内联呈现（渲染为「接口明细」）；数据库表由「数据模型」章组件承载，
+# 契约-表映射写「数据模型」章。跨仓合成遵循 buildSynthRules：接口单一定义（side/consumers/producers）、
+# 字段表请求/响应分列、示例带真实 JSON body、错误表按 backend/guard/internal 分类。
 id: api-design
 title: 接口与数据设计
-when: input.containsApiChange || input.hasPersistence
+when: input.containsApiChange
 depends_on: [architecture]
 outline_points:
   - { id: O1, text: 接口总览与调用方/鉴权（含面/消费方/生产方）, required: true, kind: narrative }
@@ -14,11 +14,6 @@ outline_points:
   - { id: O5, text: 前端请求封装（拦截器/重试/缓存/DTO→VO）, required: false, kind: narrative }
   - { id: O6, text: 前端错误处理（错误码统一/Loading-Empty-Error 状态）, required: false, kind: narrative }
   - { id: O7, text: 接口 Mock 与联调（Mock 策略/契约先行，前端可并行开发）, required: false, kind: narrative }
-  - { id: DM1, text: 数据流总览与契约-表映射（每接口 ↔ 读写表/列）, required: true, kind: mixed }
-  - { id: DM2, text: 表结构与 DDL（既有表参考标注）, required: true, kind: entity }
-  - { id: DM3, text: 字段说明 + 本迭代用法, required: true, kind: entity }
-  - { id: DM4, text: 存量填充策略（G3）, required: true, kind: narrative }
-  - { id: DM5, text: 回滚数据兼容（G4）, required: true, kind: narrative }
 entities:
   interfaces:
     required: [id, name, method, path, errors]
@@ -27,11 +22,6 @@ entities:
       errors_table: required
       request_example: required
       success_response_example: required
-  tables:
-    required: [id, name, ddl]
-    each:
-      migration: required
-      rollback: required
 narratives:
   design_notes: required
 gates:
@@ -43,8 +33,6 @@ gates:
   - 错误表按 backend（gRPC→HTTP 映射）/ guard（前端守卫行为）/ internal（Worker 内部语义）分类
   - 涉及前端对接时，请求封装与错误码统一方案必须与契约对齐（R5，字段名/错误码禁各写各的）
   - 前端接口 Mock 必须与契约一致（禁 Mock 一套、真实接口另一套）
-  - 有表实体时必须给出「契约-表映射」（每接口 ↔ 读写表/列）
-  - 每张表必须有完整 CREATE TABLE（含 ENGINE/CHARSET）；零 DDL 迭代仍须展示现网 DDL（禁止假装不涉及数据库）
-  - JSON/新列必须有存量填充策略（G3）；必须有回滚数据兼容说明（G4）
+  - 涉及表实体时，契约-表映射由「数据模型」章给出（本处指引引用，不在本章写表 DDL）
 map_prompt: prompts/document/map/api-design.md
-output_budget_tokens: 12000
+output_budget_tokens: 8000

package/templates/document/chapters/architecture.yaml

@@ -1,4 +1,4 @@
-# 架构设计（0→1 候选；依赖技术选型；扩展：C4 分层 + ADR 决策记录）
+# 架构设计（0→1 候选；依赖技术选型；扩展：C4 分层）
 id: architecture
 title: 架构设计
 when: input.hasLogic && input.hasBackend
@@ -8,7 +8,6 @@ outline_points:
   - { id: AR2, text: 核心组件与职责边界, required: true, kind: narrative }
   - { id: AR3, text: 架构一致性自检, required: false, kind: narrative }
   - { id: AR4, text: C4 分层（Context 系统上下文 / Container 容器 / Component 组件），标注层级与依赖方向, required: false, kind: narrative }
-  - { id: AR5, text: 关键架构决策记录（ADR：背景/决策/后果/备选，沉淀 tech-selection 的 decisions）, required: false, kind: narrative }
 entities: {}
 narratives:
   architecture_notes: required

package/templates/document/chapters/core-logic.yaml

@@ -1,16 +1,18 @@
-# 核心算法 / 逻辑说明
+# 关键实现规则（候选；依赖主业务流程——渲染紧随其后的"下一环节"；可读性整改：承接上下文、只写图中未覆盖规则）
 id: core-logic
-title: 核心算法/逻辑
+title: 关键实现规则
 when: input.hasLogic
-depends_on: [architecture]
+depends_on: [core-flow]
 outline_points:
-  - { id: LOG1, text: 核心算法/流程说明, required: true, kind: narrative }
-  - { id: LOG2, text: 边界与异常处理, required: true, kind: narrative }
+  - { id: LOG1, text: 编译规则（排序/展开/校验/信封冻结）, required: true, kind: narrative }
+  - { id: LOG2, text: 执行与上报规则（信封校验/共享变量/失败策略细节/写入顺序/幂等键/abort）, required: true, kind: narrative }
 entities: {}
 narratives:
   core_logic: required
 gates:
+  - 开头必须承接主业务流程上下文（一句话说明本规则回答"每一步实现怎么落地"），禁止孤立开头
+  - 只写主流程图未覆盖的细节；与主流程/接口章重复的内容必须用交叉引用
   - 超 5 行流程必须 Mermaid（G1）
-  - 复杂交互页状态机用 stateDiagram-v2
+  - 正文中文化（代码标识符只允许在术语表/字段表/示例）
 map_prompt: prompts/document/map/core-logic.md
 output_budget_tokens: 3000

package/templates/document/chapters/data-model.yaml

@@ -1,13 +1,16 @@
-# 数据模型（候选；依赖接口设计）
+# 数据模型（候选；依赖接口设计）——数据库表的唯一承载章节组件
+# 涉及数据库的表时本组件必选（when hasPersistence）：表结构与 DDL、字段说明、存量填充 G3、回滚 G4、
+# 契约-表映射。接口契约本体在「接口与数据设计」章（接口明细），本章通过映射表与接口对齐。
 id: data-model
 title: 数据模型
 when: input.hasPersistence
 depends_on: [api-design]
 outline_points:
-  - { id: DM1, text: 表结构与 DDL, required: true, kind: entity }
-  - { id: DM2, text: 字段说明 + 本迭代用法, required: true, kind: entity }
-  - { id: DM3, text: 存量填充策略（G3）, required: true, kind: narrative }
-  - { id: DM4, text: 回滚数据兼容（G4）, required: true, kind: narrative }
+  - { id: DM1, text: 数据流总览 + 契约-表映射（每接口 ↔ 读写表/列）, required: true, kind: mixed }
+  - { id: DM2, text: 表结构与 DDL, required: true, kind: entity }
+  - { id: DM3, text: 字段说明 + 本迭代用法, required: true, kind: entity }
+  - { id: DM4, text: 存量填充策略（G3）, required: true, kind: narrative }
+  - { id: DM5, text: 回滚数据兼容（G4）, required: true, kind: narrative }
 entities:
   tables:
     required: [id, name, ddl]
@@ -18,6 +21,7 @@ narratives:
   data_notes: required
 gates:
   - 每张表必须有完整 CREATE TABLE（含 ENGINE/CHARSET）
+  - 有接口实体时必须给出「契约-表映射」（每接口 ↔ 读写表/列），禁止接口讲接口、表讲表
   - JSON/新列必须有存量填充策略（G3）
   - 必须有回滚数据兼容说明（G4）
   - 零 DDL 迭代仍须展示现网 DDL（禁止假装不涉及数据库）

package/templates/document/chapters/mvp-boundary.yaml

@@ -7,9 +7,6 @@ outline_points:
   - { id: MVP1, text: MVP 核心功能清单, required: true, kind: entity }
   - { id: MVP2, text: 后续版本功能, required: true, kind: narrative }
   - { id: MVP3, text: 预估复杂度与开发阶段, required: true, kind: narrative }
-entities:
-  decisions:
-    required: [id, text]
 narratives:
   mvp_notes: required
 gates:

package/templates/document/chapters/requirement.yaml

@@ -1,18 +1,16 @@
-# 需求（feature 必选）
+# 需求（feature 必选；可读性整改：不写验收小节，验证由测试策略承接）
 id: requirement
 title: 需求
 when: null
 depends_on: []
 outline_points:
   - { id: REQ1, text: 功能需求描述, required: true, kind: narrative }
-  - { id: REQ2, text: 验收标准（Given-When-Then）, required: true, kind: mixed }
-entities:
-  decisions:
-    required: [id, text]
+  - { id: REQ2, text: 目标与边界（MVP 范围/跨仓依赖/约束；不写 Given-When-Then 验收）, required: true, kind: narrative }
+entities: {}
 narratives:
   requirement_notes: required
 gates:
-  - 需求必须可验证（有明确验收标准）
-  - 禁止含糊需求（如「更好的体验」）
+  - 需求聚焦目标与边界，禁止含糊需求（如「更好的体验」）
+  - 不写 Given-When-Then 验收小节（验收断言由测试策略章承接）
 map_prompt: prompts/document/map/requirement.md
 output_budget_tokens: 3000

package/templates/document/chapters/tech-selection.yaml

@@ -8,9 +8,6 @@ outline_points:
   - { id: TS2, text: 后端/数据库/基础设施选型与理由, required: true, kind: mixed }
   - { id: TS3, text: 选型理由（为何不用备选）, required: true, kind: narrative }
   - { id: TS4, text: 综合评估矩阵（候选方案 × 评估维度 × 得分 × 权重；F5 预研/选型用）, required: false, kind: mixed }
-entities:
-  decisions:
-    required: [id, text]
 narratives:
   selection_reason: required
 gates:

package/templates/document/chapters/test-strategy.yaml

@@ -6,16 +6,13 @@ depends_on: [api-design, data-model]
 outline_points:
   - { id: T1, text: 分层测试矩阵, required: true, kind: entity }
   - { id: T2, text: 测试环境与数据, required: true, kind: narrative }
-  - { id: T3, text: 与验收标准的映射, required: true, kind: narrative }
+  - { id: T3, text: 验收断言承接（Given-When-Then 折叠进本表，每行加「验收依据」列）, required: true, kind: narrative }
   - { id: T4, text: 前端测试金字塔（单元 60% / 组件 30% / E2E 10%，含组件测试 Snapshot+交互）, required: false, kind: narrative }
   - { id: T5, text: 回归测试范围（对应影响面，覆盖受影响功能）, required: false, kind: narrative }
-entities:
-  decisions:
-    required: [id, text]
 narratives:
   test_notes: required
 gates:
-  - 每个测试层级必须映射到具体验收标准/场景
+  - 每个测试层级必须给出验收依据（承接需求章目标；验收不再单独成章）
   - 每个层级有工具/框架 + 可验证目标
   - 不涉及测试变更时显式标注
   - 涉及前端时，测试金字塔比例与组件测试方式必须写明（禁「跑单测」空话）

package/templates/document/chapters/ui-design.yaml

@@ -12,9 +12,6 @@ outline_points:
   - { id: UI6, text: 路由守卫/懒加载（权限/登录态/动态 import）, required: false, kind: narrative }
   - { id: UI7, text: 埋点（页面曝光/点击事件 + 参数）, required: false, kind: narrative }
   - { id: UI8, text: 浏览器兼容策略（版本 + 降级手段，README §1.4）, required: false, kind: narrative }
-entities:
-  decisions:
-    required: [id, text]
 narratives:
   ui_notes: required
 gates:

package/templates/document/profiles/approve.yaml

@@ -12,11 +12,12 @@ required:
   - implementability # 可实施性评估（7 维）
 optional_candidates:
   - ui-design       # 前端/UI（条件: uiInScope）
-  - core-logic      # 核心算法/逻辑
+  - core-logic      # 关键实现规则（依赖闭合用 core-flow）
   - config-runtime  # 配置与运行环境
   - compat-migration # 兼容性与迁移
   - acceptance      # 验收标准
   - deploy          # 部署/发布/回滚
   - signoff         # 审批意见（签字栏）
 forbidden: [reproduce, root-cause, impact, fix, regression]
-shared: []
+shared:
+  - core-flow       # 仅依赖闭合：core-logic 依赖 core-flow，approve 不渲染主流程章

package/templates/document/profiles/feature.yaml

@@ -20,4 +20,4 @@ optional_candidates:
 shared:                       # 仅闭合允许、不渲染：impact 依赖 root-cause；前端链依赖 frontend-architecture
   - root-cause
   - frontend-architecture
-forbidden: [reproduce, root-cause, fix, regression, goal, mvp-boundary, non-goals, research, poc-demo, benchmark, migration-guide, deploy, ops, closed-loop, implementability, config-runtime, acceptance]
+forbidden: [reproduce, root-cause, fix, regression, goal, mvp-boundary, research, poc-demo, benchmark, migration-guide, deploy, ops, closed-loop, implementability, config-runtime, acceptance]