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

package/dist/core/approval/review-pack.js

@@ -1,205 +0,0 @@
-import { createHash } from 'node:crypto';
-import { promises as fs } from 'node:fs';
-import { parseApprovalReviewResult } from './playbook-schema.js';
-import { readApprovalIndex } from './assemble.js';
-import { lintApprovalDocument } from './lint.js';
-import { getApprovalPartPath, getApprovalReviewPath, getApprovalReviewPacketPath, } from './paths.js';
-const AI_REVIEW_CHECKLIST = [
-    'Cross-part naming: same entity/id canonical across §2, §4, diagrams, index.yaml (no 暂定/TBD for listed ids)',
-    'Decision traceability: each §2/decisions[] row reflected with concrete behavior in §4',
-    'Inventory ↔ body: every index table/interface/page/design_point has substantive content in its part',
-    'Depth parity: sibling parts / feature_slices have comparable depth (no one-line stubs next to full sections)',
-    'Cross-reference integrity: refs use stable ids (§4.5 In, P*, Page*, T*); targets exist',
-    'Diagram ↔ prose: sequence/flow diagrams match adjacent text (actors, messages, errors)',
-    'Contract completeness: listed interfaces/page-apis meet Part E minimum (incl. failure example when api_in_scope)',
-    'Enum/state closure: status/enum sets explicit and closed where defined (no open-ended 「等」)',
-    'Unclosed branches: every mentioned retry/cancel/timeout/idempotency path has outcome or [待 refine 澄清]',
-    'UI ↔ API alignment: §4.6 fields and api refs match §4.5 when ui_in_scope',
-    'Multi-repo parity: each in-scope repo slice has proportionate depth when multi_repo.enabled',
-    'Stub purge: no TODO/待补充/placeholder-only parts',
-    'Verdict coherence: §9 readiness matches §4 depth',
-];
-function sha256(content) {
-    return createHash('sha256').update(content, 'utf8').digest('hex');
-}
-export async function computeReviewPartHashes(changeDir, partIds) {
-    const hashes = [];
-    for (const partId of partIds) {
-        try {
-            const content = await fs.readFile(getApprovalPartPath(changeDir, partId), 'utf-8');
-            hashes.push({ id: partId, sha256: sha256(content) });
-        }
-        catch {
-            // missing part handled elsewhere
-        }
-    }
-    return hashes;
-}
-export async function generateReviewPacket(options) {
-    const diagnostics = [];
-    const { changeDir } = 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 index: ${message}` },
-            ],
-        };
-    }
-    const lintResult = await lintApprovalDocument({ changeDir, strict: false });
-    const parts = [];
-    for (const partId of index.parts_order) {
-        try {
-            const content = await fs.readFile(getApprovalPartPath(changeDir, partId), 'utf-8');
-            parts.push({
-                id: partId,
-                sha256: sha256(content),
-                bytes: Buffer.byteLength(content, 'utf8'),
-            });
-        }
-        catch {
-            diagnostics.push({
-                code: 'review_part_missing',
-                severity: 'warning',
-                message: `Part "${partId}" missing for review packet`,
-                part: partId,
-            });
-        }
-    }
-    const packet = {
-        schema: 'specflow.approval.review-packet/v1',
-        change: index.change,
-        generated_at: new Date().toISOString(),
-        index_summary: {
-            interfaces: index.interfaces.length,
-            pages: index.pages.length,
-            tables: index.tables.length,
-            parts: parts.length,
-        },
-        lint_diagnostics: lintResult.diagnostics,
-        parts,
-        checklist: [...AI_REVIEW_CHECKLIST],
-        instructions: [
-            'Stage 12e AI Review: Read prompts/approval/ai-review.md',
-            '1. Read approval/review-packet.json and all parts listed',
-            '2. Fix issues in parts (not in assembled approval.md)',
-            '3. Write approval/review-result.json with findings + part_hashes (specflow approval review-hashes <change> --json)',
-            '4. Re-run: specflow approval finalize <change>',
-        ].join('\n'),
-    };
-    const packetPath = getApprovalReviewPacketPath(changeDir);
-    await fs.writeFile(packetPath, JSON.stringify(packet, null, 2), 'utf-8');
-    return { ok: true, packet, packetPath, diagnostics };
-}
-export async function checkApprovalReview(options) {
-    const diagnostics = [];
-    const { changeDir, requirePass = 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 index: ${message}` },
-            ],
-        };
-    }
-    const reviewRequired = options.forceRequire === true ||
-        index.acp?.review?.required_pass === true ||
-        index.acp?.review?.enabled === true;
-    let review;
-    try {
-        const raw = JSON.parse(await fs.readFile(getApprovalReviewPath(changeDir), 'utf-8'));
-        review = parseApprovalReviewResult(raw);
-    }
-    catch {
-        if (reviewRequired && requirePass) {
-            return {
-                ok: false,
-                diagnostics: [
-                    {
-                        code: 'review_missing',
-                        severity: 'error',
-                        message: 'approval/review-result.json missing; run AI review (Stage 12e) and write review-result.json',
-                    },
-                ],
-            };
-        }
-        return { ok: true, diagnostics: [] };
-    }
-    if (review.change !== index.change) {
-        diagnostics.push({
-            code: 'review_change_mismatch',
-            severity: 'error',
-            message: `review-result change "${review.change}" != index change "${index.change}"`,
-        });
-    }
-    const openFindings = review.findings.filter((f) => f.status === 'open');
-    for (const f of openFindings) {
-        diagnostics.push({
-            code: 'review_finding_open',
-            severity: f.severity === 'critical' ? 'error' : 'warning',
-            message: `[${f.id}] ${f.message}`,
-            part: f.part,
-        });
-    }
-    const waivedWithoutReason = review.findings.filter((f) => f.status === 'waived' && !f.waiver_reason?.trim());
-    for (const f of waivedWithoutReason) {
-        diagnostics.push({
-            code: 'review_waiver_missing_reason',
-            severity: 'error',
-            message: `[${f.id}] waived finding must include waiver_reason`,
-            part: f.part,
-        });
-    }
-    if (review.verdict === 'fail') {
-        diagnostics.push({
-            code: 'review_verdict_fail',
-            severity: 'error',
-            message: 'review-result verdict is fail',
-        });
-    }
-    if (review.part_hashes && review.part_hashes.length > 0) {
-        for (const entry of review.part_hashes) {
-            try {
-                const content = await fs.readFile(getApprovalPartPath(changeDir, entry.id), 'utf-8');
-                const current = sha256(content);
-                if (current !== entry.sha256) {
-                    diagnostics.push({
-                        code: 'review_part_stale',
-                        severity: 'error',
-                        message: `Part "${entry.id}" changed after AI review; re-run Stage 12e and update review-result.json part_hashes`,
-                        part: entry.id,
-                    });
-                }
-            }
-            catch {
-                diagnostics.push({
-                    code: 'review_part_missing',
-                    severity: 'error',
-                    message: `Part "${entry.id}" in review-result.part_hashes not found on disk`,
-                    part: entry.id,
-                });
-            }
-        }
-    }
-    else if (reviewRequired) {
-        diagnostics.push({
-            code: 'review_part_hashes_missing',
-            severity: 'error',
-            message: 'review-result.json must include part_hashes[] (sha256 of each part after fixes); see ai-review.md §4',
-        });
-    }
-    const lintResult = await lintApprovalDocument({ changeDir, strict: true });
-    diagnostics.push(...lintResult.diagnostics);
-    const hasError = diagnostics.some((d) => d.severity === 'error');
-    return { ok: !hasError, review, diagnostics };
-}

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

