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

package/dist/core/document/engine.js

@@ -0,0 +1,487 @@
+/**
+ * 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 } from './review.js';
+import { renderDocument, renderHtml } from './render.js';
+import { runGates } from './gates.js';
+import { resolvePaths } from './paths.js';
+import { parseEntities } from './schemas.js';
+import { lintNarrative } from './lint.js';
+import { checkStructuredCoverage } from './coverage.js';
+import { resolveProjectConventionPaths } from '../project-conventions.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 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 });
+        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 };
+    // 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(join(paths.chaptersDir, `${f.chapterId}.md`), 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) {
+        for (let round = 0; round < maxRounds; round++) {
+            const packet = await buildReviewPacket(workRoot, change, outline);
+            const candidate = await reviewWithAgent(llm, packet, options.reviewPrompt);
+            // 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) {
+                        const existing = narrativeMap.get(chId) ?? '';
+                        narrativeMap.set(chId, `${existing}\n\n<!-- review-fix ${finding.id} -->\n${finding.message}`);
+                        if (persist) {
+                            await fs.mkdir(paths.chaptersDir, { recursive: true });
+                            await fs.writeFile(join(paths.chaptersDir, `${chId}.md`), narrativeMap.get(chId), 'utf-8');
+                        }
+                    }
+                }
+            });
+            // 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;
+                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);
+                    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(paths.entities, JSON.stringify(allEntities, null, 2), 'utf-8');
+                    }
+                }
+            }
+            // 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);
+            review = candidate;
+            reviewDiags = check.diagnostics.map((d) => ({ gate: 'review', code: d.code, severity: d.severity, message: d.message }));
+            if (check.ok) {
+                break;
+            }
+        }
+    }
+    if (review && persist) {
+        await writeReviewResult(workRoot, review);
+    }
+    // --- Pass 4: render (T9) ---
+    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap });
+    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) ---
+    const gates = await runGates({
+        outline,
+        chapterNarratives: narrativeMap,
+        chapterEntities: entityMap,
+        chapterTokens: tokenMap,
+        chapterBudget: budgetMap,
+        entities: allEntities,
+        review,
+        workRoot,
+    });
+    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, ...gates.diagnostics],
+        tokenEstimate: totalTokens,
+    };
+}
+/**
+ * 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;
+}
+/**
+ * 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) {
+            const sources = outline.chapters.map((ch) => recordDigestSources(ch, allEntities));
+            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(join(paths.chaptersDir, `${ch.id}.md`), '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);
+                        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.
+        allEntities.interfaces.push(...fill.entities.interfaces);
+        allEntities.tables.push(...fill.entities.tables);
+        allEntities.decisions.push(...fill.entities.decisions);
+        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(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 'bugfix':
+            return ['database', 'api', 'architecture'];
+        case 'feature':
+            return ['api', 'database', 'frontend', 'architecture'];
+        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,
+    });
+    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(join(paths.chaptersDir, `${ch.id}.md`), 'utf-8');
+            narrativeMap.set(ch.id, content);
+            tokenMap.set(ch.id, estimateTokens(content));
+        }
+        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 = parseEntities(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 });
+        }
+    }
+    // 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 });
+    }
+    const hasError = diags.some((d) => d.severity === 'error');
+    if (hasError) {
+        return { ok: false, diagnostics: diags };
+    }
+    // Render.
+    const documentMd = renderDocument({ outline, entities: allEntities, narratives: narrativeMap });
+    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 };

package/dist/core/{approval → document}/forbidden-patterns.d.ts

@@ -1,6 +1,8 @@
-/** Shared stub / inconsistency patterns for assemble lazy-check and approval lint. */
+/**
+ * Document Engine — anti-lazy patterns (carried over from ACP, reworked).
+ * Used by lint.ts to reject stub / lazy content in narratives and digests.
+ */
 export declare const FORBIDDEN_STUB_PATTERNS: readonly RegExp[];
-/** Semantic inconsistency hints (warnings unless strict mode) — long-document generic. */
 export declare const INCONSISTENCY_HINT_PATTERNS: readonly RegExp[];
 export declare function findForbiddenMatch(content: string): RegExp | null;
 export declare function findInconsistencyHints(content: string): readonly RegExp[];

package/dist/core/document/forbidden-patterns.js

