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

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

@@ -0,0 +1,63 @@
+/**
+ * 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;
+    /** Multi-repo source repo name (synthesize). When set, segment ids carry `<repo>` so outline
+     *  points can reference "repo1 的提案段" and Pass 2 fetches only the involved repo's原文. */
+    repo?: string;
+}
+/**
+ * 按实际累计字符数切分（P2）：此前按「20 行/段」切分，单条超长行会击穿 4000 字符预算，
+ * 中文短行则浪费预算。现在累计字符达到预算即开新段；单条超长行强制单独成段。
+ * 同时记录行号区间（startLine/endLine）供 Pass 2 fetchSegments 取原文。
+ */
+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>;

package/dist/core/document/input-digest.js

@@ -0,0 +1,200 @@
+/**
+ * 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 { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { segmentIndexPath } from './paths.js';
+const SEGMENT_CHAR_BUDGET = 4000; // ~1-2k tokens per segment, bounded context
+/**
+ * 按实际累计字符数切分（P2）：此前按「20 行/段」切分，单条超长行会击穿 4000 字符预算，
+ * 中文短行则浪费预算。现在累计字符达到预算即开新段；单条超长行强制单独成段。
+ * 同时记录行号区间（startLine/endLine）供 Pass 2 fetchSegments 取原文。
+ */
+export function segmentInputs(inputs) {
+    const segments = [];
+    for (const input of inputs) {
+        const lines = input.content.split('\n');
+        const chunks = [];
+        let current = [];
+        let currentChars = 0;
+        let currentStart = 1;
+        for (let li = 0; li < lines.length; li++) {
+            const line = lines[li];
+            // 单条超长行强制按字符切分（P2）：否则一条 10000 字符行永远单独成段击穿预算。
+            if (current.length === 0 && line.length + 1 > SEGMENT_CHAR_BUDGET) {
+                for (let ci = 0; ci < line.length; ci += SEGMENT_CHAR_BUDGET) {
+                    chunks.push({ lines: [line.slice(ci, ci + SEGMENT_CHAR_BUDGET)], startLine: li + 1 });
+                }
+                continue;
+            }
+            if (current.length > 0 && currentChars + line.length + 1 > SEGMENT_CHAR_BUDGET) {
+                chunks.push({ lines: current, startLine: currentStart });
+                current = [];
+                currentChars = 0;
+                currentStart = li + 1;
+            }
+            current.push(line);
+            currentChars += line.length + 1;
+            if (currentChars >= SEGMENT_CHAR_BUDGET) {
+                chunks.push({ lines: current, startLine: currentStart });
+                current = [];
+                currentChars = 0;
+                currentStart = li + 2;
+            }
+        }
+        if (current.length > 0)
+            chunks.push({ lines: current, startLine: currentStart });
+        if (chunks.length === 0)
+            chunks.push({ lines: [''], startLine: 1 });
+        for (const chunk of chunks) {
+            const idx = segments.length + 1;
+            // Segment id carries the repo prefix (e.g. `seg-repo1-proposal-01`) so multi-repo
+            // synthesis can trace which repo a segment belongs to across Pass 0.5 → Pass 2.
+            const repoPrefix = input.repo ? `${input.repo}-` : '';
+            segments.push({
+                id: `seg-${repoPrefix}${input.type}-${String(idx).padStart(2, '0')}`,
+                type: input.type,
+                label: `${input.repo ? `${input.repo} · ` : ''}${input.type} #${idx}`,
+                source: input.source,
+                startLine: chunk.startLine,
+                endLine: chunk.startLine + chunk.lines.length - 1,
+                content: chunk.lines.join('\n'),
+            });
+        }
+    }
+    return segments;
+}
+// ============= Compression (T4.2) =============
+const COMPRESS_SYSTEM = '你是长文档输入压缩器。将给定原文段压缩为紧凑摘要，保留：关键实体名（接口/表/页面）、决策线索、约束、来源仓标记（如「来源仓：repo1」）。不要复述细节，只要提炼。';
+export async function compressSegment(seg, llm) {
+    const input = {
+        system: COMPRESS_SYSTEM,
+        messages: [{ role: 'user', content: `段 ${seg.id}（${seg.label}）：\n${seg.content}` }],
+    };
+    const summary = (await llm.complete(input)).content.trim();
+    return {
+        id: seg.id,
+        type: seg.type,
+        label: seg.label,
+        summary,
+        entity_candidates: extractEntityCandidates(summary),
+    };
+}
+/** Heuristic entity-candidate extraction: backtick tokens + PascalCase/snake tokens. */
+export function extractEntityCandidates(text) {
+    const out = new Set();
+    for (const m of text.matchAll(/`([^`]+)`/g))
+        out.add(m[1].trim());
+    for (const m of text.matchAll(/\b([A-Z][A-Za-z0-9]{2,})\b/g))
+        out.add(m[1]);
+    return [...out];
+}
+// ============= Merge (T4.3) =============
+const MERGE_SYSTEM = '你是长文档输入压缩合并器。将多段摘要合并为一份全局摘要（~1-2k token），保留各段 id、实体候选与关键约束，不丢失任何段。';
+export async function mergeSegmentDigests(digests, llm) {
+    const payload = digests.map((d) => `[${d.id}] ${d.summary}`).join('\n\n');
+    const input = {
+        system: MERGE_SYSTEM,
+        messages: [{ role: 'user', content: payload }],
+    };
+    const summary = (await llm.complete(input)).content.trim();
+    return { segments: digests, summary };
+}
+// ============= Segment index (T4.4) =============
+export async function writeSegmentIndex(workRoot, segments) {
+    const index = {
+        schema: 'specflow.document.segments/v1',
+        segments: segments.map((s) => ({
+            id: s.id,
+            type: s.type,
+            label: s.label,
+            source: s.source,
+            startLine: s.startLine,
+            endLine: s.endLine,
+        })),
+    };
+    const path = segmentIndexPath(workRoot);
+    await fs.mkdir(join(workRoot, 'segments'), { recursive: true });
+    await fs.writeFile(path, JSON.stringify(index, null, 2), 'utf-8');
+    return path;
+}
+export async function readSegmentIndex(workRoot) {
+    const raw = JSON.parse(await fs.readFile(segmentIndexPath(workRoot), 'utf-8'));
+    // 运行时 schema 校验（P2）：防止截断/被篡改的索引产生裸 TypeError 或注入任意路径。
+    if (!raw || typeof raw !== 'object' || raw.schema !== 'specflow.document.segments/v1' || !Array.isArray(raw.segments)) {
+        throw new Error(`Invalid segment index at ${segmentIndexPath(workRoot)}: schema or segments missing`);
+    }
+    return raw;
+}
+/** Fetch original text for a set of source_segments (bounded, decision 9). */
+export async function fetchSegments(workRoot, segmentIds) {
+    const index = await readSegmentIndex(workRoot);
+    const wanted = new Set(segmentIds);
+    const matched = index.segments.filter((s) => wanted.has(s.id));
+    const parts = [];
+    for (const s of matched) {
+        parts.push(`[${s.id} · ${s.label}] ${s.source} ${s.startLine}-${s.endLine}`);
+        // source 来自引擎写入的段索引（由显式输入文件构成）。读取前做基础校验：
+        // 拒绝空串与明显越界的相对路径；绝对路径（--code 显式输入）放行。
+        if (!s.source || s.source.includes('\0')) {
+            parts.push('(原文路径非法，使用段摘要)');
+            continue;
+        }
+        try {
+            const text = await fs.readFile(s.source, 'utf-8');
+            const lines = text.split('\n').slice(Math.max(0, s.startLine - 1), s.endLine);
+            parts.push(lines.join('\n'));
+        }
+        catch {
+            parts.push('(原文不可读，使用段摘要)');
+        }
+    }
+    return parts.join('\n\n');
+}
+// ============= Top-level orchestration (T4.x entry) =============
+const MAX_CONCURRENT_COMPRESS = 4; // 并发压缩上限（P2）
+/** 段级压缩：失败回退「原文摘要」并记录诊断（P2），不中断整个生成。 */
+async function compressSegmentSafe(seg, llm) {
+    try {
+        return await compressSegment(seg, llm);
+    }
+    catch (e) {
+        // 降级：压缩失败时用原文截断作摘要（保留事实，避免全盘失败）。
+        return {
+            id: seg.id,
+            type: seg.type,
+            label: seg.label,
+            summary: `（压缩失败，使用原文摘要）${seg.content.slice(0, 800)}`,
+            entity_candidates: extractEntityCandidates(seg.content),
+        };
+    }
+}
+export async function compressInputs(workRoot, inputs, llm) {
+    const segments = segmentInputs(inputs);
+    await writeSegmentIndex(workRoot, segments);
+    // 并发压缩（P2）：段与段无依赖，串行是主耗时点；带上限并行避免打爆限流。
+    const digests = [];
+    for (let i = 0; i < segments.length; i += MAX_CONCURRENT_COMPRESS) {
+        const batch = segments.slice(i, i + MAX_CONCURRENT_COMPRESS);
+        const batchResults = await Promise.all(batch.map((seg) => compressSegmentSafe(seg, llm)));
+        digests.push(...batchResults);
+    }
+    if (digests.length === 0) {
+        return { segments: [], summary: '' };
+    }
+    try {
+        return await mergeSegmentDigests(digests, llm);
+    }
+    catch {
+        // 合并失败：回退为拼接摘要（不中断）。
+        return {
+            segments: digests,
+            summary: digests.map((d) => `[${d.id}] ${d.summary}`).join('\n\n'),
+        };
+    }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Document Engine — input feature registry + `when` DSL + content-based feature detection.
+ *
+ * `when` expression grammar (design §3.1, decision 9):
+ *   term      := "input." <feature> | "(" expr ")" | "!" term
+ *   and-or    := term (("&&" | "||") term)*
+ * Built-in features: containsApiChange, hasPersistence, uiInScope, hasLogic, hasBackend, includeSignoff.
+ * Unknown features surface as validation warnings (T2.3).
+ *
+ * Feature VALUES are derived by `detectInputFeatures` (deterministic keyword scoring over the
+ * input text + file-type hints), NOT hardcoded booleans — so e.g. `uiInScope` can actually
+ * become true when the input mentions UI, and `document plan/run` selects chapters such as
+ * `ui-design` accordingly.
+ */
+import type { SegmentableInput } from './input-digest.js';
+export declare const INPUT_FEATURES: readonly ["containsApiChange", "hasPersistence", "uiInScope", "hasLogic", "hasBackend", "includeSignoff"];
+export type InputFeatureMap = Record<string, boolean>;
+export declare function isKnownFeature(name: string): boolean;
+/**
+ * Detect input features deterministically from the input content (+ file-type hints).
+ *
+ * - `containsApiChange` / `hasPersistence`: file-type hints (design/specs typically carry API
+ *   surface / persistence) OR content keywords.
+ * - `uiInScope`: content only — the file type cannot reveal UI scope (was previously hardcoded
+ *   `false`, which made `ui-design` unreachable).
+ * - `hasBackend`: content keywords (后端/接口/数据库/服务端…) — distinguishes fullstack from
+ *   pure-frontend variants (F1 §2.4).
+ * - `hasLogic`: content keywords, with a lenient default of true for any non-empty input —
+ *   a false negative would silently drop core optional chapters (architecture / test-strategy)
+ *   whose `when: input.hasLogic`.
+ */
+export declare function detectInputFeatures(inputs: SegmentableInput[]): InputFeatureMap;
+/** Tokenize a when expression into a simple AST via recursive descent. */
+export interface WhenExpr {
+    op: 'and' | 'or' | 'not' | 'feature';
+    feature?: string;
+    left?: WhenExpr;
+    right?: WhenExpr;
+}
+export declare function parseWhen(expr: string): WhenExpr;
+export declare function evaluateWhen(expr: string, features: InputFeatureMap): boolean;
+/** Collect feature names referenced in a when expression (for T2.3 validation). */
+export declare function featuresInWhen(expr: string): string[];

package/dist/core/document/input-features.js

@@ -0,0 +1,161 @@
+/**
+ * Document Engine — input feature registry + `when` DSL + content-based feature detection.
+ *
+ * `when` expression grammar (design §3.1, decision 9):
+ *   term      := "input." <feature> | "(" expr ")" | "!" term
+ *   and-or    := term (("&&" | "||") term)*
+ * Built-in features: containsApiChange, hasPersistence, uiInScope, hasLogic, hasBackend, includeSignoff.
+ * Unknown features surface as validation warnings (T2.3).
+ *
+ * Feature VALUES are derived by `detectInputFeatures` (deterministic keyword scoring over the
+ * input text + file-type hints), NOT hardcoded booleans — so e.g. `uiInScope` can actually
+ * become true when the input mentions UI, and `document plan/run` selects chapters such as
+ * `ui-design` accordingly.
+ */
+export const INPUT_FEATURES = [
+    'containsApiChange',
+    'hasPersistence',
+    'uiInScope',
+    'hasLogic',
+    'hasBackend',
+    'includeSignoff',
+];
+export function isKnownFeature(name) {
+    return INPUT_FEATURES.includes(name);
+}
+// ============= Content-based feature detection (decision 8 · P1-J) =============
+/** Deterministic keyword groups per feature. Short ASCII keywords are matched at word
+ *  boundaries (`\bapp\b` does not match "approach"); CJK keywords are plain substring. */
+const FEATURE_KEYWORDS = {
+    containsApiChange: ['接口', 'api', 'endpoint', 'rest', 'http', 'proto', '请求', '响应', '鉴权', '错误码', '路由'],
+    hasPersistence: ['数据库', 'database', '存储', '持久化', '数据模型', '表结构', 'ddl', 'mysql', 'postgres', 'sqlite', 'redis', 'mongodb', '缓存'],
+    uiInScope: ['前端', 'ui', '页面', '界面', '交互', '按钮', '表单', '弹窗', '样式', '小程序', 'h5', '移动端', 'dashboard', 'frontend', '可视化'],
+    hasLogic: ['逻辑', '算法', '规则', '计算', '流程', '校验', '判断', '状态机', 'algorithm'],
+    hasBackend: ['后端', '服务端', '服务器', '接口', 'api', 'rest', '数据库', '微服务', 'backend', 'server', 'daemon', '后台', '网关'],
+};
+function hasAnyKeyword(text, keywords) {
+    return keywords.some((kw) => {
+        if (/^[A-Za-z0-9_.-]+$/.test(kw)) {
+            // Word-boundary match for Latin keywords ("app" ≠ "approach", "ui" ≠ "require").
+            return new RegExp(`\\b${kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(text);
+        }
+        return text.includes(kw);
+    });
+}
+/**
+ * Detect input features deterministically from the input content (+ file-type hints).
+ *
+ * - `containsApiChange` / `hasPersistence`: file-type hints (design/specs typically carry API
+ *   surface / persistence) OR content keywords.
+ * - `uiInScope`: content only — the file type cannot reveal UI scope (was previously hardcoded
+ *   `false`, which made `ui-design` unreachable).
+ * - `hasBackend`: content keywords (后端/接口/数据库/服务端…) — distinguishes fullstack from
+ *   pure-frontend variants (F1 §2.4).
+ * - `hasLogic`: content keywords, with a lenient default of true for any non-empty input —
+ *   a false negative would silently drop core optional chapters (architecture / test-strategy)
+ *   whose `when: input.hasLogic`.
+ */
+export function detectInputFeatures(inputs) {
+    const text = inputs.map((i) => i.content).join('\n').toLowerCase();
+    const types = new Set(inputs.map((i) => i.type));
+    return {
+        containsApiChange: types.has('design') || types.has('specs') || hasAnyKeyword(text, FEATURE_KEYWORDS.containsApiChange),
+        hasPersistence: types.has('specs') || hasAnyKeyword(text, FEATURE_KEYWORDS.hasPersistence),
+        uiInScope: hasAnyKeyword(text, FEATURE_KEYWORDS.uiInScope),
+        hasBackend: hasAnyKeyword(text, FEATURE_KEYWORDS.hasBackend),
+        hasLogic: hasAnyKeyword(text, FEATURE_KEYWORDS.hasLogic) || inputs.length > 0,
+    };
+}
+class WhenParser {
+    src;
+    pos = 0;
+    constructor(src) {
+        this.src = src;
+        this.src = src.replace(/\s+/g, '');
+    }
+    parse() {
+        const expr = this.parseOr();
+        if (this.pos < this.src.length) {
+            throw new Error(`WhenParser: unexpected token at ${this.pos}: "${this.src.slice(this.pos)}"`);
+        }
+        return expr;
+    }
+    parseOr() {
+        let left = this.parseAnd();
+        while (this.peek('||')) {
+            this.pos += 2;
+            left = { op: 'or', left, right: this.parseAnd() };
+        }
+        return left;
+    }
+    parseAnd() {
+        let left = this.parseNot();
+        while (this.peek('&&')) {
+            this.pos += 2;
+            left = { op: 'and', left, right: this.parseNot() };
+        }
+        return left;
+    }
+    parseNot() {
+        if (this.peek('!')) {
+            this.pos += 1;
+            return { op: 'not', right: this.parseNot() };
+        }
+        if (this.peek('(')) {
+            this.pos += 1;
+            const inner = this.parseOr();
+            if (!this.peek(')'))
+                throw new Error('WhenParser: missing ")"');
+            this.pos += 1;
+            return inner;
+        }
+        return this.parseFeature();
+    }
+    parseFeature() {
+        const m = this.src.slice(this.pos).match(/^input\.[A-Za-z_][A-Za-z0-9_]*/);
+        if (!m)
+            throw new Error(`WhenParser: expected input.<feature> at "${this.src.slice(this.pos)}"`);
+        this.pos += m[0].length;
+        return { op: 'feature', feature: m[0].slice('input.'.length) };
+    }
+    peek(token) {
+        return this.src.startsWith(token, this.pos);
+    }
+}
+export function parseWhen(expr) {
+    if (!expr || !expr.trim())
+        throw new Error('WhenParser: empty expression');
+    return new WhenParser(expr).parse();
+}
+export function evaluateWhen(expr, features) {
+    const ast = parseWhen(expr);
+    return evalNode(ast, features);
+}
+function evalNode(node, features) {
+    switch (node.op) {
+        case 'feature':
+            return features[node.feature] === true;
+        case 'not':
+            return !evalNode(node.right, features);
+        case 'and':
+            return evalNode(node.left, features) && evalNode(node.right, features);
+        case 'or':
+            return evalNode(node.left, features) || evalNode(node.right, features);
+        default:
+            return false;
+    }
+}
+/** Collect feature names referenced in a when expression (for T2.3 validation). */
+export function featuresInWhen(expr) {
+    const out = [];
+    walk(parseWhen(expr), out);
+    return out;
+}
+function walk(node, acc) {
+    if (node.op === 'feature')
+        acc.push(node.feature);
+    if (node.left)
+        walk(node.left, acc);
+    if (node.right)
+        walk(node.right, acc);
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Document Engine — lint: reference checks, stub detection, budget checks (decision 6).
+ */
+export interface LintDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    chapter?: string;
+}
+export interface LintOptions {
+    /** Minimum meaningful content length for narrative (default 20). */
+    minNarrativeChars?: number;
+}
+export declare function lintNarrative(chapterId: string, narrative: string, options?: LintOptions): LintDiagnostic[];
+export interface BudgetDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    chapter?: string;
+}
+/** Check chapter output against per-chapter budget (decision 6/P6). */
+export declare function checkBudget(chapterId: string, tokens: number, budgetTokens?: number): BudgetDiagnostic[];
+export declare function checkNumericPresence(chapterId: string, narrative: string, gates?: readonly string[]): DiagramLintDiagnostic[];
+export interface DiagramLintDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    chapter?: string;
+}
+/** Check that a chapter's narrative satisfies its diagram gates (README §1.7). */
+export declare function checkDiagramPresence(chapterId: string, narrative: string, gates?: readonly string[]): DiagramLintDiagnostic[];
+export declare function checkGoldenSignals(chapterId: string, narrative: string, gates?: readonly string[]): DiagramLintDiagnostic[];
+export interface RepoSectionDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    chapter?: string;
+}
+export declare function checkRepoSectionCoverage(chapterId: string, narrative: string, repos: readonly string[]): RepoSectionDiagnostic[];

