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

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

@@ -0,0 +1,28 @@
+/**
+ * Document Engine — injectable LLM interface
+ *
+ * The engine does NOT bind to any specific LLM SDK. Consumers provide a
+ * `DocumentLLM` implementation. The engine only ever calls `complete`; token
+ * estimation for budget checks is done via `estimateTokens` (character-based).
+ */
+export interface LLMMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface LLMInput {
+    system?: string;
+    messages: LLMMessage[];
+}
+export interface LLMOutput {
+    content: string;
+}
+export interface DocumentLLM {
+    /** Generic completion — returns raw text. */
+    complete(input: LLMInput): Promise<LLMOutput>;
+}
+/**
+ * Default character-based token estimate.
+ * NOTE: under-counts Chinese (~1 char ≈ 1 token vs len/4); budget gates are
+ * intentionally lenient.
+ */
+export declare function estimateTokens(text: string): number;

package/dist/core/document/llm.js

@@ -0,0 +1,22 @@
+/**
+ * Document Engine — injectable LLM interface
+ *
+ * The engine does NOT bind to any specific LLM SDK. Consumers provide a
+ * `DocumentLLM` implementation. The engine only ever calls `complete`; token
+ * estimation for budget checks is done via `estimateTokens` (character-based).
+ */
+/**
+ * Default character-based token estimate.
+ * NOTE: under-counts Chinese (~1 char ≈ 1 token vs len/4); budget gates are
+ * intentionally lenient.
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    // Count CJK chars at 1 token/char, others at ~4 chars/token.
+    let tokens = 0;
+    for (const ch of text) {
+        tokens += /[\u2E80-\u9FFF\uF900-\uFAFF\uFF00-\uFFEF\u3000-\u303F]/.test(ch) ? 1 : 0.25;
+    }
+    return Math.max(1, Math.ceil(tokens));
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Document Engine — Pass 2 per-chapter fill-in (decisions 6/8/9).
+ *
+ * Four-layer context injection per chapter:
+ *   ① outline points + global entities/decisions
+ *   ② dependency digests (navigation)
+ *   ③ upstream contract entities injected deterministically (registry + referenced full contracts)
+ *   ④ source segments (original input by source_segments)
+ *
+ * Fills by point kind: entity/mixed → structured contract entities; narrative/mixed → Markdown.
+ * Output budget enforced per chapter (decision 6/P6). fill_once falls back to per-chapter when
+ * the estimated input context exceeds the budget (decision 9).
+ */
+import { Outline, OutlineChapter, Entities, ChapterComponent } from './schemas.js';
+import type { DocumentLLM, LLMInput } from './llm.js';
+export interface ChapterFill {
+    chapterId: string;
+    narrative: string;
+    entities: Entities;
+    tokens: number;
+}
+export interface MapContext {
+    outline: Outline;
+    digests: Map<string, string>;
+    upstreamEntities: Entities;
+    workRoot: string;
+    chapterById: Map<string, ChapterComponent>;
+    /** buildChapterContext 结果缓存（P2）：fill_once/shouldFillOnce/回退/review 重填会重复
+     *  构建同一章节上下文（含重复 fetchSegments 整文件 IO），按 chapterId 缓存消除。 */
+    contextCache?: Map<string, {
+        input: LLMInput;
+        estimatedTokens: number;
+    }>;
+}
+export declare function buildChapterContext(chapter: OutlineChapter, ctx: MapContext): Promise<{
+    input: LLMInput;
+    estimatedTokens: number;
+}>;
+export interface FillChapterResult {
+    ok: boolean;
+    fill?: ChapterFill;
+    error?: string;
+}
+export declare function fillChapter(llm: DocumentLLM, chapter: OutlineChapter, ctx: MapContext, budgetTokens?: number): Promise<FillChapterResult>;
+export declare function shouldFillOnce(outline: Outline, ctx: MapContext): Promise<boolean>;
+export interface FillOnceResult {
+    ok: boolean;
+    chapters: ChapterFill[];
+    fellBackToPerChapter: boolean;
+    error?: string;
+}
+export declare function fillOnce(llm: DocumentLLM, outline: Outline, ctx: MapContext): Promise<FillOnceResult>;

