@tea-agent/loop-agent 0.42.0-next.1 → 0.42.0-next.10

package/dist/workflows/dag/frontend-review-context.js

@@ -4,11 +4,166 @@ import path from "node:path";
 import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
 import { formatFrontendWorktreeDiffStdout, runFrontendWorktreeDiffGate, } from "./frontend-worktree-diff.js";
 import { frontendLintAssessmentArtifactSchema } from "./frontend-lint-baseline.js";
-import { frontendImplementationContractSchema, } from "./frontend-implementation-contract.js";
-import { frontendRepairAssessmentSchema } from "./frontend-repair.js";
+import { deterministicSha256, FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID, frontendImplementationContractSchema, writeFrontendContractReviewArtifacts, } from "./frontend-implementation-contract.js";
 import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
-import { ledgerStatsLine, parseLedgerJson, } from "../../task/source-prepare/ledger.js";
-export const FRONTEND_REVIEW_CONTEXT_SCHEMA_ID = "frontend-review-context-v1";
+import { ledgerStatsLine, parseLedgerJson } from "../../task/source-prepare/ledger.js";
+export const FRONTEND_REVIEW_CONTEXT_SCHEMA_ID = "frontend-review-context-v2";
+/**
+ * Deterministically assemble the cumulative diff from a task baseline and the
+ * current candidate snapshot. Same input always yields the same output:
+ * paths are sorted, statuses are derived from a fixed decision table, and both
+ * digests use canonical JSON hashing.
+ */
+export function assembleCumulativeDiffContext(input) {
+    const baselineByPath = new Map(input.baselineEntries.map((entry) => [entry.path, entry.sha256]));
+    const currentByPath = new Map(input.currentEntries.map((entry) => [entry.path, entry.sha256]));
+    const allPaths = new Set([
+        ...baselineByPath.keys(),
+        ...currentByPath.keys(),
+    ]);
+    const sortedPaths = [...allPaths].sort();
+    const perPath = sortedPaths
+        .map((p) => {
+        const baselineSha256 = baselineByPath.get(p) ?? null;
+        const hasCurrent = currentByPath.has(p);
+        const currentSha256 = hasCurrent
+            ? (currentByPath.get(p) ?? null)
+            : null;
+        let status;
+        if (baselineSha256 === null) {
+            status = currentSha256 === null ? "deleted" : "added";
+        }
+        else if (currentSha256 === null) {
+            status = hasCurrent ? "deleted" : "unchanged";
+        }
+        else {
+            status =
+                currentSha256 === baselineSha256 ? "unchanged" : "modified";
+        }
+        return { path: p, status, baselineSha256, currentSha256 };
+    })
+        // Cumulative diff carries only actual changes. The worktree baseline is
+        // the full repository inventory (git ls-files -co), so an unfiltered
+        // perPath enumerates thousands of unchanged hashes (e.g. 3000+ entries
+        // ≈ 700KB), ballooning the review context and blowing the review node
+        // read budget on a single read. Unchanged entries add no diff evidence.
+        .filter((entry) => entry.status !== "unchanged");
+    const baselineDigest = deterministicSha256([...input.baselineEntries].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const cumulativeDigest = deterministicSha256(perPath);
+    return {
+        schemaId: "frontend-cumulative-diff-context-v1",
+        baselineDigest,
+        perPath,
+        cumulativeDigest,
+        empty: perPath.length === 0,
+    };
+}
+async function sha256File(filePath) {
+    try {
+        const bytes = await readFile(filePath);
+        return createHash("sha256").update(bytes).digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Capture the cumulative diff from the frozen worktree baseline and the
+ * run-owned diff gate output. Pure status/digest logic lives in
+ * `assembleCumulativeDiffContext`; this wrapper only does IO.
+ */
+export async function captureCumulativeDiffContext(input) {
+    const root = path.resolve(input.workspaceRoot);
+    let baselineEntries = [];
+    try {
+        const raw = JSON.parse(await readFile(path.join(input.runDir, "contracts/frontend-worktree-baseline.json"), "utf8"));
+        baselineEntries = (raw.files ?? [])
+            .map((file) => ({ path: file, sha256: raw.hashes?.[file] ?? null }))
+            .filter((entry) => entry.sha256 !== null);
+    }
+    catch {
+        // Missing baseline → empty baseline entries (still deterministic).
+    }
+    const candidatePaths = [
+        ...new Set([...input.diff.changedFiles, ...input.diff.untrackedFiles]),
+    ];
+    const currentEntries = [];
+    for (const file of candidatePaths) {
+        currentEntries.push({
+            path: file,
+            sha256: await sha256File(path.join(root, file)),
+        });
+    }
+    return assembleCumulativeDiffContext({ baselineEntries, currentEntries });
+}
+const TYPED_TO_LEGACY = {
+    approve_review: "pass",
+    request_review_changes: "request-revision",
+};
+function isTypedReviewTerminalVerdict(value) {
+    return value === "approve_review" || value === "request_review_changes";
+}
+function isLegacyReviewVerdict(value) {
+    return value === "pass" || value === "request-revision";
+}
+/**
+ * Deterministic, fail-closed equivalence between the typed review terminal
+ * verdict(s) observed in the attempt and the legacy JSON verdict.
+ *
+ * Fail-closed cases (all yield `match: false` with an explicit reason):
+ *   - no typed terminal fact;
+ *   - more than one typed terminal fact (conflicting);
+ *   - an unknown typed terminal kind;
+ *   - a missing/illegal legacy JSON verdict.
+ */
+export function compareTypedReviewToLegacyJsonVerdict(input) {
+    const kinds = [...input.typedKinds];
+    const legacyVerdict = isLegacyReviewVerdict(input.legacyVerdict ?? "")
+        ? input.legacyVerdict
+        : undefined;
+    if (kinds.length === 0) {
+        return {
+            typedVerdict: undefined,
+            legacyVerdict,
+            match: false,
+            reason: "typed review terminal fact missing",
+        };
+    }
+    if (kinds.length > 1) {
+        return {
+            typedVerdict: undefined,
+            legacyVerdict,
+            match: false,
+            reason: `conflicting typed review terminal facts: ${[...new Set(kinds)].join(",")}`,
+        };
+    }
+    const typedVerdict = kinds[0];
+    if (!isTypedReviewTerminalVerdict(typedVerdict)) {
+        return {
+            typedVerdict: undefined,
+            legacyVerdict,
+            match: false,
+            reason: `unknown typed review terminal fact kind: ${typedVerdict}`,
+        };
+    }
+    if (!legacyVerdict) {
+        return {
+            typedVerdict,
+            legacyVerdict: undefined,
+            match: false,
+            reason: "legacy JSON verdict missing or not pass|request-revision",
+        };
+    }
+    const expected = TYPED_TO_LEGACY[typedVerdict];
+    return {
+        typedVerdict,
+        legacyVerdict,
+        match: expected === legacyVerdict,
+        reason: expected === legacyVerdict
+            ? "typed review verdict matches legacy JSON verdict"
+            : `typed review verdict ${typedVerdict} maps to ${expected} but legacy JSON verdict is ${legacyVerdict}`,
+    };
+}
 /**
  * review-context 稳定失败枚举（AC-011 / AC-HARD-005）：v2 drift / manifest 失败返回
  * 结构化、可消费的 failure code（稳定枚举 + reason 的 envelope），既有调用方无需字符串
@@ -52,6 +207,37 @@ async function readOptionalLintAssessment(runDir) {
         throw new Error(`frontend review context invalid ${relativePath}`);
     }
 }
+async function readOptionalRepairAssessment(runDir) {
+    const relativePath = "contracts/frontend-repair-assessment.json";
+    try {
+        return JSON.parse(await readFile(path.join(runDir, relativePath), "utf8"));
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return undefined;
+        }
+        throw new Error(`frontend review context invalid ${relativePath}`);
+    }
+}
+/** M8: verify failure ownership facts written by frontend-verify-shell. */
+async function readOptionalVerifyFailure(runDir) {
+    const relativePath = "contracts/frontend-verify-failure.json";
+    try {
+        return JSON.parse(await readFile(path.join(runDir, relativePath), "utf8"));
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return undefined;
+        }
+        throw new Error(`frontend review context invalid ${relativePath}`);
+    }
+}
 function assertReviewEvidence(input) {
     const contract = frontendImplementationContractSchema.safeParse(input.contract);
     if (!contract.success) {
@@ -94,47 +280,105 @@ function assertReviewEvidence(input) {
         trace.mockStrategy !== contract.data.mockApi.strategy) {
         throw new FrontendReviewContextFailure("review-context-verification-unbound", "frontend review context verification trace is not bound to a passing contract");
     }
-    const assessment = frontendRepairAssessmentSchema.safeParse(input.repairAssessment);
-    if (!assessment.success) {
-        throw new FrontendReviewContextFailure("review-context-invalid-contract", "frontend review context invalid repair assessment");
-    }
 }
 export async function runFrontendReviewContextGate(input) {
-    const contract = await readRequiredJson(input.runDir, "contracts/frontend-implementation-contract.json");
+    const contractRelativePath = "contracts/frontend-implementation-contract.json";
+    let contractRaw;
+    try {
+        contractRaw = await readFile(path.join(input.runDir, contractRelativePath), "utf8");
+    }
+    catch (error) {
+        throw new FrontendReviewContextFailure("review-context-manifest-missing", `frontend review context missing or invalid ${contractRelativePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let contract;
+    try {
+        contract = JSON.parse(contractRaw);
+    }
+    catch (error) {
+        throw new FrontendReviewContextFailure("review-context-manifest-missing", `frontend review context missing or invalid ${contractRelativePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
     const parsedContract = frontendImplementationContractSchema.safeParse(contract);
     if (!parsedContract.success) {
         throw new FrontendReviewContextFailure("review-context-invalid-contract", "frontend review context invalid implementation contract");
     }
+    // Authorized diff surface = deliverable files + every verification-target
+    // file the contract references. The writer legitimately writes VT test
+    // artifacts (behavior verification), and the reviewer must audit their
+    // diffs; scoping this to targets.files alone failed the baseline-overlap
+    // check on app.test.js (r19 extreme smoke).
+    const authorizedChangedPaths = [
+        ...new Set([
+            ...parsedContract.data.targets.files,
+            ...parsedContract.data.verificationTargets.map((target) => target.file),
+        ]),
+    ];
     const diff = await runFrontendWorktreeDiffGate({
         ...input,
-        authorizedChangedPaths: parsedContract.data.targets.files,
+        authorizedChangedPaths,
     });
     const verificationTrace = await readRequiredJson(input.runDir, "contracts/frontend-verification-trace.json");
-    const repairAssessment = await readRequiredJson(input.runDir, "contracts/frontend-repair-assessment.json");
+    const repairAssessment = await readOptionalRepairAssessment(input.runDir);
+    const verifyFailure = await readOptionalVerifyFailure(input.runDir);
     const lintAssessment = await readOptionalLintAssessment(input.runDir);
+    const cumulativeDiff = await captureCumulativeDiffContext({
+        runDir: input.runDir,
+        workspaceRoot: input.workspaceRoot,
+        diff,
+    });
     assertReviewEvidence({ contract, verificationTrace, repairAssessment });
     // Source fidelity ledger 核对（AC-008 / AC-FIDELITY-008）：ledger 缺失/漂移即阻断；
     // 同时把核对清单注入 review-context 供最终 reviewer 机械化核对。
     const sourceFidelity = await buildReviewSourceFidelityChecklist(input, parsedContract.data);
+    const contractReviewArtifacts = await writeFrontendContractReviewArtifacts({
+        runDir: input.runDir,
+        outputDir: "contracts",
+        artifactName: "frontend-implementation-contract.json",
+        canonical: parsedContract.data,
+        canonicalArtifact: {
+            path: path.join(input.runDir, contractRelativePath),
+            sha256: createHash("sha256").update(contractRaw).digest("hex"),
+            bytes: Buffer.byteLength(contractRaw, "utf8"),
+        },
+    });
     const payload = {
-        schemaVersion: 1,
+        schemaVersion: 2,
         schemaId: FRONTEND_REVIEW_CONTEXT_SCHEMA_ID,
-        contract,
+        contractRef: {
+            path: contractRelativePath,
+            schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
+            sha256: contractReviewArtifacts.index.contract.sha256,
+            bytes: contractReviewArtifacts.index.contract.bytes,
+            indexPath: contractReviewArtifacts.index.relativePath,
+            indexSha256: contractReviewArtifacts.index.artifactSha256,
+            capacityDiagnosticPath: contractReviewArtifacts.capacity.relativePath,
+            capacityDiagnosticSha256: contractReviewArtifacts.capacity.artifactSha256,
+            sections: contractReviewArtifacts.index.sections,
+        },
         verificationTrace,
-        repairAssessment,
+        ...(repairAssessment ? { repairAssessment } : {}),
+        ...(verifyFailure ? { verifyFailure } : {}),
         ...(lintAssessment ? { lintAssessment } : {}),
         sourceFidelity,
         diff: {
             schemaId: diff.schemaId,
             patchPath: diff.patchPath,
             patchSha256: diff.patchSha256,
+            reviewSummaryPath: diff.reviewSummaryPath,
+            reviewIndexPath: diff.reviewIndexPath,
             changedFiles: diff.changedFiles,
             untrackedFiles: diff.untrackedFiles,
             empty: diff.empty,
         },
+        cumulativeDiff,
     };
     const artifactPath = await writeDagRunJsonArtifact(input.runDir, "contracts/frontend-review-context.json", payload);
-    return { ok: true, artifactPath, diff };
+    return {
+        ok: true,
+        artifactPath,
+        diff,
+        contractRef: payload.contractRef,
+        capacity: contractReviewArtifacts.capacity,
+    };
 }
 /**
  * 最终 review 核对清单（机械化）：ledger 缺失/漂移、canonical requirement 漏项、
@@ -193,6 +437,8 @@ export function formatFrontendReviewContextStdout(result) {
     return [
         "Frontend review context: pass",
         `Artifact: ${result.artifactPath}`,
+        `Contract index: ${result.contractRef.indexPath}`,
+        `Capacity: ${result.capacity.overallLevel} (${result.capacity.relativePath}, non-blocking)`,
         formatFrontendWorktreeDiffStdout(result.diff),
     ].join("\n");
 }

package/dist/workflows/dag/frontend-review-findings.js

@@ -0,0 +1,270 @@
+import path from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readTypedEventStoreFromJsonl, } from "./frontend-typed-event-store.js";
+/**
+ * Frontend review findings → downstream work (direction A).
+ *
+ * When `frontend-review-pi` commits `request_review_changes`, the implementation
+ * must not silently finish: the run becomes "not passed" (partial_failed +
+ * terminalReason=review-request-changes), and the committed findings are
+ * rendered into a downstream-task PRD draft that a later DAG round can consume
+ * instead of repeating the previous flow. Rendering is deterministic (pure);
+ * only the JSONL read and PRD write are IO.
+ *
+ * The design-review analog (`request_design_changes`) reuses the same PRD
+ * rendering and typed-fact channel: a design rejection is a definite finding
+ * (not a protocol/environment error), so it auto-re-enters the next plan round
+ * with the committed design findings instead of terminating the run.
+ */
+export const FRONTEND_REVIEW_FINDINGS_PRD_REL = "contracts/frontend-review-findings-prd.md";
+/** Review node id whose committed typed facts drive the findings PRD. */
+export const FRONTEND_REVIEW_NODE_ID = "frontend-review-pi";
+/** Design review node id whose committed typed facts drive the findings PRD. */
+export const FRONTEND_DESIGN_REVIEW_NODE_ID = "frontend-design-review-pi";
+/** Deterministic issueCategory → failure owner mapping (A+B AC-009 §4.10). */
+export function classifyReviewIssueCategoryFailureOwner(issueCategory) {
+    switch (issueCategory) {
+        case "implementation-mismatch":
+            return "implementation";
+        case "approved-design-defect":
+            return "plan";
+        case "target-surface-defect":
+            return "scout";
+        case "contract-requirement-gap":
+            return "contract";
+        case "unknown":
+        default:
+            return "unknown";
+    }
+}
+const API_SIGNAL_RE = /\b(api|fetch|axios|graphql|endpoint|远程|接口)\b/i;
+/** Negations for the API signal. CJK "无 API/无接口" has no \b boundary, so
+ * it is matched separately from the ASCII no api/not-needed forms. */
+const API_NEGATION_RE = /(?:^|[^\w])(?:no\s+api|not-needed)(?:$|[^\w])|无\s*api|无\s*接口/i;
+const SMALL_SIGNAL_WORDS = [
+    "单文件局部修复",
+    "局部样式",
+    "文案调整",
+    "无远程接口",
+];
+function topLevelDir(p) {
+    const normalized = p.replace(/\\/g, "/");
+    const first = normalized.split("/").filter(Boolean)[0] ?? "";
+    return first;
+}
+/** Collect unique non-empty finding `file` values (sorted, de-duplicated). */
+function findingTargetFiles(fact) {
+    const files = new Set();
+    for (const finding of fact.findings) {
+        if (typeof finding.file === "string" && finding.file.trim()) {
+            files.add(finding.file.trim());
+        }
+    }
+    return [...files].sort();
+}
+/**
+ * Deterministically derive the fix scope for the downstream task. Same fact
+ * always yields the same scope. The shape mirrors `resolveFrontendTaskShape`
+ * signals (concentrated paths, no remote API → micro/small) so that when the
+ * PRD draft is used as the next task's requirement, the frontend DAG generator
+ * routes a small fix to micro/small instead of the full 11-node standard
+ * topology.
+ */
+export function deriveFrontendReviewFixScope(fact) {
+    const targetFiles = findingTargetFiles(fact);
+    const blob = fact.findings
+        .map((f) => `${f.issue} ${f.requiredChange ?? ""} ${f.file ?? ""}`)
+        .join("\n");
+    const hasApiSignal = API_SIGNAL_RE.test(blob) && !API_NEGATION_RE.test(blob);
+    const topDirs = new Set(targetFiles.map(topLevelDir));
+    const concentrated = targetFiles.length > 0 && topDirs.size <= 1 && targetFiles.length <= 4;
+    let shape;
+    let complexity;
+    let reason;
+    if (targetFiles.length === 0) {
+        shape = "standard";
+        complexity = "medium";
+        reason =
+            "findings carry no file references; scope unknown, keep standard topology";
+    }
+    else if (hasApiSignal) {
+        shape = "standard";
+        complexity = "medium";
+        reason = `findings reference a remote API signal; standard topology required (files=${targetFiles.length})`;
+    }
+    else if (concentrated && targetFiles.length <= 1) {
+        shape = "micro";
+        complexity = "trivial";
+        reason = "single-file concentrated fix without remote API";
+    }
+    else if (concentrated) {
+        shape = "small";
+        complexity = "low";
+        reason = `concentrated fix across ${targetFiles.length} file(s) in one top-level directory`;
+    }
+    else {
+        shape = "standard";
+        complexity = "medium";
+        reason = `fix spans ${targetFiles.length} file(s) across ${topDirs.size} top-level directories; standard topology`;
+    }
+    const allowedPaths = [
+        ...new Set([
+            ...targetFiles,
+            ...targetFiles.map((f) => `${topLevelDir(f)}/**`),
+        ]),
+    ].sort();
+    return {
+        shape,
+        complexity,
+        targetFiles,
+        allowedPaths,
+        smallSignals: [...SMALL_SIGNAL_WORDS],
+        hasApiSignal,
+        reason,
+    };
+}
+/**
+ * Read the committed `request_review_changes` fact from the review node's typed
+ * event store. Returns undefined when no committed request fact exists (e.g.
+ * approve_review, missing store, or an unreadable store).
+ */
+export async function readCommittedReviewRequestFact(input) {
+    const { runDir: reviewRunDir } = input;
+    const reviewNodeId = input.reviewNodeId ?? FRONTEND_REVIEW_NODE_ID;
+    return readCommittedRequestFactByKind({
+        runDir: reviewRunDir,
+        nodeId: reviewNodeId,
+        factsFile: "review-typed-facts.jsonl",
+        kind: "request_review_changes",
+    });
+}
+/**
+ * Read the committed `request_design_changes` fact from the design review
+ * node's typed event store. Returns undefined when no committed request fact
+ * exists (e.g. approve_design, missing store, or an unreadable store).
+ */
+export async function readCommittedDesignRequestFact(input) {
+    const { runDir: designRunDir } = input;
+    const designNodeId = input.designNodeId ?? FRONTEND_DESIGN_REVIEW_NODE_ID;
+    return readCommittedRequestFactByKind({
+        runDir: designRunDir,
+        nodeId: designNodeId,
+        factsFile: "design-typed-facts.jsonl",
+        kind: "request_design_changes",
+    });
+}
+async function readCommittedRequestFactByKind(input) {
+    let records;
+    try {
+        records = await readTypedEventStoreFromJsonl(path.join(input.runDir, input.nodeId, input.factsFile));
+    }
+    catch {
+        return undefined;
+    }
+    const committed = records.filter((record) => record.phase === "committed");
+    if (committed.length === 0)
+        return undefined;
+    const request = committed.find((record) => record.fact.kind === input.kind);
+    if (!request)
+        return undefined;
+    const fact = request.fact;
+    if (typeof fact !== "object" || fact === null)
+        return undefined;
+    return fact;
+}
+function bulletList(items) {
+    if (!items || items.length === 0)
+        return "_(none)_";
+    return items.map((item) => `- ${item}`).join("\n");
+}
+function findingLines(findings) {
+    if (findings.length === 0)
+        return "_(none)_";
+    return findings
+        .map((finding) => {
+        const location = [finding.file, finding.line]
+            .filter((value) => value !== undefined)
+            .join(":");
+        const prefix = location ? `[${location}] ` : "";
+        const requiredChange = finding.requiredChange
+            ? `\n  - requiredChange: ${finding.requiredChange}`
+            : "";
+        return `- ${prefix}${finding.severity}: ${finding.issue}${requiredChange}`;
+    })
+        .join("\n");
+}
+/**
+ * Deterministically render a downstream-task PRD draft from a committed
+ * `request_review_changes` / `request_design_changes` fact. Same fact always
+ * renders byte-identical output; the parent run id and review node id are the
+ * only context.
+ */
+export function renderFrontendReviewFindingsPrd(input) {
+    const { parentRunId, fact } = input;
+    const isDesign = fact.kind === "request_design_changes";
+    const reviewNodeId = input.reviewNodeId ??
+        (isDesign ? FRONTEND_DESIGN_REVIEW_NODE_ID : FRONTEND_REVIEW_NODE_ID);
+    const restartPhase = classifyReviewIssueCategoryFailureOwner(fact.issueCategory);
+    const scope = deriveFrontendReviewFixScope(fact);
+    const targetSummary = scope.targetFiles.length > 0
+        ? scope.targetFiles.join(", ")
+        : fact.issueCategory;
+    return [
+        `# 修复 ${isDesign ? "设计" : "review"} 发现（${scope.shape}）：${targetSummary}`,
+        "",
+        "## 背景",
+        "",
+        `- parentRunId: \`${parentRunId}\``,
+        `- reviewNodeId: \`${reviewNodeId}\``,
+        `- typedVerdict: \`${fact.kind}\``,
+        `- issueCategory: \`${fact.issueCategory}\``,
+        `- restartPhase/failureOwner: \`${restartPhase}\``,
+        "",
+        "## 修复范围（供下一轮任务生成路由）",
+        "",
+        `- 建议 shape：\`${scope.shape}\`（micro=7 / small=10 / standard=11 节点）`,
+        `- 建议 complexity：\`${scope.complexity}\``,
+        `- 推导依据：${scope.reason}`,
+        ...(scope.hasApiSignal ? ["- ⚠️ findings 含远程 API/接口信号，走 standard 拓扑"] : []),
+        scope.targetFiles.length > 0
+            ? [`- 目标文件：${scope.targetFiles.map((f) => `\`${f}\``).join(", ")}`]
+            : ["- 目标文件：_(findings 未提供 file 引用，需人工补全)_"],
+        scope.allowedPaths.length > 0
+            ? [`- 建议 allowedPaths：${scope.allowedPaths.map((p) => `\`${p}\``).join(", ")}`]
+            : [],
+        scope.shape === "micro" || scope.shape === "small"
+            ? [`- 范围信号：${scope.smallSignals.join("、")}（供 shape 分类器识别，避免退化为全节点流程）`]
+            : [],
+        "",
+        "## 问题清单",
+        "",
+        findingLines(fact.findings),
+        "",
+        "## 证据引用",
+        "",
+        bulletList(fact.evidenceRefs),
+        "",
+        "## 修复目标",
+        "",
+        `- 按 issueCategory 映射的重启阶段（${restartPhase}）定点修复，不复用上一轮未通过的实现。`,
+        "- 逐条关闭上面「问题清单」中的 findings，并保留上一轮已通过的验证目标继续有效。",
+        `- 完成修复后重新走 frontend DAG 的 ${isDesign ? "plan → design" : "implement → verify → review"} 链，直到${isDesign ? " design-review 提交 approve_design" : " review 提交 approve_review"}。`,
+        "",
+    ].join("\n");
+}
+/** Write the findings PRD draft under the run dir (run-owned artifact). */
+export async function writeFrontendReviewFindingsPrd(input) {
+    const markdown = renderFrontendReviewFindingsPrd(input);
+    const abs = path.join(input.runDir, FRONTEND_REVIEW_FINDINGS_PRD_REL);
+    await mkdir(path.dirname(abs), { recursive: true });
+    await writeFile(abs, markdown, "utf8");
+    return FRONTEND_REVIEW_FINDINGS_PRD_REL;
+}
+export async function readFrontendReviewFindingsPrd(runDir) {
+    try {
+        return await readFile(path.join(runDir, FRONTEND_REVIEW_FINDINGS_PRD_REL), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}