@@ -1,223 +0,0 @@
-export type ApprovalGenerationMode = 'segmented' | 'monolithic';
-export type ApprovalPartStatus = 'draft' | 'ok' | 'retry';
-export interface ApprovalOptionalChapters {
-    readonly s5: boolean;
-    readonly s7: boolean;
-    readonly s8: boolean;
-}
-export interface ApprovalBatching {
-    readonly tables_per_call: number;
-    readonly interfaces_per_call: number;
-    readonly pages_per_call: number;
-    readonly capabilities_per_call: number;
-}
-export type ApprovalRepoRole = 'platform' | 'web' | 'worker' | 'hub' | 'other';
-export type ApprovalDocumentMode = 'unified' | 'per_repo';
-export interface ApprovalMultiRepoEntry {
-    readonly id: string;
-    readonly label: string;
-    readonly role?: ApprovalRepoRole;
-    readonly change: string;
-    readonly root_hint?: string;
-}
-export interface ApprovalOutputRef {
-    readonly repo: string;
-    readonly change: string;
-    readonly path: string;
-}
-export interface ApprovalMultiRepoBundle {
-    readonly enabled?: boolean;
-    readonly playbook?: string;
-    readonly output?: string;
-    readonly readonly?: boolean;
-}
-export interface ApprovalMultiRepo {
-    readonly enabled: boolean;
-    readonly document_mode?: ApprovalDocumentMode;
-    readonly primary_repo?: string;
-    readonly repos: readonly ApprovalMultiRepoEntry[];
-    readonly outputs?: {
-        readonly unified?: ApprovalOutputRef;
-        readonly per_repo?: readonly ApprovalOutputRef[];
-    };
-    readonly bundle?: ApprovalMultiRepoBundle;
-}
-export interface ApprovalFeatureSlice {
-    readonly id: string;
-    readonly repos?: readonly string[];
-    readonly interfaces?: readonly string[];
-    readonly pages?: readonly string[];
-    readonly design_points?: readonly string[];
-    readonly parts: readonly string[];
-}
-export interface ApprovalAcpReview {
-    readonly enabled?: boolean;
-    readonly required_pass?: boolean;
-}
-export interface ApprovalAcpBlock {
-    readonly pipeline?: 'acp/v1' | 'acp/v2';
-    readonly context_budget_tokens?: number;
-    readonly output_budget_tokens?: number;
-    readonly feature_slices?: readonly ApprovalFeatureSlice[];
-    readonly review?: ApprovalAcpReview;
-}
-export interface ApprovalTableRef {
-    readonly id: string;
-    readonly name: string;
-    readonly action: string;
-    readonly part: string;
-    readonly repo?: string;
-}
-export interface ApprovalInterfaceFrozen {
-    readonly rpc?: string;
-    readonly http_path?: string;
-    readonly status_enum?: readonly string[];
-}
-export interface ApprovalInterfaceRef {
-    readonly id: string;
-    readonly short: string;
-    readonly change: string;
-    readonly part: string;
-    readonly repo?: string;
-    readonly layers?: readonly string[];
-    readonly pairs_with?: string;
-    readonly feature_slice?: string;
-    readonly frozen?: ApprovalInterfaceFrozen;
-}
-export interface ApprovalPageRef {
-    readonly id: string;
-    readonly route: string;
-    readonly apis: readonly string[];
-    readonly part: string;
-    readonly repo?: string;
-}
-export interface ApprovalCapabilityRef {
-    readonly id: string;
-    readonly part: string;
-}
-export interface ApprovalConventionsResolved {
-    readonly architecture?: readonly string[];
-    readonly database?: readonly string[];
-    readonly api?: readonly string[];
-    readonly frontend?: readonly string[];
-}
-export interface ApprovalIndex {
-    readonly schema: 'specflow.approval.index/v1';
-    readonly change: string;
-    readonly generated_at: string;
-    readonly mode: ApprovalGenerationMode;
-    readonly ui_in_scope: boolean;
-    readonly db_in_scope: boolean;
-    readonly api_in_scope: boolean;
-    readonly optional: ApprovalOptionalChapters;
-    readonly parts_order: readonly string[];
-    readonly design_points: readonly string[];
-    readonly decisions: readonly string[];
-    readonly tables: readonly ApprovalTableRef[];
-    readonly interfaces: readonly ApprovalInterfaceRef[];
-    readonly pages: readonly ApprovalPageRef[];
-    readonly capabilities: readonly ApprovalCapabilityRef[];
-    readonly batching: ApprovalBatching;
-    readonly conventions: ApprovalConventionsResolved;
-    readonly multi_repo?: ApprovalMultiRepo;
-    readonly acp?: ApprovalAcpBlock;
-    readonly meta?: {
-        readonly language?: string;
-        readonly tech_stack?: string;
-        readonly project_mode?: string;
-    };
-}
-export interface ApprovalManifestPart {
-    readonly id: string;
-    readonly path: string;
-    readonly status: ApprovalPartStatus;
-    readonly sha256?: string;
-    readonly updated_at?: string;
-}
-export interface ApprovalManifest {
-    readonly schema: 'specflow.approval.manifest/v1';
-    readonly change: string;
-    readonly parts: readonly ApprovalManifestPart[];
-    readonly assembled_at?: string;
-    readonly approval_sha256?: string;
-}
-export type ApprovalDiagnosticSeverity = 'error' | 'warning';
-export interface ApprovalDiagnostic {
-    readonly code: string;
-    readonly severity: ApprovalDiagnosticSeverity;
-    readonly message: string;
-    readonly part?: string;
-}
-export interface ApprovalReviewFinding {
-    readonly id: string;
-    readonly severity: 'critical' | 'important' | 'minor';
-    readonly category: string;
-    readonly message: string;
-    readonly part?: string;
-    readonly status: 'open' | 'fixed' | 'waived';
-    readonly waiver_reason?: string;
-}
-export interface ApprovalReviewResult {
-    readonly schema: 'specflow.approval.review/v1';
-    readonly change: string;
-    readonly reviewed_at: string;
-    readonly reviewer: 'ai' | 'human';
-    readonly findings: readonly ApprovalReviewFinding[];
-    readonly verdict: 'pass' | 'fail' | 'pass_with_waivers';
-    readonly summary?: string;
-    readonly part_hashes?: readonly {
-        readonly id: string;
-        readonly sha256: string;
-    }[];
-}
-export interface ApprovalReviewPacket {
-    readonly schema: 'specflow.approval.review-packet/v1';
-    readonly change: string;
-    readonly generated_at: string;
-    readonly index_summary: {
-        readonly interfaces: number;
-        readonly pages: number;
-        readonly tables: number;
-        readonly parts: number;
-    };
-    readonly lint_diagnostics: readonly ApprovalDiagnostic[];
-    readonly parts: readonly {
-        readonly id: string;
-        readonly sha256: string;
-        readonly bytes: number;
-    }[];
-    readonly checklist: readonly string[];
-    readonly instructions: string;
-}
-export interface ApprovalPlaybookSource {
-    readonly repo: string;
-    readonly change: string;
-    readonly include_parts?: 'all' | readonly string[];
-    readonly root?: string;
-}
-export interface ApprovalPlaybook {
-    readonly schema: 'specflow.approval.playbook/v1';
-    readonly change: string;
-    readonly title: string;
-    readonly primary_repo: string;
-    readonly sources: readonly ApprovalPlaybookSource[];
-    readonly overlay?: readonly string[];
-    readonly assemble: {
-        readonly inject_headers?: boolean;
-        readonly dedupe_appendix?: boolean;
-        readonly output: string;
-        readonly readonly?: boolean;
-    };
-}
-export interface ApprovalBundleResult {
-    readonly ok: boolean;
-    readonly outputPath?: string;
-    readonly diagnostics: readonly ApprovalDiagnostic[];
-    readonly markdown?: string;
-}
-export interface ApprovalAssembleResult {
-    readonly markdown?: string;
-    readonly outputPath?: string;
-    readonly diagnostics: readonly ApprovalDiagnostic[];
-    readonly ok: boolean;
-}

