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

package/dist/core/approval/playbook-schema.d.ts

@@ -0,0 +1,182 @@
+import { z } from 'zod';
+import type { ApprovalPlaybook } from './types.js';
+export declare const approvalPlaybookSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"specflow.approval.playbook/v1">;
+    change: z.ZodString;
+    title: z.ZodString;
+    primary_repo: z.ZodString;
+    sources: z.ZodArray<z.ZodObject<{
+        repo: z.ZodString;
+        change: z.ZodString;
+        include_parts: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"all">, z.ZodArray<z.ZodString, "many">]>>;
+        root: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        repo: string;
+        change: string;
+        root?: string | undefined;
+        include_parts?: string[] | "all" | undefined;
+    }, {
+        repo: string;
+        change: string;
+        root?: string | undefined;
+        include_parts?: string[] | "all" | undefined;
+    }>, "many">;
+    overlay: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    assemble: z.ZodObject<{
+        inject_headers: z.ZodOptional<z.ZodBoolean>;
+        dedupe_appendix: z.ZodOptional<z.ZodBoolean>;
+        output: z.ZodString;
+        readonly: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        output: string;
+        readonly?: boolean | undefined;
+        inject_headers?: boolean | undefined;
+        dedupe_appendix?: boolean | undefined;
+    }, {
+        output: string;
+        readonly?: boolean | undefined;
+        inject_headers?: boolean | undefined;
+        dedupe_appendix?: boolean | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    schema: "specflow.approval.playbook/v1";
+    change: string;
+    primary_repo: string;
+    title: string;
+    sources: {
+        repo: string;
+        change: string;
+        root?: string | undefined;
+        include_parts?: string[] | "all" | undefined;
+    }[];
+    assemble: {
+        output: string;
+        readonly?: boolean | undefined;
+        inject_headers?: boolean | undefined;
+        dedupe_appendix?: boolean | undefined;
+    };
+    overlay?: string[] | undefined;
+}, {
+    schema: "specflow.approval.playbook/v1";
+    change: string;
+    primary_repo: string;
+    title: string;
+    sources: {
+        repo: string;
+        change: string;
+        root?: string | undefined;
+        include_parts?: string[] | "all" | undefined;
+    }[];
+    assemble: {
+        output: string;
+        readonly?: boolean | undefined;
+        inject_headers?: boolean | undefined;
+        dedupe_appendix?: boolean | undefined;
+    };
+    overlay?: string[] | undefined;
+}>;
+export declare const approvalReviewResultSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"specflow.approval.review/v1">;
+    change: z.ZodString;
+    reviewed_at: z.ZodString;
+    reviewer: z.ZodEnum<["ai", "human"]>;
+    findings: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        severity: z.ZodEnum<["critical", "important", "minor"]>;
+        category: z.ZodString;
+        message: z.ZodString;
+        part: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<["open", "fixed", "waived"]>;
+        waiver_reason: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "fixed" | "open" | "waived";
+        message: string;
+        id: string;
+        severity: "critical" | "important" | "minor";
+        category: string;
+        part?: string | undefined;
+        waiver_reason?: string | undefined;
+    }, {
+        status: "fixed" | "open" | "waived";
+        message: string;
+        id: string;
+        severity: "critical" | "important" | "minor";
+        category: string;
+        part?: string | undefined;
+        waiver_reason?: string | undefined;
+    }>, "many">;
+    verdict: z.ZodEnum<["pass", "fail", "pass_with_waivers"]>;
+    summary: z.ZodOptional<z.ZodString>;
+    part_hashes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        sha256: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        sha256: string;
+    }, {
+        id: string;
+        sha256: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    schema: "specflow.approval.review/v1";
+    change: string;
+    reviewed_at: string;
+    reviewer: "ai" | "human";
+    findings: {
+        status: "fixed" | "open" | "waived";
+        message: string;
+        id: string;
+        severity: "critical" | "important" | "minor";
+        category: string;
+        part?: string | undefined;
+        waiver_reason?: string | undefined;
+    }[];
+    verdict: "fail" | "pass" | "pass_with_waivers";
+    part_hashes?: {
+        id: string;
+        sha256: string;
+    }[] | undefined;
+    summary?: string | undefined;
+}, {
+    schema: "specflow.approval.review/v1";
+    change: string;
+    reviewed_at: string;
+    reviewer: "ai" | "human";
+    findings: {
+        status: "fixed" | "open" | "waived";
+        message: string;
+        id: string;
+        severity: "critical" | "important" | "minor";
+        category: string;
+        part?: string | undefined;
+        waiver_reason?: string | undefined;
+    }[];
+    verdict: "fail" | "pass" | "pass_with_waivers";
+    part_hashes?: {
+        id: string;
+        sha256: string;
+    }[] | undefined;
+    summary?: string | undefined;
+}>;
+export declare function parseApprovalPlaybook(raw: unknown): ApprovalPlaybook;
+export declare function parseApprovalReviewResult(raw: unknown): {
+    schema: "specflow.approval.review/v1";
+    change: string;
+    reviewed_at: string;
+    reviewer: "ai" | "human";
+    findings: {
+        status: "fixed" | "open" | "waived";
+        message: string;
+        id: string;
+        severity: "critical" | "important" | "minor";
+        category: string;
+        part?: string | undefined;
+        waiver_reason?: string | undefined;
+    }[];
+    verdict: "fail" | "pass" | "pass_with_waivers";
+    part_hashes?: {
+        id: string;
+        sha256: string;
+    }[] | undefined;
+    summary?: string | undefined;
+};

