@gordon.gan/specflow 1.4.6-beta → 1.7.0-beta

package/README.md

@@ -126,7 +126,7 @@ npm install -g @gordon.gan/specflow
 npm install -g github:Gordon-Gan-Jiang/specflow
 
 # 验证
-specflow --version   # 以 npm / package.json 为准（当前 1.4.6-beta）
+specflow --version   # 以 npm / package.json 为准（当前 1.7.0-beta）
 specflow --help
 ```
 
@@ -282,7 +282,7 @@ specflow init
 | **explore** | 读代码、比方案、定边界；产出 `explore.md`，confirmed 后 handoff 到 propose |
 | **propose** | 一次产出 proposal、delta specs、design、tasks（第一轮深度思考，非占位骨架）；叙述语言跟 `artifacts.language` |
 | **refine** | 内部多轮循环（≥2 轮，AI 判断收敛）；可更新任意 artifact |
-| **approval** | refine 后可选：AI 对四件套做 7 维闭环性检查（含代码落地性、基线对照）+ 设计质量评估 + 可实施性评估，生成 `approval.md` 供人工审批；非轻量变更分片写入 `approval/parts/` 后 `specflow approval assemble` 拼接；不改 phase，不阻塞 apply |
+| **approval** | refine 后可选：AI 7 维闭环 + 设计质量 + 可实施性 → `approval.md`；非轻量变更走 **ACP**：分片 `approval/parts/` → Stage 12e AI Review → **`specflow approval finalize`**（lint / review-check / assemble / 多仓 bundle）；不改 phase，不阻塞 apply |
 | **apply** | Phase A 重写 tasks.md；Phase B 按语言路由 ECC 审查 + TDD 逐任务执行；可选 `--yes` |
 | **review** | 代码审查，对照 specs 检查回归 |
 | **test** | 单元 + 集成 + E2E + 回归测试 |

package/dist/cli/commands/approval-assemble.d.ts

@@ -1,21 +1,64 @@
 /**
- * CLI: specflow approval assemble | check
+ * CLI: specflow approval assemble | check | lint | bundle | review-pack | review-check | finalize
  *
- * Deterministic Reduce step for segmented approval generation.
- * No LLM — merges approval/parts/*.md per approval/index.yaml.
+ * ACP (Approval Compiler Pipeline) — deterministic Reduce/Verify; Map is LLM in skill.
+ * Prefer `specflow approval finalize` for the full Verify → Reduce → bundle chain.
  */
 import type { Command } from 'commander';
-export interface ApprovalAssembleCommandOptions {
+export interface ApprovalCommandOptions {
     readonly store?: string;
     readonly cwd?: string;
     readonly force?: boolean;
     readonly json?: boolean;
     readonly noLazyCheck?: boolean;
+    readonly strict?: boolean;
+    readonly playbook?: string;
+    readonly workspaceRoot?: string;
+    readonly dryRun?: boolean;
+    readonly requireReview?: boolean;
+    readonly skipReview?: boolean;
+    readonly bundle?: boolean;
+    readonly noBundle?: boolean;
+    readonly render?: boolean;
+    readonly renderInput?: string;
+    readonly renderOutput?: string;
 }
-export declare function runApprovalAssemble(changeName: string, options: ApprovalAssembleCommandOptions & {
+export declare function runApprovalAssemble(changeName: string, options: ApprovalCommandOptions & {
     checkOnly?: boolean;
 }): Promise<{
     exitCode: number;
     payload: unknown;
 }>;
+export declare function runApprovalLint(changeName: string, options: ApprovalCommandOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function runApprovalBundle(changeName: string, options: ApprovalCommandOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function runApprovalReviewPack(changeName: string, options: ApprovalCommandOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function runApprovalReviewCheck(changeName: string, options: ApprovalCommandOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function runApprovalReviewHashes(changeName: string, options: ApprovalCommandOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function runApprovalRender(changeName: string, options: ApprovalCommandOptions & {
+    input?: string;
+    output?: string;
+    title?: string;
+}): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function runApprovalFinalize(changeName: string, options: ApprovalCommandOptions): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
 export declare function registerApprovalAssembleCommand(program: Command): void;

package/dist/cli/commands/approval-assemble.js

@@ -1,13 +1,20 @@
 /**
- * CLI: specflow approval assemble | check
+ * CLI: specflow approval assemble | check | lint | bundle | review-pack | review-check | finalize
  *
- * Deterministic Reduce step for segmented approval generation.
- * No LLM — merges approval/parts/*.md per approval/index.yaml.
+ * ACP (Approval Compiler Pipeline) — deterministic Reduce/Verify; Map is LLM in skill.
+ * Prefer `specflow approval finalize` for the full Verify → Reduce → bundle chain.
  */
 import { promises as fs } from 'node:fs';
 import { addStoreOption, resolveRootFromCommandOptions } from '../shared/store-option.js';
 import { validateChangeName } from '../../utils/change-utils.js';
-import { assembleApprovalDocument, getChangeDirectory, getApprovalOutputPath, } from '../../core/approval/index.js';
+import { assembleApprovalDocument, bundleApprovalDocument, checkApprovalReview, generateReviewPacket, getApprovalOutputPath, getChangeDirectory, lintApprovalDocument, finalizeApprovalDocument, computeReviewPartHashes, readApprovalIndex, renderApprovalDocument, resolveApprovalRenderPaths, resolvePlaybookPath, } from '../../core/approval/index.js';
+function printDiagnostics(diagnostics) {
+    for (const d of diagnostics) {
+        const prefix = d.severity === 'error' ? 'ERROR' : 'WARN';
+        const part = d.part ? ` [${d.part}]` : '';
+        console.error(`${prefix}${part}: ${d.message}`);
+    }
+}
 export async function runApprovalAssemble(changeName, options) {
     validateChangeName(changeName);
     const projectRoot = await resolveRootFromCommandOptions({
@@ -21,6 +28,21 @@ export async function runApprovalAssemble(changeName, options) {
     catch {
         throw new Error(`Change "${changeName}" not found at ${changeDir}`);
     }
+    if (options.requireReview) {
+        const reviewCheck = await checkApprovalReview({
+            changeDir,
+            requirePass: true,
+            forceRequire: true,
+        });
+        if (!reviewCheck.ok) {
+            const payload = { ok: false, stage: 'review-check', diagnostics: reviewCheck.diagnostics };
+            if (options.json) {
+                return { exitCode: 1, payload };
+            }
+            printDiagnostics(reviewCheck.diagnostics);
+            return { exitCode: 1, payload };
+        }
+    }
     const result = await assembleApprovalDocument({
         changeDir,
         checkOnly: options.checkOnly ?? false,
@@ -38,11 +60,7 @@ export async function runApprovalAssemble(changeName, options) {
         return { exitCode: result.ok ? 0 : 1, payload };
     }
     if (result.diagnostics.length > 0) {
-        for (const d of result.diagnostics) {
-            const prefix = d.severity === 'error' ? 'ERROR' : 'WARN';
-            const part = d.part ? ` [${d.part}]` : '';
-            console.error(`${prefix}${part}: ${d.message}`);
-        }
+        printDiagnostics(result.diagnostics);
     }
     if (result.ok) {
         if (options.checkOnly) {
@@ -55,41 +73,336 @@ export async function runApprovalAssemble(changeName, options) {
     }
     return { exitCode: 1, payload };
 }
+export async function runApprovalLint(changeName, options) {
+    validateChangeName(changeName);
+    const projectRoot = await resolveRootFromCommandOptions({
+        store: options.store,
+        cwd: options.cwd,
+    });
+    const changeDir = getChangeDirectory(projectRoot, changeName);
+    const result = await lintApprovalDocument({
+        changeDir,
+        strict: options.strict ?? false,
+    });
+    const payload = { ok: result.ok, change: changeName, diagnostics: result.diagnostics };
+    if (options.json) {
+        return { exitCode: result.ok ? 0 : 1, payload };
+    }
+    printDiagnostics(result.diagnostics);
+    if (result.ok) {
+        console.info(`Lint passed for change "${changeName}".`);
+        return { exitCode: 0, payload };
+    }
+    return { exitCode: 1, payload };
+}
+export async function runApprovalBundle(changeName, options) {
+    validateChangeName(changeName);
+    const projectRoot = await resolveRootFromCommandOptions({
+        store: options.store,
+        cwd: options.cwd,
+    });
+    const workspaceRoot = options.workspaceRoot ?? projectRoot;
+    const changeDir = getChangeDirectory(projectRoot, changeName);
+    const playbookPath = await resolvePlaybookPath(changeDir, options.playbook);
+    const result = await bundleApprovalDocument({
+        workspaceRoot,
+        changeDir,
+        playbookPath,
+        write: !options.dryRun,
+    });
+    const payload = {
+        ok: result.ok,
+        change: changeName,
+        output: result.outputPath,
+        playbook: playbookPath,
+        dry_run: options.dryRun ?? false,
+        diagnostics: result.diagnostics,
+    };
+    if (options.json) {
+        return { exitCode: result.ok ? 0 : 1, payload };
+    }
+    printDiagnostics(result.diagnostics);
+    if (result.ok) {
+        if (options.dryRun) {
+            console.info(`Bundle dry-run OK for "${changeName}" → ${result.outputPath}`);
+        }
+        else {
+            console.info(`Wrote bundle ${result.outputPath}`);
+        }
+        return { exitCode: 0, payload };
+    }
+    return { exitCode: 1, payload };
+}
+export async function runApprovalReviewPack(changeName, options) {
+    validateChangeName(changeName);
+    const projectRoot = await resolveRootFromCommandOptions({
+        store: options.store,
+        cwd: options.cwd,
+    });
+    const changeDir = getChangeDirectory(projectRoot, changeName);
+    const result = await generateReviewPacket({ changeDir });
+    const payload = {
+        ok: result.ok,
+        change: changeName,
+        packet_path: result.packetPath,
+        diagnostics: result.diagnostics,
+    };
+    if (options.json) {
+        return { exitCode: result.ok ? 0 : 1, payload };
+    }
+    printDiagnostics(result.diagnostics);
+    if (result.ok) {
+        console.info(`Wrote review packet ${result.packetPath}`);
+        console.info('Run AI review (Stage 12e), then: specflow approval review-check');
+        return { exitCode: 0, payload };
+    }
+    return { exitCode: 1, payload };
+}
+export async function runApprovalReviewCheck(changeName, options) {
+    validateChangeName(changeName);
+    const projectRoot = await resolveRootFromCommandOptions({
+        store: options.store,
+        cwd: options.cwd,
+    });
+    const changeDir = getChangeDirectory(projectRoot, changeName);
+    const result = await checkApprovalReview({
+        changeDir,
+        requirePass: options.requireReview !== false,
+    });
+    const payload = {
+        ok: result.ok,
+        change: changeName,
+        verdict: result.review?.verdict,
+        diagnostics: result.diagnostics,
+    };
+    if (options.json) {
+        return { exitCode: result.ok ? 0 : 1, payload };
+    }
+    printDiagnostics(result.diagnostics);
+    if (result.ok) {
+        console.info(`Review check passed for "${changeName}" (verdict=${result.review?.verdict ?? 'n/a'}).`);
+        return { exitCode: 0, payload };
+    }
+    return { exitCode: 1, payload };
+}
+export async function runApprovalReviewHashes(changeName, options) {
+    validateChangeName(changeName);
+    const projectRoot = await resolveRootFromCommandOptions({
+        store: options.store,
+        cwd: options.cwd,
+    });
+    const changeDir = getChangeDirectory(projectRoot, changeName);
+    let index;
+    try {
+        index = await readApprovalIndex(changeDir);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Cannot read index: ${message}`);
+    }
+    const part_hashes = await computeReviewPartHashes(changeDir, index.parts_order);
+    const payload = { change: changeName, part_hashes };
+    if (options.json) {
+        return { exitCode: 0, payload };
+    }
+    console.info(JSON.stringify(part_hashes, null, 2));
+    return { exitCode: 0, payload };
+}
+export async function runApprovalRender(changeName, options) {
+    validateChangeName(changeName);
+    const projectRoot = await resolveRootFromCommandOptions({
+        store: options.store,
+        cwd: options.cwd,
+    });
+    const changeDir = getChangeDirectory(projectRoot, changeName);
+    const paths = resolveApprovalRenderPaths(changeDir, options.input, options.output);
+    const result = await renderApprovalDocument({
+        changeDir,
+        inputPath: paths.inputPath,
+        outputPath: paths.outputPath,
+        title: options.title,
+        write: !options.dryRun,
+    });
+    const payload = {
+        ok: result.ok,
+        change: changeName,
+        input: paths.inputPath,
+        output: result.outputPath,
+        sha256: result.sha256,
+        dry_run: options.dryRun ?? false,
+        diagnostics: result.diagnostics,
+    };
+    if (options.json) {
+        return { exitCode: result.ok ? 0 : 1, payload };
+    }
+    if (result.diagnostics.length > 0) {
+        printDiagnostics(result.diagnostics);
+    }
+    if (result.ok) {
+        if (options.dryRun) {
+            console.info(`Render dry-run OK for "${changeName}" → ${result.outputPath}`);
+        }
+        else {
+            console.info(`Wrote ${result.outputPath}`);
+        }
+        return { exitCode: 0, payload };
+    }
+    return { exitCode: 1, payload };
+}
+export async function runApprovalFinalize(changeName, options) {
+    validateChangeName(changeName);
+    const projectRoot = await resolveRootFromCommandOptions({
+        store: options.store,
+        cwd: options.cwd,
+    });
+    const changeDir = getChangeDirectory(projectRoot, changeName);
+    const bundleMode = options.noBundle ? false : options.bundle ? true : 'auto';
+    const result = await finalizeApprovalDocument({
+        changeDir,
+        workspaceRoot: options.workspaceRoot ?? projectRoot,
+        strict: options.strict ?? true,
+        skipReview: options.skipReview ?? false,
+        force: options.force ?? true,
+        bundle: bundleMode,
+        playbook: options.playbook,
+        dryRun: options.dryRun ?? false,
+        validateLazy: !options.noLazyCheck,
+    });
+    const payload = {
+        ok: result.ok,
+        paused: result.paused ?? false,
+        stage: result.stage,
+        change: changeName,
+        output: result.outputPath,
+        bundle: result.bundlePath,
+        review_packet: result.reviewPacketPath,
+        diagnostics: result.diagnostics,
+    };
+    if (options.json) {
+        const exitCode = result.ok ? 0 : result.paused ? 2 : 1;
+        return { exitCode, payload };
+    }
+    printDiagnostics(result.diagnostics);
+    if (result.paused) {
+        console.info(`Paused at AI review for "${changeName}". Complete Stage 12e in-session, then re-run finalize.`);
+        if (result.reviewPacketPath) {
+            console.info(`Review packet: ${result.reviewPacketPath}`);
+        }
+        return { exitCode: 2, payload };
+    }
+    if (result.ok) {
+        console.info(`Finalized approval for "${changeName}" (stage=${result.stage}).`);
+        if (result.outputPath) {
+            console.info(`Wrote ${result.outputPath}`);
+        }
+        if (result.bundlePath) {
+            console.info(`Wrote bundle ${result.bundlePath}`);
+        }
+        if (options.render && !options.dryRun) {
+            const paths = resolveApprovalRenderPaths(changeDir, options.renderInput, options.renderOutput);
+            const renderResult = await renderApprovalDocument({
+                changeDir,
+                inputPath: paths.inputPath,
+                outputPath: paths.outputPath,
+                write: true,
+            });
+            if (renderResult.ok && renderResult.outputPath) {
+                console.info(`Wrote ${renderResult.outputPath}`);
+            }
+            else {
+                printDiagnostics(renderResult.diagnostics);
+                return { exitCode: 1, payload: { ...payload, render: renderResult } };
+            }
+        }
+        return { exitCode: 0, payload };
+    }
+    console.error(`Finalize failed at stage "${result.stage}" for "${changeName}".`);
+    return { exitCode: 1, payload };
+}
+function bindJsonAction(action) {
+    return async (change, opts) => {
+        const { exitCode, payload } = await action(change, opts);
+        if (opts.json) {
+            console.info(JSON.stringify(payload, null, 2));
+        }
+        if (exitCode !== 0) {
+            process.exitCode = exitCode;
+        }
+    };
+}
 export function registerApprovalAssembleCommand(program) {
-    const approval = program.command('approval').description('Approval document utilities');
+    const approval = program.command('approval').description('Approval document utilities (ACP)');
+    addStoreOption(approval
+        .command('finalize <change>')
+        .description('Run full ACP finalize: lint → review-check → check → assemble → bundle (preferred entry)')
+        .option('--skip-review', 'Skip AI review gate even when acp.review is enabled')
+        .option('--bundle', 'Force multi-repo bundle after assemble')
+        .option('--no-bundle', 'Skip bundle even when multi_repo.bundle.enabled')
+        .option('--playbook <path>', 'Path to playbook YAML (bundle step)')
+        .option('--workspace-root <path>', 'Workspace root for multi-repo bundle')
+        .option('--force', 'Overwrite existing approval.md (default: true)', true)
+        .option('--dry-run', 'Validate through check without writing approval.md or bundle')
+        .option('--strict', 'Strict lint (default: true)', true)
+        .option('--json', 'Output result as JSON')
+        .option('--no-lazy-check', 'Skip stub/lazy content validation on parts')
+        .option('--render', 'Also render approval.md to approval.html after finalize')
+        .option('--render-input <path>', 'Markdown input for --render (default: approval.md)')
+        .option('--render-output <path>', 'HTML output for --render (default: approval.html)')
+        .action(bindJsonAction(runApprovalFinalize)));
+    addStoreOption(approval
+        .command('render <change>')
+        .description('Render approval.md (or bundle markdown) to standalone HTML')
+        .option('--input <path>', 'Input markdown (default: approval.md)')
+        .option('--output <path>', 'Output HTML (default: same name with .html)')
+        .option('--title <text>', 'HTML document title override')
+        .option('--dry-run', 'Validate render without writing HTML file')
+        .option('--json', 'Output result as JSON')
+        .action(bindJsonAction((change, opts) => runApprovalRender(change, opts))));
     addStoreOption(approval
         .command('assemble <change>')
         .description('Merge approval/parts into approval.md (deterministic, no LLM)')
         .option('--force', 'Overwrite existing approval.md')
+        .option('--require-review', 'Require approval/review-result.json pass before assemble')
         .option('--json', 'Output result as JSON')
         .option('--no-lazy-check', 'Skip stub/lazy content validation on parts')
-        .action(async (change, opts) => {
-        const { exitCode, payload } = await runApprovalAssemble(change, {
-            ...opts,
-            checkOnly: false,
-        });
-        if (opts.json) {
-            console.info(JSON.stringify(payload, null, 2));
-        }
-        if (exitCode !== 0) {
-            process.exitCode = exitCode;
-        }
-    }));
+        .action(bindJsonAction((change, opts) => runApprovalAssemble(change, { ...opts, checkOnly: false }))));
     addStoreOption(approval
         .command('check <change>')
         .description('Validate approval parts and index without writing approval.md')
         .option('--json', 'Output result as JSON')
         .option('--no-lazy-check', 'Skip stub/lazy content validation on parts')
-        .action(async (change, opts) => {
-        const { exitCode, payload } = await runApprovalAssemble(change, {
-            ...opts,
-            checkOnly: true,
-        });
-        if (opts.json) {
-            console.info(JSON.stringify(payload, null, 2));
-        }
-        if (exitCode !== 0) {
-            process.exitCode = exitCode;
-        }
-    }));
+        .action(bindJsonAction((change, opts) => runApprovalAssemble(change, { ...opts, checkOnly: true }))));
+    addStoreOption(approval
+        .command('lint <change>')
+        .description('Cross-part consistency lint (IR freeze, pairs_with, page apis)')
+        .option('--strict', 'Treat inconsistency hints as errors')
+        .option('--json', 'Output result as JSON')
+        .action(bindJsonAction(runApprovalLint)));
+    addStoreOption(approval
+        .command('bundle <change>')
+        .description('Deterministic multi-repo bundle view from approval-playbook.yaml')
+        .option('--playbook <path>', 'Path to playbook YAML')
+        .option('--workspace-root <path>', 'Workspace root containing multiple repo planning roots')
+        .option('--dry-run', 'Validate bundle without writing output file')
+        .option('--json', 'Output result as JSON')
+        .action(bindJsonAction(runApprovalBundle)));
+    addStoreOption(approval
+        .command('review-pack <change>')
+        .description('Generate AI review packet (review-packet.json) for Stage 12e')
+        .option('--json', 'Output result as JSON')
+        .action(bindJsonAction(runApprovalReviewPack)));
+    addStoreOption(approval
+        .command('review-hashes <change>')
+        .description('Print part_hashes[] JSON for review-result.json after Stage 12e fixes')
+        .option('--json', 'Output result as JSON')
+        .action(bindJsonAction(runApprovalReviewHashes)));
+    addStoreOption(approval
+        .command('review-check <change>')
+        .description('Validate review-result.json + strict lint before assemble')
+        .option('--no-require-review', 'Skip requiring review-result when acp.review not enabled')
+        .option('--json', 'Output result as JSON')
+        .action(bindJsonAction((change, opts) => runApprovalReviewCheck(change, {
+        ...opts,
+        requireReview: opts.noRequireReview ? false : true,
+    }))));
 }

