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

package/dist/core/artifact-language.js

@@ -18,13 +18,23 @@ export function requireArtifactLanguage(value) {
 }
 export function renderArtifactLanguageGuidance(language) {
     const narrativeLanguage = language === 'zh-CN' ? 'Simplified Chinese' : 'English';
+    const styleLines = language === 'zh-CN'
+        ? [
+            'Chinese narrative must be brief: one idea per sentence; no filler.',
+            'Write how-to / process / handling as numbered 1. 2. 3. steps (one sentence each).',
+            'Do not collapse multi-step flows into a paragraph.',
+            'Leave tables, Mermaid, DDL, HTTP examples, and protocol markers unchanged.',
+        ]
+        : ['Keep narrative concise. Use numbered steps for how-to. Leave tables and diagrams unchanged.'];
     return [
         '## Artifact language policy',
         '',
         `Write all non-protocol business content in ${narrativeLanguage}.`,
-        'This includes proposal narrative, requirement and scenario descriptions, text after WHEN/THEN, design rationale, and task descriptions.',
+        'This includes proposal narrative, requirement and scenario descriptions, text after WHEN/THEN, design rationale, task descriptions, explore, and approval.',
         'Do not mix narrative languages in the same artifact.',
         '',
+        ...styleLines,
+        '',
         'Keep SpecFlow protocol markers unchanged, including:',
         '- `ADDED Requirements`, `MODIFIED Requirements`, `REMOVED Requirements`, and `RENAMED Requirements`',
         '- `Requirement:`, `Scenario:`, `WHEN`, and `THEN`',

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

@@ -0,0 +1,6 @@
+/**
+ * Document Engine — chapter component library loader.
+ * Loads templates/document/chapters/*.yaml, validates each parses, returns a Map.
+ */
+import { ChapterComponent } from './schemas.js';
+export declare function loadChapterLibrary(dir?: string): Promise<Map<string, ChapterComponent>>;

package/dist/core/document/chapters.js

@@ -0,0 +1,21 @@
+/**
+ * Document Engine — chapter component library loader.
+ * Loads templates/document/chapters/*.yaml, validates each parses, returns a Map.
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+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 lib = new Map();
+    for (const file of entries) {
+        if (!file.endsWith('.yaml') && !file.endsWith('.yml'))
+            continue;
+        const raw = yaml.load(await fs.readFile(join(dir, file), 'utf-8'));
+        const ch = parseChapterComponent(raw);
+        lib.set(ch.id, ch);
+    }
+    return lib;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Document Engine — coverage completeness (decision 8·P1-B + decision 9·kind).
+ *
+ * Two channels:
+ *  - Structured (at generation): for kind=entity|mixed points, referenced entity ids must appear
+ *    in the chapter's structured entity contribution.
+ *  - Semantic (at review R14): for kind=narrative|mixed points, produces a checklist consumed by
+ *    the reviewer to verify the corresponding section exists and is non-stub.
+ */
+import { Outline, Entities } from './schemas.js';
+export interface CoverageDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    chapter?: string;
+    point?: string;
+}
+/** Structured channel: verify referenced entities are present in the chapter's entity contribution. */
+export declare function checkStructuredCoverage(outline: Outline, chapterEntities: Map<string, Entities>): CoverageDiagnostic[];
+/** Semantic checklist for reviewer (R14): narrative|mixed points → must have a non-stub section. */
+export declare function semanticCoverageChecklist(outline: Outline): Array<{
+    chapter: string;
+    pointId: string;
+    text: string;
+}>;

package/dist/core/document/coverage.js

@@ -0,0 +1,49 @@
+/**
+ * Document Engine — coverage completeness (decision 8·P1-B + decision 9·kind).
+ *
+ * Two channels:
+ *  - Structured (at generation): for kind=entity|mixed points, referenced entity ids must appear
+ *    in the chapter's structured entity contribution.
+ *  - Semantic (at review R14): for kind=narrative|mixed points, produces a checklist consumed by
+ *    the reviewer to verify the corresponding section exists and is non-stub.
+ */
+/** Structured channel: verify referenced entities are present in the chapter's entity contribution. */
+export function checkStructuredCoverage(outline, chapterEntities) {
+    const diags = [];
+    for (const ch of outline.chapters) {
+        const ents = chapterEntities.get(ch.id) ?? { interfaces: [], tables: [], decisions: [] };
+        const present = new Set([
+            ...ents.interfaces.map((i) => i.id),
+            ...ents.tables.map((t) => t.id),
+            ...ents.decisions.map((d) => d.id),
+        ]);
+        for (const p of ch.points) {
+            if (p.kind === 'narrative')
+                continue; // narrative → semantic channel only
+            for (const ref of p.references ?? []) {
+                if (!present.has(ref)) {
+                    diags.push({
+                        code: 'entity_not_filled',
+                        severity: 'error',
+                        chapter: ch.id,
+                        point: p.id,
+                        message: `Point "${p.id}" references entity "${ref}" but chapter "${ch.id}" has no such entity`,
+                    });
+                }
+            }
+        }
+    }
+    return diags;
+}
+/** Semantic checklist for reviewer (R14): narrative|mixed points → must have a non-stub section. */
+export function semanticCoverageChecklist(outline) {
+    const list = [];
+    for (const ch of outline.chapters) {
+        for (const p of ch.points) {
+            if (p.kind === 'narrative' || p.kind === 'mixed') {
+                list.push({ chapter: ch.id, pointId: p.id, text: p.text });
+            }
+        }
+    }
+    return list;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Document Engine — dependency digests (decisions 2 + 8·P1-D + 9).
+ *
+ *  - extractConstraintList: deterministic constraint items (entity/decision/point ids) that a
+ *    chapter's digest MUST preserve (decision 8).
+ *  - generateDigest: bounded LLM summary carrying the constraint list; deterministic fallback.
+ *  - lintDigest: bidirectional lint — forward (digest ids exist in source) + reverse (constraint
+ *    items present in digest).
+ *  - recordDigestSources / affectedDownstream: invalidation propagation (decision 9).
+ */
+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;
+    chapterTitle: string;
+    source: string;
+    constraints: ConstraintItem[];
+}
+export declare function generateDigest(llm: DocumentLLM, input: DigestInput): Promise<string>;
+/** Deterministic fallback: render entity registry as a one-line digest. */
+export declare function deterministicDigest(entities: Entities, ids: string[]): string;
+export interface DigestLintDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+}
+export declare function lintDigest(digest: string, constraints: ConstraintItem[], knownEntityIds: Set<string>): DigestLintDiagnostic[];
+export interface DigestSource {
+    chapterId: string;
+    /** entity ids this digest depends on (for granular invalidation). */
+    entityIds: string[];
+}
+export declare function recordDigestSources(chapter: OutlineChapter, sourceEntities: Entities): DigestSource;
+/**
+ * Given a changed chapter, return the set of downstream chapters whose digests are invalidated.
+ * (decision 9): only direct dependents whose digest references one of the changed entities are
+ * invalidated. Outline change → caller passes allDownstream (full invalidation).
+ */
+export declare function affectedDownstream(changedChapterId: string, changedEntityIds: string[], downstreamSources: DigestSource[]): string[];

