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

package/templates/document/profiles/migration.yaml

@@ -0,0 +1,42 @@
+# 全栈技术升级（F4 · fullstack-migration）
+# 升级评估 → 兼容性分析 → 渐进式迁移 → 迁移指南 → 测试 → 灰度发布/回滚
+id: migration
+name: 技术升级方案
+required:
+  - goal                  # 升级动机/收益/工作量边界
+  - impact                # Breaking Change 清单/影响范围
+  - compat-migration      # 兼容性分析 + 渐进式迁移方案 + 新旧 API 对照（扩展）
+  - migration-guide       # 代码迁移指南（逐模块 checklist/codemod/陷阱/培训）
+  - test-strategy         # 回归测试（视觉/功能/性能回归）
+  - deploy                # 灰度发布方案 + 回滚预案
+optional_candidates:
+  - performance           # 性能基准对比（新旧产物体积/加载/运行时）
+  - api-design            # API 变化对照表（when: input.containsApiChange）
+  - data-model            # 数据迁移（when: input.hasPersistence）
+  - architecture          # 新旧架构对比（后端）
+  - ui-design             # 样式/UI 迁移范围（when: input.uiInScope）
+  - ops                   # 运维监控（灰度期指标/告警）
+  - signoff
+forbidden:
+  - reproduce             # 非 Bug/功能场景
+  - root-cause            # （入 shared 闭合，不渲染）
+  - fix
+  - regression
+  - requirement
+  - tech-selection        # 非 0→1 场景（入 shared 闭合，不渲染）
+  - mvp-boundary
+  - non-goals
+  - research              # 非预研（F5 用）
+  - poc-demo
+  - benchmark
+  - frontend-architecture # 迁移不重画前端架构（入 shared 闭合，不渲染）
+  - component-design
+  - state-management
+  - acceptance
+shared:
+  - root-cause              # 仅闭合允许、不渲染：impact 章节 depends_on [root-cause]，但迁移场景不渲染根因章
+  - tech-selection          # 仅闭合允许、不渲染：architecture（新旧架构对比，可选）依赖
+  - frontend-architecture   # 仅闭合允许、不渲染：performance 依赖（迁移不重画前端架构）
+appendices:
+  - anti-ai
+  - handoff

package/templates/document/profiles/poc.yaml

@@ -0,0 +1,46 @@
+# 全栈技术预研/选型（F5 · fullstack-poc）
+# 证据链：research（调研）→ poc-demo（验证）→ benchmark（数据）→ tech-selection（综合推荐）
+# forbidden 已含全部全栈实现章节（frontend-architecture/component-design/state-management/
+#   performance/ops/migration-guide/a11y，见 docs/scenario-templates/f5-poc.md §6.4）
+id: poc
+name: 技术预研/选型
+required:
+  - research                # A 调研：候选 ≥2 + 社区活跃度 + 团队匹配
+  - poc-demo                # B 验证：最小验证 + 判据 + 已知限制
+  - benchmark               # B 数据：同条件同设备 + 原始测量值
+  - tech-selection          # C 综合推荐：评估矩阵 + 一句话立场（声明序渲染在证据链末尾）
+optional_candidates:
+  - goal                    # A 预研背景与边界
+  - impact                  # D 采用后影响范围（dep: root-cause → shared 闭合）
+  - signoff                 # Z 签字栏（when: input.includeSignoff）
+shared:
+  - root-cause              # 仅闭合允许、不渲染（impact 依赖）
+forbidden:
+  - reproduce               # 非 Bug
+  - root-cause              # 非 Bug
+  - fix                     # 非 Bug
+  - regression              # 非 Bug
+  - requirement             # 非功能开发
+  - api-design              # 无实现设计（无契约可冻结）
+  - data-model              # 无实现设计（无表可建）
+  - ui-design               # 无实现设计（无页面可画）
+  - architecture            # 预研不设计架构
+  - frontend-architecture   # 预研不设计前端架构
+  - component-design        # 预研不设计组件
+  - state-management        # 预研不设计状态
+  - performance             # 预研不写实现性能方案（benchmark 已覆盖测量）
+  - ops                     # 预研不写运维运营
+  - migration-guide         # 预研不做代码迁移
+  - deploy                  # 无部署交付
+  - test-strategy           # 无测试策略
+  - config-runtime          # 无配置实现
+  - acceptance              # 无验收标准
+  - core-logic              # 无核心逻辑实现
+  - mvp-boundary            # 非 0→1
+  - non-goals               # 非 0→1（一句话立场覆盖）
+  - compat-migration        # 非迁移（F4）
+  - closed-loop             # 审批专用
+  - implementability        # 审批专用
+appendices:
+  - anti-ai                 # 附录 B · 去AI味自检（五维自检表，≥3 条）
+  - handoff                 # 附录 C · 下游交付衔接（交付矩阵 + 三步）

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

@@ -1,64 +0,0 @@
-/**
- * CLI: specflow approval assemble | check | lint | bundle | review-pack | review-check | finalize
- *
- * 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 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: 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,408 +0,0 @@
-/**
- * CLI: specflow approval assemble | check | lint | bundle | review-pack | review-check | finalize
- *
- * 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, 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({
-        store: options.store,
-        cwd: options.cwd,
-    });
-    const changeDir = getChangeDirectory(projectRoot, changeName);
-    try {
-        await fs.access(changeDir);
-    }
-    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,
-        force: options.force ?? false,
-        validateLazy: !options.noLazyCheck,
-    });
-    const payload = {
-        ok: result.ok,
-        change: changeName,
-        output: result.outputPath ?? getApprovalOutputPath(changeDir),
-        check_only: options.checkOnly ?? 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.checkOnly) {
-            console.info(`Check passed for change "${changeName}" (parts ready to assemble).`);
-        }
-        else {
-            console.info(`Wrote ${result.outputPath}`);
-        }
-        return { exitCode: 0, payload };
-    }
-    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 (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(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(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.d.ts

@@ -1,10 +0,0 @@
-import type { ApprovalAssembleResult, ApprovalIndex, ApprovalManifest } from './types.js';
-export declare function readApprovalIndex(changeDir: string): Promise<ApprovalIndex>;
-export declare function readApprovalManifest(changeDir: string): Promise<ApprovalManifest | null>;
-export interface AssembleApprovalOptions {
-    readonly changeDir: string;
-    readonly checkOnly?: boolean;
-    readonly force?: boolean;
-    readonly validateLazy?: boolean;
-}
-export declare function assembleApprovalDocument(options: AssembleApprovalOptions): Promise<ApprovalAssembleResult>;