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

package/dist/core/document/engine.js

@@ -0,0 +1,722 @@
+/**
+ * Document Engine — unified orchestration entry (T11.2).
+ *
+ * runDocument wires Pass 0.5 → 1 → 2 → 3 → 4 + gates. Consumers inject the LLM,
+ * the work root, and the input. An `outlineOnly` mode stops after Pass 1 (for user gate).
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { estimateTokens } from './llm.js';
+import { compressInputs } from './input-digest.js';
+import { generateOutline, lintOutline, outlineHasErrors, freezeOutline, readOutline } from './outline.js';
+import { expandProfile } from './profiles.js';
+import { generateDigest, extractConstraintList, lintDigest, deterministicDigest, recordDigestSources, affectedDownstream } from './digests.js';
+import { fillChapter, fillOnce, shouldFillOnce } from './map.js';
+import { buildReviewPacket, reviewWithAgent, checkReviewResult, writeReviewResult, computePartHashes, applyFindings, sha256 } from './review.js';
+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 { checkStructuredCoverage } from './coverage.js';
+import { resolveProjectConventionPaths } from '../project-conventions.js';
+import { extractContracts, EMPTY_CONTRACTS } from './extract.js';
+const DEFAULT_MAX_ROUNDS = 3;
+const OUTLINE_MAX_CONFIRM_ROUNDS = 2;
+export async function runDocument(options) {
+    const { llm, workRoot, profile, library, inputs, inputFeatures, change } = options;
+    const maxRounds = options.maxRounds ?? DEFAULT_MAX_ROUNDS;
+    const persist = options.persist ?? true;
+    const paths = resolvePaths(workRoot);
+    // --- Pass 0.5: input compression (T4) ---
+    const inputDigest = await compressInputs(workRoot, inputs, llm);
+    // --- Pass 0.5b: deterministic contract extraction (grounding P0, engine-level) ---
+    // 显式注入的提取结果优先（测试/宿主）；否则从 projectRoot + 输入文件扫描 OpenAPI/proto/DDL。
+    const extractedContracts = options.extractedContracts
+        ?? (options.projectRoot
+            ? await extractContracts(inputs, options.projectRoot)
+            : EMPTY_CONTRACTS);
+    // --- Pass 1: outline (T5) with user confirmation gate (T5.4) ---
+    const expanded = expandProfile(profile, library, inputFeatures);
+    if (expanded.chapters.length === 0) {
+        return { ok: false, stage: 'profile-expand', diagnostics: expanded.diagnostics.map((d) => ({ gate: 'profile', code: d.code, severity: d.severity, message: d.message })) };
+    }
+    let outline;
+    let confirmed = false;
+    const confirmer = options.outlineConfirmer;
+    for (let round = 0; round < OUTLINE_MAX_CONFIRM_ROUNDS; round++) {
+        outline = await generateOutline(llm, { profile, inputDigest, prompt: options.outlinePrompt, extractedContracts });
+        const outlineDiags = lintOutline(outline, profile);
+        if (outlineHasErrors(outlineDiags)) {
+            return { ok: false, stage: 'outline-lint', diagnostics: outlineDiags.map((d) => ({ gate: 'outline', code: d.code, severity: d.severity, message: d.message, chapter: d.chapter })) };
+        }
+        // User confirmation gate: if a confirmer is provided, ask; reject → regenerate.
+        if (confirmer) {
+            if (await confirmer(outline)) {
+                confirmed = true;
+                break;
+            }
+            // rejected → loop regenerates
+        }
+        else {
+            confirmed = true; // non-interactive / test path: auto-accept
+            break;
+        }
+    }
+    if (!confirmed || !outline) {
+        return { ok: false, stage: 'outline-unconfirmed', outline: outline ?? undefined, diagnostics: [{ gate: 'outline', code: 'outline_rejected', severity: 'error', message: 'Outline rejected by user after max confirm rounds' }] };
+    }
+    if (persist)
+        await freezeOutline(workRoot, outline);
+    if (options.outlineOnly) {
+        return { ok: true, stage: 'outline-only', outline, diagnostics: [] };
+    }
+    // --- Chapter-by-chapter fill (Pass 2, T6) with real dependency digests (T7) ---
+    const chapterById = library;
+    const ctx = { outline, digests: new Map(), upstreamEntities: { interfaces: [], tables: [], decisions: [] }, workRoot, chapterById, contextCache: new Map() };
+    // Process in DAG order: outline.chapters is already topological from expandProfile.
+    const narrativeMap = new Map();
+    const entityMap = new Map();
+    const tokenMap = new Map();
+    const budgetMap = new Map();
+    const allEntities = { interfaces: [], tables: [], decisions: [] };
+    const useFillOnce = await shouldFillOnce(outline, ctx);
+    if (useFillOnce) {
+        const result = await fillOnce(llm, outline, ctx);
+        if (!result.ok) {
+            // Honest degradation: fill_once failed → fall back to per-chapter fill (decision 9).
+            const fillErr = await fillAllChapters(outline, ctx, narrativeMap, entityMap, tokenMap, budgetMap, allEntities, llm, persist, paths, options.incremental);
+            if (fillErr.length > 0) {
+                return { ok: false, stage: 'fill', outline, diagnostics: fillErr };
+            }
+        }
+        else {
+            for (const f of result.chapters) {
+                narrativeMap.set(f.chapterId, f.narrative);
+                entityMap.set(f.chapterId, f.entities);
+                tokenMap.set(f.chapterId, f.tokens);
+                budgetMap.set(f.chapterId, chapterById.get(f.chapterId)?.output_budget_tokens);
+                allEntities.interfaces.push(...f.entities.interfaces);
+                allEntities.tables.push(...f.entities.tables);
+                allEntities.decisions.push(...f.entities.decisions);
+                if (persist) {
+                    await fs.mkdir(paths.chaptersDir, { recursive: true });
+                    await fs.writeFile(chapterPath(paths.workRoot, f.chapterId), f.narrative, 'utf-8');
+                }
+            }
+        }
+    }
+    else {
+        const fillErr = await fillAllChapters(outline, ctx, narrativeMap, entityMap, tokenMap, budgetMap, allEntities, llm, persist, paths, options.incremental);
+        if (fillErr.length > 0) {
+            return { ok: false, stage: 'fill', outline, diagnostics: fillErr };
+        }
+    }
+    // --- Pass 3: AI review with real fix→re-review loop (T8, decision 9) ---
+    if (persist)
+        await fs.writeFile(paths.entities, JSON.stringify(allEntities, null, 2), 'utf-8');
+    let review;
+    let reviewDiags = [];
+    if (!options.skipReview) {
+        let prevFindings = [];
+        // 跨轮去重：同一 finding 只应用一次（open → 应用后标记；fixed/waived 不再应用）。
+        const appliedFindingIds = new Set();
+        // 跨轮累积修复章节：post_review_repairs 必须记录所有轮次的 engine 改动，
+        // 否则后一轮（无新修复）会用空集合覆盖前一轮的 tamper 豁免记录。
+        const touchedChapters = new Set();
+        for (let round = 0; round < maxRounds; round++) {
+            const packet = await buildReviewPacket(workRoot, change, outline, prevFindings, narrativeMap);
+            const candidate = await reviewWithAgent(llm, packet, options.reviewPrompt);
+            // Authoritative snapshot of what the reviewer actually saw: the LLM cannot compute sha256
+            // reliably, so the engine replaces the reviewer-reported hashes with its own computation
+            // taken at review time. This snapshot becomes the tamper baseline — it is NOT refreshed
+            // after repairs (that made the check vacuous).
+            // persist=false 时磁盘无章节文件 → 基于内存 narrativeMap 计算（P2：否则篡改校验形同虚设）。
+            if (persist) {
+                candidate.part_hashes = await computePartHashes(workRoot, outline.chapters.map((c) => c.id));
+            }
+            else {
+                candidate.part_hashes = [...narrativeMap.entries()].map(([id, content]) => ({ id, sha256: sha256(content) }));
+            }
+            // Apply findings by target:
+            //   narrative → append fix note to chapters/<id>.md
+            //   entity   → regenerate the affected chapter (real entity repair via re-fill)
+            const entityRefills = [];
+            await applyFindings(workRoot, candidate.findings, async (finding) => {
+                const target = finding.target ?? 'narrative';
+                if (target === 'entity' || target === 'mixed') {
+                    if (finding.chapter)
+                        entityRefills.push(finding.chapter);
+                }
+                if (target === 'narrative' || target === 'mixed') {
+                    const chId = finding.chapter;
+                    if (chId) {
+                        touchedChapters.add(chId);
+                        const existing = narrativeMap.get(chId) ?? '';
+                        // Note format: message INSIDE the HTML comment so `stripReviewNotes` can remove the
+                        // whole note from the final render; the audit trail stays in chapters/<id>.md and
+                        // review-result.json. message/id 可能含 `-->`，先净化避免注释提前闭合注入 HTML。
+                        const safeId = String(finding.id).replace(/--/g, '—');
+                        const safeMsg = String(finding.message).replace(/--/g, '—').replace(/<!--/g, '〈!--');
+                        narrativeMap.set(chId, `${existing}\n\n<!-- review-fix ${safeId}: ${safeMsg} -->`);
+                        if (persist) {
+                            await fs.mkdir(paths.chaptersDir, { recursive: true });
+                            await fs.writeFile(chapterPath(paths.workRoot, chId), narrativeMap.get(chId), 'utf-8');
+                        }
+                    }
+                }
+            }, appliedFindingIds);
+            // Entity targets: re-fill the affected chapters so contract entities are regenerated (real fix).
+            for (const chId of new Set(entityRefills)) {
+                const ch = outline.chapters.find((c) => c.id === chId);
+                if (!ch)
+                    continue;
+                touchedChapters.add(ch.id);
+                ctx.upstreamEntities = allEntities;
+                ctx.digests = await buildDigestsFor(ch, ctx.chapterById, outline, narrativeMap, allEntities, llm);
+                const result = await fillChapter(llm, ch, ctx, ctx.chapterById.get(ch.id)?.output_budget_tokens);
+                if (result.ok && result.fill) {
+                    narrativeMap.set(ch.id, result.fill.narrative);
+                    tokenMap.set(ch.id, result.fill.tokens);
+                    // 按「章节所有权」整体替换该章节的实体（P2）：先移除该章旧实体（含 id 漂移的陈旧实体），
+                    // 再合并新实体，避免全量按 id 过滤时误删他章副本/残留已改名实体。
+                    // 注意顺序：先读旧实体（entityMap 当前值）用于移除，再写新实体。
+                    const oldEntities = entityMap.get(ch.id);
+                    removeChapterEntities(allEntities, oldEntities);
+                    mergeEntities(allEntities, result.fill.entities);
+                    entityMap.set(ch.id, result.fill.entities);
+                    if (persist) {
+                        await fs.mkdir(paths.chaptersDir, { recursive: true });
+                        await fs.writeFile(chapterPath(paths.workRoot, ch.id), result.fill.narrative, 'utf-8');
+                        await fs.writeFile(paths.entities, JSON.stringify(allEntities, null, 2), 'utf-8');
+                    }
+                }
+                else {
+                    // refill 失败（P2）：记录诊断而非静默吞掉，避免问题只在模糊的 review_finding_open 中暴露。
+                    reviewDiags.push({
+                        gate: 'review',
+                        code: 'entity_refill_failed',
+                        severity: 'warning',
+                        message: `Review entity refill for chapter "${ch.id}" failed: ${result.error ?? 'unknown error'}`,
+                        chapter: ch.id,
+                    });
+                }
+            }
+            // Record which chapters the ENGINE changed after the review snapshot (repairs are
+            // engine-sanctioned, not external tampering) so the tamper check can distinguish the two.
+            candidate.post_review_repairs = [...touchedChapters].map((chapter) => ({
+                chapter,
+                at: new Date().toISOString(),
+            }));
+            // 当前哈希：persist 时读磁盘，否则用内存 narrativeMap（P2：与 review 时快照同源）。
+            const currentHashes = persist
+                ? await computePartHashes(workRoot, outline.chapters.map((c) => c.id))
+                : [...narrativeMap.entries()].map(([id, content]) => ({ id, sha256: sha256(content) }));
+            const check = await checkReviewResult(workRoot, candidate, outline, currentHashes);
+            review = candidate;
+            reviewDiags = check.diagnostics.map((d) => ({ gate: 'review', code: d.code, severity: d.severity, message: d.message }));
+            if (check.ok) {
+                break;
+            }
+            // Feed this round's findings to the next round so the reviewer verifies the applied
+            // fix notes instead of re-reporting the same issues (closed loop, decision 9).
+            prevFindings = candidate.findings;
+        }
+    }
+    if (review && persist) {
+        await writeReviewResult(workRoot, review);
+    }
+    // --- Pass 4: render (T9) ---
+    const appendixAntiAI = await readAppendix(workRoot, 'anti-ai');
+    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap, profile, appendixAntiAI });
+    if (persist)
+        await fs.writeFile(paths.documentMd, documentMd, 'utf-8');
+    let documentHtml;
+    if (options.renderHtmlOutput !== false) {
+        documentHtml = await renderHtml(documentMd, change);
+        if (persist)
+            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,
+        chapterEntities: entityMap,
+        chapterTokens: tokenMap,
+        chapterBudget: budgetMap,
+        entities: allEntities,
+        review,
+        workRoot,
+        library,
+        repos: synthRepos,
+        // 审查篡改校验的当前哈希（P2）：persist=false 时磁盘无章节，传最终内存快照。
+        currentHashes: review && persist
+            ? await computePartHashes(workRoot, outline.chapters.map((c) => c.id))
+            : review
+                ? [...narrativeMap.entries()].map(([id, content]) => ({ id, sha256: sha256(content) }))
+                : undefined,
+    });
+    // 附录覆盖校验（§7.3）：anti-ai 自检条目为空/不足 → warning。
+    const appendixDiags = appendixDiagnostics(profile, appendixAntiAI);
+    let totalTokens = 0;
+    for (const t of tokenMap.values())
+        totalTokens += t;
+    return {
+        ok: gates.ok,
+        stage: gates.ok ? 'done' : 'gates-fail',
+        outline,
+        documentMd,
+        documentHtml,
+        diagnostics: [...reviewDiags, ...appendixDiags, ...gates.diagnostics],
+        tokenEstimate: totalTokens,
+    };
+}
+/** Read an LLM-written appendix file (appendices/<name>.md); missing → empty string. */
+async function readAppendix(workRoot, name) {
+    try {
+        return await fs.readFile(join(workRoot, 'appendices', `${name}.md`), 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+/** 附录覆盖校验（README §7.3）：profile.appendices 含 anti-ai 但自检条目为空/不足 → warning。 */
+export function appendixDiagnostics(profile, antiAiContent) {
+    if (!profile.appendices.includes('anti-ai'))
+        return [];
+    const items = antiAiContent
+        .trim()
+        .split('\n')
+        .filter((l) => l.trim().length > 0 && !l.trim().startsWith('#'))
+        .length;
+    if (items === 0) {
+        return [{ gate: 'appendix', code: 'anti_ai_empty', severity: 'warning', message: '附录 B 去AI味自检条目为空（profile.appendices 含 anti-ai，需 ≥3 条）' }];
+    }
+    if (items < 3) {
+        return [{ gate: 'appendix', code: 'anti_ai_too_few', severity: 'warning', message: `附录 B 去AI味自检仅 ${items} 条（需 ≥3 条）` }];
+    }
+    return [];
+}
+/**
+ * Build dependency digests for a chapter's direct deps (decisions 2 + 8).
+ * For each dep chapter, derive its constraint list (points/entities/decisions it must preserve),
+ * generate a bounded LLM summary carrying those constraints, then bidirectional lint:
+ *   - forward: digest ids must exist in source entities
+ *   - reverse: every constraint item must appear in the digest
+ * On lint error, fall back to the deterministic entity-registry digest (honest degradation).
+ */
+async function buildDigestsFor(chapter, library, outline, narrativeMap, allEntities, llm) {
+    const digests = new Map();
+    const chapterById = new Map(outline.chapters.map((ch) => [ch.id, ch]));
+    const comp = library.get(chapter.id);
+    for (const dep of comp?.depends_on ?? []) {
+        const depChapter = chapterById.get(dep);
+        if (!depChapter)
+            continue;
+        const source = narrativeMap.get(dep) ?? '';
+        const constraints = extractConstraintList(depChapter, allEntities);
+        const knownIds = new Set([
+            ...allEntities.interfaces.map((i) => i.id),
+            ...allEntities.tables.map((t) => t.id),
+            ...allEntities.decisions.map((d) => d.id),
+        ]);
+        let digest = '';
+        if (source.trim().length > 0) {
+            try {
+                digest = await generateDigest(llm, {
+                    chapterId: dep,
+                    chapterTitle: depChapter.title,
+                    source,
+                    constraints,
+                });
+            }
+            catch {
+                digest = ''; // LLM failure → fall through to deterministic registry
+            }
+        }
+        // Bidirectional lint; on error fall back to deterministic registry.
+        const lint = lintDigest(digest || '', constraints, knownIds);
+        if (digest && lint.every((d) => d.severity !== 'error')) {
+            digests.set(dep, digest);
+        }
+        else {
+            const ids = constraints.filter((c) => c.kind === 'entity').map((c) => c.id);
+            digests.set(dep, deterministicDigest(allEntities, ids));
+        }
+    }
+    return digests;
+}
+/** 按 id 去重合并契约实体（P2）：同一 id 保留后写者（最新版本），避免共享实体重复渲染。 */
+function mergeEntities(target, incoming) {
+    const interfaceIds = new Set(target.interfaces.map((i) => i.id));
+    for (const it of incoming.interfaces) {
+        if (interfaceIds.has(it.id)) {
+            target.interfaces = target.interfaces.map((x) => (x.id === it.id ? it : x));
+        }
+        else {
+            interfaceIds.add(it.id);
+            target.interfaces.push(it);
+        }
+    }
+    const tableIds = new Set(target.tables.map((t) => t.id));
+    for (const tb of incoming.tables) {
+        if (tableIds.has(tb.id)) {
+            target.tables = target.tables.map((x) => (x.id === tb.id ? tb : x));
+        }
+        else {
+            tableIds.add(tb.id);
+            target.tables.push(tb);
+        }
+    }
+    const decisionIds = new Set(target.decisions.map((d) => d.id));
+    for (const d of incoming.decisions) {
+        if (decisionIds.has(d.id)) {
+            target.decisions = target.decisions.map((x) => (x.id === d.id ? d : x));
+        }
+        else {
+            decisionIds.add(d.id);
+            target.decisions.push(d);
+        }
+    }
+}
+/** 从目标集合中移除某章节贡献的全部实体（按章节所有权，P2）。 */
+function removeChapterEntities(target, chapterEntities) {
+    if (!chapterEntities)
+        return;
+    const ids = new Set([
+        ...chapterEntities.interfaces.map((i) => i.id),
+        ...chapterEntities.tables.map((t) => t.id),
+        ...chapterEntities.decisions.map((d) => d.id),
+    ]);
+    target.interfaces = target.interfaces.filter((i) => !ids.has(i.id));
+    target.tables = target.tables.filter((t) => !ids.has(t.id));
+    target.decisions = target.decisions.filter((d) => !ids.has(d.id));
+}
+/** 从章节叙述提取其内嵌的契约实体（```json 块，与 map.ts 语义一致）。 */
+function extractChapterEntities(content) {
+    const out = { interfaces: [], tables: [], decisions: [] };
+    const jsonBlockRe = /```json\s*([\s\S]*?)```/g;
+    let m;
+    while ((m = jsonBlockRe.exec(content)) !== null) {
+        try {
+            const parsed = parseEntitiesLenient(JSON.parse(m[1]));
+            mergeEntities(out, parsed);
+        }
+        catch {
+            // 非实体块（叙述示例）→ 忽略
+        }
+    }
+    return out;
+}
+/**
+ * Fill all chapters in DAG order (real dependency digests + per-chapter budget).
+ * Returns [] on success, or a non-empty error diagnostic array on failure.
+ */
+async function fillAllChapters(outline, ctx, narrativeMap, entityMap, tokenMap, budgetMap, allEntities, llm, persist, paths, incremental) {
+    // Compute invalidation set (decision 9): which chapters' digests reference the changed entities.
+    let refillSet;
+    if (incremental) {
+        const changedChapterId = incremental.changedChapterId;
+        const changedEntityIds = incremental.changedEntityIds ?? [];
+        if (changedChapterId || changedEntityIds.length > 0) {
+            // 失效集必须基于「已知实体集合」计算，而不是入口处的空 allEntities（P2）：
+            // 用 outline 冻结的实体注册表作为 known ids，否则 affectedDownstream 恒返回空、
+            // 增量失效静默 no-op。实体注册表在 Pass 1 已冻结，是增量场景下唯一可靠的已知集。
+            const registry = {
+                interfaces: outline.entities
+                    .filter((e) => /^I\d+$/.test(e.id))
+                    .map((e) => ({ id: e.id, name: e.frozen, method: 'GET', path: '/', errors: [], failure_examples: [] })),
+                tables: outline.entities
+                    .filter((e) => /^T\d+$/.test(e.id))
+                    .map((e) => ({ id: e.id, name: e.frozen, ddl: '' })),
+                decisions: [],
+            };
+            const sources = outline.chapters.map((ch) => recordDigestSources(ch, registry));
+            const affected = affectedDownstream(changedChapterId ?? '', changedEntityIds, sources);
+            refillSet = new Set(affected);
+        }
+    }
+    for (const ch of outline.chapters) {
+        // Incremental skip (decision 9): reuse cache only for chapters that (a) are not in the
+        // invalidation set, (b) are not the change source, and (c) produce NO contract entities —
+        // entity-producing chapters always refill to avoid entity-state divergence across maps.
+        const producesEntities = ch.points.some((p) => (p.kind === 'entity' || p.kind === 'mixed') && (p.references ?? []).length > 0);
+        if (refillSet && !refillSet.has(ch.id) && !(incremental?.changedChapterId === ch.id) && !producesEntities) {
+            if (persist) {
+                try {
+                    const cached = await fs.readFile(chapterPath(paths.workRoot, ch.id), 'utf-8');
+                    if (cached.trim().length > 0) {
+                        narrativeMap.set(ch.id, cached);
+                        tokenMap.set(ch.id, estimateTokens(cached));
+                        budgetMap.set(ch.id, ctx.chapterById.get(ch.id)?.output_budget_tokens);
+                        // 缓存复用的章节：把其上一轮产出的契约实体合并回 allEntities（P2），
+                        // 否则第 175 行用内存中的精简集合覆写 entities.json 会丢掉缓存章节的实体。
+                        const cachedEntities = extractChapterEntities(cached);
+                        mergeEntities(allEntities, cachedEntities);
+                        entityMap.set(ch.id, cachedEntities);
+                        continue;
+                    }
+                }
+                catch {
+                    // no cache → fall through to refill
+                }
+            }
+        }
+        // Real dependency digests (decision 2/8): for each direct dep, build a digest that carries
+        // the dep chapter's constraint list (entities/points it must preserve) via a bounded LLM
+        // summary, then bidirectional lint; fall back to deterministic registry on lint error.
+        ctx.upstreamEntities = allEntities;
+        ctx.digests = await buildDigestsFor(ch, ctx.chapterById, outline, narrativeMap, allEntities, llm);
+        const budget = ctx.chapterById.get(ch.id)?.output_budget_tokens;
+        const result = await fillChapter(llm, ch, ctx, budget);
+        if (!result.ok || !result.fill) {
+            return [{ gate: 'map', code: 'fill_failed', severity: 'error', message: result.error ?? `fill ${ch.id} failed`, chapter: ch.id }];
+        }
+        const fill = result.fill;
+        narrativeMap.set(ch.id, fill.narrative);
+        entityMap.set(ch.id, fill.entities);
+        tokenMap.set(ch.id, fill.tokens);
+        budgetMap.set(ch.id, budget);
+        // Merge entities for downstream digest/render（按 id 去重，P2：同一 id 保留新版本）。
+        mergeEntities(allEntities, fill.entities);
+        if (persist) {
+            await fs.mkdir(paths.chaptersDir, { recursive: true });
+            await fs.writeFile(chapterPath(paths.workRoot, ch.id), fill.narrative, 'utf-8');
+            await fs.writeFile(paths.entities, JSON.stringify(allEntities, null, 2), 'utf-8');
+        }
+    }
+    return [];
+}
+/** Map a scene profile to the project-convention topics it should read (approval-era: 项目约定 > guidance > LLM). */
+export function sceneTopics(profileId) {
+    switch (profileId) {
+        case '0to1':
+            return ['architecture', 'database', 'api', 'frontend'];
+        case 'frontend-0to1':
+            return ['frontend', 'api'];
+        case 'bugfix':
+            return ['database', 'api', 'frontend', 'architecture'];
+        case 'feature':
+            return ['api', 'database', 'frontend', 'architecture'];
+        case 'migration':
+            return ['frontend', 'api', 'database', 'architecture'];
+        case 'poc':
+            return ['frontend', 'api', 'database'];
+        default:
+            return [];
+    }
+}
+/** Emit the Agent-executable step list (no LLM call — the Agent's IDE model does the work). */
+export function planSteps(options) {
+    const { profile, library, inputFeatures, inputs, workRoot, projectRoot } = options;
+    const expanded = expandProfile(profile, library, inputFeatures);
+    const steps = [];
+    // Prep: read project conventions / IDE rules & skills (approval-era "项目约定 > guidance > LLM").
+    // The Agent MUST ground the document in the project's own conventions before generating —
+    // even when no convention files are found, it scans IDE skills/rules + guidance packs.
+    if (projectRoot) {
+        const topics = sceneTopics(profile.id);
+        const conventionFiles = [];
+        for (const topic of topics) {
+            conventionFiles.push(...resolveProjectConventionPaths({ projectRoot, topic: topic }));
+        }
+        const found = conventionFiles.length > 0
+            ? `解析到的规约文件：${conventionFiles.join('、')}`
+            : '未发现项目规约文件（config conventions 或中立文档），请扫描 IDE skills/rules（.cursor / .claude / .agents）与 guidance packs（skills/guidance-packs.yaml 等）';
+        steps.push({
+            id: 'conventions',
+            phase: 'prep',
+            title: '读取项目规约与 IDE 规则',
+            description: `生成前先读取项目规约（优先级：项目约定 > SpecFlow guidance > LLM）。${found}。` +
+                '将相关约束（数据库 DDL 约定、API 规范、前端规约、架构禁令）落实到后续章节；未发现时显式标注「未发现项目规约」。',
+            prompt: '.claude/specflow/prompts/document/outline/general.md',
+            inputFiles: conventionFiles,
+            outputFile: 'digests/conventions.md',
+            required: false,
+        });
+    }
+    // Prep: compress inputs into a digest (skip for single short description).
+    const multiInput = inputs.length > 1 || inputs.some((i) => i.content.length > 800);
+    if (multiInput) {
+        steps.push({
+            id: 'input-summary',
+            phase: 'prep',
+            title: '压缩输入为全局摘要',
+            description: '阅读全部输入（proposal/design/specs/code），产出紧凑摘要（保留实体候选与约束），写入 digests/input-summary.md。',
+            prompt: '.claude/specflow/prompts/document/outline/general.md',
+            inputFiles: inputs.map((i) => i.source),
+            outputFile: 'digests/input-summary.md',
+            required: true,
+        });
+    }
+    // Outline.
+    steps.push({
+        id: 'outline',
+        phase: 'outline',
+        title: '生成文档大纲',
+        description: `按 ${profile.id} 场景（必选章 ${profile.required.join('、')}）生成 outline.yaml：章节顺序 + 每章要点（kind/references）+ 实体注册表 + 决策。`,
+        prompt: '.claude/specflow/prompts/document/outline/general.md',
+        inputFiles: multiInput ? ['digests/input-summary.md'] : [],
+        outputFile: 'outline.yaml',
+        required: true,
+    });
+    // Fill each chapter.
+    for (const chId of expanded.chapters) {
+        steps.push({
+            id: `chapter:${chId}`,
+            phase: 'fill',
+            title: `填充章节 ${chId}`,
+            description: `按 outline.yaml 中 ${chId} 的要点填空，契约实体写入 entities.json（接口须含 failure_examples，表须含 ddl），叙述写入 chapters/${chId}.md。`,
+            prompt: `.claude/specflow/prompts/document/map/${chId}.md`,
+            inputFiles: ['outline.yaml'],
+            outputFile: `chapters/${chId}.md`,
+            required: true,
+        });
+    }
+    // Review (optional).
+    steps.push({
+        id: 'review',
+        phase: 'review',
+        title: 'AI 审查',
+        description: '独立审查全部章节，产出 review-result.json（findings + part_hashes，R14 覆盖核对）。',
+        prompt: '.claude/specflow/prompts/document/review/ai-review.md',
+        inputFiles: expanded.chapters.map((c) => `chapters/${c}.md`),
+        outputFile: 'review-result.json',
+        required: false,
+    });
+    // 附录（profile.appendices，§7.3）：anti-ai 需要 LLM 条目；handoff 为确定性模板，无需步骤。
+    if (profile.appendices.includes('anti-ai')) {
+        steps.push({
+            id: 'appendix:anti-ai',
+            phase: 'fill',
+            title: '填写去AI味自检条目（附录 B）',
+            description: '按五维自检表（不做决策/数字具体/竞品立场/此刻合理性/优先级倾斜）写至少 3 条自检条目，写入 appendices/anti-ai.md。缺失将触发 validate warning。',
+            prompt: '.claude/specflow/prompts/document/map/anti-ai.md',
+            inputFiles: expanded.chapters.map((c) => `chapters/${c}.md`),
+            outputFile: 'appendices/anti-ai.md',
+            required: true,
+        });
+    }
+    return { steps, chapters: expanded.chapters };
+}
+/** Read Agent-written artifacts from workRoot, validate (lint/coverage/zod) and render. No LLM. */
+export async function validateWork(options) {
+    const { profile, workRoot } = options;
+    const paths = resolvePaths(workRoot);
+    const diags = [];
+    // Read outline (readOutline handles both YAML and JSON).
+    let outline;
+    try {
+        outline = await readOutline(workRoot);
+    }
+    catch (e) {
+        return { ok: false, diagnostics: [{ gate: 'outline', code: 'outline_unreadable', severity: 'error', message: `Cannot read outline.yaml: ${e instanceof Error ? e.message : String(e)}` }] };
+    }
+    // Outline lint.
+    const outlineDiags = lintOutline(outline, profile);
+    diags.push(...outlineDiags.map((d) => ({ gate: 'outline', code: d.code, severity: d.severity, message: d.message, chapter: d.chapter })));
+    // Read chapters + entities.
+    const narrativeMap = new Map();
+    const entityMap = new Map();
+    const allEntities = { interfaces: [], tables: [], decisions: [] };
+    const tokenMap = new Map();
+    for (const ch of outline.chapters) {
+        try {
+            const content = await fs.readFile(chapterPath(paths.workRoot, ch.id), 'utf-8');
+            narrativeMap.set(ch.id, content);
+            tokenMap.set(ch.id, estimateTokens(content));
+            // 章节级实体归属：从章节内嵌 ```json 块提取该章贡献的契约实体，供结构化覆盖校验
+            // （与 map.ts 的提取语义一致；无法解析的块不影响叙述 lint）。
+            const chapterEntities = { interfaces: [], tables: [], decisions: [] };
+            const jsonBlockRe = /```json\s*([\s\S]*?)```/g;
+            let jm;
+            while ((jm = jsonBlockRe.exec(content)) !== null) {
+                try {
+                    const parsed = parseEntitiesLenient(JSON.parse(jm[1]));
+                    chapterEntities.interfaces.push(...parsed.interfaces);
+                    chapterEntities.tables.push(...parsed.tables);
+                    chapterEntities.decisions.push(...parsed.decisions);
+                }
+                catch {
+                    // 非实体块（叙述示例 JSON）→ 忽略
+                }
+            }
+            entityMap.set(ch.id, chapterEntities);
+        }
+        catch (e) {
+            diags.push({ gate: 'lint', code: 'chapter_missing', severity: 'error', message: `Missing chapter file ${ch.id}.md`, chapter: ch.id });
+        }
+    }
+    // entities.json.
+    try {
+        const raw = await fs.readFile(paths.entities, 'utf-8');
+        const parsed = parseEntitiesLenient(JSON.parse(raw));
+        allEntities.interfaces = parsed.interfaces;
+        allEntities.tables = parsed.tables;
+        allEntities.decisions = parsed.decisions;
+    }
+    catch (e) {
+        diags.push({ gate: 'entities', code: 'entities_unreadable', severity: 'warning', message: `entities.json unreadable or invalid: ${e instanceof Error ? e.message : String(e)}` });
+    }
+    // Narrative lint.
+    for (const [chId, narrative] of narrativeMap) {
+        for (const d of lintNarrative(chId, narrative)) {
+            diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: chId });
+        }
+    }
+    // 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.
+    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)
+    }
+    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 });
+            }
+        }
+    }
+    // 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 });
+    }
+    // 附录覆盖校验（§7.3）：anti-ai 自检条目为空/不足 → warning。
+    const appendixAntiAI = await readAppendix(workRoot, 'anti-ai');
+    diags.push(...appendixDiagnostics(profile, appendixAntiAI));
+    const hasError = diags.some((d) => d.severity === 'error');
+    if (hasError) {
+        return { ok: false, diagnostics: diags };
+    }
+    // Render (appendices driven by profile.appendices).
+    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap, profile, appendixAntiAI });
+    await fs.writeFile(paths.documentMd, documentMd, 'utf-8');
+    let documentHtml;
+    if (options.renderHtmlOutput !== false) {
+        documentHtml = await renderHtml(documentMd, outline.profile);
+        await fs.writeFile(paths.documentHtml, documentHtml, 'utf-8');
+    }
+    return { ok: true, diagnostics: diags, documentMd, documentHtml };
+}
+export { expandProfile };