package/dist/core/document/digests.js

@@ -0,0 +1,136 @@
+/**
+ * Document Engine — dependency digests (decisions 2 + 8·P1-D + 9).
+ *
+ *  - extractConstraintList: deterministic constraint items (entity/decision/point ids) that a
+ *    chapter's digest MUST preserve (decision 8).
+ *  - generateDigest: bounded LLM summary carrying the constraint list; deterministic fallback.
+ *  - lintDigest: bidirectional lint — forward (digest ids exist in source) + reverse (constraint
+ *    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 = [];
+    for (const p of chapter.points) {
+        items.push({ kind: 'point', id: p.id, label: p.text.slice(0, 40) });
+        for (const ref of p.references ?? []) {
+            items.push({ kind: 'entity', id: ref, label: ref });
+        }
+    }
+    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) });
+            }
+        }
+    }
+    // dedupe by kind+id
+    const seen = new Set();
+    return items.filter((it) => {
+        const k = `${it.kind}:${it.id}`;
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+}
+// ============= Digest generation (T7.2) =============
+const DIGEST_SYSTEM = '你是依赖摘要生成器。为下游章节生成上游章节的紧凑摘要，必须逐项保留约束清单中的每一项（实体 id / 决策 id / 要点 id 及其一句话含义）。禁止引入上游没有的实体。';
+export async function generateDigest(llm, input) {
+    const constraintText = input.constraints.map((c) => `- ${c.kind} ${c.id}: ${c.label}`).join('\n');
+    const llmInput = {
+        system: DIGEST_SYSTEM,
+        messages: [
+            {
+                role: 'user',
+                content: `上游章节 ${input.chapterId}（${input.chapterTitle}）：\n${input.source.slice(0, 6000)}\n\n必须保留的约束清单：\n${constraintText}`,
+            },
+        ],
+    };
+    const res = await llm.complete(llmInput);
+    return res.content.trim();
+}
+/** Deterministic fallback: render entity registry as a one-line digest. */
+export function deterministicDigest(entities, ids) {
+    const lines = [];
+    for (const it of entities.interfaces) {
+        if (ids.length === 0 || ids.includes(it.id)) {
+            lines.push(`I ${it.id}: ${it.name} ${it.method} ${it.path}`);
+        }
+    }
+    for (const t of entities.tables) {
+        if (ids.length === 0 || ids.includes(t.id)) {
+            lines.push(`T ${t.id}: ${t.name}`);
+        }
+    }
+    for (const d of entities.decisions) {
+        if (ids.length === 0 || ids.includes(d.id)) {
+            lines.push(`D ${d.id}: ${d.text}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function lintDigest(digest, constraints, knownEntityIds) {
+    const diags = [];
+    // Reverse: every constraint item must appear in digest (decision 8).
+    for (const c of constraints) {
+        if (!digest.includes(c.id)) {
+            diags.push({
+                code: 'constraint_missing',
+                severity: 'error',
+                message: `Digest missing constraint ${c.kind} ${c.id} (${c.label})`,
+            });
+        }
+    }
+    // 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.)
+    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))
+        mentioned.add(m[1]);
+    for (const id of mentioned) {
+        if (knownEntityIds.size > 0 && !knownEntityIds.has(id) && !/^I\d+$/.test(id) && !/^T\d+$/.test(id)) {
+            diags.push({
+                code: 'digest_hallucinated_entity',
+                severity: 'warning',
+                message: `Digest mentions unknown entity "${id}"`,
+            });
+        }
+    }
+    return diags;
+}
+export function recordDigestSources(chapter, sourceEntities) {
+    const entityIds = new Set();
+    for (const p of chapter.points) {
+        for (const ref of p.references ?? [])
+            entityIds.add(ref);
+    }
+    // Include referenced entity ids that actually exist in source entities.
+    const known = new Set([
+        ...sourceEntities.interfaces.map((i) => i.id),
+        ...sourceEntities.tables.map((t) => t.id),
+    ]);
+    return {
+        chapterId: chapter.id,
+        entityIds: [...entityIds].filter((id) => known.has(id)),
+    };
+}
+/**
+ * Given a changed chapter, return the set of downstream chapters whose digests are invalidated.
+ * (decision 9): only direct dependents whose digest references one of the changed entities are
+ * invalidated. Outline change → caller passes allDownstream (full invalidation).
+ */
+export function affectedDownstream(changedChapterId, changedEntityIds, downstreamSources) {
+    const changed = new Set(changedEntityIds);
+    const affected = new Set();
+    for (const ds of downstreamSources) {
+        if (ds.chapterId === changedChapterId)
+            continue;
+        if (ds.entityIds.some((id) => changed.has(id)))
+            affected.add(ds.chapterId);
+    }
+    return [...affected];
+}

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

@@ -0,0 +1,92 @@
+/**
+ * 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 { ScenarioProfile, ChapterComponent, Outline } from './schemas.js';
+import type { DocumentLLM } from './llm.js';
+import { SegmentableInput } from './input-digest.js';
+import { expandProfile } from './profiles.js';
+import { GateDiagnostic } from './gates.js';
+export interface RunDocumentOptions {
+    llm: DocumentLLM;
+    workRoot: string;
+    profile: ScenarioProfile;
+    library: Map<string, ChapterComponent>;
+    inputs: SegmentableInput[];
+    inputFeatures: Record<string, boolean>;
+    change: string;
+    outlineOnly?: boolean;
+    /** Skip Pass 3 AI review entirely (fast path; no findings applied, no review-result written). */
+    skipReview?: boolean;
+    /** User confirmation gate for the generated outline (T5.4). If absent, outline is auto-accepted
+     *  (non-interactive / test path). Return true to accept, false to reject (→ regenerate). */
+    outlineConfirmer?: (outline: Outline) => Promise<boolean>;
+    /** Incremental refill (decision 9 · invalidation propagation). When a chapter/entity changed,
+     *  only downstream chapters whose digests reference the changed entities are refilled; unaffected
+     *  chapters are reused from persisted `chapters/<id>.md` when present. Default: full refill. */
+    incremental?: {
+        changedChapterId?: string;
+        changedEntityIds?: string[];
+    };
+    maxRounds?: number;
+    renderHtmlOutput?: boolean;
+    outlinePrompt?: string;
+    reviewPrompt?: string;
+    /** Persist per-chapter files/entities to workRoot (default true). */
+    persist?: boolean;
+}
+export interface RunDocumentResult {
+    ok: boolean;
+    stage: string;
+    outline?: Outline;
+    documentMd?: string;
+    documentHtml?: string;
+    diagnostics: GateDiagnostic[];
+    tokenEstimate?: number;
+}
+export declare function runDocument(options: RunDocumentOptions): Promise<RunDocumentResult>;
+export interface AgentStep {
+    /** stable id: 'input-summary' | 'outline' | 'chapter:<id>' | 'review' */
+    id: string;
+    phase: 'prep' | 'outline' | 'fill' | 'review';
+    title: string;
+    description: string;
+    prompt: string;
+    inputFiles: string[];
+    outputFile: string;
+    required: boolean;
+}
+export interface PlanStepsInput {
+    profile: ScenarioProfile;
+    library: Map<string, ChapterComponent>;
+    inputFeatures: Record<string, boolean>;
+    inputs: SegmentableInput[];
+    workRoot: string;
+    /** Project root to resolve project conventions / IDE rules & skills (approval-era behaviour). */
+    projectRoot?: string;
+}
+/** Map a scene profile to the project-convention topics it should read (approval-era: 项目约定 > guidance > LLM). */
+export declare function sceneTopics(profileId: string): string[];
+export interface PlanStepsResult {
+    steps: AgentStep[];
+    chapters: string[];
+}
+/** Emit the Agent-executable step list (no LLM call — the Agent's IDE model does the work). */
+export declare function planSteps(options: PlanStepsInput): PlanStepsResult;
+export interface ValidateWorkInput {
+    profile: ScenarioProfile;
+    library: Map<string, ChapterComponent>;
+    workRoot: string;
+    renderHtmlOutput?: boolean;
+}
+export interface ValidateWorkResult {
+    ok: boolean;
+    diagnostics: GateDiagnostic[];
+    documentMd?: string;
+    documentHtml?: string;
+}
+/** Read Agent-written artifacts from workRoot, validate (lint/coverage/zod) and render. No LLM. */
+export declare function validateWork(options: ValidateWorkInput): Promise<ValidateWorkResult>;
+export { expandProfile };