package/dist/core/document/lint.js

@@ -0,0 +1,147 @@
+/**
+ * Document Engine — lint: reference checks, stub detection, budget checks (decision 6).
+ */
+import { findForbiddenMatch, findInconsistencyHints } from './forbidden-patterns.js';
+export function lintNarrative(chapterId, narrative, options = {}) {
+    const diags = [];
+    const min = options.minNarrativeChars ?? 20;
+    const trimmed = narrative.trim();
+    if (trimmed.length < min) {
+        diags.push({ code: 'narrative_too_short', severity: 'error', chapter: chapterId, message: `Chapter "${chapterId}" narrative too short (< ${min} chars)` });
+    }
+    const forbidden = findForbiddenMatch(trimmed);
+    if (forbidden) {
+        diags.push({ code: 'forbidden_pattern', severity: 'error', chapter: chapterId, message: `Chapter "${chapterId}": forbidden stub pattern (${forbidden.source})` });
+    }
+    for (const hint of findInconsistencyHints(trimmed)) {
+        diags.push({ code: 'inconsistency_hint', severity: 'warning', chapter: chapterId, message: `Chapter "${chapterId}": possible inconsistency (${hint.source})` });
+    }
+    return diags;
+}
+/** Check chapter output against per-chapter budget (decision 6/P6). */
+export function checkBudget(chapterId, tokens, budgetTokens) {
+    if (budgetTokens === undefined)
+        return [];
+    if (tokens > budgetTokens) {
+        return [{ code: 'budget_exceeded', severity: 'error', chapter: chapterId, message: `Chapter "${chapterId}" ${tokens} tokens exceeds budget ${budgetTokens}` }];
+    }
+    return [];
+}
+// ============= Numeric-presence lint (反AI决策 #2 · 数字门禁确定性化) =============
+//
+// Chapters whose `gates` demand concrete numbers (原始测量值 / 给数字 — e.g. F5 benchmark
+// 与 research) must contain at least one digit in the narrative. Turns the prompt-level
+// "数字门禁" into a validate-able rule for the most number-dependent chapters.
+const DIGIT_RE = /\d/;
+export function checkNumericPresence(chapterId, narrative, gates = []) {
+    const joinedGates = gates.join(' ');
+    const wantsNumbers = /原始测量值|给数字/.test(joinedGates);
+    if (!wantsNumbers)
+        return [];
+    if (!DIGIT_RE.test(narrative)) {
+        return [{
+                code: 'number_gate_missing',
+                severity: 'error',
+                chapter: chapterId,
+                message: `Chapter "${chapterId}" gates require concrete numbers (原始测量值/给数字) but narrative contains no digits`,
+            }];
+    }
+    return [];
+}
+/**
+ * Fresh non-global copies of the diagram regexes. The module-level `/g` regexes are
+ * stateful (`.test()` advances `lastIndex`), so calling them for consecutive chapters with
+ * diagrams (e.g. frontend-architecture graph then core-flow sequence) could miss matches.
+ * `runGates` iterates chapters in order, so a stale `lastIndex` from a previous chapter's
+ * mermaid graph would leak into the next chapter's check. Use per-call copies to stay
+ * deterministic.
+ */
+function freshMermaidRE() { return /```mermaid\s*[\s\S]*?```/gi; }
+// 允许 `%%` 注释 / `%%{init:{...}}%%` 指令出现在 sequenceDiagram 之前（P2：合法的 mermaid 时序图
+// 常以 init 指令开头，之前会被误报 sequence_diagram_missing）。
+function freshSequenceRE() { return /```mermaid\s*(?:%%[^\n]*\n|\s)*sequenceDiagram[\s\S]*?```/gi; }
+/** Check that a chapter's narrative satisfies its diagram gates (README §1.7). */
+export function checkDiagramPresence(chapterId, narrative, gates = []) {
+    const diags = [];
+    const joinedGates = gates.join(' ');
+    const wantsMermaid = /mermaid/i.test(joinedGates);
+    const wantsSequence = /时序图|sequence/i.test(joinedGates);
+    if (!wantsMermaid && !wantsSequence)
+        return diags; // no diagram gate → no check
+    const hasMermaidBlock = freshMermaidRE().test(narrative);
+    if (wantsMermaid && !hasMermaidBlock) {
+        diags.push({
+            code: 'diagram_missing',
+            severity: 'error',
+            chapter: chapterId,
+            message: `Chapter "${chapterId}" gates require a Mermaid diagram but none found (missing \`\`\`mermaid block)`,
+        });
+        return diags;
+    }
+    if (wantsSequence && !freshSequenceRE().test(narrative)) {
+        diags.push({
+            code: 'sequence_diagram_missing',
+            severity: 'error',
+            chapter: chapterId,
+            message: `Chapter "${chapterId}" gates require a sequence diagram (sequenceDiagram) but none found`,
+        });
+    }
+    // "图必须有文字说明": the narrative must contain text OUTSIDE the mermaid block(s).
+    const withoutMermaid = narrative.replace(freshMermaidRE(), '').trim();
+    if (hasMermaidBlock && withoutMermaid.length === 0) {
+        diags.push({
+            code: 'diagram_without_text',
+            severity: 'error',
+            chapter: chapterId,
+            message: `Chapter "${chapterId}" contains only a diagram with no textual explanation (图必须有文字说明)`,
+        });
+    }
+    return diags;
+}
+// ============= Ops golden-signals presence lint (SRE 四金信号，f1-0to1.md §2.6.3) =============
+//
+// A chapter whose `gates` reference 四金信号 must name all four golden signals in the narrative
+// (延迟/流量/错误/饱和度); a missing one surfaces as a warning (per f1 §2.6.3: 缺一报 warning).
+const GOLDEN_SIGNALS = [
+    { key: '延迟', aliases: ['延迟', 'latency', '耗时', '响应时间', 'p95', 'lcp'] },
+    { key: '流量', aliases: ['流量', 'traffic', 'qps', '请求量', '吞吐', 'rps'] },
+    { key: '错误', aliases: ['错误率', 'errors', 'error rate', '5xx', '4xx'] },
+    // 饱和度用强信号（P2）：cpu/内存/连接数 作为独立提及常出现于排障段，不代表监控覆盖。
+    { key: '饱和度', aliases: ['饱和度', 'saturation', '资源使用率'] },
+];
+export function checkGoldenSignals(chapterId, narrative, gates = []) {
+    const joinedGates = gates.join(' ');
+    if (!/四金信号|golden signals/i.test(joinedGates))
+        return [];
+    const lower = narrative.toLowerCase();
+    const missing = GOLDEN_SIGNALS.filter((s) => !s.aliases.some((a) => lower.includes(a)));
+    if (missing.length === 0)
+        return [];
+    return [{
+            code: 'golden_signal_missing',
+            severity: 'warning',
+            chapter: chapterId,
+            message: `Chapter "${chapterId}" gates require SRE 四金信号 monitoring but missing: ${missing.map((m) => m.key).join('、')}（监控必须覆盖延迟/流量/错误/饱和度）`,
+        }];
+}
+export function checkRepoSectionCoverage(chapterId, narrative, repos) {
+    if (repos.length < 2)
+        return []; // 非 synthesize 或单仓 → 不校验
+    const diags = [];
+    for (const repo of repos) {
+        // 匹配 `### <repo>` 小节标题（行首，可带后缀如 `### repo1 · 目标`）
+        const sectionRe = new RegExp(`^###\\s+${escapeRegExp(repo)}(?:\\s|：|:|·|$)`, 'm');
+        if (!sectionRe.test(narrative)) {
+            diags.push({
+                code: 'repo_section_missing',
+                severity: 'error',
+                chapter: chapterId,
+                message: `Chapter "${chapterId}" 缺少仓 ${repo} 的分仓小节（应含 \`### ${repo}\`，合成文档每章必须按仓分节，防止跨仓内容互相稀释）`,
+            });
+        }
+    }
+    return diags;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}