@@ -0,0 +1,33 @@
+/**
+ * Document Engine — anti-lazy patterns (carried over from ACP, reworked).
+ * Used by lint.ts to reject stub / lazy content in narratives and digests.
+ */
+export const FORBIDDEN_STUB_PATTERNS = [
+    /\bTODO\b/i,
+    /待补充/,
+    /此处省略/,
+    /详见\s*(?:上文|下文|附件)(?!.*§)/,
+    /略\s*[。.]?$/,
+    /\bTBD\b\s*[。.]?$/,
+    /(?:^|\n)\s*(?:同上|同前)\s*[。.]?\s*(?:\n|$)/,
+    /实现时(?:命名|对齐)/,
+    /(?:RPC|rpc).*暂定/,
+    /暂定\s*[`']?\w+[`']?/,
+];
+export const INCONSISTENCY_HINT_PATTERNS = [
+    /\b(?:等|etc\.?)\s*[。.)]/,
+    /(?:status|状态|enum|枚举)[^.\n]{0,30}(?:等|etc)/i,
+    /(?:^|[\s，。；])同前(?!缀)/,
+    /(?:^|[\s，。；])同上(?!所述)/,
+    /\b(?:待定|未定)\b/i,
+];
+export function findForbiddenMatch(content) {
+    for (const p of FORBIDDEN_STUB_PATTERNS) {
+        if (p.test(content))
+            return p;
+    }
+    return null;
+}
+export function findInconsistencyHints(content) {
+    return INCONSISTENCY_HINT_PATTERNS.filter((p) => p.test(content));
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Document Engine — gate orchestration (T10.4).
+ * Runs lint → structured coverage → review check → budget → zod, collecting diagnostics.
+ */
+import { Outline, Entities, ReviewResult } from './schemas.js';
+export interface GateDiagnostic {
+    gate: string;
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    chapter?: string;
+}
+export interface GatesInput {
+    outline: Outline;
+    chapterNarratives: Map<string, string>;
+    chapterEntities: Map<string, Entities>;
+    chapterTokens: Map<string, number>;
+    chapterBudget: Map<string, number | undefined>;
+    entities: Entities;
+    review?: ReviewResult;
+    workRoot: string;
+}
+export interface GatesResult {
+    ok: boolean;
+    diagnostics: GateDiagnostic[];
+}
+export declare function runGates(input: GatesInput): Promise<GatesResult>;

package/dist/core/document/gates.js

@@ -0,0 +1,33 @@
+/**
+ * Document Engine — gate orchestration (T10.4).
+ * Runs lint → structured coverage → review check → budget → zod, collecting diagnostics.
+ */
+import { lintNarrative, checkBudget } from './lint.js';
+import { checkStructuredCoverage } from './coverage.js';
+import { checkReviewResult } from './review.js';
+export async function runGates(input) {
+    const diags = [];
+    // lint: narrative stub/short + budget per chapter
+    for (const [chId, narrative] of input.chapterNarratives) {
+        for (const d of lintNarrative(chId, narrative)) {
+            diags.push({ gate: 'lint', code: d.code, severity: d.severity, message: d.message, chapter: chId });
+        }
+        const tokens = input.chapterTokens.get(chId) ?? 0;
+        const budget = input.chapterBudget.get(chId);
+        for (const b of checkBudget(chId, tokens, budget)) {
+            diags.push({ gate: 'budget', code: b.code, severity: b.severity, message: b.message, chapter: chId });
+        }
+    }
+    // structured coverage
+    for (const d of checkStructuredCoverage(input.outline, input.chapterEntities)) {
+        diags.push({ gate: 'coverage', code: d.code, severity: d.severity, message: d.message, chapter: d.chapter });
+    }
+    // review check (semantic channel + tamper + verdict)
+    if (input.review) {
+        const r = await checkReviewResult(input.workRoot, input.review, input.outline);
+        for (const d of r.diagnostics) {
+            diags.push({ gate: 'review', code: d.code, severity: d.severity, message: d.message });
+        }
+    }
+    return { ok: diags.every((d) => d.severity !== 'error'), diagnostics: diags };
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Document Engine — public entry point.
+ * Exports schemas, LLM interface, paths, and (as implemented) the pipeline.
+ */
+export * from './schemas.js';
+export * from './llm.js';
+export * from './paths.js';

package/dist/core/document/index.js

@@ -0,0 +1,7 @@
+/**
+ * Document Engine — public entry point.
+ * Exports schemas, LLM interface, paths, and (as implemented) the pipeline.
+ */
+export * from './schemas.js';
+export * from './llm.js';
+export * from './paths.js';

package/dist/core/document/input-digest.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Document Engine — Pass 0.5 input compression + source segmentation (decision 8·P0-A, decision 9).
+ *
+ * Long inputs are split into stable segments (seg id → original file + line range),
+ * each segment is compressed in a bounded-context LLM call, then segment digests are
+ * merged into a global input digest (~1–2k tokens). Pass 1 generates the outline from the
+ * global digest; Pass 2 pulls original detail by `source_segments` from the segment index.
+ */
+import type { DocumentLLM } from './llm.js';
+export interface InputSegment {
+    id: string;
+    type: string;
+    label: string;
+    source: string;
+    startLine: number;
+    endLine: number;
+    content: string;
+}
+export interface SegmentDigest {
+    id: string;
+    type: string;
+    label: string;
+    summary: string;
+    entity_candidates: string[];
+}
+export interface GlobalInputDigest {
+    segments: SegmentDigest[];
+    summary: string;
+}
+export interface SegmentIndex {
+    schema: 'specflow.document.segments/v1';
+    segments: Array<{
+        id: string;
+        type: string;
+        label: string;
+        source: string;
+        startLine: number;
+        endLine: number;
+    }>;
+}
+export interface SegmentableInput {
+    type: string;
+    source: string;
+    content: string;
+}
+export declare function segmentInputs(inputs: SegmentableInput[]): InputSegment[];
+export declare function compressSegment(seg: InputSegment, llm: DocumentLLM): Promise<SegmentDigest>;
+/** Heuristic entity-candidate extraction: backtick tokens + PascalCase/snake tokens. */
+export declare function extractEntityCandidates(text: string): string[];
+export declare function mergeSegmentDigests(digests: SegmentDigest[], llm: DocumentLLM): Promise<GlobalInputDigest>;
+export declare function writeSegmentIndex(workRoot: string, segments: InputSegment[]): Promise<string>;
+export declare function readSegmentIndex(workRoot: string): Promise<SegmentIndex>;
+/** Fetch original text for a set of source_segments (bounded, decision 9). */
+export declare function fetchSegments(workRoot: string, segmentIds: string[]): Promise<string>;
+export declare function compressInputs(workRoot: string, inputs: SegmentableInput[], llm: DocumentLLM): Promise<GlobalInputDigest>;