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

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

@@ -717,12 +717,15 @@ function buildSynthRules(dirs) {
     return [
         `## 跨仓合成规则（必须遵守）`,
         `1. **统一大纲**：一次生成一份 outline，章节覆盖所有仓，不按仓分章（跨仓对比/汇总放进对应章节）。`,
-        `2. **契约实体命名空间**：跨仓实体 id 用 \`<repo>_<id>\` 前缀（如 \`repo1_I1\`、\`repo2_T1\`），禁止不同仓共用裸 id。`,
-        `3. **每章必须分仓小节（质量门禁，validate 强制）**：每个必选章节的叙述按仓分节，用 \`### <repo>\` 小节标题（可带后缀如 \`### repo1 · 目标\`），且每个仓（${repoList}）都必须出现。禁止把多仓内容混写成一段（会导致细节互相稀释）。`,
-        `4. **全局视角**（若所选 profile 包含对应章节）：goal 写多仓总目标与边界；tech-selection 对比各仓技术方案；api-design/data-model 分仓列契约；closed-loop 跨仓统一闭环检查；implementability 跨仓统一可实施性评估。其他场景章节（如 reproduce/root-cause/fix、requirement/test-strategy、research/poc-demo/benchmark）同样按仓分节并给出跨仓结论。`,
+        `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/存量 G3/回滚 G4），契约-表映射写数据模型章，两章按「接口与数据设计 → 数据模型」顺序并列；closed-loop 跨仓统一闭环检查；implementability 跨仓统一可实施性评估。`,
         `5. **跨仓依赖/风险**：涉及仓间依赖（接口调用/数据共享/发布顺序）时显式标注「跨仓依赖」。`,
         `6. **按需加载规约（重要）**：写某个仓的小节时，**只读取该仓**的规约/IDE rules/guidance（该仓的 \`docs/\`、\`.cursor\`、\`.claude\`、\`.agents\` 等），**禁止一次性读取全部仓的规约**；只有写跨仓内容（接口对接/数据共享/发布顺序）时才读取**涉及仓**的规约。未读取的仓规约不得臆测，必要时标注「未读取该仓规约，待确认」。`,
         `7. **输入归属**：每段输入带「来源仓」标记，段 id 携带仓前缀（如 \`seg-repo1-proposal-01\`）；引用原文时按段 id 精确取回对应仓的片段，不整篇重读。`,
+        `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, checkRepoSectionCoverage } 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';
@@ -227,8 +227,18 @@ export async function runDocument(options) {
         await writeReviewResult(workRoot, review);
     }
     // --- Pass 4: render (T9) ---
+    // Multi-repo synthesize marker: repos.json (written by document synthesize) — 提前读取，
+    // 供渲染文档头元信息与 runGates 整体性门禁共用（Agent 模式 validateWork 亦同）。
+    let synthRepos = [];
+    try {
+        const raw = JSON.parse(await fs.readFile(reposPath(workRoot), 'utf-8'));
+        synthRepos = Array.isArray(raw) ? raw.filter((r) => typeof r === 'string') : [];
+    }
+    catch {
+        // no repos.json → not a synthesize workRoot → gate skipped (bundle/run unaffected)
+    }
     const appendixAntiAI = await readAppendix(workRoot, 'anti-ai');
-    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap, profile, appendixAntiAI });
+    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap, profile, appendixAntiAI, repos: synthRepos.length > 0 ? synthRepos : undefined });
     if (persist)
         await fs.writeFile(paths.documentMd, documentMd, 'utf-8');
     let documentHtml;
@@ -238,16 +248,6 @@ export async function runDocument(options) {
             await fs.writeFile(paths.documentHtml, documentHtml, 'utf-8');
     }
     // --- Gates (T10) ---
-    // Multi-repo synthesize marker: repos.json (written by document synthesize) → runGates enforces
-    // the per-repo section gate in the library pipeline too (not only Agent-mode validateWork).
-    let synthRepos = [];
-    try {
-        const raw = JSON.parse(await fs.readFile(reposPath(workRoot), 'utf-8'));
-        synthRepos = Array.isArray(raw) ? raw.filter((r) => typeof r === 'string') : [];
-    }
-    catch {
-        // no repos.json → not a synthesize workRoot → gate skipped (bundle/run unaffected)
-    }
     const gates = await runGates({
         outline,
         chapterNarratives: narrativeMap,
@@ -675,8 +675,8 @@ export async function validateWork(options) {
         }
     }
     // Multi-repo synthesize quality gate: if repos.json exists (document synthesize wrote it),
-    // every required chapter must have a per-repo section (`### <repo>`) for ALL repos.
-    // This prevents "伪统一" — cross-repo content diluting each other into vague prose.
+    // 整体性组织门禁——全文级仓覆盖（防某仓被概括掉）+ 空壳小节拦截（禁「某仓无 X」占位），
+    // 替代旧「每章必须 ### <repo> 分仓小节」；另附契约质量 lint（与 runGates 库模式一致）。
     let synthRepos = [];
     try {
         const raw = JSON.parse(await fs.readFile(reposPath(workRoot), 'utf-8'));
@@ -686,18 +686,40 @@ export async function validateWork(options) {
         // no repos.json → not a synthesize workRoot → gate skipped (bundle/run unaffected)
     }
     if (synthRepos.length >= 2) {
-        const requiredIds = new Set(profile.required);
-        for (const ch of outline.chapters) {
-            if (!requiredIds.has(ch.id))
-                continue;
-            const narrative = narrativeMap.get(ch.id);
-            if (narrative === undefined)
-                continue; // chapter_missing already reported
-            for (const d of checkRepoSectionCoverage(ch.id, narrative, synthRepos)) {
-                diags.push({ gate: 'synthesize', code: d.code, severity: d.severity, message: d.message, chapter: ch.id });
+        for (const d of checkRepoCoverage(synthRepos, narrativeMap)) {
+            diags.push({ gate: 'synthesize', code: d.code, severity: d.severity, message: d.message });
+        }
+        for (const [chId, narrative] of narrativeMap) {
+            for (const d of checkRepoSectionStub(chId, narrative, synthRepos)) {
+                diags.push({ gate: 'synthesize', code: d.code, severity: d.severity, message: d.message, chapter: chId });
             }
         }
     }
+    for (const d of checkDuplicateContract(allEntities.interfaces)) {
+        diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message });
+    }
+    for (const d of checkExamplePresence(allEntities.interfaces)) {
+        diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message });
+    }
+    for (const d of checkForwardDecisionRef(narrativeMap, allEntities.decisions)) {
+        diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: d.chapter });
+    }
+    for (const [chId, narrative] of narrativeMap) {
+        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)) {
+            diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message });
+        }
+    }
     // Structured coverage (entity points must be filled).
     for (const d of checkStructuredCoverage(outline, entityMap)) {
         diags.push({ gate: 'coverage', code: d.code, severity: d.severity, message: d.message, chapter: d.chapter });
@@ -710,7 +732,7 @@ export async function validateWork(options) {
         return { ok: false, diagnostics: diags };
     }
     // Render (appendices driven by profile.appendices).
-    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap, profile, appendixAntiAI });
+    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap, profile, appendixAntiAI, repos: synthRepos.length > 0 ? synthRepos : undefined });
     await fs.writeFile(paths.documentMd, documentMd, 'utf-8');
     let documentHtml;
     if (options.renderHtmlOutput !== false) {

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, checkRepoSectionCoverage } 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) {
@@ -48,18 +48,44 @@ export async function runGates(input) {
             }
         }
     }
