@gordon.gan/specflow 1.8.0-beta → 1.8.2-beta

package/dist/core/document/profile-validator.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Document Engine — Profile static validator (decision 8 · P1-H).
+ *
+ * Validates a ScenarioProfile at load time (fail-fast) before any generation:
+ *  1. Existence     — every required/optional chapter id exists in the library
+ *  2. Required met  — required is non-empty and fully present
+ *  3. Closure       — every depends_on target is in the profile (or declared shared)
+ *  4. Acyclic       — depends_on forms a DAG (topological sort, cycle → error)
+ *  5. When-usable   — when expressions reference known input features
+ */
+import { ScenarioProfile, ChapterComponent } from './schemas.js';
+export interface ValidationDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    chapter?: string;
+}
+export interface ProfileValidationOptions {
+    profile: ScenarioProfile;
+    library: Map<string, ChapterComponent>;
+}
+export declare function validateProfile(options: ProfileValidationOptions): ValidationDiagnostic[];
+export declare function hasErrors(diags: ValidationDiagnostic[]): boolean;

package/dist/core/document/profile-validator.js

@@ -0,0 +1,155 @@
+/**
+ * Document Engine — Profile static validator (decision 8 · P1-H).
+ *
+ * Validates a ScenarioProfile at load time (fail-fast) before any generation:
+ *  1. Existence     — every required/optional chapter id exists in the library
+ *  2. Required met  — required is non-empty and fully present
+ *  3. Closure       — every depends_on target is in the profile (or declared shared)
+ *  4. Acyclic       — depends_on forms a DAG (topological sort, cycle → error)
+ *  5. When-usable   — when expressions reference known input features
+ */
+import { isKnownFeature, parseWhen, featuresInWhen } from './input-features.js';
+export function validateProfile(options) {
+    const { profile, library } = options;
+    const diags = [];
+    const declared = new Set([
+        ...profile.required,
+        ...profile.optional_candidates,
+        ...profile.forbidden,
+        ...profile.shared,
+    ]);
+    // 1. Existence: every referenced chapter id exists in the library.
+    for (const id of declared) {
+        if (!library.has(id)) {
+            diags.push({
+                code: 'chapter_not_found',
+                severity: 'error',
+                message: `Chapter "${id}" referenced by profile "${profile.id}" does not exist in the library`,
+            });
+        }
+    }
+    // 2. Required non-empty + all present.
+    if (profile.required.length === 0) {
+        diags.push({
+            code: 'required_empty',
+            severity: 'error',
+            message: `Profile "${profile.id}" must declare at least one required chapter`,
+        });
+    }
+    // 2b. 分类冲突（P2）：同一章节出现在 required∩forbidden / optional∩forbidden 时，
+    // expandProfile 会静默从 selected 删除，必需章节凭空消失。加载期即报错。
+    const requiredSet = new Set(profile.required);
+    const optionalSet = new Set(profile.optional_candidates);
+    for (const id of profile.forbidden) {
+        if (requiredSet.has(id)) {
+            diags.push({ code: 'category_conflict', severity: 'error', chapter: id, message: `Chapter "${id}" is in both required and forbidden` });
+        }
+        if (optionalSet.has(id)) {
+            diags.push({ code: 'category_conflict', severity: 'error', chapter: id, message: `Chapter "${id}" is in both optional_candidates and forbidden` });
+        }
+    }
+    // 2c. 数组内重复 id。
+    for (const [label, list] of [['required', profile.required], ['optional_candidates', profile.optional_candidates], ['forbidden', profile.forbidden], ['shared', profile.shared]]) {
+        const seenIds = new Set();
+        for (const id of list) {
+            if (seenIds.has(id)) {
+                diags.push({ code: 'duplicate_id', severity: 'warning', chapter: id, message: `Chapter "${id}" appears more than once in ${label}` });
+            }
+            seenIds.add(id);
+        }
+    }
+    // 3+4. Dependency closure + acyclic over the selected chapters.
+    //    A chapter may depend on: another selected chapter, a shared chapter, or a chapter in
+    //    required/optional that we include in the closure graph.
+    //    closure 检查覆盖 required + optional_candidates（P2）：可选章节是 LLM 可能选中的
+    //    渲染章节，其悬空依赖必须报错；shared 章节仅作依赖闭合、不渲染，其 depends_on
+    //    不需要闭包（引擎不会填充 shared 章节）。
+    const closureNodes = new Set([...profile.required, ...profile.optional_candidates, ...profile.shared]);
+    const renderedIds = [...profile.required, ...profile.optional_candidates];
+    for (const id of renderedIds) {
+        const ch = library.get(id);
+        if (!ch)
+            continue;
+        for (const dep of ch.depends_on) {
+            if (!closureNodes.has(dep)) {
+                diags.push({
+                    code: 'dependency_unclosed',
+                    severity: 'error',
+                    chapter: id,
+                    message: `Chapter "${id}" depends on "${dep}" which is not in the profile's required/optional/shared set`,
+                });
+            }
+        }
+    }
+    // Acyclic check via Kahn's algorithm on selected + shared nodes.
+    // 注意：不再排除自依赖（dep !== n 过滤已删除，P2）——自环必须被正确判为环。
+    const nodes = [...closureNodes].filter((n) => library.has(n));
+    const indegree = new Map();
+    const adj = new Map();
+    for (const n of nodes) {
+        indegree.set(n, 0);
+        adj.set(n, []);
+    }
+    for (const n of nodes) {
+        const ch = library.get(n);
+        for (const dep of ch.depends_on) {
+            if (closureNodes.has(dep) && library.has(dep)) {
+                adj.get(dep).push(n);
+                indegree.set(n, (indegree.get(n) ?? 0) + 1);
+            }
+        }
+    }
+    const queue = nodes.filter((n) => indegree.get(n) === 0);
+    const seen = new Set();
+    while (queue.length > 0) {
+        const cur = queue.shift();
+        seen.add(cur);
+        for (const next of adj.get(cur) ?? []) {
+            indegree.set(next, (indegree.get(next) ?? 1) - 1);
+            if (indegree.get(next) === 0)
+                queue.push(next);
+        }
+    }
+    for (const n of nodes) {
+        if (!seen.has(n)) {
+            diags.push({
+                code: 'dependency_cycle',
+                severity: 'error',
+                chapter: n,
+                message: `Dependency cycle detected involving chapter "${n}"`,
+            });
+        }
+    }
+    // 5. When-usable: every when expression must parse and reference known input features.
+    //    （覆盖 shared 章节，P2；未知 feature 提级为 error——拼错 feature 会静默丢章节）
+    for (const id of [...profile.required, ...profile.optional_candidates, ...profile.shared]) {
+        const ch = library.get(id);
+        if (!ch?.when)
+            continue;
+        try {
+            parseWhen(ch.when);
+            for (const f of featuresInWhen(ch.when)) {
+                if (!isKnownFeature(f)) {
+                    diags.push({
+                        code: 'when_unknown_feature',
+                        severity: 'error',
+                        chapter: id,
+                        message: `when expression of chapter "${id}" references unknown input feature "${f}"`,
+                    });
+                }
+            }
+        }
+        catch (e) {
+            diags.push({
+                code: 'when_invalid',
+                severity: 'error',
+                chapter: id,
+                message: `when expression of chapter "${id}" is invalid: ${e instanceof Error ? e.message : String(e)}`,
+            });
+        }
+    }
+    return diags;
+}
+export function hasErrors(diags) {
+    return diags.some((d) => d.severity === 'error');
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Document Engine — scenario profile loader + expansion.
+ * Loads templates/document/profiles/*.yaml, validates via profile-validator,
+ * and expands a profile into the concrete chapter selection given input features.
+ */
+import { ScenarioProfile } from './schemas.js';
+import { ValidationDiagnostic } from './profile-validator.js';
+import { ChapterComponent } from './schemas.js';
+export interface ExpandedProfile {
+    profile: ScenarioProfile;
+    /** Chapters in render order: required first (in order), then selected optional candidates. */
+    chapters: string[];
+    diagnostics: ValidationDiagnostic[];
+}
+export declare function loadProfile(profileId: string, dir?: string): Promise<ScenarioProfile>;
+/**
+ * Expand a profile against input features:
+ *  - required chapters always included (in declared order)
+ *  - optional candidates included when their `when` (if any) evaluates true, or when no `when`
+ *  - forbidden chapters never included
+ *  - output respects dependency order (topological) so dependents come after dependencies
+ */
+export declare function expandProfile(profile: ScenarioProfile, library: Map<string, ChapterComponent>, features: Record<string, boolean>): ExpandedProfile;

package/dist/core/document/profiles.js

@@ -0,0 +1,76 @@
+/**
+ * Document Engine — scenario profile loader + expansion.
+ * Loads templates/document/profiles/*.yaml, validates via profile-validator,
+ * and expands a profile into the concrete chapter selection given input features.
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+import { parseScenarioProfile } from './schemas.js';
+import { validateProfile, hasErrors } from './profile-validator.js';
+import { evaluateWhen } from './input-features.js';
+import { resolveTemplateDir } from './asset-paths.js';
+/** profile id 白名单（P2）：拒绝路径穿越（../、绝对路径）。 */
+const PROFILE_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+export async function loadProfile(profileId, dir) {
+    if (!PROFILE_ID_RE.test(profileId)) {
+        throw new Error(`Invalid profile id "${profileId}": must match ${PROFILE_ID_RE}`);
+    }
+    // 默认从「用户 cwd/templates 优先、包内 templates fallback」解析（多仓工作区也能跑）。
+    const resolvedDir = dir ?? (await resolveTemplateDir(join('document', 'profiles')));
+    const raw = yaml.load(await fs.readFile(join(resolvedDir, `${profileId}.yaml`), 'utf-8'));
+    return parseScenarioProfile(raw);
+}
+/**
+ * Expand a profile against input features:
+ *  - required chapters always included (in declared order)
+ *  - optional candidates included when their `when` (if any) evaluates true, or when no `when`
+ *  - forbidden chapters never included
+ *  - output respects dependency order (topological) so dependents come after dependencies
+ */
+export function expandProfile(profile, library, features) {
+    const diags = validateProfile({ profile, library });
+    if (hasErrors(diags)) {
+        return { profile, chapters: [], diagnostics: diags };
+    }
+    const selected = new Set(profile.required);
+    for (const id of profile.optional_candidates) {
+        const ch = library.get(id);
+        if (!ch)
+            continue;
+        if (ch.when && !evaluateWhen(ch.when, features))
+            continue;
+        selected.add(id);
+    }
+    for (const id of profile.forbidden)
+        selected.delete(id);
+    // Topological order over selected chapters (dependencies first).
+    const ordered = [];
+    const visited = new Set();
+    const stack = new Set();
+    const visit = (id) => {
+        if (visited.has(id))
+            return;
+        if (stack.has(id))
+            return; // cycle — validator should have caught it
+        stack.add(id);
+        const ch = library.get(id);
+        if (ch) {
+            for (const dep of ch.depends_on) {
+                if (selected.has(dep))
+                    visit(dep);
+            }
+        }
+        stack.delete(id);
+        visited.add(id);
+        if (selected.has(id))
+            ordered.push(id);
+    };
+    for (const id of profile.required)
+        visit(id);
+    for (const id of profile.optional_candidates) {
+        if (selected.has(id))
+            visit(id);
+    }
+    return { profile, chapters: ordered, diagnostics: diags };
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Document Engine — Pass 4 deterministic rendering (decisions 7/9).
+ *
+ * Renders the final document by concatenating chapters in outline order (NOT assemble):
+ * contract entities → Markdown tables/code blocks; narrative → verbatim into its chapter.
+ * Optional HTML render reuses `marked`.
+ */
+import { Outline, Entities, InterfaceEntity, TableEntity } from './schemas.js';
+/** HTML 转义：用于 <title>/<h1> 插值（防存储型 XSS）。 */
+export declare function escapeHtml(s: string): string;
+/** Markdown 表格单元格转义：转义 | 与换行（防破坏列对齐/拆行）。 */
+export declare function escapeTableCell(s: string): string;
+/** 代码围栏内容转义：把可能提前终止 ``` 围栏的行替换为安全形式。 */
+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;
+export interface RenderDocumentInput {
+    outline: Outline;
+    entities: Entities;
+    /** chapterId → narrative markdown */
+    narratives: Map<string, string>;
+    /** Scenario profile — drives appendices rendering (profile.appendices, §7.2/7.3). */
+    profile?: {
+        appendices?: string[];
+    };
+    /** LLM-written anti-AI self-check items (from appendices/anti-ai.md, optional). */
+    appendixAntiAI?: string;
+}
+/** 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. */
+export declare function stripReviewNotes(text: string): string;
+/**
+ * 从章节叙述中剥离内嵌的**契约实体 JSON 块**（```json {"entities": {...}} ```）。
+ * 这些块是 Agent 写给引擎提取的机器中间格式（map 提示词要求 kind=entity|mixed 要点产出），
+ * 引擎已把其中实体提取进 entities.json，并在文档末尾「契约实体」章节渲染为人类可读的表格。
+ * 最终 document.md 不应再出现原始 JSON——否则读者看到看不懂的 `decisions`/`interfaces` 结构。
+ *
+ * 判定：JSON 可解析且按 Entities schema 解析成功（含 interfaces/tables/decisions 任一非空）
+ * 才剥离；无法解析的块（叙述中的示例 JSON）原样保留，避免误删正文。
+ */
+export declare function stripEntityJsonBlocks(text: string): string;
+/**
+ * 剥离章节叙述首行的**冗余 H1 标题**：叙述以 `# <章节标题>` 开头（Agent 生成正文时习惯性地
+ * 重复了大纲章节标题），而 renderDocument 已为每章输出 `## <title>`——二者叠加造成标题重复。
+ * 仅当首行非空是 H1 且其内容与章节标题 trim 后一致时才剥离，避免误删正文中的真实内容。
+ */
+export declare function stripLeadingTitle(text: string, chapterTitle: string): string;
+export declare function renderDocument(input: RenderDocumentInput): string;
+/** 附录 B · 去AI味自检（frontend-dev-guide §十一 → README §1.6 五维表）。 */
+export declare function renderAppendixAntiAI(content?: string): string;
+/** 附录 C · 下游交付衔接（frontend-dev-guide §八 → README §1.5 矩阵 + 三步）。 */
+export declare function renderAppendixHandoff(): string;
+export declare function renderHtml(markdown: string, title?: string): Promise<string>;

package/dist/core/document/render.js

@@ -0,0 +1,243 @@
+/**
+ * Document Engine — Pass 4 deterministic rendering (decisions 7/9).
+ *
+ * Renders the final document by concatenating chapters in outline order (NOT assemble):
+ * contract entities → Markdown tables/code blocks; narrative → verbatim into its chapter.
+ * Optional HTML render reuses `marked`.
+ */
+import { marked } from 'marked';
+import { parseEntities } from './schemas.js';
+// ============= Escaping helpers（P1-5/6：HTML 与 markdown 注入面） =============
+/** HTML 转义：用于 <title>/<h1> 插值（防存储型 XSS）。 */
+export function escapeHtml(s) {
+    return String(s)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/** Markdown 表格单元格转义：转义 | 与换行（防破坏列对齐/拆行）。 */
+export function escapeTableCell(s) {
+    return String(s).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+/** 代码围栏内容转义：把可能提前终止 ``` 围栏的行替换为安全形式。 */
+export function escapeFenceContent(s) {
+    return String(s).split('\n').map((line) => (line.trimStart().startsWith('```') ? `\\\`\\\`\\\`${line.slice(3)}` : line)).join('\n');
+}
+/** 单行内联文本：转义换行，避免注入新标题/新行。 */
+export function escapeInline(s) {
+    return String(s).replace(/\r?\n/g, ' ');
+}
+// ============= Contract entity → Markdown (T9.1) =============
+export function renderInterface(i) {
+    const rows = [
+        `##### ${i.id} · ${escapeInline(i.name)}（${i.method} ${i.path}）`,
+        '',
+        '**字段表**',
+        '',
+        '| 字段 | 类型 | 必填 | 说明 |',
+        '|------|------|------|------|',
+        ...[...i.request_fields ?? [], ...i.response_fields ?? []].map((f) => `| ${escapeTableCell(f.name)} | ${escapeTableCell(f.type)} | ${f.required ? '是' : '否'} | ${escapeTableCell(f.desc ?? '')} |`),
+        '',
+        '**成功示例**',
+        '',
+        '```http',
+        `${i.method} ${escapeFenceContent(i.path)}`,
+        '```',
+        '',
+        '**失败示例**',
+        '',
+        ...i.failure_examples.map((ex) => `- ${escapeInline(ex)}`),
+        '',
+        '**错误**',
+        '',
+        '| 条件 | 状态 | 说明 |',
+        '|------|------|------|',
+        ...i.errors.map((e) => `| ${escapeTableCell(e.condition)} | ${escapeTableCell(e.status)} | ${escapeTableCell(e.note ?? '')} |`),
+    ];
+    return rows.join('\n');
+}
+export function renderTable(t) {
+    return [
+        `##### ${t.id} · ${escapeInline(t.name)}`,
+        '',
+        '```sql',
+        escapeFenceContent(t.ddl),
+        '```',
+        '',
+        ...(t.migration ? ['**存量填充策略**', '', t.migration, ''] : []),
+        ...(t.rollback ? ['**回滚兼容**', '', t.rollback, ''] : []),
+    ].join('\n');
+}
+export function renderDecisions(decisions) {
+    if (decisions.length === 0)
+        return '';
+    return [
+        '**决策记录**',
+        '',
+        '| 决策 | 结论 |',
+        '|------|------|',
+        ...decisions.map((d) => `| ${escapeTableCell(d.id)} | ${escapeTableCell(d.text)} |`),
+    ].join('\n');
+}
+export function renderEntities(entities) {
+    const parts = [];
+    for (const i of entities.interfaces)
+        parts.push(renderInterface(i));
+    for (const t of entities.tables)
+        parts.push(renderTable(t));
+    const decisionsMd = renderDecisions(entities.decisions);
+    if (decisionsMd)
+        parts.push(decisionsMd);
+    return parts.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. */
+export function stripReviewNotes(text) {
+    return text.replace(/<!--\s*review-fix[\s\S]*?-->/g, '').replace(/\n{3,}/g, '\n\n').trim();
+}
+/**
+ * 从章节叙述中剥离内嵌的**契约实体 JSON 块**（```json {"entities": {...}} ```）。
+ * 这些块是 Agent 写给引擎提取的机器中间格式（map 提示词要求 kind=entity|mixed 要点产出），
+ * 引擎已把其中实体提取进 entities.json，并在文档末尾「契约实体」章节渲染为人类可读的表格。
+ * 最终 document.md 不应再出现原始 JSON——否则读者看到看不懂的 `decisions`/`interfaces` 结构。
+ *
+ * 判定：JSON 可解析且按 Entities schema 解析成功（含 interfaces/tables/decisions 任一非空）
+ * 才剥离；无法解析的块（叙述中的示例 JSON）原样保留，避免误删正文。
+ */
+export function stripEntityJsonBlocks(text) {
+    const jsonBlockRe = /```json\s*([\s\S]*?)```/g;
+    const parts = [];
+    let last = 0;
+    let m;
+    while ((m = jsonBlockRe.exec(text)) !== null) {
+        parts.push(text.slice(last, m.index));
+        let isEntityBlock = false;
+        try {
+            const parsed = parseEntities(JSON.parse(m[1]));
+            isEntityBlock = (parsed.interfaces?.length ?? 0) + (parsed.tables?.length ?? 0) + (parsed.decisions?.length ?? 0) > 0;
+        }
+        catch {
+            isEntityBlock = false;
+        }
+        if (!isEntityBlock)
+            parts.push(m[0]);
+        last = m.index + m[0].length;
+    }
+    parts.push(text.slice(last));
+    return parts.join('').replace(/\n{3,}/g, '\n\n').trim();
+}
+/**
+ * 剥离章节叙述首行的**冗余 H1 标题**：叙述以 `# <章节标题>` 开头（Agent 生成正文时习惯性地
+ * 重复了大纲章节标题），而 renderDocument 已为每章输出 `## <title>`——二者叠加造成标题重复。
+ * 仅当首行非空是 H1 且其内容与章节标题 trim 后一致时才剥离，避免误删正文中的真实内容。
+ */
+export function stripLeadingTitle(text, chapterTitle) {
+    const trimmed = text.trim();
+    const firstLine = trimmed.split('\n', 1)[0] ?? '';
+    const m = /^#\s+(.*)$/.exec(firstLine.trim());
+    if (!m)
+        return text;
+    if (m[1].trim() !== chapterTitle.trim())
+        return text;
+    // 去掉首行后，剩余部分（去掉紧邻的空行）即为叙述正文。
+    const rest = trimmed.slice(firstLine.length).replace(/^\n+/, '');
+    return rest;
+}
+export function renderDocument(input) {
+    const { outline, entities, narratives, profile, appendixAntiAI } = input;
+    const body = [`# 方案文档：${escapeInline(outline.profile)}`, ''];
+    for (const ch of outline.chapters) {
+        body.push(`## ${escapeInline(ch.title)}`, '');
+        // 依次净化：剥内嵌契约 JSON 块（机器中间格式）→ 剥与章节标题重复的首行 H1 → 剥引擎修复注记。
+        const narrative = stripLeadingTitle(stripEntityJsonBlocks(stripReviewNotes(narratives.get(ch.id) ?? '')), ch.title);
+        if (narrative.trim())
+            body.push(narrative.trim(), '');
+    }
+    // Contract entities: append to the chapters that reference them (simplified: append in a
+    // final "契约" section, since entities are cross-chapter).
+    const contractMd = renderEntities(entities);
+    if (contractMd.trim()) {
+        body.push('---', '', '## 契约实体', '', contractMd, '');
+    }
+    // 产物溯源附录 (borrowed from approval · appendix A): each chapter's data source.
+    body.push('---', '', '## 附录 A: 产物溯源', '');
+    body.push('| 章节 | 数据来源 | 处理方式 |');
+    body.push('|------|---------|---------|');
+    for (const ch of outline.chapters) {
+        body.push(`| ${escapeTableCell(ch.title)} | 输入素材 / 项目规约 / 大纲要点 | LLM 生成 + 引擎校验 |`);
+    }
+    body.push('', '');
+    // 附录 B/C: rendered from profile.appendices (decision: deterministic templates, §7.3).
+    const appendices = profile?.appendices ?? [];
+    if (appendices.includes('anti-ai')) {
+        body.push('---', '', renderAppendixAntiAI(appendixAntiAI), '');
+    }
+    if (appendices.includes('handoff')) {
+        body.push('---', '', renderAppendixHandoff(), '');
+    }
+    return body.join('\n').replace(/\n{3,}/g, '\n\n').trim() + '\n';
+}
+// ============= 附录 B/C（§7.3 确定性渲染） =============
+/** 附录 B · 去AI味自检（frontend-dev-guide §十一 → README §1.6 五维表）。 */
+export function renderAppendixAntiAI(content) {
+    const items = (content ?? '').trim();
+    const table = [
+        '## 附录 B: 去AI味自检',
+        '',
+        '> 每份交付末尾必须附「去AI味自检」，至少 3 条；缺一视为交付不完整（README §1.6）。',
+        '',
+        '| 维度 | 自检问题 | AI 味反例 |',
+        '|------|---------|----------|',
+        '| 不做决策 | 明确说了「不做什么」？ | 只列功能清单 |',
+        '| 数字具体 | 指标/约束具体到数字？ | 「提升体验」 |',
+        '| 竞品立场 | 与竞品差异有一句话立场？ | 「借鉴头部最佳实践」 |',
+        '| 此刻合理性 | 为什么现在做？不做会怎样？ | 不解释时机 |',
+        '| 优先级倾斜 | P0/P1 有倾斜逻辑？ | 全功能同等权重 |',
+        '',
+        items
+            ? items
+            : '> （自检条目由生成流程填充，至少 3 条；缺失将触发引擎 warning）',
+        '',
+    ];
+    return table.join('\n');
+}
+/** 附录 C · 下游交付衔接（frontend-dev-guide §八 → README §1.5 矩阵 + 三步）。 */
+export function renderAppendixHandoff() {
+    const matrix = [
+        '## 附录 C: 下游交付衔接',
+        '',
+        '| 下游角色 | 交付物 | 对方需要的核心信息 | 常见退货原因 |',
+        '|---------|--------|------------------|-------------|',
+        '| 后端 | 接口对接文档/契约 | 请求/响应/错误码约定、时序、分页排序约定 | 字段名与后端对不上、错误处理各写各的 |',
+        '| QA | 自测报告/测试范围 | 已测/未测项、环境地址、Mock 说明、已知问题 | 无自测记录、环境缺数据 |',
+        '| UI 设计师 | 还原实现（可访问预览） | 各断点/状态实现效果、偏差清单及原因 | 偏差无说明，被当 bug 打回 |',
+        '| DevOps | 构建产物/部署配置 | 环境变量清单、构建命令、SPA 路由回退、缓存策略 | 部署后白屏 404 |',
+        '',
+        '**交付动作三步**：',
+        '',
+        '1. **交前核对**：核心链路自测 + 契约确认 + 预览可访问。',
+        '2. **交底说明**：测什么 / 不测什么 / 已知问题。',
+        '3. **交后跟进**：Bug 24h 分级响应、首周每日巡检。',
+        '',
+    ];
+    return matrix.join('\n');
+}
+// ============= HTML (T9.3) =============
+export async function renderHtml(markdown, title = '方案文档') {
+    const bodyHtml = await marked.parse(markdown);
+    const hasMermaid = bodyHtml.includes('class="language-mermaid"') || bodyHtml.includes('mermaid');
+    const mermaidScript = hasMermaid
+        ? '<script type="module">\nimport mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";\nmermaid.initialize({ startOnLoad: true });\n</script>'
+        : '';
+    const safeTitle = escapeHtml(title);
+    return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${safeTitle}</title>
+<style>body{max-width:920px;margin:0 auto;padding:2rem;font-family:system-ui,sans-serif;line-height:1.65}table{border-collapse:collapse;width:100%}th,td{border:1px solid #ddd;padding:.4rem}pre{background:#f6f8fa;padding:1rem;overflow-x:auto}</style>
+</head>
+<body><h1>${safeTitle}</h1><article>${bodyHtml}</article>${mermaidScript}</body></html>`;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Document Engine — Pass 3 AI review (decision 9 · target + max_rounds + part_hashes).
+ *
+ * Fresh-context reviewer (separate from generator) produces findings with a `target`
+ * (entity|narrative|mixed). Findings apply by target; review-result is validated against
+ * part_hashes (post-review tamper detection) and max_rounds (infinite-loop guard).
+ */
+import { ReviewResult, ReviewFinding, Outline } from './schemas.js';
+import type { DocumentLLM } from './llm.js';
+export declare const AI_REVIEW_CHECKLIST: readonly ["R1 跨章命名一致", "R2 决策落地", "R3 实体↔正文", "R4 深度均衡", "R5 交叉引用稳定", "R6 图文一致", "R7 契约完整", "R8 枚举闭合", "R9 分支闭合", "R10 UI↔API 对齐", "R11 场景一致", "R12 stub 清除", "R13 结论一致", "R14 大纲要点覆盖"];
+export interface ReviewPacket {
+    schema: 'specflow.document.review-packet/v1';
+    change: string;
+    outline: Outline;
+    chapters: Map<string, string>;
+    checklist: readonly string[];
+    /** decision 8/9 · P1-B: concrete narrative/mixed points the reviewer must verify (semantic channel). */
+    semanticChecklist: Array<{
+        chapter: string;
+        pointId: string;
+        text: string;
+    }>;
+    /** Previous round's findings (decision 9 · closed loop): the reviewer must verify each was
+     *  addressed via the `<!-- review-fix -->` note in the chapter and not re-report fixed ones. */
+    prevFindings: ReviewFinding[];
+}
+export declare function buildReviewPacket(workRoot: string, change: string, outline: Outline, prevFindings?: ReviewFinding[], 
+/** 内存态章节覆盖（P2）：persist=false 时磁盘无章节文件，传 narrativeMap 让评审者
+ *  看到真实内容而非空串；缺省时回退读磁盘。 */
+narratives?: Map<string, string>): Promise<ReviewPacket>;
+export declare function reviewWithAgent(llm: DocumentLLM, packet: ReviewPacket, prompt?: string): Promise<ReviewResult>;
+/**
+ * 应用待修复的 findings。闭环语义（decision 9）：
+ *  - status==='open'（默认）→ 尚未解决，需要应用修复（追加 fix note / 重填实体）。
+ *  - status==='fixed'  → 评审者已确认上一轮注记生效，仅作闭环核对记账，不再应用。
+ *  - status==='waived' → 豁免，不应用。
+ * 同一 finding 可能跨轮被回显，按 id 去重避免注记/修复重复累积。
+ */
+export declare function applyFindings(workRoot: string, findings: ReviewFinding[], apply: (finding: ReviewFinding) => Promise<void>, appliedIds?: Set<string>): Promise<void>;
+export declare function sha256(content: string): string;
+export declare function computePartHashes(workRoot: string, chapterIds: string[]): Promise<{
+    id: string;
+    sha256: string;
+}[]>;
+export interface ReviewCheckResult {
+    ok: boolean;
+    diagnostics: Array<{
+        code: string;
+        severity: 'error' | 'warning';
+        message: string;
+    }>;
+}
+export declare function checkReviewResult(workRoot: string, review: ReviewResult, outline: Outline, currentHashesParam?: Array<{
+    id: string;
+    sha256: string;
+}>): Promise<ReviewCheckResult>;
+export declare function writeReviewResult(workRoot: string, review: ReviewResult): Promise<void>;