package/dist/core/approval/types.js

@@ -1 +0,0 @@
-export {};

package/prompts/approval/acp-pipeline.md

@@ -1,106 +0,0 @@
-# Approval · ACP Pipeline (Approval Compiler Pipeline)
-
-> Router for `/specflow:approval` **Stage 12** when `acp.pipeline=acp/v2` (recommended for non-lightweight changes).
-> Legacy segmented flow remains valid; ACP adds **lint**, **AI review**, and **bundle** gates.
-
----
-
-## Pipeline (hard order)
-
-```text
-Phase 1  Analyze     → analysis.json + IR planner (chat gate)
-Phase 2  IR Freeze   → index.yaml (+ interfaces[].frozen, feature_slices, acp.review)
-Phase 3  Skeleton    → parts 01–03, 04-detail-core, 06/09/10
-Phase 4  Slot Map    → batched parts 04.4–04.9 (vertical slice first)
-Phase 5  AI Review    → Stage 12e in-session (prompts/approval/ai-review.md) — **inside /specflow-approval**
-Phase 6  finalize      → specflow approval finalize <change> [--bundle] [--render]
-Phase 7  render        → specflow approval render <change> [--input] [--output]
-
-**Preferred**: one `finalize` after Map + AI review. Subcommands (`lint`, `assemble`, …) are for CI/debug only.
-```
-
-**Never** skip Phase 6a–6b with LLM paste. **Never** write `approval-unified.md` by hand when bundle is enabled.
-
----
-
-## index.yaml ACP block
-
-```yaml
-acp:
-  pipeline: acp/v2
-  context_budget_tokens: 40000
-  output_budget_tokens: 8000
-  feature_slices:
-    - id: step-reporting
-      parts: [04.5-api-worker, 04.5-api-east, 04-detail-core]
-      interfaces: [I13, I14, I16, I17]
-  review:
-    enabled: true
-    required_pass: true
-```
-
-## interfaces[].frozen (IR freeze before Map)
-
-```yaml
-interfaces:
-  - id: I14
-    short: SubmitStepResult
-    change: scenario-job-compile
-    part: 04.5-api-worker
-    pairs_with: I13
-    layers: [L3]
-    frozen:
-      rpc: scheduler.Scheduler.SubmitStepResult
-      http_path: POST /internal/v1/tasks/{job_id}/step-results
-      status_enum: [passed, failed, skipped, error]
-```
-
----
-
-## Multi-repo default
-
-- **True source**: `per_repo` — each repo `approval/` + `approval.md`
-- **Read-only view**: `approval bundle` from `approval-playbook.yaml`
-- Do **not** LLM-unify three repos into one primary `approval/parts`
-
-See `multi-repo-guidance.md` + `templates/approval-playbook.yaml` (+ example `templates/approval-playbook-talos-scenario-job-compile.yaml`).
-
-**Orchestration**: multi-repo mode A uses **Stage 1c** subagent parallel dispatch (`multi-repo-spoke-subagent.md`) — not a single-repo `finalize` across repos.
-
----
-
-## Context packet (Map batch)
-
-Read only:
-
-1. `index.yaml` subset for this batch (ids + frozen fields)
-2. `analysis.json` verdicts (not full Pass essays)
-3. design/spec **snippets** for batch entities
-4. 1–2 anchor files for this batch
-5. guidance router (path only, not full paste)
-
-Do **not** reload entire four-artifact sets each batch.
-
----
-
-## CLI reference
-
-| Command | Purpose |
-|---------|---------|
-| `approval render` | MD → standalone HTML (tables, GFM, mermaid via CDN) |
-| `approval finalize` | **Preferred** — full lint → review-check → check → assemble → bundle |
-| `approval lint` | Cross-part consistency (CI / debug) |
-| `approval review-pack` | Emit `review-packet.json` (debug; finalize auto-runs when needed) |
-| `approval review-check` | Validate `review-result.json` (debug) |
-| `approval check` | Part presence + lazy stub (debug) |
-| `approval assemble` | Deterministic Reduce (debug) |
-| `approval bundle` | Multi-repo readonly merge (debug; finalize can auto-run) |
-
----
-
-## Related guidance
-
-- `segmented-generation.md` — Map anti-lazy L1–L10
-- `ai-review.md` — Stage 12e AI approval/revision
-- `runtime-guidance.md` — optional async/lease/cancel (when in scope)
-- `api-guidance.md` — optional multi-layer API contracts (when api_in_scope)

