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

package/templates/document/chapters/ui-design.yaml

@@ -0,0 +1,22 @@
+# UI 设计（feature 候选；依赖接口）
+id: ui-design
+title: 前端/UI 设计
+when: input.uiInScope
+depends_on: [api-design]
+outline_points:
+  - { id: UI1, text: 页面/路由清单 + 栈五元组（G5）, required: true, kind: mixed }
+  - { id: UI2, text: 关键页空态/加载/错误三项（G6）, required: true, kind: narrative }
+  - { id: UI3, text: 状态与数据获取方案, required: true, kind: narrative }
+  - { id: UI4, text: 至少 1 条「本迭代不选/不适用」, required: true, kind: narrative }
+entities:
+  decisions:
+    required: [id, text]
+narratives:
+  ui_notes: required
+gates:
+  - uiInScope 时必须给页面清单 + 五元组（G5）
+  - 关键页必须写空态/加载/错误三项（G6）
+  - 禁止臆造页面树
+  - 性能/XSS/埋点仅 design 点名时才写
+map_prompt: prompts/document/map/ui-design.md
+output_budget_tokens: 6000

package/templates/document/profiles/0to1.yaml

@@ -0,0 +1,12 @@
+# 0→1 项目方案（决策 3）
+id: 0to1
+name: 0→1 项目方案
+required: [goal, tech-selection, mvp-boundary, non-goals]
+optional_candidates:
+  - signoff
+  - architecture
+  - api-design
+  - data-model
+  - test-strategy
+forbidden: [reproduce, root-cause, impact, fix, regression, requirement, ui-design]
+shared: []

package/templates/document/profiles/approve.yaml

@@ -0,0 +1,22 @@
+# 审批文档场景（四件套 → 审批文档，对齐 approval 能力）
+id: approve
+name: 审批文档（四件套）
+required:
+  - goal            # 绪论与边界
+  - tech-selection  # 技术方案评估（选型/决策/风险/质量）
+  - architecture    # 架构整体设计
+  - api-design      # 接口设计（含对外/跨端）
+  - data-model      # 数据结构/模型变更
+  - test-strategy   # 测试策略
+  - closed-loop     # 闭环性检查（7 Pass）
+  - implementability # 可实施性评估（7 维）
+optional_candidates:
+  - ui-design       # 前端/UI（条件: uiInScope）
+  - core-logic      # 核心算法/逻辑
+  - config-runtime  # 配置与运行环境
+  - compat-migration # 兼容性与迁移
+  - acceptance      # 验收标准
+  - deploy          # 部署/发布/回滚
+  - signoff         # 审批意见（签字栏）
+forbidden: [reproduce, root-cause, impact, fix, regression]
+shared: []

package/templates/document/profiles/bugfix.yaml

@@ -0,0 +1,10 @@
+# 修 bug 方案（决策 3）
+id: bugfix
+name: 修 bug 方案
+required: [reproduce, root-cause, fix]
+optional_candidates:
+  - impact
+  - regression
+  - signoff
+forbidden: [tech-selection, mvp-boundary, non-goals, goal, api-design, data-model, ui-design, requirement]
+shared: []

package/templates/document/profiles/feature.yaml

@@ -0,0 +1,11 @@
+# 功能开发方案（决策 3）
+id: feature
+name: 功能开发方案
+required: [requirement, test-strategy]
+optional_candidates:
+  - signoff
+  - api-design
+  - data-model
+  - ui-design
+forbidden: [reproduce, root-cause, impact, fix, regression, goal, tech-selection, mvp-boundary, non-goals]
+shared: []

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>;