@gordon.gan/specflow 1.4.4-beta → 1.5.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.4-beta）
+specflow --version   # 以 npm / package.json 为准（当前 1.5.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` 供人工审批；不改 phase，不阻塞 apply |
+| **approval** | refine 后可选：AI 对四件套做 7 维闭环性检查（含代码落地性、基线对照）+ 设计质量评估 + 可实施性评估，生成 `approval.md` 供人工审批；非轻量变更分片写入 `approval/parts/` 后 `specflow approval assemble` 拼接；不改 phase，不阻塞 apply |
 | **apply** | Phase A 重写 tasks.md；Phase B 按语言路由 ECC 审查 + TDD 逐任务执行；可选 `--yes` |
 | **review** | 代码审查，对照 specs 检查回归 |
 | **test** | 单元 + 集成 + E2E + 回归测试 |

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

@@ -0,0 +1,21 @@
+/**
+ * CLI: specflow approval assemble | check
+ *
+ * Deterministic Reduce step for segmented approval generation.
+ * No LLM — merges approval/parts/*.md per approval/index.yaml.
+ */
+import type { Command } from 'commander';
+export interface ApprovalAssembleCommandOptions {
+    readonly store?: string;
+    readonly cwd?: string;
+    readonly force?: boolean;
+    readonly json?: boolean;
+    readonly noLazyCheck?: boolean;
+}
+export declare function runApprovalAssemble(changeName: string, options: ApprovalAssembleCommandOptions & {
+    checkOnly?: boolean;
+}): Promise<{
+    exitCode: number;
+    payload: unknown;
+}>;
+export declare function registerApprovalAssembleCommand(program: Command): void;

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

@@ -0,0 +1,95 @@
+/**
+ * CLI: specflow approval assemble | check
+ *
+ * Deterministic Reduce step for segmented approval generation.
+ * No LLM — merges approval/parts/*.md per approval/index.yaml.
+ */
+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';
+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}`);
+    }
+    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) {
+        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}`);
+        }
+    }
+    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 function registerApprovalAssembleCommand(program) {
+    const approval = program.command('approval').description('Approval document utilities');
+    addStoreOption(approval
+        .command('assemble <change>')
+        .description('Merge approval/parts into approval.md (deterministic, no LLM)')
+        .option('--force', 'Overwrite existing 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: false,
+        });
+        if (opts.json) {
+            console.info(JSON.stringify(payload, null, 2));
+        }
+        if (exitCode !== 0) {
+            process.exitCode = exitCode;
+        }
+    }));
+    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;
+        }
+    }));
+}

package/dist/cli/index.js

@@ -16,6 +16,7 @@ import { registerStoreCommand } from './commands/store.js';
 import { registerShowCommand } from './commands/show.js';
 import { registerContextCommand } from './commands/context.js';
 import { registerWorksetCommand } from './commands/workset.js';
+import { registerApprovalAssembleCommand } from './commands/approval-assemble.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf-8'));
@@ -43,6 +44,7 @@ registerStoreCommand(program);
 registerShowCommand(program);
 registerContextCommand(program);
 registerWorksetCommand(program);