package/dist/core/approval/playbook-schema.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+export const approvalPlaybookSchema = z.object({
+    schema: z.literal('specflow.approval.playbook/v1'),
+    change: z.string().min(1),
+    title: z.string().min(1),
+    primary_repo: z.string().min(1),
+    sources: z
+        .array(z.object({
+        repo: z.string().min(1),
+        change: z.string().min(1),
+        include_parts: z.union([z.literal('all'), z.array(z.string().min(1))]).optional(),
+        root: z.string().min(1).optional(),
+    }))
+        .min(1),
+    overlay: z.array(z.string().min(1)).optional(),
+    assemble: z.object({
+        inject_headers: z.boolean().optional(),
+        dedupe_appendix: z.boolean().optional(),
+        output: z.string().min(1),
+        readonly: z.boolean().optional(),
+    }),
+});
+export const approvalReviewResultSchema = z.object({
+    schema: z.literal('specflow.approval.review/v1'),
+    change: z.string().min(1),
+    reviewed_at: z.string().min(1),
+    reviewer: z.enum(['ai', 'human']),
+    findings: z.array(z.object({
+        id: z.string().min(1),
+        severity: z.enum(['critical', 'important', 'minor']),
+        category: z.string().min(1),
+        message: z.string().min(1),
+        part: z.string().optional(),
+        status: z.enum(['open', 'fixed', 'waived']),
+        waiver_reason: z.string().optional(),
+    })),
+    verdict: z.enum(['pass', 'fail', 'pass_with_waivers']),
+    summary: z.string().optional(),
+    part_hashes: z
+        .array(z.object({
+        id: z.string().min(1),
+        sha256: z.string().min(64).max(64),
+    }))
+        .optional(),
+});
+export function parseApprovalPlaybook(raw) {
+    return approvalPlaybookSchema.parse(raw);
+}
+export function parseApprovalReviewResult(raw) {
+    return approvalReviewResultSchema.parse(raw);
+}

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

