@gordon.gan/specflow 1.8.0-alpha → 1.8.1-beta

package/dist/core/document/chapters.js

@@ -8,13 +8,28 @@ import yaml from 'js-yaml';
 import { parseChapterComponent } from './schemas.js';
 const DEFAULT_CHAPTERS_DIR = join(process.cwd(), 'templates', 'document', 'chapters');
 export async function loadChapterLibrary(dir = DEFAULT_CHAPTERS_DIR) {
-    const entries = await fs.readdir(dir);
+    const entries = await fs.readdir(dir, { withFileTypes: true });
     const lib = new Map();
-    for (const file of entries) {
+    const seen = new Set();
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue; // 跳过目录（P2：避免 EISDIR）
+        const file = entry.name;
         if (!file.endsWith('.yaml') && !file.endsWith('.yml'))
             continue;
-        const raw = yaml.load(await fs.readFile(join(dir, file), 'utf-8'));
+        let raw;
+        try {
+            raw = yaml.load(await fs.readFile(join(dir, file), 'utf-8'));
+        }
+        catch (e) {
+            throw new Error(`Failed to parse chapter file ${file}: ${e instanceof Error ? e.message : String(e)}`);
+        }
         const ch = parseChapterComponent(raw);
+        // 重复 id 检测（P2）：Map.set 静默覆盖且覆盖顺序依赖目录枚举，id 碰撞会静默改变整条流水线。
+        if (seen.has(ch.id)) {
+            throw new Error(`Duplicate chapter id "${ch.id}" (in ${file}); chapter ids must be unique across templates/document/chapters/`);
+        }
+        seen.add(ch.id);
         lib.set(ch.id, ch);
     }
     return lib;

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

@@ -10,7 +10,6 @@
  */
 import { OutlineChapter, ConstraintItem, Entities } from './schemas.js';
 import type { DocumentLLM } from './llm.js';
-export declare const DIGEST_BUDGET_TOKENS = 1000;
 export declare function extractConstraintList(chapter: OutlineChapter, entities: Entities): ConstraintItem[];
 export interface DigestInput {
     chapterId: string;

package/dist/core/document/digests.js

@@ -8,7 +8,6 @@
  *    items present in digest).
  *  - recordDigestSources / affectedDownstream: invalidation propagation (decision 9).
  */
-export const DIGEST_BUDGET_TOKENS = 1000;
 // ============= Constraint extraction (T7.1) =============
 export function extractConstraintList(chapter, entities) {
     const items = [];
@@ -19,11 +18,13 @@ export function extractConstraintList(chapter, entities) {
         }
     }
     for (const d of entities.decisions) {
-        if (chapter.points.some((p) => (p.references ?? []).includes(d.id)) || true) {
-            // decisions referenced anywhere are preserved if they relate to this chapter's points
-            if (chapter.points.some((p) => p.text.includes(d.text.slice(0, 20)) || (p.references ?? []).includes(d.id))) {
-                items.push({ kind: 'decision', id: d.id, label: d.text.slice(0, 40) });
-            }
+        // A decision is preserved in this chapter's digest when the chapter references it
+        // (deterministic signal) or its text is mentioned in a point (heuristic fallback).
+        // (Previously wrapped in an always-true `|| true` outer condition — dead code removed.)
+        const referenced = chapter.points.some((p) => (p.references ?? []).includes(d.id));
+        const mentioned = chapter.points.some((p) => p.text.includes(d.text.slice(0, 20)));
+        if (referenced || mentioned) {
+            items.push({ kind: 'decision', id: d.id, label: d.text.slice(0, 40) });
         }
     }
     // dedupe by kind+id
@@ -75,8 +76,11 @@ export function deterministicDigest(entities, ids) {
 export function lintDigest(digest, constraints, knownEntityIds) {
     const diags = [];
     // Reverse: every constraint item must appear in digest (decision 8).
+    // 用整词匹配（P2）：短 id 子串匹配会把 T1 误判为出现（T10/ST1/GET /api/T1），
+    // 或把 t1/D-1 误判为缺失 → 触发确定性回退丢弃约束。
     for (const c of constraints) {
-        if (!digest.includes(c.id)) {
+        const re = new RegExp(`(^|[^A-Za-z0-9_])${escapeRegExp(c.id)}($|[^A-Za-z0-9_])`);
+        if (!re.test(digest)) {
             diags.push({
                 code: 'constraint_missing',
                 severity: 'error',
@@ -85,14 +89,14 @@ export function lintDigest(digest, constraints, knownEntityIds) {
         }
     }
     // Forward: any entity id mentioned in digest that we can detect must exist in known set.
-    // (Heuristic: backtick-quoted tokens + bare I\d+/T\d+ ids.)
+    // （P2 修复：此前 I\d+/T\d+ 被豁免导致前向检查恒不触发；现加入 D\d+ 且不再豁免。）
     const mentioned = new Set();
     for (const m of digest.matchAll(/`([A-Za-z0-9_.]+)`/g))
         mentioned.add(m[1]);
-    for (const m of digest.matchAll(/\b(I\d+|T\d+)\b/g))
+    for (const m of digest.matchAll(/\b(I\d+|T\d+|D\d+)\b/g))
         mentioned.add(m[1]);
     for (const id of mentioned) {
-        if (knownEntityIds.size > 0 && !knownEntityIds.has(id) && !/^I\d+$/.test(id) && !/^T\d+$/.test(id)) {
+        if (knownEntityIds.size > 0 && !knownEntityIds.has(id)) {
             diags.push({
                 code: 'digest_hallucinated_entity',
                 severity: 'warning',
@@ -102,6 +106,10 @@ export function lintDigest(digest, constraints, knownEntityIds) {
     }
     return diags;
 }
+/** 转义正则特殊字符（供整词匹配使用）。 */
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 export function recordDigestSources(chapter, sourceEntities) {
     const entityIds = new Set();
     for (const p of chapter.points) {

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

@@ -9,6 +9,7 @@ import type { DocumentLLM } from './llm.js';
 import { SegmentableInput } from './input-digest.js';
 import { expandProfile } from './profiles.js';
 import { GateDiagnostic } from './gates.js';
+import { ExtractedContracts } from './extract.js';
 export interface RunDocumentOptions {
     llm: DocumentLLM;
     workRoot: string;
@@ -34,6 +35,12 @@ export interface RunDocumentOptions {
     renderHtmlOutput?: boolean;
     outlinePrompt?: string;
     reviewPrompt?: string;
+    /** Project root for deterministic contract extraction (OpenAPI/proto/DDL). Optional —
+     *  when set, engine extracts real contract entities and injects them into outline
+     *  generation as frozen candidates (grounding P0). */
+    projectRoot?: string;
+    /** Pre-extracted contracts (skip file scan). Useful for tests/hosts that already know them. */
+    extractedContracts?: ExtractedContracts;
     /** Persist per-chapter files/entities to workRoot (default true). */
     persist?: boolean;
 }
@@ -47,6 +54,8 @@ export interface RunDocumentResult {
     tokenEstimate?: number;
 }
 export declare function runDocument(options: RunDocumentOptions): Promise<RunDocumentResult>;
+/** 附录覆盖校验（README §7.3）：profile.appendices 含 anti-ai 但自检条目为空/不足 → warning。 */
+export declare function appendixDiagnostics(profile: ScenarioProfile, antiAiContent: string): GateDiagnostic[];
 export interface AgentStep {
     /** stable id: 'input-summary' | 'outline' | 'chapter:<id>' | 'review' */
     id: string;

package/dist/core/document/engine.js

@@ -12,14 +12,15 @@ import { generateOutline, lintOutline, outlineHasErrors, freezeOutline, readOutl
 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 } from './review.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 } from './paths.js';
+import { resolvePaths, reposPath, chapterPath } from './paths.js';
 import { parseEntities } from './schemas.js';
-import { lintNarrative } from './lint.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) {
@@ -29,6 +30,12 @@ export async function runDocument(options) {
     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) {
@@ -38,7 +45,7 @@ export async function runDocument(options) {
     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 });
+        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 })) };
@@ -66,7 +73,7 @@ export async function runDocument(options) {
     }
     // --- 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 };
+    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();
@@ -94,7 +101,7 @@ export async function runDocument(options) {
                 allEntities.decisions.push(...f.entities.decisions);
                 if (persist) {
                     await fs.mkdir(paths.chaptersDir, { recursive: true });
-                    await fs.writeFile(join(paths.chaptersDir, `${f.chapterId}.md`), f.narrative, 'utf-8');
+                    await fs.writeFile(chapterPath(paths.workRoot, f.chapterId), f.narrative, 'utf-8');
                 }
             }
         }
@@ -111,9 +118,26 @@ export async function runDocument(options) {
     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);
+            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)
@@ -127,59 +151,84 @@ export async function runDocument(options) {
                 if (target === 'narrative' || target === 'mixed') {
                     const chId = finding.chapter;
                     if (chId) {
+                        touchedChapters.add(chId);
                         const existing = narrativeMap.get(chId) ?? '';
-                        narrativeMap.set(chId, `${existing}\n\n<!-- review-fix ${finding.id} -->\n${finding.message}`);
+                        // 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(join(paths.chaptersDir, `${chId}.md`), narrativeMap.get(chId), 'utf-8');
+                            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);
-                    entityMap.set(ch.id, result.fill.entities);
                     tokenMap.set(ch.id, result.fill.tokens);
-                    // Replace this chapter's entities in allEntities (remove old, add new).
-                    allEntities.interfaces = allEntities.interfaces.filter((i) => !result.fill.entities.interfaces.some((n) => n.id === i.id));
-                    allEntities.tables = allEntities.tables.filter((t) => !result.fill.entities.tables.some((n) => n.id === t.id));
-                    allEntities.decisions = allEntities.decisions.filter((d) => !result.fill.entities.decisions.some((n) => n.id === d.id));
-                    allEntities.interfaces.push(...result.fill.entities.interfaces);
-                    allEntities.tables.push(...result.fill.entities.tables);
-                    allEntities.decisions.push(...result.fill.entities.decisions);
+                    // 按「章节所有权」整体替换该章节的实体（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(join(paths.chaptersDir, `${ch.id}.md`), result.fill.narrative, 'utf-8');
+                        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,
+                    });
+                }
             }
-            // After applying fixes, refresh part_hashes so tamper checks verify against the fixed state
-            // (repairs are engine-driven, not external tampering).
-            if (persist) {
-                candidate.part_hashes = await computePartHashes(workRoot, outline.chapters.map((c) => c.id));
-            }
-            const check = await checkReviewResult(workRoot, candidate, outline);
+            // 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 documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap });
+    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;
@@ -189,6 +238,16 @@ 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,
@@ -198,7 +257,17 @@ export async function runDocument(options) {
         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;
@@ -208,10 +277,36 @@ export async function runDocument(options) {
         outline,
         documentMd,
         documentHtml,
-        diagnostics: [...reviewDiags, ...gates.diagnostics],
+        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),
@@ -261,6 +356,68 @@ async function buildDigestsFor(chapter, library, outline, narrativeMap, allEntit
     }
     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 = parseEntities(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.
@@ -272,7 +429,19 @@ async function fillAllChapters(outline, ctx, narrativeMap, entityMap, tokenMap,
         const changedChapterId = incremental.changedChapterId;
         const changedEntityIds = incremental.changedEntityIds ?? [];
         if (changedChapterId || changedEntityIds.length > 0) {
-            const sources = outline.chapters.map((ch) => recordDigestSources(ch, allEntities));
+            // 失效集必须基于「已知实体集合」计算，而不是入口处的空 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);
         }
@@ -285,11 +454,16 @@ async function fillAllChapters(outline, ctx, narrativeMap, entityMap, tokenMap,
         if (refillSet && !refillSet.has(ch.id) && !(incremental?.changedChapterId === ch.id) && !producesEntities) {
             if (persist) {
                 try {
-                    const cached = await fs.readFile(join(paths.chaptersDir, `${ch.id}.md`), 'utf-8');
+                    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;
                     }
                 }
@@ -313,13 +487,11 @@ async function fillAllChapters(outline, ctx, narrativeMap, entityMap, tokenMap,
         entityMap.set(ch.id, fill.entities);
         tokenMap.set(ch.id, fill.tokens);
         budgetMap.set(ch.id, budget);
-        // Merge entities for downstream digest/render.
-        allEntities.interfaces.push(...fill.entities.interfaces);
-        allEntities.tables.push(...fill.entities.tables);
-        allEntities.decisions.push(...fill.entities.decisions);
+        // 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(join(paths.chaptersDir, `${ch.id}.md`), fill.narrative, 'utf-8');
+            await fs.writeFile(chapterPath(paths.workRoot, ch.id), fill.narrative, 'utf-8');
             await fs.writeFile(paths.entities, JSON.stringify(allEntities, null, 2), 'utf-8');
         }
     }
@@ -330,10 +502,16 @@ export function sceneTopics(profileId) {
     switch (profileId) {
         case '0to1':
             return ['architecture', 'database', 'api', 'frontend'];
+        case 'frontend-0to1':
+            return ['frontend', 'api'];
         case 'bugfix':
-            return ['database', 'api', 'architecture'];
+            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 [];
     }
@@ -416,6 +594,19 @@ export function planSteps(options) {
         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. */
@@ -441,9 +632,26 @@ export async function validateWork(options) {
     const tokenMap = new Map();
     for (const ch of outline.chapters) {
         try {
-            const content = await fs.readFile(join(paths.chaptersDir, `${ch.id}.md`), 'utf-8');
+            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 = parseEntities(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 });
@@ -466,16 +674,43 @@ export async function validateWork(options) {
             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.
-    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap });
+    // 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) {