Require review-first discovery before remediation

Add a concrete planning.reviewFindings prerequisite so broad review-and-fix requests cannot enter remediation mode before an audit produces findings. Keep real review_and_fix completion strict and document the v2.0.14 release contract.

Constraint: Add a narrow planning-context/tool-schema contract without adding commands, tools, runtime modes, state paths, package exports, or dependencies

Constraint: Keep zod aligned with @opencode-ai/plugin; dependency contract verified unchanged at zod 4.1.8

Rejected: Loosen reviewFindingClosures, reviewScopeLedger, or final-review gates | that would make shallow no-change completion easier instead of forcing discovery first

Rejected: Raise the bundle sanity budget | prompt wording was trimmed so the bundle remains under the existing 720896-byte ceiling

Confidence: high

Scope-risk: moderate

Directive: Use goalMode: review_and_fix only after concrete findings are recorded in planning.reviewFindings; no-findings review-and-fix starts as goalMode: review

Tested: bun test tests/config/prompt-contracts.test.ts tests/plan-graph-validation.test.ts tests/prompt-mode-behavior-eval.test.ts tests/prompt-mode-capture.test.ts tests/runtime/plan-and-tool-schema-contracts.test.ts tests/completion-gates.test.ts tests/runtime/evidence-packets.test.ts; bun test tests/config/tool-schemas.test.ts; bun run build plus bundle sanity; bun run typecheck; bun run lint; bun run check

Not-tested: Live GitHub-hosted CI/release workflow for tag v2.0.14 before push

Author: vriesdcrv

CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [2.0.14] - 2026-05-07
+
+Route no-findings review-and-fix work through review-first discovery
+
+Flow 2.0.14 fixes the review-and-fix quality regression where broad codebase review requests with no concrete findings could be planned as a single `review_and_fix` feature and then degrade into repeated completion-payload retries. Planning now has an explicit `planning.reviewFindings` context ledger for concrete existing review findings, and `review_and_fix` plan application fails fast when that ledger is empty.
+
+No-findings review-and-fix requests now stay in `goalMode: review` for audit/discovery first. Once a review produces concrete findings, a remediation replan can use `goalMode: review_and_fix` with those findings recorded in `planning.reviewFindings`, preserving the strict finding-to-fix-to-validation chain.
+
+The release deliberately keeps the existing completion gates strict. Real `review_and_fix` remediation still requires closure evidence, review-scope accounting, final-review evidence, and reviewer approval; this patch changes when remediation mode may start, not what it must prove before completion.
+
+Prompt contracts, planner/auto/planning-researcher guidance, and prompt-mode calibration fixtures now mirror the runtime rule: no findings means review-first discovery, known findings means strict remediation. Regression coverage locks both paths, including inline-only `planning.reviewFindings` acceptance and audit-only no-findings calibration.
+
+Constraint: Add only a narrow planning-context contract for concrete review findings; do not add commands, tools, runtime modes, state paths, package exports, or dependencies
+Constraint: Accept a narrow raw tool-schema budget increase for `planning.reviewFindings` while keeping the bundle sanity budget unchanged
+Constraint: Preserve strict `review_and_fix` completion gates for actual remediation with known findings
+Constraint: Keep `zod` aligned with `@opencode-ai/plugin`; no dependency-version changes in this patch
+Rejected: Loosen `reviewFindingClosures`, `reviewScopeLedger`, or final-review requirements for no-change completions | that would make shallow review-and-fix completion easier instead of forcing discovery first
+Rejected: Keep broad no-findings review-and-fix as a single remediation feature | it frames the agent around completion accounting before findings exist
+Rejected: Infer known findings from natural-language goals alone | `planning.reviewFindings` gives the runtime and prompts a concrete, auditable prerequisite
+Confidence: high
+Scope-risk: moderate
+Reversibility: clean
+Directive: Use `goalMode: review_and_fix` only after concrete findings are recorded in `planning.reviewFindings`; broad review-and-fix/codebase-review requests without findings must start as `goalMode: review`
+Tested: `bun test tests/config/prompt-contracts.test.ts tests/plan-graph-validation.test.ts tests/prompt-mode-behavior-eval.test.ts tests/prompt-mode-capture.test.ts tests/runtime/plan-and-tool-schema-contracts.test.ts tests/completion-gates.test.ts tests/runtime/evidence-packets.test.ts` (91 pass, 1262 expect calls); `bun test tests/config/tool-schemas.test.ts`; `bun run build` plus bundle sanity at 720706 bytes; `bun run typecheck`; `bun run lint`; Oracle review found no blockers and P2 follow-ups were applied; `bun run check`
+Not-tested: Live GitHub-hosted CI/release workflow runs for tag `v2.0.14` before push
+
 ## [2.0.13] - 2026-05-07
 
 Dedupe final-completion tool guidance in subagent prompts