package/dist/core/approval/assemble.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import yaml from 'js-yaml';
 import { parseApprovalIndex } from './index-schema.js';
+import { findForbiddenMatch } from './forbidden-patterns.js';
 import { getApprovalIndexPath, getApprovalManifestPath, getApprovalOutputPath, getApprovalPartPath, getApprovalPartsDir, } from './paths.js';
 const OPTIONAL_PREFIXES = {
     s5: ['05-', '05.'],
@@ -21,17 +22,6 @@ const CHAPTER_HEADERS = {
     'appendix-a': '## 附录 A: 产物溯源',
 };
 const SECTION4_HEADER = '## 4. 方案详细设计 (Detailed Design)';
-const LAZY_PATTERNS = [
-    /\bTODO\b/i,
-    /待补充/,
-    /待 refine 澄清(?!.*\[)/,
-    /此处省略/,
-    /详见\s*(?:上文|下文|附件)(?!.*§)/,
-    /略\s*[。.]?$/,
-    /TBD\s*[。.]?$/,
-    /(?:^|\n)\s*\.{3}\s*(?:\n|$)/,
-    /(?:^|\n)\s*(?:同上|同前)\s*[。.]?\s*(?:\n|$)/,
-];
 const MIN_PART_BYTES = {
     '04.4': 200,
     '04.5': 200,
@@ -80,10 +70,9 @@ function detectLazyContent(partId, content) {
             return `part content below minimum for ${prefix} (${trimmed.length} bytes)`;
         }
     }
-    for (const pattern of LAZY_PATTERNS) {
-        if (pattern.test(trimmed)) {
-            return `lazy/stub pattern detected: ${pattern.source}`;
-        }
+    const forbidden = findForbiddenMatch(trimmed);
+    if (forbidden) {
+        return `lazy/stub pattern detected: ${forbidden.source}`;
     }
     if (/^#+\s*4\.\s/m.test(trimmed)) {
         return 'part must not contain top-level "## 4." heading (assemble injects section 4)';
@@ -96,14 +85,36 @@ function detectLazyContent(partId, content) {
     }
     return null;
 }
+function partHasAppendixA(partContents) {
+    for (const content of partContents.values()) {
+        if (/^#{2,3}\s+附录\s*A/m.test(content)) {
+            return true;
+        }
+    }
+    return false;
+}
 function buildDocumentHeader(index) {
     const meta = index.meta ?? {};
     const lang = meta.language ?? 'en';
     const stack = meta.tech_stack ?? 'unknown';
     const projectMode = meta.project_mode ?? 'brownfield';
     const modeNote = index.mode === 'segmented' ? 'segmented+assemble' : 'monolithic';
+    let multiRepoBlock = '';
+    const mr = index.multi_repo;
+    if (mr?.enabled && mr.repos.length >= 2) {
+        const mode = mr.document_mode ?? 'pending';
+        const primary = mr.primary_repo ?? '—';
+        const bundleNote = mr.bundle?.enabled ? ' | 合订: approval bundle (只读)' : '';
+        const repoLines = mr.repos
+            .map((r) => `- ${r.label} \`${r.id}/${r.change}\``)
+            .join('\n');
+        multiRepoBlock = `
+> **多仓范围** (${mode}${mode === 'unified' ? `, 主仓: ${primary}` : mr.bundle?.enabled ? `, bundle 主仓: ${primary}` : ''}${bundleNote}):
+${repoLines}
+`;
+    }
     return `# 技术方案审批文档: ${index.change}
-
+${multiRepoBlock}
 > 本文档由 \`/specflow:approval\` 基于 refine 收敛后的四件套 + 现有代码与 spec 基线生成,
 > 含架构与详细设计等章节,供人工审批使用。AI 闭环/预审结论在对话中反馈,不写入本文。
 > 生成时间: ${index.generated_at} | phase: refined | 产物语言: ${lang} | 技术栈: ${stack} | 项目模式: ${projectMode} | 生成模式: ${modeNote}
@@ -166,6 +177,42 @@ export async function assembleApprovalDocument(options) {
             ],
         };
     }
+    if (index.multi_repo?.enabled) {
+        const mr = index.multi_repo;
+        if (!mr.document_mode) {
+            diagnostics.push({
+                code: 'multi_repo_mode_missing',
+                severity: 'error',
+                message: 'multi_repo.enabled but document_mode not set; ask user unified vs per_repo before assemble',
+            });
+        }
+        if (mr.document_mode === 'unified') {
+            if (!mr.primary_repo) {
+                diagnostics.push({
+                    code: 'multi_repo_primary_missing',
+                    severity: 'error',
+                    message: 'multi_repo.document_mode=unified requires primary_repo',
+                });
+            }
+            else {
+                const primary = mr.repos.find((r) => r.id === mr.primary_repo);
+                if (primary && primary.change !== index.change) {
+                    diagnostics.push({
+                        code: 'multi_repo_change_mismatch',
+                        severity: 'warning',
+                        message: `index.change "${index.change}" differs from primary repo change "${primary.change}"; assemble in primary planning root`,
+                    });
+                }
+            }
+        }
+        if (mr.document_mode === 'per_repo' && !mr.outputs?.per_repo?.length) {
+            diagnostics.push({
+                code: 'multi_repo_outputs_missing',
+                severity: 'warning',
+                message: 'per_repo mode should list outputs.per_repo[] with each repo approval path',
+            });
+        }
+    }
     const partsDir = getApprovalPartsDir(changeDir);
     try {
         await fs.access(partsDir);
@@ -225,7 +272,7 @@ export async function assembleApprovalDocument(options) {
         }
         body.push(content.trim(), '', '---', '');
     }
-    if (!index.parts_order.includes('appendix-a')) {
+    if (!index.parts_order.includes('appendix-a') && !partHasAppendixA(partContents)) {
         body.push(buildAppendix().trim());
     }
     for (const table of index.tables) {

package/dist/core/approval/bundle.d.ts

@@ -0,0 +1,9 @@
+import type { ApprovalBundleResult } from './types.js';
+export interface BundleApprovalOptions {
+    readonly workspaceRoot: string;
+    readonly changeDir: string;
+    readonly playbookPath: string;
+    readonly write?: boolean;
+}
+export declare function bundleApprovalDocument(options: BundleApprovalOptions): Promise<ApprovalBundleResult>;
+export declare function resolvePlaybookPath(changeDir: string, explicitPath?: string): Promise<string>;