package/dist/core/document/map.js

@@ -0,0 +1,296 @@
+/**
+ * Document Engine — Pass 2 per-chapter fill-in (decisions 6/8/9).
+ *
+ * Four-layer context injection per chapter:
+ *   ① outline points + global entities/decisions
+ *   ② dependency digests (navigation)
+ *   ③ upstream contract entities injected deterministically (registry + referenced full contracts)
+ *   ④ source segments (original input by source_segments)
+ *
+ * Fills by point kind: entity/mixed → structured contract entities; narrative/mixed → Markdown.
+ * Output budget enforced per chapter (decision 6/P6). fill_once falls back to per-chapter when
+ * the estimated input context exceeds the budget (decision 9).
+ */
+import { parseEntities, parseInterfaceEntity, parseTableEntity, parseDecisionEntity } from './schemas.js';
+import { estimateTokens } from './llm.js';
+import { fetchSegments } from './input-digest.js';
+const MAP_SYSTEM = '你是方案文档撰写员。按给定章节要点"填空题"式展开：逐要点填充，不自由发挥。' +
+    'kind=entity 或 mixed 的要点 → 产出结构化契约实体（JSON）；kind=narrative 或 mixed 的要点 → 产出叙述 Markdown。' +
+    '契约实体必须满足字段约束（接口须含 failure_examples，表须含 ddl/migration/rollback）。';
+// ============= Four-layer context build (T6.2) =============
+export async function buildChapterContext(chapter, ctx) {
+    // 缓存命中直接返回（P2：同一章节上下文在 fill_once 决策/执行/回退/review 重填中会被多次构建）
+    if (ctx.contextCache) {
+        const cached = ctx.contextCache.get(chapter.id);
+        if (cached)
+            return cached;
+    }
+    const { outline, digests, upstreamEntities, workRoot } = ctx;
+    // ① outline points + global entities/decisions
+    const chapterPoints = chapter.points.map((p) => `${p.id} [${p.kind}] ${p.text}${(p.references ?? []).length ? ` refs=${(p.references ?? []).join(',')}` : ''}`).join('\n');
+    const globalEntities = outline.entities.map((e) => `${e.id} (${e.frozen}${e.standalone ? ', standalone' : ''})`).join(', ');
+    // ② dependency digests
+    const deps = [];
+    const chComp = ctx.chapterById.get(chapter.id);
+    for (const dep of chComp?.depends_on ?? []) {
+        const d = digests.get(dep);
+        if (d)
+            deps.push(`[依赖 ${dep}] ${d}`);
+    }
+    // ③ upstream contract entities: registry (all) + full contracts for referenced ids
+    const referencedIds = new Set();
+    for (const p of chapter.points)
+        for (const r of p.references ?? [])
+            referencedIds.add(r);
+    const registry = [
+        ...upstreamEntities.interfaces.map((i) => `I ${i.id}: ${i.name}`),
+        ...upstreamEntities.tables.map((t) => `T ${t.id}: ${t.name}`),
+    ].join('\n');
+    const fullContracts = [
+        ...upstreamEntities.interfaces.filter((i) => referencedIds.has(i.id)),
+        ...upstreamEntities.tables.filter((t) => referencedIds.has(t.id)),
+    ].map((e) => JSON.stringify(e)).join('\n');
+    // ④ source segments
+    const segmentIds = new Set();
+    for (const p of chapter.points)
+        for (const s of p.source_segments ?? [])
+            segmentIds.add(s);
+    const segments = segmentIds.size > 0 ? await fetchSegments(workRoot, [...segmentIds]) : '';
+    const content = [
+        `## 章节 ${chapter.id}（${chapter.title}）`,
+        `### 要点清单（填空）`,
+        chapterPoints,
+        `### 全局实体/决策`,
+        globalEntities,
+        deps.length ? `### 依赖摘要\n${deps.join('\n\n')}` : '',
+        registry ? `### 上游契约实体注册表\n${registry}` : '',
+        fullContracts ? `### 上游契约实体完整契约（引用）\n${fullContracts}` : '',
+        segments ? `### 本片片段（原文）\n${segments}` : '',
+    ].filter(Boolean).join('\n\n');
+    const input = {
+        system: MAP_SYSTEM,
+        messages: [{ role: 'user', content }],
+    };
+    const built = { input, estimatedTokens: estimateTokens(content) + estimateTokens(MAP_SYSTEM) };
+    if (ctx.contextCache)
+        ctx.contextCache.set(chapter.id, built);
+    return built;
+}
+export async function fillChapter(llm, chapter, ctx, budgetTokens) {
+    let input;
+    let estimatedTokens;
+    try {
+        const built = await buildChapterContext(chapter, ctx);
+        input = built.input;
+        estimatedTokens = built.estimatedTokens;
+    }
+    catch (e) {
+        return { ok: false, error: `Chapter "${chapter.id}" context build failed: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    // Input-side budget guard（P2-adjacent）：在 LLM 调用之前拒绝明显超预算输入，
+    // 避免昂贵调用已发出后才失败（decision 6/P6 hard gate）。
+    const maxInputTokens = budgetTokens ? budgetTokens * 4 : undefined;
+    if (maxInputTokens !== undefined && estimatedTokens > maxInputTokens) {
+        return { ok: false, error: `Chapter "${chapter.id}" input context ${estimatedTokens} tokens exceeds 4× output budget` };
+    }
+    let res;
+    try {
+        res = await llm.complete(input);
+    }
+    catch (e) {
+        return { ok: false, error: `Chapter "${chapter.id}" LLM call failed: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    const narrative = res.content.trim();
+    // Extract embedded contract entities (JSON blocks). Strict: if this chapter's points require
+    // entities (kind=entity|mixed with references) and none are extracted, fail loudly rather than
+    // silently produce a contract-less chapter (decision 1 layered source of truth).
+    let entities = { interfaces: [], tables: [], decisions: [] };
+    const jsonMatch = narrative.match(/```json\s*([\s\S]*?)```/g);
+    // 记录成功解析为实体块的围栏文本：清洗时只移除这些块，保留叙述中的 JSON 示例（P2）。
+    const parsedEntityBlocks = [];
+    if (jsonMatch) {
+        // 按 id 去重合并（P1-9）：同一实体跨块/跨引用重复输出时只保留最后出现的版本，
+        // 防止共享实体在 entities.json 与最终文档中重复渲染。
+        const merged = { interfaces: [], tables: [], decisions: [] };
+        const seenInterface = new Set();
+        const seenTable = new Set();
+        const seenDecision = new Set();
+        for (const block of jsonMatch) {
+            let parsed;
+            try {
+                parsed = JSON.parse(block.replace(/```json\s*/, '').replace(/```$/, '').trim());
+            }
+            catch {
+                continue; // 非法 JSON → 非实体块，忽略
+            }
+            if (!parsed || typeof parsed !== 'object' || !parsed.entities)
+                continue;
+            const rawEntities = parsed.entities;
+            // 逐实体容错（P2）：单个实体字段不合 zod（如接口缺 failure_examples）不再丢弃同块其它
+            // 合法实体；非法项跳过并继续，尽量保留有效契约。
+            const e = { interfaces: [], tables: [], decisions: [] };
+            for (const it of rawEntities.interfaces ?? []) {
+                try {
+                    e.interfaces.push(parseInterfaceEntity(it));
+                }
+                catch { /* 跳过非法接口 */ }
+            }
+            for (const tb of rawEntities.tables ?? []) {
+                try {
+                    e.tables.push(parseTableEntity(tb));
+                }
+                catch { /* 跳过非法表 */ }
+            }
+            for (const d of rawEntities.decisions ?? []) {
+                try {
+                    e.decisions.push(parseDecisionEntity(d));
+                }
+                catch { /* 跳过非法决策 */ }
+            }
+            if (e.interfaces.length + e.tables.length + e.decisions.length === 0)
+                continue;
+            parsedEntityBlocks.push(block);
+            for (const it of e.interfaces) {
+                if (!seenInterface.has(it.id)) {
+                    seenInterface.add(it.id);
+                    merged.interfaces.push(it);
+                }
+            }
+            for (const tb of e.tables) {
+                if (!seenTable.has(tb.id)) {
+                    seenTable.add(tb.id);
+                    merged.tables.push(tb);
+                }
+            }
+            for (const d of e.decisions) {
+                if (!seenDecision.has(d.id)) {
+                    seenDecision.add(d.id);
+                    merged.decisions.push(d);
+                }
+            }
+        }
+        entities = merged;
+    }
+    // Clean the narrative: remove ONLY the successfully-parsed ```json entity blocks so they are
+    // not rendered verbatim inside chapters; narrative JSON examples (e.g. API response samples)
+    // are preserved (P2). Contract entities are rendered deterministically in the 契约 section.
+    let cleanNarrative = narrative;
+    for (const block of parsedEntityBlocks) {
+        cleanNarrative = cleanNarrative.replace(block, '');
+    }
+    cleanNarrative = cleanNarrative.replace(/\n{3,}/g, '\n\n').trim();
+    // 空叙述早失败（P2）：LLM 只输出实体块未产出叙述时立即报错，与 fillOnce 的检查对齐，
+    // 避免拖到管线末尾 gates-fail 才暴露。
+    if (cleanNarrative.length === 0) {
+        return { ok: false, error: `Chapter "${chapter.id}" produced no narrative (LLM returned only entity JSON or empty content)` };
+    }
+    // Strict: entity-requiring points must have their referenced entities filled.
+    const requiredEntityIds = new Set();
+    for (const p of chapter.points) {
+        if ((p.kind === 'entity' || p.kind === 'mixed') && (p.references ?? []).length > 0) {
+            for (const ref of p.references)
+                requiredEntityIds.add(ref);
+        }
+    }
+    const filledEntityIds = new Set([
+        ...entities.interfaces.map((i) => i.id),
+        ...entities.tables.map((t) => t.id),
+        ...entities.decisions.map((d) => d.id),
+    ]);
+    for (const id of requiredEntityIds) {
+        if (!filledEntityIds.has(id)) {
+            return { ok: false, error: `Chapter "${chapter.id}" requires entity "${id}" (point references) but none was extracted` };
+        }
+    }
+    const tokens = estimateTokens(cleanNarrative) + estimateTokens(JSON.stringify(entities));
+    if (budgetTokens !== undefined && tokens > budgetTokens) {
+        return { ok: false, error: `Chapter "${chapter.id}" output ${tokens} tokens exceeds budget ${budgetTokens}` };
+    }
+    return {
+        ok: true,
+        fill: { chapterId: chapter.id, narrative: cleanNarrative, entities, tokens },
+    };
+}
+// ============= fill_once decision (T6.5/T6.6) =============
+export async function shouldFillOnce(outline, ctx) {
+    if (!outline.fill_once?.enabled)
+        return false;
+    const budget = outline.fill_once.input_budget_tokens ?? 8000;
+    let total = 0;
+    try {
+        for (const ch of outline.chapters) {
+            const { estimatedTokens } = await buildChapterContext(ch, ctx);
+            total += estimatedTokens;
+        }
+    }
+    catch {
+        return false; // 上下文构建失败 → 回退 per-chapter（P2）
+    }
+    return total <= budget;
+}
+const FILL_ONCE_SYSTEM = '你是方案文档撰写员。一次填完全部章节，输出结构化 JSON：' +
+    '{"chapters":{"<chapterId>":{"narrative":"本章叙述 Markdown","entities":{"interfaces":[...],"tables":[...],"decisions":[...]}},...}}。' +
+    '每章内容必须差异化（针对该章要点），禁止复制同一段到所有章节。契约实体须含 failure_examples（接口）/ddl（表）。';
+export async function fillOnce(llm, outline, ctx) {
+    // Build a single combined context (all chapters) — bounded by shouldFillOnce pre-check.
+    // try/catch（P2）：上下文构建与 LLM 调用任一抛错都应回退 per-chapter，而不是穿透崩溃。
+    let res;
+    try {
+        const sections = [];
+        for (const ch of outline.chapters) {
+            const { input } = await buildChapterContext(ch, ctx);
+            sections.push(input.messages[0].content);
+        }
+        res = await llm.complete({
+            system: FILL_ONCE_SYSTEM,
+            messages: [{ role: 'user', content: sections.join('\n\n=====\n\n') }],
+        });
+    }
+    catch (e) {
+        return {
+            ok: false,
+            chapters: [],
+            fellBackToPerChapter: true,
+            error: `fill_once: context build or LLM call failed (${e instanceof Error ? e.message : String(e)})`,
+        };
+    }
+    const content = res.content.trim();
+    // Parse structured per-chapter output; fall back to per-chapter fill on parse failure.
+    try {
+        const parsed = JSON.parse(content);
+        if (!parsed.chapters || typeof parsed.chapters !== 'object') {
+            return { ok: false, chapters: [], fellBackToPerChapter: true, error: 'fill_once: missing chapters object' };
+        }
+        const chapters = [];
+        for (const ch of outline.chapters) {
+            const entry = parsed.chapters[ch.id];
+            if (!entry || typeof entry.narrative !== 'string' || entry.narrative.trim().length === 0) {
+                return { ok: false, chapters: [], fellBackToPerChapter: true, error: `fill_once: chapter ${ch.id} missing narrative` };
+            }
+            let entities = { interfaces: [], tables: [], decisions: [] };
+            try {
+                if (entry.entities)
+                    entities = parseEntities(entry.entities);
+            }
+            catch {
+                entities = { interfaces: [], tables: [], decisions: [] };
+            }
+            const narrative = entry.narrative.trim();
+            chapters.push({
+                chapterId: ch.id,
+                narrative,
+                entities,
+                tokens: estimateTokens(narrative) + estimateTokens(JSON.stringify(entities)),
+            });
+        }
+        return { ok: true, chapters, fellBackToPerChapter: false };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            chapters: [],
+            fellBackToPerChapter: true,
+            error: `fill_once: unparsable output (${e instanceof Error ? e.message : String(e)})`,
+        };
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Document Engine — Pass 1 outline generation + lint + freeze (decisions 6/8/9).
+ *
+ * Generates the Outline from the global input digest + profile constraints,
+ * lints it (required/forbidden, references forward + reverse, kind consistency),
+ * then freezes to work/outline.yaml.
+ */
+import { Outline, ScenarioProfile } from './schemas.js';
+import type { DocumentLLM } from './llm.js';
+import { GlobalInputDigest } from './input-digest.js';
+import { ExtractedContracts } from './extract.js';
+export interface OutlineDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    chapter?: string;
+}
+export interface GenerateOutlineOptions {
+    profile: ScenarioProfile;
+    inputDigest: GlobalInputDigest;
+    prompt?: string;
+    /** 工程契约候选（grounding P0 确定性提取）：冻结实体名供大纲注册表引用，禁止改名/编造。 */
+    extractedContracts?: ExtractedContracts;
+}
+export declare function generateOutline(llm: DocumentLLM, options: GenerateOutlineOptions): Promise<Outline>;
+export declare function lintOutline(outline: Outline, profile: ScenarioProfile): OutlineDiagnostic[];
+export declare function outlineHasErrors(diags: OutlineDiagnostic[]): boolean;
+export declare function freezeOutline(workRoot: string, outline: Outline): Promise<string>;
+export declare function readOutline(workRoot: string): Promise<Outline>;

package/dist/core/document/outline.js

@@ -0,0 +1,171 @@
+/**
+ * Document Engine — Pass 1 outline generation + lint + freeze (decisions 6/8/9).
+ *
+ * Generates the Outline from the global input digest + profile constraints,
+ * lints it (required/forbidden, references forward + reverse, kind consistency),
+ * then freezes to work/outline.yaml.
+ */
+import { promises as fs } from 'node:fs';
+import yaml from 'js-yaml';
+import { parseOutline } from './schemas.js';
+const DEFAULT_PROMPT = '你是文档大纲设计专家。基于全局输入摘要与场景 Profile 约束，生成结构化文档大纲。见 prompts/document/outline/general.md。';
+const OUTLINE_SYSTEM = '你是文档大纲设计专家。严格按输入要求输出 JSON 大纲，满足所有硬规则（章节约束/要点 kind/references 完整性/source_segments）。';
+// ============= Generation (T5.2) =============
+/** 剥离 LLM 输出中的 ```json 围栏与前后缀文本（P2：与 map.ts 的围栏处理一致）。 */
+function extractJsonBlock(content) {
+    const trimmed = content.trim();
+    const fence = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fence)
+        return fence[1].trim();
+    // 无围栏：尝试取首个平衡 {...} 块（容忍前后缀说明文字）。
+    const start = trimmed.indexOf('{');
+    const end = trimmed.lastIndexOf('}');
+    if (start >= 0 && end > start)
+        return trimmed.slice(start, end + 1);
+    return trimmed;
+}
+export async function generateOutline(llm, options) {
+    const { profile, inputDigest } = options;
+    const prompt = options.prompt ?? DEFAULT_PROMPT;
+    const extracted = options.extractedContracts;
+    // Grounding 注入：工程契约候选（事实）。大纲注册表必须原样引用这些 frozen 名，
+    // 禁止改名/编造；无提取时该段省略（行为与旧版一致）。
+    const extractedBlock = extracted && (extracted.interfaces.length > 0 || extracted.tables.length > 0)
+        ? [
+            `## 工程契约候选（确定性提取，事实）`,
+            `以下实体来自工程数据源（OpenAPI/proto/DDL），是已确认的事实：`,
+            ...extracted.interfaces.map((it) => `- ${it.id} (${it.method} ${it.path}) name=${it.name}${it.request_fields?.length ? ` request=[${it.request_fields.map((f) => `${f.name}:${f.type}`).join(', ')}]` : ''}${it.response_fields?.length ? ` response=[${it.response_fields.map((f) => `${f.name}:${f.type}`).join(', ')}]` : ''}`),
+            ...extracted.tables.map((tb) => `- ${tb.id} (table) name=${tb.name} fields=[${tb.fields?.map((f) => `${f.name}:${f.type}`).join(', ') ?? ''}]`),
+            `规则：大纲 entities 注册表引用这些实体时，frozen 必须使用上述 name；references 用上述 id；禁止新增同名异义实体。`,
+        ].join('\n')
+        : '';
+    const input = {
+        system: OUTLINE_SYSTEM,
+        messages: [
+            { role: 'user', content: prompt },
+            {
+                role: 'user',
+                content: [
+                    `Profile: ${JSON.stringify(profile)}`,
+                    `全局输入摘要: ${inputDigest.summary}`,
+                    `段摘要: ${inputDigest.segments.map((s) => `[${s.id}] ${s.summary}`).join('\n')}`,
+                    extractedBlock,
+                ].filter(Boolean).join('\n\n'),
+            },
+        ],
+    };
+    // Retry up to 2 times on PARSE failure only（P2）：LLM 服务/传输错误（限流/5xx）立即抛出，
+    // 不背靠背重试放大延迟与成本；确定性解析错误才重试。
+    let lastParseErr;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        let res;
+        try {
+            res = await llm.complete(input);
+        }
+        catch (e) {
+            throw new Error(`generateOutline: LLM call failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        try {
+            const outline = parseOutline(JSON.parse(extractJsonBlock(res.content)));
+            return outline;
+        }
+        catch (e) {
+            lastParseErr = e;
+        }
+    }
+    throw new Error(`generateOutline: failed to parse outline after retries: ${lastParseErr}`);
+}
+// ============= Lint (T5.3) =============
+export function lintOutline(outline, profile) {
+    const diags = [];
+    // 1. Required chapters all present.
+    for (const id of profile.required) {
+        if (!outline.chapters.some((c) => c.id === id)) {
+            diags.push({ code: 'required_missing', severity: 'error', message: `Required chapter "${id}" missing from outline` });
+        }
+    }
+    // 2. Forbidden chapters absent.
+    for (const id of profile.forbidden) {
+        if (outline.chapters.some((c) => c.id === id)) {
+            diags.push({ code: 'forbidden_present', severity: 'error', chapter: id, message: `Forbidden chapter "${id}" present in outline` });
+        }
+    }
+    // 3. Duplicate chapter ids.
+    const seenCh = new Set();
+    for (const ch of outline.chapters) {
+        if (seenCh.has(ch.id))
+            diags.push({ code: 'duplicate_chapter', severity: 'error', chapter: ch.id, message: `Duplicate chapter "${ch.id}"` });
+        seenCh.add(ch.id);
+    }
+    // 4. Duplicate point ids within a chapter.
+    for (const ch of outline.chapters) {
+        const seenP = new Set();
+        for (const p of ch.points) {
+            if (seenP.has(p.id))
+                diags.push({ code: 'duplicate_point', severity: 'error', chapter: ch.id, message: `Duplicate point "${p.id}"` });
+            seenP.add(p.id);
+        }
+    }
+    // 4b. Duplicate entity ids in registry（P2）：重复注册会被 Set 静默折叠，正向引用校验失效。
+    const seenEntity = new Set();
+    for (const e of outline.entities) {
+        if (seenEntity.has(e.id))
+            diags.push({ code: 'duplicate_entity', severity: 'error', message: `Duplicate entity "${e.id}" in registry` });
+        seenEntity.add(e.id);
+    }
+    const entityIds = new Set(outline.entities.map((e) => e.id));
+    // 5. References forward: point references must exist in entity registry.
+    // 6. Kind consistency: references present → kind must not be narrative; ≤3 unique refs per point.
+    for (const ch of outline.chapters) {
+        for (const p of ch.points) {
+            const refs = [...new Set(p.references ?? [])]; // 去重（P2：重复引用不误触 ≤3 门禁）
+            if (refs.length > 3) {
+                diags.push({ code: 'too_many_references', severity: 'error', chapter: ch.id, message: `Point "${p.id}" references >3 entities` });
+            }
+            if ((p.references ?? []).length !== refs.length) {
+                diags.push({ code: 'duplicate_reference', severity: 'warning', chapter: ch.id, message: `Point "${p.id}" has duplicate references` });
+            }
+            for (const ref of refs) {
+                if (!entityIds.has(ref)) {
+                    diags.push({ code: 'reference_unknown', severity: 'error', chapter: ch.id, message: `Point "${p.id}" references unknown entity "${ref}"` });
+                }
+            }
+            if (refs.length > 0 && p.kind === 'narrative') {
+                diags.push({ code: 'kind_inconsistent', severity: 'error', chapter: ch.id, message: `Point "${p.id}" has references but kind=narrative` });
+            }
+        }
+    }
+    // 7. References reverse (decision 9): every non-standalone entity must be referenced by ≥1 point.
+    const referenced = new Set();
+    for (const ch of outline.chapters) {
+        for (const p of ch.points) {
+            for (const ref of p.references ?? [])
+                referenced.add(ref);
+        }
+    }
+    for (const ent of outline.entities) {
+        if (!ent.standalone && !referenced.has(ent.id)) {
+            diags.push({ code: 'entity_unreferenced', severity: 'error', message: `Entity "${ent.id}" not referenced by any point (mark standalone to exempt)` });
+        }
+    }
+    // 8. Every chapter must have ≥1 point.
+    for (const ch of outline.chapters) {
+        if (ch.points.length === 0) {
+            diags.push({ code: 'chapter_no_points', severity: 'error', chapter: ch.id, message: `Chapter "${ch.id}" has no points` });
+        }
+    }
+    return diags;
+}
+export function outlineHasErrors(diags) {
+    return diags.some((d) => d.severity === 'error');
+}
+// ============= Freeze (T5.4/T5.5) =============
+export async function freezeOutline(workRoot, outline) {
+    const path = `${workRoot}/outline.yaml`;
+    await fs.writeFile(path, yaml.dump(outline, { noRefs: true }), 'utf-8');
+    return path;
+}
+export async function readOutline(workRoot) {
+    const raw = yaml.load(await fs.readFile(`${workRoot}/outline.yaml`, 'utf-8'));
+    return parseOutline(raw);
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Document Engine — injectable path resolution.
+ *
+ * Replaces ACP's hardcoded `specflow/changes` + `validateChangeName`. The
+ * caller supplies a `workRoot`; all artifact paths derive from it.
+ */
+export interface DocumentPaths {
+    workRoot: string;
+    outline: string;
+    entities: string;
+    chaptersDir: string;
+    documentMd: string;
+    documentHtml: string;
+}
+/** Resolve all engine artifact paths under a caller-provided work root. */
+export declare function resolvePaths(workRoot: string): DocumentPaths;
+/** 章节 id 白名单：仅允许安全标识符，拒绝路径分隔符/`..`/空串（防路径穿越，P0-3）。 */
+export declare const CHAPTER_ID_RE: RegExp;
+export declare function assertChapterId(chapterId: string): void;
+export declare function chapterPath(workRoot: string, chapterId: string): string;
+/** Multi-repo synthesize marker: list of repo names (written by document synthesize). */
+export declare function reposPath(workRoot: string): string;
+export declare function segmentIndexPath(workRoot: string): string;

package/dist/core/document/paths.js

@@ -0,0 +1,36 @@
+/**
+ * Document Engine — injectable path resolution.
+ *
+ * Replaces ACP's hardcoded `specflow/changes` + `validateChangeName`. The
+ * caller supplies a `workRoot`; all artifact paths derive from it.
+ */
+import { join } from 'node:path';
+/** Resolve all engine artifact paths under a caller-provided work root. */
+export function resolvePaths(workRoot) {
+    return {
+        workRoot,
+        outline: join(workRoot, 'outline.yaml'),
+        entities: join(workRoot, 'entities.json'),
+        chaptersDir: join(workRoot, 'chapters'),
+        documentMd: join(workRoot, 'document.md'),
+        documentHtml: join(workRoot, 'document.html'),
+    };
+}
+/** 章节 id 白名单：仅允许安全标识符，拒绝路径分隔符/`..`/空串（防路径穿越，P0-3）。 */
+export const CHAPTER_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+export function assertChapterId(chapterId) {
+    if (!CHAPTER_ID_RE.test(chapterId)) {
+        throw new Error(`Invalid chapter id "${chapterId}": must match ${CHAPTER_ID_RE}`);
+    }
+}
+export function chapterPath(workRoot, chapterId) {
+    assertChapterId(chapterId);
+    return join(workRoot, 'chapters', `${chapterId}.md`);
+}
+/** Multi-repo synthesize marker: list of repo names (written by document synthesize). */
+export function reposPath(workRoot) {
+    return join(workRoot, 'repos.json');
+}
+export function segmentIndexPath(workRoot) {
+    return join(workRoot, 'segments', 'index.json');
+}