docs/releases/v2.0.14.md

@@ -0,0 +1,25 @@
+# v2.0.14
+
+Route no-findings review-and-fix work through review-first discovery
+
+Flow 2.0.14 fixes the review-and-fix quality regression where broad codebase review requests with no concrete findings could be planned as a single `review_and_fix` feature and then degrade into repeated completion-payload retries. Planning now has an explicit `planning.reviewFindings` context ledger for concrete existing review findings, and `review_and_fix` plan application fails fast when that ledger is empty.
+
+No-findings review-and-fix requests now stay in `goalMode: review` for audit/discovery first. Once a review produces concrete findings, a remediation replan can use `goalMode: review_and_fix` with those findings recorded in `planning.reviewFindings`, preserving the strict finding-to-fix-to-validation chain.
+
+The release deliberately keeps the existing completion gates strict. Real `review_and_fix` remediation still requires closure evidence, review-scope accounting, final-review evidence, and reviewer approval; this patch changes when remediation mode may start, not what it must prove before completion.
+
+Prompt contracts, planner/auto/planning-researcher guidance, and prompt-mode calibration fixtures now mirror the runtime rule: no findings means review-first discovery, known findings means strict remediation. Regression coverage locks both paths, including inline-only `planning.reviewFindings` acceptance and audit-only no-findings calibration.
+
+Constraint: Add only a narrow planning-context contract for concrete review findings; do not add commands, tools, runtime modes, state paths, package exports, or dependencies
+Constraint: Accept a narrow raw tool-schema budget increase for `planning.reviewFindings` while keeping the bundle sanity budget unchanged
+Constraint: Preserve strict `review_and_fix` completion gates for actual remediation with known findings
+Constraint: Keep `zod` aligned with `@opencode-ai/plugin`; no dependency-version changes in this patch
+Rejected: Loosen `reviewFindingClosures`, `reviewScopeLedger`, or final-review requirements for no-change completions | that would make shallow review-and-fix completion easier instead of forcing discovery first
+Rejected: Keep broad no-findings review-and-fix as a single remediation feature | it frames the agent around completion accounting before findings exist
+Rejected: Infer known findings from natural-language goals alone | `planning.reviewFindings` gives the runtime and prompts a concrete, auditable prerequisite
+Confidence: high
+Scope-risk: moderate
+Reversibility: clean
+Directive: Use `goalMode: review_and_fix` only after concrete findings are recorded in `planning.reviewFindings`; broad review-and-fix/codebase-review requests without findings must start as `goalMode: review`
+Tested: `bun test tests/config/prompt-contracts.test.ts tests/plan-graph-validation.test.ts tests/prompt-mode-behavior-eval.test.ts tests/prompt-mode-capture.test.ts tests/runtime/plan-and-tool-schema-contracts.test.ts tests/completion-gates.test.ts tests/runtime/evidence-packets.test.ts` (91 pass, 1262 expect calls); `bun test tests/config/tool-schemas.test.ts`; `bun run build` plus bundle sanity at 720706 bytes; `bun run typecheck`; `bun run lint`; Oracle review found no blockers and P2 follow-ups were applied; `bun run check`
+Not-tested: Live GitHub-hosted CI/release workflow runs for tag `v2.0.14` before push

package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugin-flow",
-  "version": "2.0.13",
+  "version": "2.0.14",
   "description": "Stateful planning and execution workflow plugin for OpenCode",
   "type": "module",
   "main": "dist/index.js",

src/prompts/contracts.ts