@@ -0,0 +1,20 @@
+import type { ApprovalDiagnostic } from './types.js';
+export interface RenderApprovalOptions {
+    readonly changeDir: string;
+    readonly inputPath?: string;
+    readonly outputPath?: string;
+    readonly title?: string;
+    readonly write?: boolean;
+}
+export interface RenderApprovalResult {
+    readonly ok: boolean;
+    readonly outputPath?: string;
+    readonly html?: string;
+    readonly sha256?: string;
+    readonly diagnostics: readonly ApprovalDiagnostic[];
+}
+export declare function renderApprovalDocument(options: RenderApprovalOptions): Promise<RenderApprovalResult>;
+export declare function resolveApprovalRenderPaths(changeDir: string, input?: string, output?: string): {
+    inputPath: string;
+    outputPath: string;
+};

package/dist/core/approval/render.js

@@ -0,0 +1,210 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { marked } from 'marked';
+import { getApprovalOutputPath } from './paths.js';
+const APPROVAL_HTML_STYLES = `
+:root {
+  color-scheme: light dark;
+  --text: #1a1a1a;
+  --muted: #555;
+  --border: #ddd;
+  --code-bg: #f6f8fa;
+  --quote-bg: #f0f4ff;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --text: #e6edf3;
+    --muted: #9da7b3;
+    --border: #30363d;
+    --code-bg: #161b22;
+    --quote-bg: #1c2333;
+  }
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "PingFang SC",
+    "Hiragino Sans GB", "Microsoft YaHei", sans-serif;
+  line-height: 1.65;
+  color: var(--text);
+  background: #fff;
+}
+@media (prefers-color-scheme: dark) {
+  body { background: #0d1117; }
+}
+.page {
+  max-width: 920px;
+  margin: 0 auto;
+  padding: 2rem 1.5rem 4rem;
+}
+.meta {
+  font-size: 0.875rem;
+  color: var(--muted);
+  margin-bottom: 2rem;
+  padding-bottom: 1rem;
+  border-bottom: 1px solid var(--border);
+}
+article h1 { font-size: 1.75rem; margin-top: 0; }
+article h2 { font-size: 1.35rem; margin-top: 2rem; border-bottom: 1px solid var(--border); padding-bottom: 0.35rem; }
+article h3 { font-size: 1.15rem; margin-top: 1.5rem; }
+article h4, article h5 { font-size: 1rem; margin-top: 1.25rem; }
+article p, article li { margin: 0.5rem 0; }
+article blockquote {
+  margin: 1rem 0;
+  padding: 0.75rem 1rem;
+  border-left: 4px solid #0969da;
+  background: var(--quote-bg);
+  color: var(--muted);
+}
+article table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 1rem 0;
+  font-size: 0.92rem;
+}
+article th, article td {
+  border: 1px solid var(--border);
+  padding: 0.45rem 0.65rem;
+  text-align: left;
+}
+article th { background: var(--code-bg); }
+article code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 0.9em;
+  background: var(--code-bg);
+  padding: 0.15em 0.35em;
+  border-radius: 4px;
+}
+article pre {
+  overflow-x: auto;
+  padding: 1rem;
+  background: var(--code-bg);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+}
+article pre code { background: none; padding: 0; }
+article hr { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
+.mermaid {
+  margin: 1rem 0;
+  text-align: center;
+}
+`.trim();
+function sha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+function defaultHtmlPath(markdownPath) {
+    if (markdownPath.endsWith('.md')) {
+        return markdownPath.slice(0, -3) + '.html';
+    }
+    return `${markdownPath}.html`;
+}
+function extractTitle(markdown, fallback) {
+    const match = markdown.match(/^#\s+(.+)$/m);
+    return match?.[1]?.trim() ?? fallback;
+}
+function configureMarked() {
+    marked.use({
+        gfm: true,
+        breaks: false,
+    });
+    marked.use({
+        renderer: {
+            code({ text, lang }) {
+                if (lang === 'mermaid') {
+                    return `<pre class="mermaid">${escapeHtml(text)}</pre>`;
+                }
+                const language = lang ? ` class="language-${lang}"` : '';
+                return `<pre><code${language}>${escapeHtml(text)}</code></pre>`;
+            },
+        },
+    });
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+function buildHtmlDocument(title, bodyHtml, sourcePath) {
+    const hasMermaid = bodyHtml.includes('class="mermaid"');
+    const mermaidScript = hasMermaid
+        ? `<script type="module">
+import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+mermaid.initialize({ startOnLoad: true, theme: 'neutral' });
+</script>`
+        : '';
+    return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(title)}</title>
+  <style>${APPROVAL_HTML_STYLES}</style>
+</head>
+<body>
+  <div class="page">
+    <div class="meta">SpecFlow approval render · source: ${escapeHtml(sourcePath)} · generated by <code>specflow approval render</code></div>
+    <article>${bodyHtml}</article>
+  </div>
+  ${mermaidScript}
+</body>
+</html>
+`;
+}
+export async function renderApprovalDocument(options) {
+    const diagnostics = [];
+    const { changeDir, write = true } = options;
+    const inputPath = options.inputPath ?? getApprovalOutputPath(changeDir);
+    const outputPath = options.outputPath ?? defaultHtmlPath(inputPath);
+    let markdown;
+    try {
+        markdown = await fs.readFile(inputPath, 'utf-8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            diagnostics: [
+                {
+                    code: 'render_input_missing',
+                    severity: 'error',
+                    message: `Cannot read markdown: ${inputPath} (${message})`,
+                },
+            ],
+        };
+    }
+    if (markdown.trim().length < 20) {
+        diagnostics.push({
+            code: 'render_input_empty',
+            severity: 'error',
+            message: `Markdown input too short or empty: ${inputPath}`,
+        });
+        return { ok: false, diagnostics };
+    }
+    configureMarked();
+    const bodyHtml = await marked.parse(markdown);
+    const title = options.title ?? extractTitle(markdown, 'Approval Document');
+    const html = buildHtmlDocument(title, bodyHtml, inputPath);
+    const hash = sha256(html);
+    if (!write) {
+        return { ok: true, outputPath, html, sha256: hash, diagnostics };
+    }
+    await fs.mkdir(dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, html, 'utf-8');
+    return { ok: true, outputPath, html, sha256: hash, diagnostics };
+}
+export function resolveApprovalRenderPaths(changeDir, input, output) {
+    const inputPath = input
+        ? input.startsWith('/')
+            ? input
+            : join(changeDir, input)
+        : getApprovalOutputPath(changeDir);
+    const outputPath = output
+        ? output.startsWith('/')
+            ? output
+            : join(changeDir, output)
+        : defaultHtmlPath(inputPath);
+    return { inputPath, outputPath };
+}

package/dist/core/approval/review-pack.d.ts

@@ -0,0 +1,26 @@
+import type { ApprovalDiagnostic, ApprovalReviewPacket, ApprovalReviewResult } from './types.js';
+export declare function computeReviewPartHashes(changeDir: string, partIds: readonly string[]): Promise<{
+    id: string;
+    sha256: string;
+}[]>;
+export interface ReviewPackOptions {
+    readonly changeDir: string;
+}
+export interface ReviewPackResult {
+    readonly ok: boolean;
+    readonly packet?: ApprovalReviewPacket;
+    readonly packetPath?: string;
+    readonly diagnostics: readonly ApprovalDiagnostic[];
+}
+export declare function generateReviewPacket(options: ReviewPackOptions): Promise<ReviewPackResult>;
+export interface ReviewCheckOptions {
+    readonly changeDir: string;
+    readonly requirePass?: boolean;
+    readonly forceRequire?: boolean;
+}
+export interface ReviewCheckResult {
+    readonly ok: boolean;
+    readonly review?: ApprovalReviewResult;
+    readonly diagnostics: readonly ApprovalDiagnostic[];
+}
+export declare function checkApprovalReview(options: ReviewCheckOptions): Promise<ReviewCheckResult>;

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

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