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

package/dist/cli/commands/document-run.js

@@ -0,0 +1,845 @@
+/**
+ * CLI: specflow techdoc {plan|validate|run} — Generic LongDoc Engine, IDE-model driven.
+ *
+ * The engine does NOT call a third-party LLM API. In Cursor/Codex the Agent runs on the IDE's
+ * model, so:
+ *   - `document plan <profile>` emits a step list the Agent executes with the IDE model.
+ *   - `document validate --work-root <path>` deterministically validates + renders Agent-written
+ *     artifacts (outline.yaml / chapters/*.md / entities.json) — no LLM call.
+ *   - `document run <profile>` guides: plan → Agent executes → validate (requires injected LLM only
+ *     for library/tests; CLI itself never fetches an API).
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { loadChapterLibrary } from '../../core/document/chapters.js';
+import { loadProfile } from '../../core/document/profiles.js';
+import { runDocument, planSteps, validateWork } from '../../core/document/engine.js';
+import { detectInputFeatures } from '../../core/document/input-features.js';
+import { detectScene, confirmationPrompt } from '../../core/document/scene-detect.js';
+import { reposPath } from '../../core/document/paths.js';
+import { readOutline } from '../../core/document/outline.js';
+async function readInputFile(path, type) {
+    const content = await fs.readFile(path, 'utf-8');
+    return { type, source: path, content };
+}
+/**
+ * 解析 --max-rounds（P2）：commander 以字符串传入，'abc'/'0' 会静默旁路 Pass 3 审查。
+ * 非法或 <1 → 抛错（由命令顶层 catch 转为 exit 1），避免质量门禁被悄悄跳过。
+ */
+function parseMaxRounds(value) {
+    if (value === undefined)
+        return 3;
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new Error(`Invalid --max-rounds "${value}": must be a positive integer`);
+    }
+    return n;
+}
+async function collectInputs(options) {
+    const inputs = [];
+    if (options.text)
+        inputs.push({ type: 'description', source: 'description', content: options.text });
+    if (options.proposal)
+        inputs.push(await readInputFile(options.proposal, 'proposal'));
+    if (options.design)
+        inputs.push(await readInputFile(options.design, 'design'));
+    if (options.specs)
+        inputs.push(await readInputFile(options.specs, 'specs'));
+    if (options.tasks)
+        inputs.push(await readInputFile(options.tasks, 'tasks'));
+    if (options.code)
+        inputs.push(await readInputFile(options.code, 'code'));
+    return inputs;
+}
+function inputFeatures(inputs, opts) {
+    // Content-based detection (deterministic keyword scoring), plus the explicit --signoff flag.
+    // Previously `uiInScope` was hardcoded false and `hasLogic` always true here, which made
+    // `ui-design` unreachable and skipped conditional chapters regardless of the input.
+    return {
+        ...detectInputFeatures(inputs),
+        includeSignoff: opts?.includeSignoff ?? false,
+    };
+}
+function stepsToMarkdown(steps, profileId) {
+    const lines = [
+        `# 文档生成步骤（${profileId}）`,
+        '',
+        '> 请你在当前 IDE 会话中用模型逐步执行以下步骤，产物写入 workRoot。',
+        '> 完成后运行 `specflow techdoc validate --work-root <path>` 校验。',
+        '',
+    ];
+    for (const s of steps) {
+        lines.push(`## ${s.id}（${s.phase}）`, '');
+        lines.push(`**做什么**：${s.description}`, '');
+        lines.push(`**参考提示词**：\`${s.prompt}\``, '');
+        if (s.inputFiles.length)
+            lines.push(`**输入**：${s.inputFiles.join(', ')}`, '');
+        lines.push(`**输出**：\`${s.outputFile}\``, '');
+        lines.push(`**必做**：${s.required ? '是' : '否（可选）'}`, '');
+        lines.push('', '---', '');
+    }
+    return lines.join('\n');
+}
+// ============= document plan =============
+export async function planDocumentCommand(profileId, options) {
+    try {
+        const library = await loadChapterLibrary();
+        const profile = await loadProfile(profileId);
+        const inputs = await collectInputs(options);
+        const workRoot = options.workRoot ?? join(process.cwd(), '.specflow', 'document');
+        await fs.mkdir(workRoot, { recursive: true });
+        const result = planSteps({
+            profile,
+            library,
+            inputFeatures: inputFeatures(inputs, { includeSignoff: options.signoff }),
+            inputs,
+            workRoot,
+            projectRoot: process.cwd(),
+        });
+        const payload = {
+            ok: true,
+            profile: profileId,
+            workRoot,
+            chapters: result.chapters,
+            steps: result.steps,
+        };
+        if (options.json) {
+            return { exitCode: 0, payload };
+        }
+        if (options.markdown) {
+            console.info(stepsToMarkdown(result.steps, profileId));
+            return { exitCode: 0, payload };
+        }
+        console.info(`文档生成步骤（${profileId}），workRoot: ${workRoot}`);
+        console.info('');
+        for (const s of result.steps) {
+            console.info(`  [${s.phase}] ${s.id}: ${s.title}`);
+            console.info(`       → ${s.outputFile}`);
+        }
+        console.info('');
+        console.info('请用 IDE 模型按上述步骤生成产物，然后运行：');
+        console.info(`  specflow techdoc validate --work-root ${workRoot}`);
+        return { exitCode: 0, payload };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json)
+            return { exitCode: 1, payload: { ok: false, error: message } };
+        console.error(`Error: ${message}`);
+        return { exitCode: 1, payload: { ok: false, error: message } };
+    }
+}
+// ============= document validate =============
+export async function validateDocumentCommand(options) {
+    try {
+        const workRoot = options.workRoot ?? join(process.cwd(), '.specflow', 'document');
+        const library = await loadChapterLibrary();
+        // Detect profile from outline.yaml (or require it). 复用 readOutline 的 YAML/JSON 双格式
+        // 解析（P2）：手写正则探测对 JSON 格式/带引号 profile 会误判。
+        const outline = await readOutline(workRoot);
+        const profile = await loadProfile(outline.profile);
+        const result = await validateWork({
+            profile,
+            library,
+            workRoot,
+            renderHtmlOutput: !options.noRender,
+        });
+        const payload = {
+            ok: result.ok,
+            workRoot,
+            document: result.documentMd ? join(workRoot, 'document.md') : undefined,
+            html: result.documentHtml ? join(workRoot, 'document.html') : undefined,
+            diagnostics: result.diagnostics,
+        };
+        if (options.json) {
+            return { exitCode: result.ok ? 0 : 1, payload };
+        }
+        if (!result.ok) {
+            console.error(`Document validation failed:`);
+            for (const d of result.diagnostics) {
+                console.error(`  [${d.gate}][${d.severity}] ${d.message}`);
+            }
+            return { exitCode: 1, payload };
+        }
+        console.info(`Document valid: ${join(workRoot, 'document.md')}`);
+        if (result.documentHtml)
+            console.info(`HTML: ${join(workRoot, 'document.html')}`);
+        return { exitCode: 0, payload };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json)
+            return { exitCode: 1, payload: { ok: false, error: message } };
+        console.error(`Error: ${message}`);
+        return { exitCode: 1, payload: { ok: false, error: message } };
+    }
+}
+// ============= document run (Agent-driven guide; library `runDocument` needs an injected LLM) =============
+let injectedLLM = null;
+export function injectLLM(llm) {
+    injectedLLM = llm;
+}
+function getInjectedLLM() {
+    return injectedLLM;
+}
+export async function runDocumentCommand(profileId, options) {
+    try {
+        // Collect inputs first (needed for scene auto-detection).
+        const inputs = await collectInputs(options);
+        if (inputs.length === 0) {
+            const msg = 'No input provided. Use --text or --proposal/--design/--specs/--code.';
+            if (options.json)
+                return { exitCode: 1, payload: { ok: false, error: msg } };
+            console.error(`Error: ${msg}`);
+            return { exitCode: 1, payload: { ok: false, error: msg } };
+        }
+        const text = inputs.map((i) => i.content).join('\n');
+        // Scene resolution: explicit profile, or auto-detect from natural language; confirm when uncertain.
+        let resolvedProfile = profileId ?? '';
+        if (!resolvedProfile) {
+            const det = detectScene(text);
+            if (det.profile && det.confidence >= 0.5) {
+                resolvedProfile = det.profile;
+            }
+            else {
+                const msg = confirmationPrompt(det, text) +
+                    '\n\n确认后重新运行，例如：\n  specflow techdoc run <profile> --text "..."';
+                const payload = { ok: false, needsConfirmation: true, candidates: det.candidates, message: msg };
+                if (options.json)
+                    return { exitCode: 0, payload };
+                console.info(msg);
+                return { exitCode: 0, payload: { ok: false, needsConfirmation: true } };
+            }
+        }
+        // One-click entry: no injected LLM → emit the Agent execution directive. The Agent (running on
+        // the IDE model) reads this and auto-completes plan → generate → validate. CLI itself never fetches an API.
+        const llm = getInjectedLLM();
+        if (!llm) {
+            const workRoot = options.workRoot ?? join(process.cwd(), '.specflow', 'document');
+            await fs.mkdir(workRoot, { recursive: true });
+            const library = await loadChapterLibrary();
+            const profile = await loadProfile(resolvedProfile);
+            const plan = planSteps({ profile, library, inputFeatures: inputFeatures(inputs, { includeSignoff: options.signoff }), inputs, workRoot, projectRoot: process.cwd() });
+            const directive = [
+                `# 一键生成技术文档（${resolvedProfile}）`,
+                '',
+                `请作为 Agent 用当前 IDE 模型自动完成以下步骤（勿中途停下来等用户分步），产物写入 workRoot: ${workRoot}`,
+                '',
+                `## 步骤`,
+                ...plan.steps.map((s) => `- [${s.phase}] **${s.id}**: ${s.title} → 输出 \`${s.outputFile}\`${s.required ? '' : '（可选）'}`),
+                '',
+                `## 完成后`,
+                `运行 \`specflow techdoc validate --work-root ${workRoot}\`，通过后向用户报告 document.md 路径；失败则修正产物后重跑。`,
+                '',
+                `提示词模板参考（IDE 资产）：`,
+                `- outline: .claude/specflow/prompts/document/outline/general.md`,
+                `- map: .claude/specflow/prompts/document/map/<章节>.md`,
+                `- review: .claude/specflow/prompts/document/review/ai-review.md`,
+            ].join('\n');
+            const payload = { ok: true, mode: 'agent-directive', workRoot, steps: plan.steps };
+            if (options.json)
+                return { exitCode: 0, payload };
+            console.info(directive);
+            return { exitCode: 0, payload };
+        }
+        // Delegates to the library runDocument for completeness (tests use this).
+        try {
+            const library = await loadChapterLibrary();
+            const profile = await loadProfile(resolvedProfile);
+            const workRoot = options.workRoot ?? join(process.cwd(), '.specflow', 'document');
+            await fs.mkdir(workRoot, { recursive: true });
+            const result = await runDocument({
+                llm,
+                workRoot,
+                profile,
+                library,
+                inputs,
+                inputFeatures: inputFeatures(inputs, { includeSignoff: options.signoff }),
+                change: resolvedProfile,
+                skipReview: options.skipReview ?? false,
+                maxRounds: parseMaxRounds(options.maxRounds),
+                renderHtmlOutput: false,
+                persist: true,
+                projectRoot: process.cwd(),
+            });
+            const payload = {
+                ok: result.ok,
+                stage: result.stage,
+                workRoot,
+                document: result.documentMd ? join(workRoot, 'document.md') : undefined,
+                diagnostics: result.diagnostics,
+            };
+            if (options.json)
+                return { exitCode: result.ok ? 0 : 1, payload };
+            if (!result.ok) {
+                console.error(`Document generation failed at stage "${result.stage}":`);
+                for (const d of result.diagnostics)
+                    console.error(`  [${d.gate}][${d.severity}] ${d.message}`);
+                return { exitCode: 1, payload };
+            }
+            console.info(`Document generated (${resolvedProfile}) in ${workRoot}`);
+            return { exitCode: 0, payload };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (options.json)
+                return { exitCode: 1, payload: { ok: false, error: message } };
+            console.error(`Error: ${message}`);
+            return { exitCode: 1, payload: { ok: false, error: message } };
+        }
+    }
+    catch (error) {
+        // 顶层兜底：collectInputs（文件不存在）/ loadProfile / planSteps / 场景识别等
+        // 任一失败都不再以未捕获 rejection 崩溃，--json 契约始终成立（P0-4）。
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json)
+            return { exitCode: 1, payload: { ok: false, error: message } };
+        console.error(`Error: ${message}`);
+        return { exitCode: 1, payload: { ok: false, error: message } };
+    }
+}
+// ============= document detect =============
+export async function detectDocumentCommand(options) {
+    try {
+        const inputs = await collectInputs(options);
+        const text = inputs.map((i) => i.content).join('\n');
+        const det = detectScene(text);
+        const payload = {
+            ok: true,
+            detected: det.profile,
+            confidence: det.confidence,
+            candidates: det.candidates,
+            reasons: det.reasons,
+        };
+        if (options.json)
+            return { exitCode: 0, payload };
+        if (det.profile) {
+            console.info(`检测到场景: ${det.profile}（置信度 ${Math.round(det.confidence * 100)}%）`);
+        }
+        else {
+            console.info(confirmationPrompt(det, text));
+        }
+        return { exitCode: 0, payload };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json)
+            return { exitCode: 1, payload: { ok: false, error: message } };
+        console.error(`Error: ${message}`);
+        return { exitCode: 1, payload: { ok: false, error: message } };
+    }
+}
+/**
+ * Discover multi-repo four-artifact sets under a workspace root.
+ * A repo contributes if `<repoRoot>/specflow/changes/<change>/` contains proposal/specs/design/tasks.
+ */
+async function discoverRepoChanges(workspaceRoot, spec) {
+    const repos = [];
+    if (spec) {
+        for (const part of spec.split(',')) {
+            const [repo, change] = part.trim().split(':');
+            if (repo && change)
+                repos.push({ repo, change, root: join(workspaceRoot, repo) });
+        }
+        return repos;
+    }
+    // Auto-scan: workspaceRoot/<repo>/specflow/changes/*/
+    const entries = await fs.readdir(workspaceRoot, { withFileTypes: true });
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        const changesDir = join(workspaceRoot, e.name, 'specflow', 'changes');
+        try {
+            const changes = await fs.readdir(changesDir);
+            for (const ch of changes) {
+                if (ch.startsWith('archive'))
+                    continue;
+                repos.push({ repo: e.name, change: ch, root: join(workspaceRoot, e.name) });
+            }
+        }
+        catch {
+            // no specflow/changes in this dir → skip
+        }
+    }
+    return repos;
+}
+export async function approveDocumentCommand(options) {
+    try {
+        const library = await loadChapterLibrary();
+        const profile = await loadProfile('approve');
+        const dirs = [];
+        if (options.workspaceRoot) {
+            dirs.push(...await discoverRepoChanges(options.workspaceRoot, options.changes ?? ''));
+        }
+        else {
+            const change = options.change ?? 'approval';
+            dirs.push({ repo: 'local', change, root: process.cwd() });
+        }
+        if (dirs.length === 0) {
+            const msg = 'No four-artifact change found. Provide --proposal/--specs/--design/--tasks or --workspace-root.';
+            if (options.json)
+                return { exitCode: 1, payload: { ok: false, error: msg } };
+            console.error(`Error: ${msg}`);
+            return { exitCode: 1, payload: { ok: false, error: msg } };
+        }
+        // Per-repo approve plan (read four artifacts, emit Agent generation steps).
+        const plans = [];
+        for (const d of dirs) {
+            const changeDir = join(d.root, 'specflow', 'changes', d.change);
+            const inputs = [];
+            for (const [type, file] of [['proposal', 'proposal.md'], ['specs', 'spec.md'], ['design', 'design.md'], ['tasks', 'tasks.md']]) {
+                try {
+                    const content = await fs.readFile(join(changeDir, file), 'utf-8');
+                    inputs.push({ type, source: join(changeDir, file), content });
+                }
+                catch {
+                    // optional missing artifact → skip
+                }
+            }
+            if (inputs.length === 0) {
+                // fall back to explicit options (four artifacts)
+                if (options.proposal)
+                    inputs.push(await readInputFile(options.proposal, 'proposal'));
+                if (options.specs)
+                    inputs.push(await readInputFile(options.specs, 'specs'));
+                if (options.design)
+                    inputs.push(await readInputFile(options.design, 'design'));
+                if (options.tasks)
+                    inputs.push(await readInputFile(options.tasks, 'tasks'));
+            }
+            if (inputs.length === 0) {
+                // 空输入拦截（P2）：该仓四件套缺失且无显式选项时禁止基于零输入生成。
+                const msg = `Repo ${d.repo}/${d.change}: no four-artifact inputs found. Provide --proposal/--specs/--design/--tasks or ensure artifacts exist.`;
+                if (options.json)
+                    return { exitCode: 1, payload: { ok: false, error: msg } };
+                console.error(`Error: ${msg}`);
+                return { exitCode: 1, payload: { ok: false, error: msg } };
+            }
+            // 多仓模式：显式 --work-root 下按 repo 派生子目录，避免各仓产物互相覆盖（P2）。
+            const workRoot = options.workRoot
+                ? join(options.workRoot, d.repo)
+                : join(changeDir, 'approval');
+            await fs.mkdir(workRoot, { recursive: true });
+            const plan = planSteps({
+                profile,
+                library,
+                inputFeatures: inputFeatures(inputs, { includeSignoff: options.signoff }),
+                inputs,
+                workRoot,
+                projectRoot: d.root,
+            });
+            plans.push({ repo: d.repo, change: d.change, steps: plan.steps, workRoot });
+        }
+        // Multi-repo bundle: merge each repo's generated document.md into one approval-unified.md.
+        if (options.bundle) {
+            if (plans.length < 2) {
+                const msg = '--bundle requires multiple repos (--workspace-root or --changes with ≥2).';
+                if (options.json)
+                    return { exitCode: 1, payload: { ok: false, error: msg } };
+                console.error(`Error: ${msg}`);
+                return { exitCode: 1, payload: { ok: false, error: msg } };
+            }
+            const sections = [`# 审批合订（多仓）`, '', `> 各仓审批文档合订视图（只读）。各仓 document.md 为真源。`, ''];
+            const errors = [];
+            for (const p of plans) {
+                const docPath = join(p.workRoot, 'document.md');
+                try {
+                    const content = await fs.readFile(docPath, 'utf-8');
+                    sections.push(`---`, '', `## 来源 · ${p.repo}（\`${p.change}\`）`, '', content.trim(), '');
+                }
+                catch {
+                    errors.push(`${p.repo}/${p.change} document.md 未生成（请先完成该仓生成并 validate）`);
+                }
+            }
+            if (errors.length > 0) {
+                const msg = `合订失败：\n  ${errors.join('\n  ')}`;
+                if (options.json)
+                    return { exitCode: 1, payload: { ok: false, error: msg } };
+                console.error(msg);
+                return { exitCode: 1, payload: { ok: false, error: msg } };
+            }
+            const unifiedPath = join(plans[0].workRoot, 'approval-unified.md');
+            await fs.writeFile(unifiedPath, sections.join('\n'), 'utf-8');
+            const payload = { ok: true, mode: 'bundle', unifiedPath, sources: plans.map((p) => ({ repo: p.repo, change: p.change, document: join(p.workRoot, 'document.md') })) };
+            if (options.json)
+                return { exitCode: 0, payload };
+            console.info(`多仓合订完成: ${unifiedPath}`);
+            return { exitCode: 0, payload };
+        }
+        // Build directive.
+        const lines = ['# 审批文档生成（approve · 四件套 → 审批）', ''];
+        lines.push('请作为 Agent 用当前 IDE 模型，对每个仓的四件套生成审批文档（含闭环检查/可实施性/质量红线），产物写入各仓 workRoot，完成后 validate。');
+        lines.push('');
+        for (const p of plans) {
+            lines.push(`## 仓 ${p.repo}（change: ${p.change}）· workRoot: ${p.workRoot}`);
+            for (const s of p.steps) {
+                lines.push(`- [${s.phase}] **${s.id}**: ${s.title} → \`${s.outputFile}\``);
+            }
+            lines.push(`  - 完成后: \`specflow techdoc validate --work-root ${p.workRoot}\``);
+            lines.push('');
+        }
+        if (plans.length > 1) {
+            lines.push('## 多仓合订（主仓）');
+            lines.push('各仓审批文档生成并 validate 通过后，主仓汇总为统一视图（只读合订）：');
+            lines.push(`  - 合并各仓 document.md 为 approval-unified.md（主仓: ${plans[0].repo}）`);
+        }
+        const payload = { ok: true, mode: 'approve', plans: plans.map((p) => ({ repo: p.repo, change: p.change, workRoot: p.workRoot, steps: p.steps })) };
+        if (options.json)
+            return { exitCode: 0, payload };
+        console.info(lines.join('\n'));
+        return { exitCode: 0, payload };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json)
+            return { exitCode: 1, payload: { ok: false, error: message } };
+        console.error(`Error: ${message}`);
+        return { exitCode: 1, payload: { ok: false, error: message } };
+    }
+}
+/**
+ * 读取一个仓的四件套，返回带来源标记 + repo 字段的输入。
+ * - content 前置 `## 来源仓：<repo>（change: <change>）`：压缩器/大纲/章节填充可见归属。
+ * - `repo` 字段：段 id 携带仓前缀（`seg-repo1-proposal-01`），Pass 2 按需取回对应仓原文。
+ */
+async function collectRepoInputs(d) {
+    const changeDir = join(d.root, 'specflow', 'changes', d.change);
+    const marker = `## 来源仓：${d.repo}（change: ${d.change}）`;
+    const inputs = [];
+    for (const [type, file] of [['proposal', 'proposal.md'], ['specs', 'spec.md'], ['design', 'design.md'], ['tasks', 'tasks.md']]) {
+        try {
+            const content = await fs.readFile(join(changeDir, file), 'utf-8');
+            inputs.push({ type, source: join(changeDir, file), content: `${marker}\n\n${content}`, repo: d.repo });
+        }
+        catch {
+            // optional missing artifact → skip
+        }
+    }
+    return inputs;
+}
+/**
+ * 跨仓合成规则（directive 与库形态 outlinePrompt 共用同一套文本）。
+ * 规则 6（按需加载规约）：写某仓章节时只读取该仓的规约/IDE rules，禁止一次性读全部仓——
+ * 防止 token 暴涨 + 注意力稀释；仅写跨仓内容（依赖/契约对接）时才读取涉及仓的规约。
+ */
+function buildSynthRules(dirs) {
+    const repoList = dirs.map((d) => d.repo).join('、');
+    return [
+        `## 跨仓合成规则（必须遵守）`,
+        `1. **统一大纲**：一次生成一份 outline，章节覆盖所有仓，不按仓分章（跨仓对比/汇总放进对应章节）。`,
+        `2. **契约实体命名空间**：跨仓实体 id 用 \`<repo>_<id>\` 前缀（如 \`repo1_I1\`、\`repo2_T1\`），禁止不同仓共用裸 id。`,
+        `3. **每章必须分仓小节（质量门禁，validate 强制）**：每个必选章节的叙述按仓分节，用 \`### <repo>\` 小节标题（可带后缀如 \`### repo1 · 目标\`），且每个仓（${repoList}）都必须出现。禁止把多仓内容混写成一段（会导致细节互相稀释）。`,
+        `4. **全局视角**（若所选 profile 包含对应章节）：goal 写多仓总目标与边界；tech-selection 对比各仓技术方案；api-design/data-model 分仓列契约；closed-loop 跨仓统一闭环检查；implementability 跨仓统一可实施性评估。其他场景章节（如 reproduce/root-cause/fix、requirement/test-strategy、research/poc-demo/benchmark）同样按仓分节并给出跨仓结论。`,
+        `5. **跨仓依赖/风险**：涉及仓间依赖（接口调用/数据共享/发布顺序）时显式标注「跨仓依赖」。`,
+        `6. **按需加载规约（重要）**：写某个仓的小节时，**只读取该仓**的规约/IDE rules/guidance（该仓的 \`docs/\`、\`.cursor\`、\`.claude\`、\`.agents\` 等），**禁止一次性读取全部仓的规约**；只有写跨仓内容（接口对接/数据共享/发布顺序）时才读取**涉及仓**的规约。未读取的仓规约不得臆测，必要时标注「未读取该仓规约，待确认」。`,
+        `7. **输入归属**：每段输入带「来源仓」标记，段 id 携带仓前缀（如 \`seg-repo1-proposal-01\`）；引用原文时按段 id 精确取回对应仓的片段，不整篇重读。`,
+    ].join('\n');
+}
+/**
+ * 解析合成用 profile：显式 --profile 优先；省略时从 --text（或四件套拼接内容）做场景识别。
+ * - 识别置信度达标 → 直接采用识别结果。
+ * - 识别不出且用户给了 --text → 返回 needsConfirmation（与 document run 行为一致，向用户确认）。
+ * - 识别不出且无 --text → 回退 approve（原 synthesize 默认，保持向后兼容，不打断流程）。
+ */
+function resolveSynthProfile(options, inputs) {
+    if (options.profile)
+        return { profileId: options.profile };
+    const detectText = (options.text ?? inputs.map((i) => i.content).join('\n')).trim();
+    const det = detectScene(detectText);
+    if (det.profile && det.confidence >= 0.5) {
+        return { profileId: det.profile, detectedText: detectText };
+    }
+    if (options.text) {
+        const message = confirmationPrompt(det, detectText) +
+            '\n\n确认后重新运行，例如：\n  specflow techdoc synthesize --workspace-root <root> --profile <profile> ...';
+        return {
+            profileId: null,
+            detectedText: detectText,
+            needsConfirmation: { candidates: det.candidates, message },
+        };
+    }
+    // 无 --text：四件套无强场景信号 → 回退 approve（原默认），不打断流程。
+    return { profileId: 'approve', detectedText: detectText, fallback: true };
+}
+export async function synthesizeDocumentCommand(options) {
+    try {
+        // workspaceRoot 必填（P2）：缺省时 fs.readdir(undefined) 会抛裸 TypeError。
+        if (!options.workspaceRoot) {
+            const msg = 'synthesize 需要 --workspace-root <path>（多仓工作区根目录，必填）。';
+            if (options.json)
+                return { exitCode: 1, payload: { ok: false, error: msg } };
+            console.error(`Error: ${msg}`);
+            return { exitCode: 1, payload: { ok: false, error: msg } };
+        }
+        const dirs = await discoverRepoChanges(options.workspaceRoot, options.changes ?? '');
+        if (dirs.length === 0) {
+            const msg = 'No multi-repo four-artifact sets found. Use --workspace-root with --changes "repo1:ch1,repo2:ch2" or auto-scan.';
+            if (options.json)
+                return { exitCode: 1, payload: { ok: false, error: msg } };
+            console.error(`Error: ${msg}`);
+            return { exitCode: 1, payload: { ok: false, error: msg } };
+        }
+        if (dirs.length < 2) {
+            const msg = 'synthesize 需要 ≥2 个仓（跨仓合成）；单仓请用 document run。';
+            if (options.json)
+                return { exitCode: 1, payload: { ok: false, error: msg } };
+            console.error(`Error: ${msg}`);
+            return { exitCode: 1, payload: { ok: false, error: msg } };
+        }
+        // 统一输入集：可选 --text 描述 + 各仓四件套（带来源仓标记）。
+        const inputs = [];
+        if (options.text)
+            inputs.push({ type: 'description', source: 'description', content: options.text });
+        for (const d of dirs) {
+            inputs.push(...await collectRepoInputs(d));
+        }
+        // 空输入拦截（P2）：四件套全缺且无 --text 时禁止基于零输入生成，与 run 命令行为一致。
+        if (inputs.length === 0) {
+            const msg = 'No input found: 各仓四件套（proposal/spec/design/tasks）均缺失，且未提供 --text。请先补齐四件套或提供 --text 描述。';
+            if (options.json)
+                return { exitCode: 1, payload: { ok: false, error: msg } };
+            console.error(`Error: ${msg}`);
+            return { exitCode: 1, payload: { ok: false, error: msg } };
+        }
+        // 场景识别：显式 --profile 优先；省略时从 --text / 四件套内容识别，不确定则向用户确认（同 document run）。
+        const resolved = resolveSynthProfile(options, inputs);
+        if (resolved.needsConfirmation) {
+            const payload = {
+                ok: false,
+                needsConfirmation: true,
+                candidates: resolved.needsConfirmation.candidates,
+                message: resolved.needsConfirmation.message,
+            };
+            if (options.json)
+                return { exitCode: 0, payload };
+            console.info(resolved.needsConfirmation.message);
+            return { exitCode: 0, payload };
+        }
+        const profileId = resolved.profileId;
+        const scene = options.profile
+            ? { profile: profileId, source: 'explicit' }
+            : resolved.fallback
+                ? { profile: profileId, source: 'fallback' }
+                : { profile: profileId, source: 'detected' };
+        const library = await loadChapterLibrary();
+        const profile = await loadProfile(profileId);
+        const workRoot = options.workRoot ?? join(options.workspaceRoot, '.specflow', 'document-synthesized');
+        await fs.mkdir(workRoot, { recursive: true });
+        // Multi-repo synthesize marker: validateWork reads this to enforce the per-repo section gate.
+        // 只有 synthesize 写 repos.json；approve --bundle / document run 不写 → 门禁不触发。
+        const repoNames = dirs.map((d) => d.repo);
+        await fs.writeFile(reposPath(workRoot), JSON.stringify(repoNames, null, 2), 'utf-8');
+        const llm = getInjectedLLM();
+        const synthRules = buildSynthRules(dirs);
+        if (!llm) {
+            // Agent-directive mode (CLI never fetches an LLM API — the Agent uses the IDE model).
+            // 不传 projectRoot=workspaceRoot：按需加载——规约由规则 6 要求按「章节涉及的仓」读取，
+            // 禁止一次性读取全部仓的规约/IDE rules（防止 token 暴涨 + 注意力稀释）。
+            const plan = planSteps({
+                profile,
+                library,
+                inputFeatures: inputFeatures(inputs, { includeSignoff: options.signoff }),
+                inputs,
+                workRoot,
+            });
+            const repoList = dirs.map((d) => `${d.repo}/${d.change}`).join('、');
+            const sceneLine = scene.source === 'detected'
+                ? `（场景识别：${scene.profile}）`
+                : scene.source === 'fallback'
+                    ? '（场景未识别，回退 approve）'
+                    : '';
+            const directive = [
+                `# 跨仓合成文档（${profile.id} · ${dirs.length} 仓${sceneLine}）`,
+                '',
+                `请作为 Agent 用当前 IDE 模型自动完成以下步骤（勿中途停下等用户分步），产物写入 workRoot: ${workRoot}`,
+                '',
+                `## 输入来源（多仓统一输入，每段已标记「来源仓」，段 id 携带仓前缀）`,
+                ...inputs.map((i) => `- \`${i.source}\`（${i.type} · 来自 ${i.content.split('\n')[0] ?? ''}）`),
+                '',
+                synthRules,
+                '',
+                `## 步骤`,
+                ...plan.steps.map((s) => `- [${s.phase}] **${s.id}**: ${s.title} → 输出 \`${s.outputFile}\`${s.required ? '' : '（可选）'}`),
+                '',
+                `## 完成后`,
+                `运行 \`specflow techdoc validate --work-root ${workRoot}\`，通过后向用户报告 document.md 路径；失败则修正产物后重跑。`,
+                '',
+                `提示词模板参考（IDE 资产）：`,
+                `- outline: .claude/specflow/prompts/document/outline/general.md`,
+                `- map: .claude/specflow/prompts/document/map/<章节>.md`,
+                `- review: .claude/specflow/prompts/document/review/ai-review.md`,
+            ].join('\n');
+            const payload = { ok: true, mode: 'synthesize-directive', profile: profile.id, scene, repos: repoList, workRoot, steps: plan.steps };
+            if (options.json)
+                return { exitCode: 0, payload };
+            console.info(directive);
+            return { exitCode: 0, payload };
+        }
+        // Library mode (tests/hosts inject an LLM): run the full pipeline once on the merged inputs.
+        // outlinePrompt 注入跨仓规则（Pass 1 统一大纲 + 命名空间 + 分仓小节 + 全局视角 + 按需读规约），
+        // 与 directive 模式同一套规则，避免库形态裸跑丢失跨仓约束。
+        try {
+            const result = await runDocument({
+                llm,
+                workRoot,
+                profile,
+                library,
+                inputs,
+                inputFeatures: inputFeatures(inputs, { includeSignoff: options.signoff }),
+                change: `synthesized:${dirs.map((d) => d.repo).join('+')}`,
+                maxRounds: options.signoff ? 3 : 2,
+                renderHtmlOutput: false,
+                persist: true,
+                outlinePrompt: synthRules,
+                projectRoot: options.workspaceRoot,
+            });
+            const payload = {
+                ok: result.ok,
+                stage: result.stage,
+                workRoot,
+                profile: profile.id,
+                scene,
+                document: result.documentMd ? join(workRoot, 'document.md') : undefined,
+                diagnostics: result.diagnostics,
+                repos: dirs.map((d) => `${d.repo}/${d.change}`),
+            };
+            if (options.json)
+                return { exitCode: result.ok ? 0 : 1, payload };
+            if (!result.ok) {
+                console.error(`Document synthesis failed at stage "${result.stage}":`);
+                for (const d of result.diagnostics)
+                    console.error(`  [${d.gate}][${d.severity}] ${d.message}`);
+                return { exitCode: 1, payload };
+            }
+            console.info(`跨仓合成文档已生成（${dirs.length} 仓，${profile.id}）: ${join(workRoot, 'document.md')}`);
+            return { exitCode: 0, payload };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (options.json)
+                return { exitCode: 1, payload: { ok: false, error: message } };
+            console.error(`Error: ${message}`);
+            return { exitCode: 1, payload: { ok: false, error: message } };
+        }
+    }
+    catch (error) {
+        // 顶层兜底（P2）：discoverRepoChanges/loadProfile/fs.mkdir/fs.writeFile 等
+        // 任一步骤失败不再以未捕获 rejection 崩溃，--json 契约始终成立。
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json)
+            return { exitCode: 1, payload: { ok: false, error: message } };
+        console.error(`Error: ${message}`);
+        return { exitCode: 1, payload: { ok: false, error: message } };
+    }
+}
+// ============= registration =============
+export function registerDocumentRunCommand(program) {
+    const doc = program
+        .command('techdoc')
+        .description('Generate scenario-based solution documents (Generic LongDoc Engine)');
+    doc
+        .command('detect')
+        .description('Auto-detect the scene profile (0to1 | frontend-0to1 | bugfix | feature | poc | migration) from natural language')
+        .option('--text <text>', 'Free-text problem description')
+        .option('--proposal <path>', 'Proposal input file')
+        .option('--design <path>', 'Design input file')
+        .option('--specs <path>', 'Specs input file')
+        .option('--code <path>', 'Code input file')
+        .option('--json', 'Output detection as JSON')
+        .action(async (opts) => {
+        const { exitCode, payload } = await detectDocumentCommand(opts);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+        if (opts.json)
+            console.info(JSON.stringify(payload, null, 2));
+    });
+    doc
+        .command('plan <profile>')
+        .description('Emit the Agent-executable step list (IDE model does the work; no LLM API call)')
+        .option('--text <text>', 'Free-text problem description')
+        .option('--proposal <path>', 'Proposal input file')
+        .option('--design <path>', 'Design input file')
+        .option('--specs <path>', 'Specs input file')
+        .option('--code <path>', 'Code input file')
+        .option('--work-root <path>', 'Work directory (default: .specflow/document)')
+        .option('--json', 'Output step list as JSON')
+        .option('--markdown', 'Output step list as Markdown')
+        .action(async (profile, opts) => {
+        const { exitCode, payload } = await planDocumentCommand(profile, opts);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+        if (opts.json)
+            console.info(JSON.stringify(payload, null, 2));
+    });
+    doc
+        .command('validate')
+        .description('Deterministically validate + render Agent-written artifacts (no LLM)')
+        .option('--work-root <path>', 'Work directory (default: .specflow/document)')
+        .option('--json', 'Output result as JSON')
+        .option('--no-render', 'Skip HTML rendering')
+        .action(async (opts) => {
+        const { exitCode, payload } = await validateDocumentCommand(opts);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+        if (opts.json)
+            console.info(JSON.stringify(payload, null, 2));
+    });
+    doc
+        .command('run [profile]')
+        .description('One-click generate a scenario document. Omit <profile> to auto-detect scene; confirm when uncertain.')
+        .option('--text <text>', 'Free-text problem description')
+        .option('--proposal <path>', 'Proposal input file')
+        .option('--design <path>', 'Design input file')
+        .option('--specs <path>', 'Specs input file')
+        .option('--code <path>', 'Code input file')
+        .option('--work-root <path>', 'Work directory (default: .specflow/document)')
+        .option('--signoff', 'Include an approval sign-off section')
+        .option('--skip-review', 'Skip Pass 3 AI review')
+        .option('--max-rounds <n>', 'AI review max rounds', '3')
+        .option('--json', 'Output result as JSON')
+        .action(async (profile, opts) => {
+        const { exitCode, payload } = await runDocumentCommand(profile, opts);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+        if (opts.json)
+            console.info(JSON.stringify(payload, null, 2));
+    });
+    doc
+        .command('synthesize')
+        .description('Synthesize multi-repo four artifacts into ONE cross-repo document (unified outline + namespaced contract entities + global overview/conclusion). Requires ≥2 repos. Omit --profile to auto-detect the scene (0to1/bugfix/feature/poc/migration) from --text or the artifacts; confirm when uncertain.')
+        .option('--workspace-root <path>', 'Multi-repo workspace root (required)')
+        .option('--changes <spec>', 'Multi-repo "repo1:change1,repo2:change2" (default: auto-scan workspaceRoot)')
+        .option('--text <text>', 'Natural-language description of the cross-repo work (used for scene detection when --profile is omitted)')
+        .option('--profile <id>', 'Synthesis profile (default: auto-detect scene from --text / artifacts; e.g. approve | 0to1 | bugfix | feature | poc | migration)')
+        .option('--work-root <path>', 'Output directory (default: <workspaceRoot>/.specflow/document-synthesized)')
+        .option('--signoff', 'Include the approval sign-off section')
+        .option('--json', 'Output result as JSON')
+        .action(async (opts) => {
+        const { exitCode, payload } = await synthesizeDocumentCommand(opts);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+        if (opts.json)
+            console.info(JSON.stringify(payload, null, 2));
+    });
+    doc
+        .command('approve')
+        .description('Generate an approval document from the four artifacts (proposal/specs/design/tasks). Multi-repo with --workspace-root.')
+        .option('--proposal <path>', 'Proposal file')
+        .option('--specs <path>', 'Specs file')
+        .option('--design <path>', 'Design file')
+        .option('--tasks <path>', 'Tasks file')
+        .option('--change <name>', 'Change name (single-repo mode)')
+        .option('--workspace-root <path>', 'Multi-repo workspace root (scan per-repo four artifacts)')
+        .option('--changes <spec>', 'Multi-repo "repo1:change1,repo2:change2"')
+        .option('--work-root <path>', 'Work directory')
+        .option('--signoff', 'Include the approval sign-off section')
+        .option('--bundle', 'Merge each repo document.md into approval-unified.md (after all repos generated+validated)')
+        .option('--json', 'Output result as JSON')
+        .action(async (opts) => {
+        const { exitCode, payload } = await approveDocumentCommand(opts);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+        if (opts.json)
+            console.info(JSON.stringify(payload, null, 2));
+    });
+}