@@ -26,6 +26,7 @@ const FLOW_PLAN_CONTRACT_BASE = `Persist a plan with:
 
 Plan rules:
 - review/review_and_fix plans must declare review scope through reviewScope or fileTargets for every target/domain the runtime must account.
+- Use goalMode: review_and_fix only when concrete findings already exist and are recorded in planning.reviewFindings; broad review-and-fix/codebase-review goals with no findings must start as goalMode: review for audit/discovery, then replan review_and_fix after findings are recorded.
 
 Record planning context separately via flow_plan_context_record or flow_plan_apply({ plan, planning: ... }) when needed — not inside \`plan\`.
 - planning.repoProfile?: string[]
@@ -36,6 +37,7 @@ Record planning context separately via flow_plan_context_record or flow_plan_app
 - planning.research?: string[]
 - planning.implementationApproach?: { chosenDirection: string, keyConstraints: string[], validationSignals: string[], sources: string[] }
 - planning.decisionLog?: { question: string, decisionMode?: autonomous_choice | recommend_confirm | human_required, decisionDomain?: architecture | product | quality | scope | delivery, options: { label: string, tradeoffs: string[] }[], recommendation: string, rationale: string[] }[]
+- planning.reviewFindings?: { findingRef: string, summary: string, sourceRefs: string[] }[] — concrete existing findings from a user-provided finding, audit report, issue, failing test, or prior review ledger; sourceRefs must be non-empty concrete refs. Missing/empty means no remediation findings are known yet.
 - planning.evidencePackets?: { id: string, purpose?: planning | review | audit | validation | general, contextLane?: planning | auto_planning | execution | review | status | history | session | reset | doctor | control, summary: string, sourceRefs?: string[], highlights?: string[], selectedContext?: string[], excludedContext?: string[], codemapSummaries?: string[], sliceSummaries?: string[], relationshipHypotheses?: string[], ambiguities?: string[], knownExclusions?: string[], alreadyCoveredFindings?: string[], validationEvidence?: { command, status, summary }[] }[]`;
 
 export const FLOW_PLAN_CONTRACT = `${FLOW_PLAN_CONTRACT_BASE}

src/prompts/fragments.ts

@@ -20,6 +20,8 @@ export const FLOW_COORDINATOR_BOUNDARY_RULE =
 	"- Stay at the coordinator layer: decide whether planning, execution, review, reset, or recovery happens next, and rely on the specialized Flow roles for their detailed contracts.";
 export const FLOW_REVIEW_FINDINGS_LOOP_RULE =
 	"- Do not complete a feature while review findings remain. Fix them, record a finding-by-finding closure ledger with code/test/validation evidence and residual risk, rerun validation, and rereview until the feature is clean or a real blocker remains.";
+export const FLOW_REVIEW_FIRST_WITHOUT_FINDINGS_PLAN_RULE =
+	"- Broad review-and-fix/codebase-review goals with no concrete existing findings in planning.reviewFindings must start as goalMode: review for audit/discovery; replan to goalMode: review_and_fix only after concrete findings are recorded in planning.reviewFindings.";
 export const FLOW_FEATURE_REVIEW_APPROVAL_RULE =
 	"- Before persisting success, get flow-reviewer approval and record it through flow_review_record_feature.";
 export const FLOW_FINAL_COMPLETION_PATH_RULE =

src/prompts/generated/role-prompts.ts

@@ -32,6 +32,7 @@ import {
 	FLOW_RESUME_ONLY_RULE,
 	FLOW_REVIEW_CONTEXT_DISCOVERY_RULE,
 	FLOW_REVIEW_FINDINGS_LOOP_RULE,
+	FLOW_REVIEW_FIRST_WITHOUT_FINDINGS_PLAN_RULE,
 	FLOW_RUNTIME_TOOLS_AUTHORITATIVE_RULE,
 	FLOW_RUNTIME_TOOLS_AUTHORITATIVE_WORKFLOW_RULE,
 	FLOW_STACK_STANDARDS_PROFILE_READONLY_RULE,
@@ -77,7 +78,7 @@ const control = getCoreRoleProtocol("control");
 const FLOW_PLANNING_RESEARCHER_EXAMPLES = renderExampleBlocks([
 	{
 		name: "review-first-codebase-review",
-		body: "If the goal asks for a full codebase review and fixes, recommend a review-first plan shape: first run a read-only codebase review/audit, then fix confirmed findings only after the audit ledger exists. Do not invent findings during research.",
+		body: "No findings: recommend goalMode: review for audit, requiresReplanAfterAudit: true. goalMode: review_and_fix only after concrete findings are recorded in planning.reviewFindings. Do not invent findings.",
 	},
 	{
 		name: "not-runtime-planner",
@@ -89,16 +90,17 @@ export const FLOW_PLANNING_RESEARCHER_AGENT_PROMPT = renderPromptSections([
 	{ title: "Role", body: "You are the Flow planning researcher." },
 	{
 		title: "Objective",
-		body: "Produce a read-only evidence packet that helps Flow planning stay phase-correct, especially for broad review-and-fix goals where findings do not exist yet.",
+		body: "Produce read-only evidence that keeps broad no-findings review-and-fix planning review-first.",
 	},
 	{
 		title: "Rules",
 		body: `${FLOW_NEVER_WRITE_FLOW_FILES_RULE}
 ${FLOW_CONTEXT_GATHERING_READONLY_RULE}
 - Stay read-only: do not write repository code, do not call Flow runtime tools, do not apply or approve plans, and do not claim execution success.
 - You are not flow-planner. Produce research for flow-planner or flow-auto to consume through normal runtime-owned planning.