+registerApprovalAssembleCommand(program);
 program.exitOverride();
 try {
     await program.parseAsync();

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

@@ -0,0 +1,10 @@
+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>;

package/dist/core/approval/assemble.js

@@ -0,0 +1,391 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import yaml from 'js-yaml';
+import { parseApprovalIndex } from './index-schema.js';
+import { getApprovalIndexPath, getApprovalManifestPath, getApprovalOutputPath, getApprovalPartPath, getApprovalPartsDir, } from './paths.js';
+const OPTIONAL_PREFIXES = {
+    s5: ['05-', '05.'],
+    s7: ['07-', '07.'],
+    s8: ['08-', '08.'],
+};
+const CHAPTER_HEADERS = {
+    '01-intro': '## 1. 绪论与边界 (Introduction & Boundaries)',
+    '02-design-review': '## 2. 技术方案评估 (Technical Design Review)',
+    '03-architecture': '## 3. 架构整体设计 (Architecture Design)',
+    '05-acceptance': '## 5. 验收标准 (Acceptance Criteria)',
+    '06-test': '## 6. 测试策略 (Test Strategy)',
+    '07-deploy': '## 7. 部署/发布/回滚方案 (Deployment & Release)',
+    '08-closed-loop': '## 8. 闭环性检查 (Closed-Loop Verification)',
+    '09-implementability': '## 9. 可实施性评估 (Implementability Assessment)',
+    '10-signoff': '## 10. 审批意见 (Approval Decision)',
+    '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|$)/,
+    /实现时(?:命名|对齐)/,
+    /(?:RPC|rpc).*暂定/,
+    /暂定\s*[`']?\w+[`']?/,
+    /\b如\s+[A-Z]\w*(?:Result|Request|Response)/,
+    /内部(?:经|调用)\s*I\d+[^.\n]{0,40}(?:一行|代替|省略)/,
+];
+const MIN_PART_BYTES = {
+    '04.4': 200,
+    '04.5': 200,
+    '04.6': 150,
+    '05-': 100,
+};
+function sha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+function isOptionalPart(partId, optional) {
+    if (OPTIONAL_PREFIXES.s5.some((p) => partId.startsWith(p))) {
+        return !optional.s5;
+    }
+    if (OPTIONAL_PREFIXES.s7.some((p) => partId.startsWith(p))) {
+        return !optional.s7;
+    }
+    if (OPTIONAL_PREFIXES.s8.some((p) => partId.startsWith(p))) {
+        return !optional.s8;
+    }
+    return false;
+}
+function isSection4Part(partId) {
+    return partId === '04-detail-core' || partId.startsWith('04.');
+}
+function headerForPart(partId) {
+    if (isSection4Part(partId)) {
+        return null;
+    }
+    if (CHAPTER_HEADERS[partId]) {
+        return CHAPTER_HEADERS[partId];
+    }
+    for (const [key, header] of Object.entries(CHAPTER_HEADERS)) {
+        if (partId.startsWith(key)) {
+            return header;
+        }
+    }
+    return null;
+}
+function detectLazyContent(partId, content) {
+    const trimmed = content.trim();
+    if (trimmed.length < 20) {
+        return 'part content too short (< 20 chars)';
+    }
+    for (const prefix of Object.keys(MIN_PART_BYTES)) {
+        if (partId.startsWith(prefix) && trimmed.length < MIN_PART_BYTES[prefix]) {
+            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}`;
+        }
+    }
+    if (/^#+\s*4\.\s/m.test(trimmed)) {
+        return 'part must not contain top-level "## 4." heading (assemble injects section 4)';
+    }
+    if (/^##\s+[1-9]\d?\./m.test(trimmed) && !partId.startsWith('05-c')) {
+        const match = trimmed.match(/^##\s+([1-9]\d?)\./m);
+        if (match && !partId.startsWith(`${match[1].padStart(2, '0')}`)) {
+            return 'part must not inject foreign chapter "## N." headings';
+        }
+    }
+    return null;
+}
+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 repoLines = mr.repos
+            .map((r) => `- ${r.label} \`${r.id}/${r.change}\``)
+            .join('\n');
+        multiRepoBlock = `
+> **多仓范围** (${mode}${mode === 'unified' ? `, 主仓: ${primary}` : ''}):
+${repoLines}
+`;
+    }
+    return `# 技术方案审批文档: ${index.change}
+${multiRepoBlock}
+> 本文档由 \`/specflow:approval\` 基于 refine 收敛后的四件套 + 现有代码与 spec 基线生成,
+> 含架构与详细设计等章节,供人工审批使用。AI 闭环/预审结论在对话中反馈,不写入本文。
+> 生成时间: ${index.generated_at} | phase: refined | 产物语言: ${lang} | 技术栈: ${stack} | 项目模式: ${projectMode} | 生成模式: ${modeNote}
+
+> **质量红线(必须满足)**:G1 超 5 行流程→图示 · G2 接口须有失败示例 · G3 JSON/新列须有存量填充策略 · G4 须有回滚数据兼容说明 · G5 有 UI 须有页面/路由清单+栈五元组 · G6 关键页须有空/加载/错态。  
+> **文风**:通俗中文、缩写首次注解、禁用含糊词;**正文禁止代码腔**(路径/函数名堆砌→可读中文)。
+
+---
+`;
+}
+function buildAppendix() {
+    return `
+---
+
+## 附录 A: 产物溯源
+
+| 章节 | 数据来源 | 处理方式 |
+|------|---------|---------|
+| 绪论与边界 | proposal + explore(可选) | AI 提炼 |
+| 技术方案评估 | design + 用户确认选型(若有) | 约束 + 技术选型 + 决策/风险/质量 |
+| 架构 / 详细设计 | design + specs + 锚点 + 约定 | 图+要点+数据/接口/前端 |
+| 验收标准 | specs | **可选** |
+| 测试策略 | §5 或 specs 名 | 分层矩阵 |
+| 部署/闭环 | 运行环境 / Pass 1–7 | **可选** |
+| 可实施性 | 四件套+代码 | 写入文档 |
+| 审批意见 | 人工 | 仅签字栏 |
+`;
+}
+export async function readApprovalIndex(changeDir) {
+    const raw = yaml.load(await fs.readFile(getApprovalIndexPath(changeDir), 'utf-8'));
+    return parseApprovalIndex(raw);
+}
+export async function readApprovalManifest(changeDir) {
+    const path = getApprovalManifestPath(changeDir);
+    try {
+        const raw = JSON.parse(await fs.readFile(path, 'utf-8'));
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export async function assembleApprovalDocument(options) {
+    const diagnostics = [];
+    const { changeDir, checkOnly = false, force = false, validateLazy = true } = options;
+    let index;
+    try {
+        index = await readApprovalIndex(changeDir);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            diagnostics: [
+                {
+                    code: 'missing_index',
+                    severity: 'error',
+                    message: `Cannot read approval/index.yaml: ${message}`,
+                },
+            ],
+        };
+    }
+    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);
+    }
+    catch {
+        diagnostics.push({
+            code: 'missing_parts_dir',
+            severity: 'error',
+            message: `Missing approval/parts/ directory at ${partsDir}`,
+        });
+        return { ok: false, diagnostics };
+    }
+    const partContents = new Map();
+    let section4Opened = false;
+    const body = [buildDocumentHeader(index)];
+    for (const partId of index.parts_order) {
+        if (isOptionalPart(partId, index.optional)) {
+            continue;
+        }
+        const partPath = getApprovalPartPath(changeDir, partId);
+        let content;
+        try {
+            content = await fs.readFile(partPath, 'utf-8');
+        }
+        catch {
+            diagnostics.push({
+                code: 'missing_part',
+                severity: 'error',
+                message: `Missing part file for "${partId}" at ${partPath}`,
+                part: partId,
+            });
+            continue;
+        }
+        if (validateLazy) {
+            const lazy = detectLazyContent(partId, content);
+            if (lazy) {
+                diagnostics.push({
+                    code: 'lazy_part_content',
+                    severity: 'error',
+                    message: `Part "${partId}": ${lazy}`,
+                    part: partId,
+                });
+            }
+        }
+        partContents.set(partId, content);
+        if (isSection4Part(partId)) {
+            if (!section4Opened) {
+                body.push(SECTION4_HEADER, '', '---', '');
+                section4Opened = true;
+            }
+            body.push(content.trim(), '');
+            continue;
+        }
+        const header = headerForPart(partId);
+        if (header) {
+            body.push(header, '');
+        }
+        body.push(content.trim(), '', '---', '');
+    }
+    if (!index.parts_order.includes('appendix-a')) {
+        body.push(buildAppendix().trim());
+    }
+    for (const table of index.tables) {
+        if (!partContents.has(table.part)) {
+            diagnostics.push({
+                code: 'id_part_mismatch',
+                severity: 'error',
+                message: `Table "${table.id}" references missing part "${table.part}"`,
+                part: table.part,
+            });
+        }
+    }
+    for (const iface of index.interfaces) {
+        if (!partContents.has(iface.part)) {
+            diagnostics.push({
+                code: 'id_part_mismatch',
+                severity: 'error',
+                message: `Interface "${iface.id}" references missing part "${iface.part}"`,
+                part: iface.part,
+            });
+        }
+    }
+    if (index.ui_in_scope) {
+        for (const page of index.pages) {
+            if (!partContents.has(page.part)) {
+                diagnostics.push({
+                    code: 'id_part_mismatch',
+                    severity: 'error',
+                    message: `Page "${page.id}" references missing part "${page.part}"`,
+                    part: page.part,
+                });
+            }
+        }
+    }
+    for (const partId of index.parts_order) {
+        if (isOptionalPart(partId, index.optional)) {
+            continue;
+        }
+        if (!partContents.has(partId)) {
+            continue;
+        }
+    }
+    const diskParts = await fs.readdir(partsDir);
+    for (const file of diskParts) {
+        if (!file.endsWith('.md')) {
+            continue;
+        }
+        const id = file.replace(/\.md$/, '');
+        const optionalSkipped = isOptionalPart(id, index.optional);
+        const inOrder = index.parts_order.includes(id);
+        if (!inOrder && !optionalSkipped) {
+            diagnostics.push({
+                code: 'orphan_part',
+                severity: 'warning',
+                message: `Part file "${file}" exists but is not listed in index.parts_order`,
+                part: id,
+            });
+        }
+        if (optionalSkipped && inOrder) {
+            diagnostics.push({
+                code: 'optional_present_but_disabled',
+                severity: 'warning',
+                message: `Optional chapter disabled but part "${id}" is still in parts_order`,
+                part: id,
+            });
+        }
+    }
+    const hasError = diagnostics.some((d) => d.severity === 'error');
+    if (hasError) {
+        return { ok: false, diagnostics };
+    }
+    const markdown = body.join('\n').replace(/\n{3,}/g, '\n\n').trim() + '\n';
+    const outputPath = getApprovalOutputPath(changeDir);
+    if (checkOnly) {
+        return { ok: true, markdown, outputPath, diagnostics };
+    }
+    if (!force) {
+        try {
+            await fs.access(outputPath);
+            diagnostics.push({
+                code: 'output_exists',
+                severity: 'warning',
+                message: `${outputPath} already exists; use --force to overwrite`,
+            });
+            return { ok: false, diagnostics, markdown, outputPath };
+        }
+        catch {
+            // ok to write
+        }
+    }
+    await fs.writeFile(outputPath, markdown, 'utf-8');
+    const manifest = {
+        schema: 'specflow.approval.manifest/v1',
+        change: index.change,
+        parts: index.parts_order
+            .filter((id) => partContents.has(id))
+            .map((id) => ({
+            id,
+            path: `approval/parts/${id}.md`,
+            status: 'ok',
+            sha256: sha256(partContents.get(id)),
+            updated_at: index.generated_at,
+        })),
+        assembled_at: new Date().toISOString(),
+        approval_sha256: sha256(markdown),
+    };
+    await fs.writeFile(getApprovalManifestPath(changeDir), JSON.stringify(manifest, null, 2), 'utf-8');
+    return { ok: true, markdown, outputPath, diagnostics };
+}