package/prompts/approval/ai-review.md

@@ -1,145 +0,0 @@
-# Approval · Stage 12e AI Review (审批 / 修订)
-
-> Runs **after** Map parts written, **before** `specflow approval finalize` completes.
-> Purpose: catch **long-document / multi-part semantic drift** that mechanical lint cannot judge; **revise parts in place**.
-
-**Scope**: checks apply to **any** segmented approval — not tied to a specific product, repo, or domain.
-Use `index.yaml` + `analysis.json` as the contract; do not inject checks from unrelated case studies.
-
----
-
-## 0. Trigger
-
-Run when **any**:
-
-- `acp.review.enabled=true` in `index.yaml` (default for non-lightweight)
-- User asks for AI 审批 / 方案审查 / 一致性检查
-- `specflow approval finalize` paused at `review-required`
-
----
-
-## 1. Prep (hard)
-
-```bash
-specflow approval finalize <change>   # pauses + writes review-packet.json if needed
-```
-
-Read:
-
-- `approval/review-packet.json` (checklist + lint diagnostics)
-- `approval/index.yaml` (inventory, design_points, frozen fields, parts_order)
-- `approval/analysis.json` (Pass verdicts — gaps to close)
-- **All** `approval/parts/*.md` in `parts_order`
-
-Optional domain packs (only when design **actually** touches that topic):
-
-- `runtime-guidance.md` — async job / lease / retry / cancel semantics
-- `api-guidance.md` — multi-layer API contracts
-- `frontend-guidance.md` — §4.6 depth
-
----
-
-## 2. Review dimensions (long-document generic)
-
-These target **failure modes of long, batched documents** — inconsistency across parts written at different times.
-
-| ID | Category | Check (generic) |
-|----|----------|-----------------|
-| R1 | **Cross-part naming** | Same entity (service, table, interface, page, enum) uses **one** canonical name/id across §2, §4, diagrams, and `index.yaml`. No 「暂定 / 实现时 / 如 Xxx / TBD」 for listed inventory ids. |
-| R2 | **Decision traceability** | Each `decisions[]` / §2 row appears in §4 with concrete behavior — not only repeated in summary. |
-| R3 | **Inventory ↔ body** | Every `tables[]` / `interfaces[]` / `pages[]` / `design_points[]` entry in index has **substantive** content in its assigned `part`. No orphan ids; no body content for ids missing from index. |
-| R4 | **Depth parity** | Parts in the same `feature_slices` or batch have **comparable** depth. No pattern of one part fully detailed while sibling parts are one-line stubs. |
-| R5 | **Cross-reference integrity** | Internal refs use stable ids (`§4.5 I2`, `P3`, `Page·列表`, `T1`) — not bare 「详见 design/tasks」. Ref targets exist and match. |
-| R6 | **Diagram ↔ prose** | Sequence / flow diagrams agree with adjacent prose (actors, message names, order, error branches). |
-| R7 | **Contract completeness** | Each listed interface/page-api has minimum skeleton from Part E (fields, success example, **failure example**, error table) — depth scaled to `api_in_scope` / `ui_in_scope`. |
-| R8 | **Enum / state closure** | Status, enum, and terminal-state sets are **explicit and closed** wherever the doc defines them — no 「等」 or open-ended lists unless explicitly extensible by design. |
-| R9 | **Unclosed branches** | Every **mentioned** branch (retry, cancel, timeout, idempotency, rollback, concurrency) has a documented outcome — or is flagged `[待 refine 澄清: …]` with owner. Do **not** assume domain-specific branches (e.g. lease reclaim) unless design/analysis mentions them. |
-| R10 | **UI ↔ API alignment** | When `ui_in_scope`: §4.6 field names, types, and api refs align with §4.5 / `pages[].apis`. |
-| R11 | **Multi-repo parity** | When `multi_repo.enabled`: each repo slice in scope has proportionate depth; no 「主仓详、他仓 stub」 unless explicitly out of scope. |
-| R12 | **Stub purge** | No `TODO` / `待补充` / `此处省略` / placeholder-only sections in parts slated for assemble. |
-| R13 | **Verdict coherence** | §9 implementability / readiness matches §4 depth — no READY alongside unexplained NEEDS REFINEMENT or contradictory gates. |
-
-**Not in default scope**: product-specific rules (talos lease wipe, ingest whitelist, L2/L3 layering) — load the matching guidance pack **only** when the change design requires it.
-
----
-
-## 3. Revision rules (hard)
-
-1. **Edit `approval/parts/*.md` only** — never edit assembled `approval.md` directly
-2. **Update `index.yaml` first** when changing frozen ids, rpc names, or inventory
-3. Each finding → fix in named `part` OR waive (`minor` only) with `waiver_reason`
-4. Re-run:
-
-```bash
-specflow approval finalize <change>
-```
-
----
-
-## 4. Write review-result.json
-
-Path: `approval/review-result.json`
-
-```json
-{
-  "schema": "specflow.approval.review/v1",
-  "change": "<change-name>",
-  "reviewed_at": "2026-08-26T12:00:00Z",
-  "reviewer": "ai",
-  "verdict": "pass",
-  "summary": "Fixed cross-part naming for I3; expanded P2 error path in 04-detail-core",
-  "part_hashes": [
-    { "id": "04.5-api", "sha256": "<sha256-after-fixes>" },
-    { "id": "04-detail-core", "sha256": "<sha256-after-fixes>" }
-  ],
-  "findings": [
-    {
-      "id": "F1",
-      "severity": "critical",
-      "category": "cross_part_naming",
-      "message": "I3 RPC name differs between §2 and 04.5-api",
-      "part": "04.5-api",
-      "status": "fixed"
-    },
-    {
-      "id": "F2",
-      "severity": "important",
-      "category": "unclosed_branch",
-      "message": "Retry path mentioned in §4.3 but no terminal outcome",
-      "part": "04-detail-core",
-      "status": "fixed"
-    }
-  ]
-}
-```
-
-| verdict | When |
-|---------|------|
-| `pass` | All findings `fixed`; strict lint pass; **`part_hashes` match current parts** |
-| `pass_with_waivers` | Only `minor` waived with `waiver_reason` |
-| `fail` | Any `critical` / `important` still `open` |
-
-**Waive policy**: only `minor` may be waived; critical/important must fix or escalate to user.
-
-**part_hashes (required when `acp.review.enabled`)**: After fixing parts, run `specflow approval review-hashes <change> --json` and copy the array into `review-result.json`. `review-check` fails if parts change after review without updating review-result.
-
----
-
-## 5. User gate
-
-When a finding requires a **product/architecture choice** the artifacts do not resolve:
-
-```text
-[待用户确认] <topic>: options A / B / C — record choice as new decision + update affected parts
-```
-
-Stop finalize until user chooses; do not invent policy.
-
----
-
-## 6. Announce
-
-```text
-AI Review: findings=<n> fixed=<n> waived=<n> verdict=pass|fail
-Next: specflow approval finalize <change>
-```