-- For full codebase review and fix goals, recommend an audit/review-first plan shape before any fix feature. Findings belong in the audit/review ledger, not planning research.
-- Do not invent findings, severity, or closure evidence. If findings are not already provided, say the fix phase must wait for a concrete review ledger.
+${FLOW_REVIEW_FIRST_WITHOUT_FINDINGS_PLAN_RULE}
+- For codebase review/fix with no findings, recommend an audit/review-first plan shape before any fix feature; copy concrete findings into planning.reviewFindings after audit.
+- Do not invent findings. If none are provided, set recommendedPlanShape.goalMode to "review", requiresReplanAfterAudit: true; fixes wait for a concrete review ledger.
 ${FLOW_STACK_STANDARDS_PROFILE_READONLY_RULE}
 ${FLOW_PACKAGE_MANAGER_PRIMARY_CONTRACT_RULE}
 ${FLOW_PACKAGE_MANAGER_AMBIGUITY_PLAN_RULE}
@@ -109,7 +111,7 @@ ${FLOW_ENGINEERING_QUALITY_RULE}
 		title: "Workflow",
 		body: `1. Normalize the request into goal, constraints, evidence requirements, and done-when.
 2. Inspect only enough local evidence to identify package manager, stack, validation scripts, local standards, and the major review surfaces.
-3. For review-and-fix goals without existing findings, recommend a review-first or replan-after-audit shape instead of a fake all-in-one fix feature.
+3. For review-and-fix goals without findings, recommend goalMode: "review" and requiresReplanAfterAudit: true; use goalMode: "review_and_fix" only after planning.reviewFindings has concrete findings.
 4. Return exactly one JSON object with no markdown fences or commentary:
 
 {
@@ -120,6 +122,7 @@ ${FLOW_ENGINEERING_QUALITY_RULE}
     "stackProfile": { "languages": unknown[], "frameworks": unknown[], "runtimes": unknown[], "packageManagers": unknown[], "tools": unknown[] },
     "standardsProfile": { "localGuidelines": unknown[], "externalGuidance": unknown[], "rules": unknown[], "gaps": unknown[], "precedence": string[] },
     "research": string[],
+    "reviewFindings": { "findingRef": string, "summary": string, "sourceRefs": string[] }[],
     "evidencePackets": unknown[]
   },
   "recommendedPlanShape": {
@@ -153,15 +156,17 @@ ${FLOW_ENGINEERING_QUALITY_RULE}
 ${FLOW_OPERATOR_PROGRESS_RULE}
 - Keep plans short, concrete, and ready to execute.
 - Broad goals are valid.
-- For broad review-and-fix goals where findings do not exist yet, use a review-first plan shape or a flow-planning-researcher handoff; do not create a fake all-in-one fix feature.
+${FLOW_REVIEW_FIRST_WITHOUT_FINDINGS_PLAN_RULE}
+- For broad review-and-fix goals without findings, use goalMode: review or a flow-planning-researcher handoff; do not create a fake all-in-one fix feature.
+- Use goalMode: review_and_fix only after concrete findings exist in planning.reviewFindings.
 - Do not start implementation after drafting a plan.`,
 	},
 	{
 		title: "Workflow",
 		body: `${renderWorkflowProtocol(planner)}
 1. Call flow_plan_start.
 2. Read enough repo context to justify the plan. When the goal is a broad review-and-fix request and Task handoff is available, ask flow-planning-researcher for a read-only planning research packet before finalizing decomposition.
-3. Persist repoProfile, packageManager, stackProfile, standardsProfile, research, implementationApproach, evidencePackets, or decisionLog with flow_plan_context_record.
+3. Persist repoProfile, packageManager, stackProfile, standardsProfile, research, implementationApproach, evidencePackets, decisionLog, or concrete reviewFindings with flow_plan_context_record.
 4. Return plan content matching:
 
 ${FLOW_PLAN_CONTRACT}
@@ -244,7 +249,7 @@ ${FLOW_STRUCTURED_RECOVERY_RULE}`,
 		body: `${renderWorkflowProtocol(auto)}
 1. Call flow_auto_prepare with the raw command argument string before planning or repo inspection.
 2. If flow_auto_prepare returns missing_goal, render that result clearly and stop.
-3. If planning is needed for a broad review-and-fix/codebase-review request, prefer a Task-tool handoff to flow-planning-researcher first so review discovery and fix execution stay phase-correct.
+3. If planning is needed for broad review-and-fix/codebase-review, use flow-planning-researcher first; without concrete planning.reviewFindings, start with goalMode: review, then goalMode: review_and_fix only after findings are recorded.
 4. If planning is needed, prefer a Task-tool handoff to flow-planner; the planning pass records stackProfile, standardsProfile, and useful evidencePackets with flow_plan_context_record, persists the plan with flow_plan_apply, and approves it with flow_plan_approve.
 5. If repo evidence and research still leave a meaningful architecture, product, or quality decision still remains, record the options and recommendation with flow_plan_context_record so the runtime summary exposes a decision gate. If any Flow tool response includes session.decisionGate with status recommend_confirm or human_required, present that recommendation clearly and stop for user confirmation.
 6. Start the next feature with flow_run_start and keep that feature active until it is clean or truly blocked.

src/runtime/domain/index.ts

@@ -23,7 +23,11 @@ export {
 	type ReviewIncludedContext,
 	type ReviewValidationEvidence,
 } from "./final-review-coverage";
-export { validatePlanGraph } from "./plan-graph-validation";
+export {
+	REVIEW_AND_FIX_FINDINGS_REQUIRED_MESSAGE,
+	validatePlanGraph,
+	validateReviewAndFixFindingPrerequisite,
+} from "./plan-graph-validation";
 export { selectProjectedFeatureSubset } from "./plan-projection";
 export {
 	mergeEvidencePackets,

src/runtime/domain/plan-graph-validation.ts

@@ -1,4 +1,20 @@
-import type { Plan } from "../schema";
+import type { Plan, PlanningContext } from "../schema";
+
+export const REVIEW_AND_FIX_FINDINGS_REQUIRED_MESSAGE =
+	"review_and_fix plans require concrete existing findings in planning.reviewFindings. For broad review/codebase-review goals without findings, apply a review-first plan with goalMode: review, run discovery/audit, then replan remediation after findings exist.";
+
+export function validateReviewAndFixFindingPrerequisite(
+	plan: Plan,
+	planning: PlanningContext,
+): string | null {
+	if (plan.goalMode !== "review_and_fix") {
+		return null;
+	}
+	if (planning.reviewFindings.length > 0) {
+		return null;
+	}
+	return REVIEW_AND_FIX_FINDINGS_REQUIRED_MESSAGE;
+}
 
 export function validatePlanGraph(plan: Plan): string | null {
 	const ids = new Set<string>();

src/runtime/domain/planning-context.ts

@@ -1,4 +1,4 @@
-import type { PlanningContext } from "../schema";
+import type { PlanningContext, ReviewFindingPlanningContext } from "../schema";
 import type { EvidencePacket } from "../schema-evidence-packets";
 
 function mergeUniqueStrings(
@@ -45,6 +45,20 @@ export function mergeEvidencePackets(
 	return [...byId.values()];
 }
 
+function mergeReviewFindings(
+	current: readonly ReviewFindingPlanningContext[] = [],
+	next?: readonly ReviewFindingPlanningContext[],
+): ReviewFindingPlanningContext[] {
+	const byRef = new Map<string, ReviewFindingPlanningContext>();
+	for (const finding of current) {
+		byRef.set(finding.findingRef, finding);
+	}
+	for (const finding of next ?? []) {
+		byRef.set(finding.findingRef, finding);
+	}
+	return [...byRef.values()];
+}
+
 export function mergePlanningContext(
 	current: PlanningContext,
 	next: Partial<PlanningContext> = {},
@@ -61,6 +75,10 @@ export function mergePlanningContext(
 			next.implementationApproach ?? current.implementationApproach,
 		decisionLog: next.decisionLog ?? current.decisionLog,
 		replanLog: mergeUniqueBySerialized(current.replanLog, next.replanLog),
+		reviewFindings: mergeReviewFindings(
+			current.reviewFindings,
+			next.reviewFindings,
+		),
 		evidencePackets: mergeEvidencePackets(
 			current.evidencePackets,
 			next.evidencePackets,