-    // Multi-repo synthesize gate (library pipeline): every non-optional chapter must have per-repo
-    // sections (`### <repo>`) when repos ≥2 — matches validateWork (Agent mode) enforcement.
+    // Multi-repo synthesize gate (library pipeline): 全文级仓覆盖 + 空壳小节拦截（整体性组织，
+    // 替代旧「每章必须 ### <repo> 分仓小节」）。matches validateWork (Agent mode) enforcement.
     if (input.repos && input.repos.length >= 2) {
-        const requiredById = new Map(input.outline.chapters.filter((c) => !c.optional).map((c) => [c.id, c]));
+        for (const d of checkRepoCoverage(input.repos, input.chapterNarratives)) {
+            diags.push({ gate: 'synthesize', code: d.code, severity: d.severity, message: d.message });
+        }
         for (const [chId, narrative] of input.chapterNarratives) {
-            if (!requiredById.has(chId))
-                continue;
-            for (const d of checkRepoSectionCoverage(chId, narrative, input.repos)) {
+            for (const d of checkRepoSectionStub(chId, narrative, input.repos)) {
                 diags.push({ gate: 'synthesize', code: d.code, severity: d.severity, message: d.message, chapter: chId });
             }
         }
     }
+    // 契约质量 lint：契约单一定义 / 示例带 body（空壳拦截）/ 前向决策引用 / 未验证数字 / 契约-表映射。
+    for (const d of checkDuplicateContract(input.entities.interfaces)) {
+        diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message });
+    }
+    for (const d of checkExamplePresence(input.entities.interfaces)) {
+        diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message });
+    }
+    for (const d of checkForwardDecisionRef(input.chapterNarratives, input.entities.decisions)) {
+        diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: d.chapter });
+    }
+    for (const [chId, narrative] of input.chapterNarratives) {
+        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)) {
+            diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message });
+        }
+    }
     // structured coverage
     for (const d of checkStructuredCoverage(input.outline, input.chapterEntities)) {
         diags.push({ gate: 'coverage', code: d.code, severity: d.severity, message: d.message, chapter: d.chapter });

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

@@ -36,4 +36,40 @@ export interface RepoSectionDiagnostic {
     message: string;
     chapter?: string;
 }
-export declare function checkRepoSectionCoverage(chapterId: string, narrative: string, repos: readonly string[]): RepoSectionDiagnostic[];
+export declare function countRepoMentions(narrative: string, repo: string): number;
+export declare function checkRepoCoverage(repos: readonly string[], narratives: ReadonlyMap<string, string>, threshold?: number): RepoSectionDiagnostic[];
+export declare function checkRepoSectionStub(chapterId: string, narrative: string, repos: readonly string[], minChars?: number): RepoSectionDiagnostic[];
+/** 同一物理端点（method+path 归一化）不得存在多个接口实体。 */
+export declare function checkDuplicateContract(interfaces: ReadonlyArray<{
+    method: string;
+    path: string;
+    id: string;
+}>): RepoSectionDiagnostic[];
+/** 空壳示例拦截：body 方法必须给 request_example（或标注「无请求体」）；有响应字段必须有成功响应示例。 */
+export declare function checkExamplePresence(interfaces: ReadonlyArray<{
+    id: string;
+    method: string;
+    request_example?: string;
+    response_fields?: unknown[];
+    success_response_example?: string;
+}>): RepoSectionDiagnostic[];
+/** 前向决策引用：叙述引用 [D#] 但该决策未在 entities.decisions 定义 → warning（P6 决策位置前移辅助检查）。 */
+export declare function checkForwardDecisionRef(narratives: ReadonlyMap<string, string>, decisions: ReadonlyArray<{
+    id: string;
+}>): RepoSectionDiagnostic[];
+/** 性能章目标数字必须标注来源/待实测（P10）。 */
+export declare function checkUnverifiedNumber(chapterId: string, narrative: string): RepoSectionDiagnostic[];
+/** 接口与数据对齐（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

@@ -124,24 +124,219 @@ export function checkGoldenSignals(chapterId, narrative, gates = []) {
             message: `Chapter "${chapterId}" gates require SRE 四金信号 monitoring but missing: ${missing.map((m) => m.key).join('、')}（监控必须覆盖延迟/流量/错误/饱和度）`,
         }];
 }
-export function checkRepoSectionCoverage(chapterId, narrative, repos) {
+export function countRepoMentions(narrative, repo) {
+    const esc = escapeRegExp(repo);
+    const re = new RegExp(`\\[${esc}\\]|^###\\s+${esc}(?:\\s|：|:|·|$)|${esc}_`, 'gm');
+    return (narrative.match(re) ?? []).length;
+}
+export function checkRepoCoverage(repos, narratives, threshold = 3) {
     if (repos.length < 2)
         return []; // 非 synthesize 或单仓 → 不校验
+    const joined = [...narratives.values()].join('\n');
+    const diags = [];
+    for (const repo of repos) {
+        if (countRepoMentions(joined, repo) < threshold) {
+            diags.push({
+                code: 'repo_coverage_missing',
+                severity: 'error',
+                message: `合成文档中仓 ${repo} 全文累计出现 < ${threshold} 次（应含 [${repo}] 标注、\`### ${repo}\` 小节或 ${repo}_ 前缀实体），疑似被概括掉`,
+            });
+        }
+    }
+    return diags;
+}
+export function checkRepoSectionStub(chapterId, narrative, repos, minChars = 40) {
     const diags = [];
     for (const repo of repos) {
-        // 匹配 `### <repo>` 小节标题（行首，可带后缀如 `### repo1 · 目标`）
-        const sectionRe = new RegExp(`^###\\s+${escapeRegExp(repo)}(?:\\s|：|:|·|$)`, 'm');
-        if (!sectionRe.test(narrative)) {
+        const re = new RegExp(`^###\\s+${escapeRegExp(repo)}(?:\\s|：|:|·|$)[\\s\\S]*?(?=^###|$)`, 'm');
+        const m = re.exec(narrative);
+        if (!m)
+            continue;
+        const sectionBody = m[0].replace(/^###[^\n]*\n/, '').trim();
+        if (sectionBody.length < minChars) {
             diags.push({
-                code: 'repo_section_missing',
+                code: 'repo_section_stub',
                 severity: 'error',
                 chapter: chapterId,
-                message: `Chapter "${chapterId}" 缺少仓 ${repo} 的分仓小节（应含 \`### ${repo}\`，合成文档每章必须按仓分节，防止跨仓内容互相稀释）`,
+                message: `Chapter "${chapterId}" 的仓 ${repo} 小节内容过短（< ${minChars} 字符，疑似「无 X」占位），请并入整体叙述或补足实质内容`,
+            });
+        }
+    }
+    return diags;
+}
+// ============= 契约质量 lint（P2/P3/P4/P6：契约单一定义 / 示例带 body / 前向决策引用） =============
+/** 同一物理端点（method+path 归一化）不得存在多个接口实体。 */
+export function checkDuplicateContract(interfaces) {
+    const diags = [];
+    const seen = new Map();
+    for (const it of interfaces) {
+        const key = `${it.method} ${it.path.trim().toLowerCase()}`;
+        const prev = seen.get(key);
+        if (prev) {
+            diags.push({
+                code: 'duplicate_contract',
+                severity: 'error',
+                message: `接口 ${it.id} 与 ${prev} 为同一物理端点（${it.method} ${it.path}），契约应单一定义并标注消费方/生产方（<repo>_<id> 仅作追溯别名）`,
             });
         }
+        else {
+            seen.set(key, it.id);
+        }
+    }
+    return diags;
+}
+const BODY_METHODS = new Set(['POST', 'PUT', 'PATCH']);
+const NO_BODY_MARK = /无请求体/;
+/** 空壳示例拦截：body 方法必须给 request_example（或标注「无请求体」）；有响应字段必须有成功响应示例。 */
+export function checkExamplePresence(interfaces) {
+    const diags = [];
+    for (const it of interfaces) {
+        const example = (it.request_example ?? '').trim();
+        const isNoBodyMark = NO_BODY_MARK.test(example);
+        // 空壳拦截：body 方法既无真实 JSON 请求体、也未显式标注「无请求体」→ error。
+        if (BODY_METHODS.has(it.method) && !isNoBodyMark && example.length === 0) {
+            diags.push({
+                code: 'request_example_missing',
+                severity: 'error',
+                message: `接口 ${it.id}（${it.method}）缺少 request_example（真实 JSON 请求体），空壳「成功示例」不合格；确无请求体请显式标注「无请求体」`,
+            });
+        }
+        if ((it.response_fields?.length ?? 0) > 0 && !it.success_response_example) {
+            diags.push({
+                code: 'response_example_missing',
+                severity: 'error',
+                message: `接口 ${it.id} 声明了响应字段但缺少 success_response_example（真实 JSON 成功响应示例）`,
+            });
+        }
+    }
+    return diags;
+}
+/** 前向决策引用：叙述引用 [D#] 但该决策未在 entities.decisions 定义 → warning（P6 决策位置前移辅助检查）。 */
+export function checkForwardDecisionRef(narratives, decisions) {
+    const defined = new Set(decisions.map((d) => d.id));
+    const diags = [];
+    const re = /\[(D\d+)\]/g;
+    for (const [chId, narrative] of narratives) {
+        let m;
+        while ((m = re.exec(narrative)) !== null) {
+            if (!defined.has(m[1])) {
+                diags.push({
+                    code: 'forward_decision_ref',
+                    severity: 'warning',
+                    chapter: chId,
+                    message: `Chapter "${chId}" 引用了未定义的决策 ${m[1]}（决策应在 ADR 章节先行定义，正文用 [D#] 引用）`,
+                });
+            }
+        }
     }
     return diags;
 }
+/** 性能章目标数字必须标注来源/待实测（P10）。 */
+export function checkUnverifiedNumber(chapterId, narrative) {
+    if (chapterId !== 'performance')
+        return [];
+    if (!/\d/.test(narrative))
+        return [];
+    if (!/待实测|门闩|测量|实测|基准/.test(narrative)) {
+        return [{
+                code: 'unverified_number',
+                severity: 'warning',
+                chapter: chapterId,
+                message: `Chapter "${chapterId}" 含目标数字但未标注「待实测/门闩/测量方法」，数字可信度不足（性能数字必须给来源或测量方式）`,
+            }];
+    }
+    return [];
+}
+/** 接口与数据对齐（P11）：有表实体时，数据模型章（或接口章）必须含契约-表映射表。 */
+export function checkDataContractMapping(narratives, entities) {
+    if ((entities.tables?.length ?? 0) === 0)
+        return [];
+    const narrative = narratives.get('data-model') ?? narratives.get('api-design') ?? '';
+    if (!/契约-表映射|映射表|接口.*表.*映射|表.*接口.*映射/.test(narrative)) {
+        return [{
+                code: 'data_contract_mapping_missing',
+                severity: 'warning',
+                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 [];
+}
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

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

@@ -16,11 +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;
-}>): string;
 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;
@@ -32,6 +31,10 @@ export interface RenderDocumentInput {
     };
     /** LLM-written anti-AI self-check items (from appendices/anti-ai.md, optional). */
     appendixAntiAI?: string;
+    /** 参与仓清单（synth 模式）：渲染文档头元信息（P7 整体性）。 */
+    repos?: string[];
+    /** 是否渲染产物溯源附录（P8：默认关闭，调试/--signoff 时开启）。 */
+    includeProvenance?: boolean;
 }
 /** 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