opencode-plugin-flow 4.3.3 → 4.3.5

package/dist/index.js

@@ -169,7 +169,7 @@ stay separate:
 | --- | --- | --- |
 | Repo shape is unclear before planning | Discovery pass | Requirements, decisions, targets, validation entries, or a review-first feature |
 | A broad finding set needs refutation | Audit pass | Surviving findings with guards checked and gaps named |
-| Changed files or risk lenses are too broad for one review pass | Review pass | One \`featureReview\` or \`finalReview\` payload owned by the manager |
+| Changed files or risk lenses are too broad for one review pass | Review pass | One feature review packet or \`finalReview\` payload owned by the manager |
 | Test strategy or route coverage is unclear | Validation pass | Candidate commands or authorized raw command evidence |
 | A claim is single-source, surprising, high-stakes, or payload-bound | Verification pass | Per-claim keep, narrow, rewrite, or remove decisions |
 | Multiple implementation paths are plausible | Candidate pass | Candidate patches inspected and validated by the manager before use |
@@ -403,7 +403,7 @@ Where accepted evidence goes:
 - Validation evidence may become \`validationRun\` only when the worker was
   explicitly authorized to run the command and reported the exact command,
   status, and raw outcome summary.
-- Review evidence informs \`featureReview\` or \`finalReview\`, but the manager
+- Review evidence informs \`featureReviewDepth\` plus \`featureReview\`, or \`finalReview\`, but the manager
   owns the pass/fail verdict and must resolve blockers, contradictions, and
   coverage gaps before returning the payload.
 - Audit evidence becomes findings only after refutation; blocking findings need
@@ -530,10 +530,10 @@ suggestions do not move into the next pass or user-facing answer.
 `;
 
 // skills/flow/references/recovery-playbook.md
-var recovery_playbook_default = '# Recovery playbook\n\nUse this when a Flow tool returns `status: "error"`, a blocker, or a `nextAction` that conflicts with memory.\n\n## First response\n\n1. Re-anchor with `flow_status`.\n2. Read the returned `summary`, `recovery`, `lastError`, and active feature.\n3. Fix the cause, then retry the smallest valid Flow action.\n\n## Common cases\n\n- `missing_session`: start with `flow_plan_save` using the user\'s goal.\n- `missing_goal`: ask for a concrete goal before planning.\n- `Approved plans cannot be changed`: use `flow_feature_reset` when only affected features need another pass; otherwise close and start a new goal.\n- `No feature is currently running`: call `flow_run_start` before completing.\n- `already in progress`: finish, reset, or block the active feature before starting another.\n- `Completion requires recorded validation evidence`: run real validation and include at least one passing `validationRun`.\n- `Completion requires all recorded validation to pass`: fix failures and rerun. Do not relabel failed checks as passed.\n- `Non-final feature completion requires targeted validation`: use `validationScope: "targeted"` for ordinary features.\n- `Final feature completion requires broad validation`: run the project-level gate and use `validationScope: "broad"`.\n- `Completion requires a passing featureReview`: run or request a real review and include a passing `featureReview` only when there are no blocking findings.\n- `Final feature completion requires a finalReview`: perform final review and include `finalReview`.\n- `Final review depth must match the plan policy`: use `reviewDepth` equal to the approved plan\'s `finalReviewPolicy`; valid final-review values are `broad` and `detailed`.\n- `Cannot close ... unfinished features`: complete, reset, defer, or abandon honestly. Do not mark completed while work remains.\n\n## Reset guidance\n\nUse `flow_feature_reset` when the active or completed work was built on the wrong assumption, validation revealed a design issue, dependencies need to be rerun, or dependent features must be invalidated. Resetting a feature also resets its dependents.\n\n## Closure guidance\n\nUse `flow_session_close`:\n\n- `completed`: only after all planned features are complete.\n- `deferred`: the user intentionally postpones unfinished work.\n- `abandoned`: the session should be archived without claiming delivery.\n\nAfter closure, the active `.flow/session.json` is removed and the archived JSON is stored under `.flow/history/`.\n';
+var recovery_playbook_default = '# Recovery playbook\n\nUse this when a Flow tool returns `status: "error"`, a blocker, or a `nextAction` that conflicts with memory.\n\n## First response\n\n1. Re-anchor with `flow_status`.\n2. Read the returned `summary`, `recovery`, `lastError`, and active feature.\n3. Fix the cause, then retry the smallest valid Flow action.\n\n## Common cases\n\n- `missing_session`: start with `flow_plan_save` using the user\'s goal.\n- `missing_goal`: ask for a concrete goal before planning.\n- `Approved plans cannot be changed`: use `flow_feature_reset` when only affected features need another pass; otherwise close and start a new goal.\n- `No feature is currently running`: call `flow_run_start` before completing.\n- `already in progress`: finish, reset, or block the active feature before starting another.\n- `Completion requires recorded validation evidence`: run real validation and include at least one passing `validationRun`.\n- `Completion requires all recorded validation to pass`: fix failures and rerun. Do not relabel failed checks as passed.\n- `Non-final feature completion requires targeted validation`: use `validationScope: "targeted"` for ordinary features.\n- `Final feature completion requires broad validation`: run the project-level gate and use `validationScope: "broad"`.\n- `Feature review depth ... does not meet the plan requirement`: rerun review\n  at the feature\'s planned depth or reset/replan if the depth was chosen\n  incorrectly.\n- `Completion requires a passing featureReview`: run or request a real review and include a passing `featureReview` only when there are no blocking findings.\n- `Review retry budget exhausted`: stop and report the remaining blocker. Do\n  not keep patching; reset or replan only after explicit user direction.\n- `Final feature completion requires a finalReview`: perform final review and include `finalReview`.\n- `Final review depth must match the plan policy`: use `reviewDepth` equal to the approved plan\'s `finalReviewPolicy`; valid final-review values are `broad` and `detailed`.\n- `Completed ... features since the last Flow checkpoint`: stop the current\n  root session and resume from `.flow/session.json` in a fresh OpenCode session.\n- `Cannot close ... unfinished features`: complete, reset, defer, or abandon honestly. Do not mark completed while work remains.\n\n## Reset guidance\n\nUse `flow_feature_reset` when the active or completed work was built on the wrong assumption, validation revealed a design issue, dependencies need to be rerun, or dependent features must be invalidated. Resetting a feature also resets its dependents.\n\n## Closure guidance\n\nUse `flow_session_close`:\n\n- `completed`: only after all planned features are complete.\n- `deferred`: the user intentionally postpones unfinished work.\n- `abandoned`: the session should be archived without claiming delivery.\n\nAfter closure, the active `.flow/session.json` is removed and the archived JSON is stored under `.flow/history/`.\n';
 
 // skills/flow/SKILL.md
-var SKILL_default = "---\nname: flow\ndescription: Manage the end-to-end Flow loop for skills-first OpenCode work. Use when a user asks for Flow-guided delivery from goal to completion, resumable autonomous delivery, or resuming or closing a Flow session. For plan-only work use flow-plan; for executing one approved feature use flow-run.\n---\n\n# Flow\n\nUse Flow as a minimal state ledger, not as a framework. Skills provide judgment; the runtime only records the approved plan, active feature, validation evidence, review evidence, and closure.\n\nRouting: this manager skill owns the whole loop and every state-changing `flow_*` call. Load `flow-plan` alone for plan-only requests and `flow-run` alone when an approved plan needs one feature executed. Answer status-only questions with `flow_status`; no skill load is needed. `flow-test`, `flow-deslop`, and `flow-ui-quality` are optional helpers loaded from inside the loop; `flow-commit` is user-triggered only and never part of the autonomous loop.\n\n## Loop\n\n1. Call `flow_status` first. Trust its active session and next action over conversation memory.\n   If the result includes `setup.skills`, follow the Skill Availability rules\n   below before loading any Flow skill.\n2. If there is no active session and the user gave a goal, load `flow-plan`, save a plan with `flow_plan_save`, then approve it with `flow_plan_approve` only after explicit user approval or prior authorization for autonomous implementation. If there is no goal, ask for one.\n3. Load `flow-run`, call `flow_run_start`, implement exactly one feature, validate it, and prepare a `flow_feature_complete` payload. For validation-heavy, regression-sensitive, browser QA, route QA, or failure-prone work, use `flow-test` to choose and summarize evidence before completion.\n4. Load `flow-review` for the required feature review. The reviewer reports a `featureReview` payload; the manager records it inside `flow_feature_complete`.\n5. On the final feature, run broad validation and include `finalReview` in the same `flow_feature_complete` call. Its `reviewDepth` must match the plan's `finalReviewPolicy`.\n6. After all features are complete, archive the session with `flow_session_close` using `kind: \"completed\"`.\n\nUse `references/parallel-orchestration.md` for broad read-only discovery, audit, validation, review, verification, or candidate implementation passes. It is the whole pass playbook — orient, slice, manifest, fan out, account, verify, synthesize, extend or stop — and its `references/handoff-format.md` companion holds the worker report templates the manager pastes into prompts. Hidden Flow workers are injected by plugin config; invoke the named worker when it is available. The manager owns every `flow_*` state change.\n\nDo not commit, push, amend, rebase, publish, or mutate releases during the\nautonomous Flow loop. Load `flow-commit` only when the user explicitly asks for\ncommit preparation or commit creation.\n\n## Skill Availability\n\nIf `flow_status` returns `setup.skills`, report that setup status and stop\nnative-loading Flow skills in the current OpenCode startup. Missing, incomplete,\nor outdated managed skills require a sync/restart cycle before their native skill\ninstructions can be trusted by the running process. Public command bundles are\nself-contained and may continue when the command prompt already embeds the\nrequired Flow instructions.\n\nIf optional helper skills such as `flow-test`, `flow-deslop`, or\n`flow-ui-quality` are unavailable, continue only with explicit coverage gaps. Do\nnot copy their rubrics into another skill and do not claim their quality checks\nwere completed.\n\n## Runtime Surface\n\n- `flow_status`: read the active session.\n- `flow_plan_save`: create a session and/or save a draft plan.\n- `flow_plan_approve`: lock the draft plan.\n- `flow_run_start`: start one runnable feature.\n- `flow_feature_complete`: record completion or a real blocker with validation and review evidence.\n- `flow_feature_reset`: reset one feature and its dependents.\n- `flow_session_close`: archive the active session as `completed`, `deferred`, or `abandoned`.\n\nThere is no `flow_context`, no separate review-record tool, and no multi-session activation surface. The single active source of truth is `.flow/session.json`; closed sessions are archived under `.flow/history/`.\n\nPlanning and running require loaded Flow tools; do not simulate plan approval or feature completion when the runtime is unavailable. Review may still return advisory output when tools, skills, or references are stale or unavailable, but the manager must not record it as Flow-gated evidence.\n\n## Hard Gates\n\n- Approved plans are immutable. To change direction, reset affected features or close the session and start a new goal.\n- Only one feature can be active at a time.\n- Completion requires at least one passing `validationRun` entry.\n- Non-final completion requires `validationScope: \"targeted\"`.\n- Final completion requires `validationScope: \"broad\"` and a passing `finalReview`.\n- Every completed feature requires a passing `featureReview` with no blocking findings.\n- `flow_session_close` accepts `kind: \"completed\"` only after an approved plan has passed final completion.\n\n## Recovery\n\n- Confused state: call `flow_status` and follow `nextAction`.\n- Wrong assumption or failed implementation path: use `flow_feature_reset` for the feature and dependents, then rerun from the corrected plan.\n- Missing validation or review evidence: gather real evidence, then call `flow_feature_complete`.\n- Approved plan is materially wrong: reset the affected features, save a revised plan if the session is back in planning; otherwise close and start a new goal.\n- Unknown runtime error: read `summary` and `recovery`; see `references/recovery-playbook.md` for common cases.\n\nNever fabricate validation output, backfill review approval you did not perform, or close as `deferred`/`abandoned` merely to avoid an unfinished-work blocker.\n";
+var SKILL_default = "---\nname: flow\ndescription: Manage the end-to-end Flow loop for skills-first OpenCode work. Use when a user asks for Flow-guided delivery from goal to completion, resumable autonomous delivery, or resuming or closing a Flow session. For plan-only work use flow-plan; for executing one approved feature use flow-run.\n---\n\n# Flow\n\nUse Flow as a minimal state ledger, not as a framework. Skills provide judgment; the runtime only records the approved plan, active feature, validation evidence, review evidence, and closure.\n\nRouting: this manager skill owns the whole loop and every state-changing `flow_*` call. Load `flow-plan` alone for plan-only requests and `flow-run` alone when an approved plan needs one feature executed. Answer status-only questions with `flow_status`; no skill load is needed. `flow-test`, `flow-deslop`, and `flow-ui-quality` are optional helpers loaded from inside the loop; `flow-commit` is user-triggered only and never part of the autonomous loop.\n\n## Loop\n\n1. Call `flow_status` first. Trust its active session and next action over conversation memory.\n   If the result includes `setup.skills`, follow the Skill Availability rules\n   below before loading any Flow skill.\n   If it includes `session.resumePacket` or `session.budget.phaseBoundary`, stop\n   and report the resume instructions unless this is a fresh user invocation\n   explicitly resuming the session. Only then may the next `flow_run_start` use\n   `phaseBoundaryAck: true`.\n2. If there is no active session and the user gave a goal, load `flow-plan`, save a plan with `flow_plan_save`, then approve it with `flow_plan_approve` only after explicit user approval or prior authorization for autonomous implementation. If there is no goal, ask for one.\n3. Load `flow-run`, call `flow_run_start`, implement exactly one feature, validate it, and prepare a `flow_feature_complete` payload. For validation-heavy, regression-sensitive, browser QA, route QA, or failure-prone work, use `flow-test` to choose and summarize evidence before completion.\n4. Load `flow-review` for the required feature review. Send a compact review\n   packet, not the accumulated root transcript. The reviewer reports\n   `featureReviewDepth` and `featureReview`; the manager records both inside\n   `flow_feature_complete`.\n5. On the final feature, run broad validation and include `finalReview` in the same `flow_feature_complete` call. Its `reviewDepth` must match the plan's `finalReviewPolicy`.\n6. After all features are complete, archive the session with `flow_session_close` using `kind: \"completed\"`.\n\nUse `references/parallel-orchestration.md` for broad read-only discovery, audit, validation, review, verification, or candidate implementation passes. It is the whole pass playbook — orient, slice, manifest, fan out, account, verify, synthesize, extend or stop — and its `references/handoff-format.md` companion holds the worker report templates the manager pastes into prompts. Hidden Flow workers are injected by plugin config; invoke the named worker when it is available. The manager owns every `flow_*` state change.\n\nDo not commit, push, amend, rebase, publish, or mutate releases during the\nautonomous Flow loop. Load `flow-commit` only when the user explicitly asks for\ncommit preparation or commit creation.\n\n## Skill Availability\n\nIf `flow_status` returns `setup.skills`, report that setup status and stop\nnative-loading Flow skills in the current OpenCode startup. Missing, incomplete,\nor outdated managed skills require a sync/restart cycle before their native skill\ninstructions can be trusted by the running process. Public command bundles are\nself-contained and may continue when the command prompt already embeds the\nrequired Flow instructions.\n\nIf optional helper skills such as `flow-test`, `flow-deslop`, or\n`flow-ui-quality` are unavailable, continue only with explicit coverage gaps. Do\nnot copy their rubrics into another skill and do not claim their quality checks\nwere completed.\n\n## Runtime Surface\n\n- `flow_status`: read the active session.\n- `flow_plan_save`: create a session and/or save a draft plan.\n- `flow_plan_approve`: lock the draft plan.\n- `flow_run_start`: start one runnable feature.\n- `flow_feature_complete`: record completion or a real blocker with validation and review evidence.\n- `flow_feature_reset`: reset one feature and its dependents.\n- `flow_session_close`: archive the active session as `completed`, `deferred`, or `abandoned`.\n\nThere is no `flow_context`, no separate review-record tool, and no multi-session activation surface. The single active source of truth is `.flow/session.json`; closed sessions are archived under `.flow/history/`.\n\nPlanning and running require loaded Flow tools; do not simulate plan approval or feature completion when the runtime is unavailable. Review may still return advisory output when tools, skills, or references are stale or unavailable, but the manager must not record it as Flow-gated evidence.\n\n## Hard Gates\n\n- Approved plans are immutable. To change direction, reset affected features or close the session and start a new goal.\n- Only one feature can be active at a time.\n- Each feature's planned `reviewDepth` is the minimum accepted\n  `featureReviewDepth` for completion.\n- Completion requires at least one passing `validationRun` entry.\n- Non-final completion requires `validationScope: \"targeted\"`.\n- Final completion requires `validationScope: \"broad\"` and a passing `finalReview`.\n- Every completed feature requires a passing `featureReview` with no blocking findings.\n- Failed reviews pause the loop by default. Autonomous repair may make at most\n  one repair plus one retry review before stopping.\n- Phase boundaries stop the current root session; resume from\n  `.flow/session.json` in a fresh OpenCode session.\n- `flow_session_close` accepts `kind: \"completed\"` only after an approved plan has passed final completion.\n\n## Budget And Retry Boundaries\n\nFlow can enforce review retry counts and feature-count phase boundaries in the\nruntime ledger. The current OpenCode plugin surface does not expose per-turn\ntoken usage to Flow; when usage is visible in the host UI or logs, stop the\ncurrent autonomous loop once the root session is large enough to threaten\nlatency or cost and report a compact handoff instead of continuing. Treat high\nvisible tokens, high non-cache tokens, or repeated reviewer fan-out as a reason\nto finish the current feature, emit the resume packet, and continue in a fresh\nsession.\n\n## Recovery\n\n- Confused state: call `flow_status` and follow `nextAction`.\n- Wrong assumption or failed implementation path: use `flow_feature_reset` for the feature and dependents, then rerun from the corrected plan.\n- Missing validation or review evidence: gather real evidence, then call `flow_feature_complete`.\n- Approved plan is materially wrong: reset the affected features, save a revised plan if the session is back in planning; otherwise close and start a new goal.\n- Unknown runtime error: read `summary` and `recovery`; see `references/recovery-playbook.md` for common cases.\n\nNever fabricate validation output, backfill review approval you did not perform, or close as `deferred`/`abandoned` merely to avoid an unfinished-work blocker.\n";
 
 // skills/flow-commit/SKILL.md
 var SKILL_default2 = `---
@@ -836,6 +836,60 @@ Apply the manager synthesis barrier from
 evidence-backed claims become plan fields.
 `;
 
+// skills/flow-plan/references/plan-quality-checklist.md
+var plan_quality_checklist_default = `# Plan quality checklist
+
+Use this checklist before \`flow_plan_save\` and again before approval if the plan
+changed during discussion. The goal is not a long planning artifact; it is a
+compact plan another agent can execute without rediscovering the work.
+
+## Must pass
+
+- Outcome: \`summary\` names the user-visible result, not an internal activity.
+- Requirements: acceptance criteria, constraints, and non-goals that affect
+  implementation are captured in \`requirements\`.
+- Decisions: assumptions, scope choices, and architecture choices already made
+  are captured in \`decisions\`.
+- Uncertainty: specification uncertainty is resolved by a decision or a user
+  question; environment uncertainty is resolved by inspection, discovery, or a
+  first evidence-producing feature.
+- Feature shape: each feature has one coherent outcome and can be reviewed on
+  its own.
+- Targets: each feature names bounded files, modules, routes, commands, docs, or
+  generated surfaces. Whole-repo targets are allowed only for explicit broad
+  audits or final validation.
+- Validation: each feature names expected check levels, such as targeted unit,
+  integration, browser/e2e, package/build, docs/static, cleanup preservation, or
+  broad project gate.
+- Dependencies: \`dependsOn\` captures true ordering and avoids hidden dependency
+  chains.
+- Review policy: \`finalReviewPolicy\` is \`detailed\` when the work changes
+  behavior, persistence, public contracts, security posture, release surfaces,
+  or multiple modules.
+
+## Revise when you see this
+
+- A feature title describes a step like "update files" instead of a result.
+- A validation entry says only "manual testing" or "run tests".
+- A feature has targets but no behavior or artifact that can be judged.
+- A feature claims cleanup or simplification without an evidence-producing
+  audit or cited smell.
+- A docs feature depends on behavior that is not yet implemented but lacks
+  \`dependsOn\`.
+- A low-risk \`finalReviewPolicy: "broad"\` is used while the plan crosses runtime,
+  schema, persistence, security, or release boundaries.
+
+## Approval summary
+
+When presenting the plan for approval, include:
+
+- The promised outcome.
+- The feature order and any dependencies that matter.
+- The main validation levels.
+- Material assumptions in \`decisions\`.
+- Any known gaps that remain intentional.
+`;
+
 // skills/flow-plan/references/planning-examples.md
 var planning_examples_default = `# Planning examples
 
@@ -914,6 +968,164 @@ Better plan:
 3. Add behavior-preservation tests for the changed service paths.
 \`\`\`
 
+## Bugfix plan
+
+Human summary:
+
+1. Reproduce and localize the failed password reset redirect.
+2. Fix the redirect state handling and cover the regression.
+3. Update release notes only if user-facing behavior changed.
+
+Payload:
+
+\`\`\`json
+{
+  "goal": "Fix password reset links landing users on the wrong page",
+  "plan": {
+    "summary": "Password reset links land users on the intended reset confirmation flow.",
+    "overview": "Start with a focused reproduction, then fix the redirect state and update user-facing notes only if the behavior change needs documentation.",
+    "requirements": [
+      "Preserve existing token validation and expiry behavior.",
+      "Users with valid reset links should not be sent to the generic sign-in page before completing the reset."
+    ],
+    "decisions": [
+      "Treat the current redirect mismatch as a regression until reproduction proves otherwise."
+    ],
+    "finalReviewPolicy": "detailed",
+    "features": [
+      {
+        "id": "reset-redirect-repro",
+        "title": "Redirect reproduction",
+        "summary": "Produce a failing focused check or trace that identifies where the reset redirect is lost.",
+        "targets": ["src/auth/reset", "tests/auth"],
+        "validation": ["targeted unit or integration reproduction for reset redirect behavior"],
+        "dependsOn": []
+      },
+      {
+        "id": "reset-redirect-fix",
+        "title": "Redirect fix",
+        "summary": "Preserve reset redirect state through token validation and completion.",
+        "targets": ["src/auth/reset", "tests/auth"],
+        "validation": ["targeted regression test passes", "auth package/build check if available"],
+        "dependsOn": ["reset-redirect-repro"]
+      },
+      {
+        "id": "reset-redirect-notes",
+        "title": "User-facing notes",
+        "summary": "Document the corrected reset-link behavior if release notes or help text mention the flow.",
+        "targets": ["CHANGELOG.md", "docs/auth.md"],
+        "validation": ["docs/static check if available", "review docs against implemented behavior"],
+        "dependsOn": ["reset-redirect-fix"]
+      }
+    ]
+  }
+}
+\`\`\`
+
+## UI/frontend plan
+
+Human summary:
+
+1. Map the current checkout empty state and responsive constraints.
+2. Implement the empty state with accessible controls and mobile layout.
+3. Verify the visual states with screenshots or browser evidence.
+
+Good feature outline:
+
+\`\`\`text
+1. Empty-state discovery - inspect the route, component boundaries, design tokens, existing empty states, and likely responsive breakpoints.
+2. Empty-state implementation - add the checkout empty state, action wiring, focus order, and loading/error boundaries in the existing component style.
+3. Visual and interaction verification - capture desktop and mobile evidence, run available route/component checks, and fix overlap or accessibility regressions.
+\`\`\`
+
+Why this is better than one "build UI" feature: the plan names the uncertain
+surface first, keeps implementation scoped to the route/components, and makes
+visual evidence part of completion rather than an afterthought.
+
+## Runtime or schema plan
+
+Human summary:
+
+1. Introduce the schema change behind a backward-compatible parser.
+2. Migrate callers and persistence writes.
+3. Add compatibility validation and docs.
+
+Good feature outline:
+
+\`\`\`text
+1. Compatible schema reader - accept old and new session payloads, with targeted parser tests for both.
+2. New writer path - emit the new field from runtime transitions and update affected callers.
+3. Compatibility sweep - run persistence/workspace tests, update docs, and verify old sessions still recover.
+\`\`\`
+
+Use \`finalReviewPolicy: "detailed"\` for this shape. Persistence and schema work
+usually has hidden downstream contracts, so feature validation should name both
+targeted parser checks and broader workspace/runtime gates.
+
+## Docs-only plan
+
+Docs-only work can use \`finalReviewPolicy: "broad"\` when it does not change
+commands, configuration, generated files, or release metadata.
+
+Good feature outline:
+
+\`\`\`text
+1. Align installation docs - update README and troubleshooting steps for the current setup flow.
+2. Verify commands and links - check documented commands against package scripts and make sure links/paths resolve.
+\`\`\`
+
+Bad validation:
+
+\`\`\`text
+validation: ["manual review"]
+\`\`\`
+
+Better validation:
+
+\`\`\`text
+validation: ["docs/static link and path review", "command examples checked against package scripts"]
+\`\`\`
+
+## Audit-first and review-first plans
+
+Use an evidence-producing first feature when the request asks to "review",
+"audit", "clean up", "modernize", or "improve" a broad area.
+
+Good feature outline:
+
+\`\`\`text
+1. Audit checkout state management - cite concrete findings with file:line evidence, refutation checks, severity, and recommended fix order.
+2. Fix confirmed high-impact state leak - only for findings that survived the audit.
+3. Regression validation - add or run checks covering the changed state paths.
+\`\`\`
+
+Do not plan fixes for guessed findings. If the audit might find no actionable
+issue, say that in the first feature summary and make later features conditional
+on evidence.
+
+## Validation examples
+
+Weak:
+
+\`\`\`text
+validation: ["run tests", "manual testing"]
+\`\`\`
+
+Stronger:
+
+\`\`\`text
+validation: [
+  "targeted unit tests for empty and invalid input",
+  "integration test for persisted session recovery",
+  "package/build gate for changed TypeScript exports",
+  "browser screenshot at desktop and mobile widths for layout-sensitive UI",
+  "docs/static review for changed command examples"
+]
+\`\`\`
+
+The stronger version says what level of evidence is expected and which behavior
+or surface it covers.
+
 ## Decomposition anti-patterns
 
 - Feature per file when behavior crosses files.
@@ -986,6 +1198,7 @@ Call \`flow_plan_save\` with:
         "id": "lowercase-kebab-case",
         "title": "Short title",
         "summary": "Outcome this feature delivers",
+        "reviewDepth": "standard",
         "targets": ["files, modules, routes, commands, or docs in scope"],
         "validation": ["focused checks expected before completion"],
         "dependsOn": []
@@ -997,6 +1210,23 @@ Call \`flow_plan_save\` with:
 
 Use only \`finalReviewPolicy: "broad"\` or \`"detailed"\`. These are the canonical final-review policy and \`reviewDepth\` enum values. Use \`"broad"\` only for low-risk, narrow work. Use \`"detailed"\` for behavioral changes, cross-module edits, migrations, releases, security-sensitive code, or large refactors.
 
+Set each feature's \`reviewDepth\` to one of:
+
+- \`quick\`: docs, comments, config-only changes, generated output, or mechanical changes fully covered by tooling.
+- \`standard\`: the default for ordinary implementation slices. The review reads every changed file and relevant tests.
+- \`detailed\`: persistence, migrations, concurrency, security, cross-module behavior, release/package surfaces, large refactors, weak validation, or any work where a missed edge case would be expensive.
+
+Do not make reviews shallower to save tokens. Reduce token use by splitting features, keeping \`targets\` precise, and using scoped review packets during execution.
+
+## Plan quality gate
+
+Before saving or asking for approval, load
+\`references/plan-quality-checklist.md\` and check the draft against it. Revise the
+plan until it passes, or record the remaining gap in \`decisions\` when the gap is
+an intentional assumption. Do not approve a plan whose outcome, requirements,
+targets, validation, or dependency order are still too vague for another agent
+to execute.
+
 ## Feature sizing
 
 - Each feature should have one owner, one coherent outcome, and a validation story.
@@ -1007,12 +1237,17 @@ Use only \`finalReviewPolicy: "broad"\` or \`"detailed"\`. These are the canonic
   validation entry should name the expected test level, such as targeted unit,
   integration, browser/e2e, package/build, docs/static, cleanup preservation, or
   broad project gate.
+- Assign \`reviewDepth\` from risk. Use \`detailed\` for persistence, migration,
+  concurrency, security, final-delivery-adjacent, or cross-module slices; use
+  \`standard\` for normal code changes; reserve \`quick\` for low-risk non-behavioral
+  work.
 
 ## Approval
 
 After saving, summarize the plan to the user. Call \`flow_plan_approve\` only after explicit user approval, unless the user already authorized autonomous implementation. Approved plans are immutable; changing them later requires reset/closure rather than silent edits.
 
-See \`references/planning-examples.md\` for payload examples and decomposition anti-patterns.
+See \`references/planning-examples.md\` for payload examples and decomposition
+anti-patterns.
 `;
 
 // skills/flow-review/references/review-rubric.md
@@ -1048,22 +1283,54 @@ If unsure whether a finding is real, read more or downgrade it. Do not promote g
 
 ## Final review checklist
 
-- Every feature is complete and together they satisfy the original goal.
-- Broad validation ran and passed.
+- The original goal is satisfied by the delivered behavior or artifacts.
+- Every approved requirement is either met or explicitly accounted for by an
+  accepted gap.
+- Plan decisions and scope boundaries still match the implementation.
+- Every planned feature is complete, has recorded validation evidence, and
+  contributes to the final outcome.
+- Feature dependencies were completed in an order that makes the evidence
+  trustworthy.
+- Changed artifacts match the plan's \`targets\`; extra changed surfaces are
+  explained and reviewed.
+- Broad validation ran and passed, or any skipped broad check is justified as a
+  non-blocking gap.
 - The final \`reviewDepth\` equals the approved \`finalReviewPolicy\`; the only final-review enum values are \`broad\` and \`detailed\`.
 - Feature-level reviews have no unresolved blocking findings.
 - Docs, commands, package metadata, and release surfaces match the delivered behavior.
 - Remaining gaps are explicit and do not contradict \`kind: "completed"\`.
 
+## Final convergence scan
+
+Run this scan before returning a passing \`finalReview\`:
+
+1. Restate the original goal and the approved plan summary in your own words.
+2. Map each requirement to delivered evidence, validation output, or an explicit
+   accepted gap.
+3. Walk every planned feature and confirm its completion evidence, review
+   result, and validation level.
+4. Compare the changed files, docs, commands, generated surfaces, and package
+   metadata to the planned targets and requirements.
+5. Check whether the validation evidence would have caught the main failure
+   modes introduced by the work.
+6. Decide whether remaining gaps are advisory or blocking before setting
+   \`status\`.
+
+Fail the final review when the delivered work cannot be traced back to the
+approved goal and requirements, even if each individual feature review passed.
+
 ## Payloads
 
 Feature review:
 
 \`\`\`json
 {
-  "status": "passed",
-  "summary": "Reviewed changed runtime files and focused tests; validation covers the new gate.",
-  "blockingFindings": []
+  "featureReviewDepth": "standard",
+  "featureReview": {
+    "status": "passed",
+    "summary": "Reviewed changed runtime files and focused tests; validation covers the new gate.",
+    "blockingFindings": []
+  }
 }
 \`\`\`
 
@@ -1071,14 +1338,17 @@ Failed feature review:
 
 \`\`\`json
 {
-  "status": "failed",
-  "summary": "Validation does not exercise the changed persistence path.",
-  "blockingFindings": [
-    {
-      "summary": "No test covers archive removal of .flow/session.json after close.",
-      "severity": "blocking"
-    }
-  ]
+  "featureReviewDepth": "detailed",
+  "featureReview": {
+    "status": "failed",
+    "summary": "Validation does not exercise the changed persistence path.",
+    "blockingFindings": [
+      {
+        "summary": "No test covers archive removal of .flow/session.json after close.",
+        "severity": "blocking"
+      }
+    ]
+  }
 }
 \`\`\`
 
@@ -1138,7 +1408,15 @@ These instructions run in two contexts, and only one of them can load helpers:
 
 - Call \`flow_status\` when available.
 - Identify whether this is a feature review or final review.
+- Prefer the manager's compact review packet over parent-session memory. The
+  packet should name the active feature, minimum \`reviewDepth\`, changed files,
+  diff summary, validation evidence, and targeted paths or risk lenses. If the
+  packet is missing important scope or evidence, record that as a coverage gap
+  or blocker instead of searching the full conversation transcript.
 - Read the approved plan fields relevant to the work: \`requirements\`, \`decisions\`, feature \`targets\`, feature \`validation\`, and dependencies.
+- For final review, also compare the original goal, full feature list, completed
+  feature evidence, changed artifacts, and final validation against the
+  convergence checklist in \`references/review-rubric.md\`.
 - Inspect the actual diff, changed files, tests, and validation output. Do not review only the completion summary.
 - In manager context, load \`flow-test\` for validation-heavy,
   regression-sensitive, browser QA, or unclear coverage reviews. If it is
@@ -1156,16 +1434,23 @@ These instructions run in two contexts, and only one of them can load helpers:
 
 ## Output
 
-For a feature review, return:
+For a feature review, return a packet the manager can copy into
+\`flow_feature_complete\`:
 
 \`\`\`json
 {
-  "status": "passed",
-  "summary": "what was reviewed and why it is acceptable",
-  "blockingFindings": []
+  "featureReviewDepth": "standard",
+  "featureReview": {
+    "status": "passed",
+    "summary": "what was reviewed and why it is acceptable",
+    "blockingFindings": []
+  }
 }
 \`\`\`
 
+\`featureReviewDepth\` must be at least the feature's planned \`reviewDepth\`.
+Use the actual depth performed: \`quick\`, \`standard\`, or \`detailed\`.
+
 For a final review, return:
 
 \`\`\`json
@@ -1317,96 +1602,7 @@ Never trim failing output, relabel a failed command as passed, or use "not run"
 `;
 
 // skills/flow-run/SKILL.md
-var SKILL_default6 = `---
-name: flow-run
-description: "Use when an approved Flow plan has a feature to implement, validate, or complete in the v4 runtime, and the work is scoped to one active feature. For planning a goal first use flow-plan; for the full goal-to-completion loop or resuming a session use flow."
----
-
-# Flow Run
-
-Use this skill for implementation after a Flow plan is approved. Work one feature at a time.
-
-If \`flow_run_start\` is unavailable, stop and tell the user to check that \`opencode-plugin-flow\` is loaded in OpenCode.
-
-## Start
-
-- Call \`flow_status\`.
-- Call \`flow_run_start\` with no \`featureId\` unless the user or plan requires a specific runnable feature.
-- Treat the returned feature as the sole scope until it is completed, blocked, or reset.
-- Helper rule: when a named helper skill is unavailable, record the gap and
-  keep the corresponding claims conservative instead of simulating its checks.
-- Load \`flow-deslop\` for cleanup/refactor features.
-- Load \`flow-ui-quality\` for frontend, UX, responsive, accessibility, or visual work.
-
-## Implement
-
-- Read the feature \`targets\`, \`summary\`, \`validation\`, dependencies, and plan \`requirements\`/\`decisions\`.
-- Keep edits scoped to the active feature. If new scope appears, stop and replan or defer it to another feature.
-- Preserve unrelated user changes in the worktree.
-- When a wrong assumption invalidates the feature, use \`flow_feature_reset\`; do not pile patches onto a bad path.
-- Do not stage, commit, push, amend, rebase, publish, or mutate releases as part
-  of feature execution. If the user explicitly asks for commit preparation, load
-  \`flow-commit\` only after \`flow_feature_complete\` has been recorded, unless the
-  user explicitly asks for a WIP commit path. Keep Git boundaries separate from
-  Flow state recording.
-
-## Validate
-
-- For complex validation, regression-sensitive changes, browser QA, route QA,
-  failure-prone checks, unclear coverage, exploratory QA, or
-  \`validationRun\` summarization, load \`flow-test\` (helper rule applies).
-- Read \`references/validation-rubric.md\` before completing.
-- Run the strongest practical checks for the changed behavior.
-- Record concrete command names, status, and observed results. "Tests pass" is not evidence.
-- Non-final features complete with \`validationScope: "targeted"\`.
-- The final feature must run a broad project-level gate and use \`validationScope: "broad"\`.
-
-For broad validation research, risky changes, or unclear coverage, use
-\`../flow/references/parallel-orchestration.md\` to fan out named Flow workers.
-Use the mode-to-agent mapping in that reference instead of generic subagents.
-Write its pass manifest before fan-out, paste the matching handoff template
-from \`../flow/references/handoff-format.md\` into every worker prompt, and
-apply its verification tiers to the handoffs that come back.
-They may report command output they actually ran or propose focused checks; the
-manager decides what is strong enough to record.
-
-For independent implementation attempts, use candidate workers only with
-explicit user authorization plus isolated worktrees or exact non-overlapping
-path ownership. Treat their output as candidate patches. The manager inspects,
-merges, validates, and records Flow state serially.
-
-## Review and complete
-
-Before \`flow_feature_complete\`, obtain a \`featureReview\` payload. Load
-\`flow-review\`; for read-only subagent reviews, the manager receives the payload
-and records it.
-
-If \`flow_status\` reports \`setup.skills\` or \`flow-review\` cannot be loaded, do
-not record a Flow-gated \`featureReview\` or \`finalReview\`. You may perform an
-advisory review using available context or the bundled review fallback provided
-by plugin config, then complete with \`status: "needs_input"\` if review evidence
-is required to proceed.
-
-For the final feature, also obtain a \`finalReview\` payload whose \`reviewDepth\` equals the approved plan's \`finalReviewPolicy\`.
-
-Complete with:
-
-\`\`\`json
-{
-  "status": "ok",
-  "featureId": "active-feature-id",
-  "summary": "what changed",
-  "artifactsChanged": [{ "path": "src/file.ts" }],
-  "validationRun": [
-    { "command": "bun test tests/foo.test.ts", "status": "passed", "summary": "3 pass, exercised foo behavior" }
-  ],
-  "validationScope": "targeted",
-  "featureReview": { "status": "passed", "summary": "review summary", "blockingFindings": [] }
-}
-\`\`\`
-
-If genuinely blocked, call \`flow_feature_complete\` with \`status: "needs_input"\` and an \`outcome\` that explains the blocker and next step. Never fabricate validation or review evidence to force progress.
-`;
+var SKILL_default6 = '---\nname: flow-run\ndescription: "Use when an approved Flow plan has a feature to implement, validate, or complete in the v4 runtime, and the work is scoped to one active feature. For planning a goal first use flow-plan; for the full goal-to-completion loop or resuming a session use flow."\n---\n\n# Flow Run\n\nUse this skill for implementation after a Flow plan is approved. Work one feature at a time.\n\nIf `flow_run_start` is unavailable, stop and tell the user to check that `opencode-plugin-flow` is loaded in OpenCode.\n\n## Start\n\n- Call `flow_status`.\n- If `flow_status` returns a `session.resumePacket` or\n  `session.budget.phaseBoundary`, stop the current autonomous loop and report\n  the resume instructions. Only call `flow_run_start` with\n  `phaseBoundaryAck: true` at the start of a fresh user invocation that is\n  explicitly resuming the Flow session; do not acknowledge a boundary inside\n  the same uninterrupted loop that created it.\n- Call `flow_run_start` with no `featureId` unless the user or plan requires a specific runnable feature.\n- Treat the returned feature as the sole scope until it is completed, blocked, or reset.\n- Helper rule: when a named helper skill is unavailable, record the gap and\n  keep the corresponding claims conservative instead of simulating its checks.\n- Load `flow-deslop` for cleanup/refactor features.\n- Load `flow-ui-quality` for frontend, UX, responsive, accessibility, or visual work.\n\n## Implement\n\n- Read the feature `targets`, `summary`, `validation`, dependencies, and plan `requirements`/`decisions`.\n- Treat the feature\'s `reviewDepth` as the minimum feature-review depth that\n  must be recorded in `flow_feature_complete`.\n- Keep edits scoped to the active feature. If new scope appears, stop and replan or defer it to another feature.\n- Preserve unrelated user changes in the worktree.\n- When a wrong assumption invalidates the feature, use `flow_feature_reset`; do not pile patches onto a bad path.\n- Do not stage, commit, push, amend, rebase, publish, or mutate releases as part\n  of feature execution. If the user explicitly asks for commit preparation, load\n  `flow-commit` only after `flow_feature_complete` has been recorded, unless the\n  user explicitly asks for a WIP commit path. Keep Git boundaries separate from\n  Flow state recording.\n\n## Validate\n\n- For complex validation, regression-sensitive changes, browser QA, route QA,\n  failure-prone checks, unclear coverage, exploratory QA, or\n  `validationRun` summarization, load `flow-test` (helper rule applies).\n- Read `references/validation-rubric.md` before completing.\n- Run the strongest practical checks for the changed behavior.\n- Record concrete command names, status, and observed results. "Tests pass" is not evidence.\n- Non-final features complete with `validationScope: "targeted"`.\n- The final feature must run a broad project-level gate and use `validationScope: "broad"`.\n\nFor broad validation research, risky changes, or unclear coverage, use\n`../flow/references/parallel-orchestration.md` to fan out named Flow workers.\nUse the mode-to-agent mapping in that reference instead of generic subagents.\nWrite its pass manifest before fan-out, paste the matching handoff template\nfrom `../flow/references/handoff-format.md` into every worker prompt, and\napply its verification tiers to the handoffs that come back.\nThey may report command output they actually ran or propose focused checks; the\nmanager decides what is strong enough to record.\n\nFor independent implementation attempts, use candidate workers only with\nexplicit user authorization plus isolated worktrees or exact non-overlapping\npath ownership. Treat their output as candidate patches. The manager inspects,\nmerges, validates, and records Flow state serially.\n\n## Review and complete\n\nBefore `flow_feature_complete`, obtain a `featureReview` payload. Load\n`flow-review`; for read-only subagent reviews, the manager receives the review\npacket and records both `featureReviewDepth` and `featureReview`.\n\nSend reviewers a compact review packet. Do not rely on the accumulated parent\nconversation. Include only:\n\n- active feature id, title, summary, `reviewDepth`, targets, validation, and dependencies\n- relevant plan requirements, decisions, and final review policy\n- changed files and a short diff summary\n- validation evidence with exact commands, status, and observed result\n- targeted paths or risk lenses the reviewer must inspect\n\nIf the review returns `status: "failed"`, do not fix inside the review pass.\nRecord the failed attempt by calling `flow_feature_complete` with the otherwise\nprepared completion payload, the failed `featureReview`, and the attempted\n`featureReviewDepth`; the runtime will reject completion and update the retry\nbudget. Default to stopping and reporting the blocker. When the user already\nauthorized autonomous implementation, make at most one repair and run one retry\nreview. If the retry fails or the runtime reports review retry budget\nexhausted, stop with the blocker.\n\nIf `flow_status` reports `setup.skills` or `flow-review` cannot be loaded, do\nnot record a Flow-gated `featureReview` or `finalReview`. You may perform an\nadvisory review using available context or the bundled review fallback provided\nby plugin config, then complete with `status: "needs_input"` if review evidence\nis required to proceed.\n\nFor the final feature, also obtain a `finalReview` payload whose `reviewDepth` equals the approved plan\'s `finalReviewPolicy`.\n\nComplete with:\n\n```json\n{\n  "status": "ok",\n  "featureId": "active-feature-id",\n  "summary": "what changed",\n  "artifactsChanged": [{ "path": "src/file.ts" }],\n  "validationRun": [\n    { "command": "bun test tests/foo.test.ts", "status": "passed", "summary": "3 pass, exercised foo behavior" }\n  ],\n  "validationScope": "targeted",\n  "featureReviewDepth": "standard",\n  "featureReview": { "status": "passed", "summary": "review summary", "blockingFindings": [] }\n}\n```\n\nIf `flow_feature_complete` returns a `session.resumePacket` or\n`session.budget.phaseBoundary`, stop after reporting the compact handoff. If\ngenuinely blocked, call `flow_feature_complete` with `status: "needs_input"` and\nan `outcome` that explains the blocker and next step. Never fabricate validation\nor review evidence to force progress.\n';
 
 // skills/flow-test/SKILL.md
 var SKILL_default7 = `---
@@ -1710,6 +1906,10 @@ var FLOW_SKILL_DEFINITIONS = [
         relativePath: "references/planning-examples.md",
         content: planning_examples_default
       },
+      {
+        relativePath: "references/plan-quality-checklist.md",
+        content: plan_quality_checklist_default
+      },
       {
         relativePath: "references/parallel-discovery.md",
         content: parallel_discovery_default
@@ -1802,6 +2002,7 @@ var FLOW_REVIEW_BUNDLED_INSTRUCTIONS = bundledFlowInstructions([
 var FLOW_PLAN_BUNDLED_INSTRUCTIONS = bundledFlowInstructions([
   ["flow-plan", "SKILL.md"],
   ["flow-plan", "references/planning-examples.md"],
+  ["flow-plan", "references/plan-quality-checklist.md"],
   ["flow-plan", "references/parallel-discovery.md"],
   ["flow", "references/parallel-orchestration.md"],
   ["flow", "references/handoff-format.md"]
@@ -1822,6 +2023,7 @@ var FLOW_AUTO_BUNDLED_INSTRUCTIONS = bundledFlowInstructions([
   ["flow", "references/handoff-format.md"],
   ["flow-plan", "SKILL.md"],
   ["flow-plan", "references/planning-examples.md"],
+  ["flow-plan", "references/plan-quality-checklist.md"],
   ["flow-plan", "references/parallel-discovery.md"],
   ["flow-run", "SKILL.md"],
   ["flow-run", "references/validation-rubric.md"],
@@ -1831,6 +2033,7 @@ var FLOW_AUTO_BUNDLED_INSTRUCTIONS = bundledFlowInstructions([
 ]);
 var FLOW_SELF_CONTAINED_COMMAND_PREFLIGHT = [
   "Call `flow_status` first. If the result includes `setup.skills`, report the setup status and continue with the bundled public Flow command instructions below.",
+  "If `flow_status` includes `session.resumePacket` or `session.budget.phaseBoundary`, stop the current autonomous loop and report the resume instructions unless this is a fresh user invocation explicitly resuming the session; only then may `flow_run_start` use `phaseBoundaryAck: true`.",
   "After `flow_status`, briefly state which bundled Flow command is running and for what goal, then continue.",
   "Do not call native Flow skills for `flow`, `flow-plan`, `flow-run`, or `flow-review` from public Flow commands. In bundled sections, `load` means read and use the corresponding bundled section in this command, and missing native public Flow skills are not blockers.",
   "Optional helper skills (`flow-test`, `flow-deslop`, `flow-ui-quality`, and user-triggered `flow-commit`) are not bundled fallbacks. If one is unavailable, record the coverage gap exactly as the bundled instructions require."
@@ -1851,6 +2054,7 @@ var FLOW_RUN_COMMAND_TEMPLATE = flowBundledCommandTemplate("Flow run", "Execute
 var FLOW_REVIEW_COMMAND_TEMPLATE = flowBundledCommandTemplate("Flow review", "Review: $ARGUMENTS", FLOW_REVIEW_BUNDLED_INSTRUCTIONS);
 var FLOW_REVIEW_AGENT_INSTRUCTIONS = [
   "Use Flow review mode. Call `flow_status` first. Do not call the native skill tool for `flow-review`; the canonical Flow review instructions and rubric are already embedded below. If Flow setup reports stale/unavailable skills, continue as advisory review only and do not present advisory review as Flow-gated `featureReview` or `finalReview` evidence.",
+  "Prefer the manager's compact review packet over the accumulated root transcript. Return feature review packets with `featureReviewDepth` plus `featureReview`; final reviews still return `finalReview` with `reviewDepth`.",
   "When the manager assigns a parallel review slice instead of a direct Flow review command, cite or drop every claim, label single-source, inferred, and unsettled claims, and return only the assigned Flow handoff. Report blocked if the assigned scope, expected coverage, or handoff shape is missing.",
   "",
   "## Bundled Flow review instructions",
@@ -2397,6 +2601,11 @@ var SessionStatusSchema = z.enum([
 var ReviewStatusSchema = z.enum(["passed", "failed"]);
 var ValidationStatusSchema = z.enum(["passed", "failed"]);
 var ValidationScopeSchema = z.enum(["targeted", "broad"]);
+var FeatureReviewDepthSchema = z.enum([
+  "quick",
+  "standard",
+  "detailed"
+]);
 var FinalReviewPolicySchema = z.enum(["broad", "detailed"]);
 var ReviewFindingSchema = z.object({
   summary: z.string().min(1),
@@ -2423,6 +2632,7 @@ var FeatureSchema = z.object({
   title: z.string().min(1),
   summary: z.string().min(1),
   status: FeatureStatusSchema.default("pending"),
+  reviewDepth: FeatureReviewDepthSchema.default("standard"),
   targets: z.array(z.string().min(1)).default([]),
   validation: z.array(z.string().min(1)).default([]),
   dependsOn: z.array(z.string().regex(FEATURE_ID_PATTERN)).default([])
@@ -2439,6 +2649,7 @@ var PlanInputSchema = PlanSchema.omit({ features: true }).extend({
   finalReviewPolicy: FinalReviewPolicySchema.optional(),
   features: z.array(FeatureSchema.omit({ status: true }).extend({
     status: FeatureStatusSchema.optional(),
+    reviewDepth: FeatureReviewDepthSchema.optional(),
     targets: z.array(z.string().min(1)).optional(),
     validation: z.array(z.string().min(1)).optional(),
     dependsOn: z.array(z.string().regex(FEATURE_ID_PATTERN)).optional()
@@ -2462,6 +2673,7 @@ var WorkerResultSchema = z.discriminatedUnion("status", [
     artifactsChanged: z.array(ArtifactSchema).default([]),
     validationRun: z.array(ValidationRunSchema).default([]),
     validationScope: ValidationScopeSchema,
+    featureReviewDepth: FeatureReviewDepthSchema,
     featureReview: ReviewSchema,
     finalReview: FinalReviewSchema.optional(),
     outcome: WorkerOutcomeSchema.optional()
@@ -2473,6 +2685,7 @@ var WorkerResultSchema = z.discriminatedUnion("status", [
     artifactsChanged: z.array(ArtifactSchema).default([]),
     validationRun: z.array(ValidationRunSchema).default([]),
     validationScope: ValidationScopeSchema.optional(),
+    featureReviewDepth: FeatureReviewDepthSchema.optional(),
     featureReview: ReviewSchema.optional(),
     finalReview: FinalReviewSchema.optional(),
     outcome: NeedsInputOutcomeSchema
@@ -2494,10 +2707,37 @@ var ExecutionHistoryEntrySchema = z.object({
   artifactsChanged: z.array(ArtifactSchema).default([]),
   validationRun: z.array(ValidationRunSchema).default([]),
   validationScope: ValidationScopeSchema.optional(),
+  featureReviewDepth: FeatureReviewDepthSchema.optional(),
   featureReview: ReviewSchema.optional(),
   finalReview: FinalReviewSchema.optional(),
   outcome: WorkerOutcomeSchema.optional()
 }).strict();
+var TokenTelemetrySchema = z.object({
+  source: z.enum(["host_unavailable", "reported"]).default("host_unavailable"),
+  visibleTokens: z.number().int().nonnegative().nullable().default(null),
+  cacheReadTokens: z.number().int().nonnegative().nullable().default(null),
+  nonCacheTokens: z.number().int().nonnegative().nullable().default(null)
+}).strict();
+var PhaseBoundarySchema = z.object({
+  reason: z.enum(["feature_limit", "token_limit", "review_failure_limit"]),
+  summary: z.string().min(1),
+  resumeInstructions: z.string().min(1),
+  recordedAt: z.string().min(1)
+}).strict();
+var BudgetTelemetrySchema = z.object({
+  phaseStartedAt: z.string().min(1).default("unknown"),
+  completedFeaturesSinceBoundary: z.number().int().nonnegative().default(0),
+  reviewCount: z.number().int().nonnegative().default(0),
+  failedReviewCount: z.number().int().nonnegative().default(0),
+  failedReviewAttemptsByFeature: z.record(z.string().regex(FEATURE_ID_PATTERN, FEATURE_ID_MESSAGE), z.number().int().nonnegative()).default({}),
+  tokenTelemetry: TokenTelemetrySchema.default({
+    source: "host_unavailable",
+    visibleTokens: null,
+    cacheReadTokens: null,
+    nonCacheTokens: null
+  }),
+  phaseBoundary: PhaseBoundarySchema.nullable().default(null)
+}).strict();
 var SessionSchema = z.object({
   version: z.literal(2),
   id: z.string().regex(/^[a-zA-Z0-9_-]+$/, "Invalid session id."),
@@ -2507,6 +2747,20 @@ var SessionSchema = z.object({
   plan: PlanSchema.nullable(),
   activeFeatureId: z.string().regex(FEATURE_ID_PATTERN, FEATURE_ID_MESSAGE).nullable(),
   history: z.array(ExecutionHistoryEntrySchema).default([]),
+  budget: BudgetTelemetrySchema.default({
+    phaseStartedAt: "unknown",
+    completedFeaturesSinceBoundary: 0,
+    reviewCount: 0,
+    failedReviewCount: 0,
+    failedReviewAttemptsByFeature: {},
+    tokenTelemetry: {
+      source: "host_unavailable",
+      visibleTokens: null,
+      cacheReadTokens: null,
+      nonCacheTokens: null
+    },
+    phaseBoundary: null
+  }),
   closure: z.object({
     kind: z.enum(["completed", "deferred", "abandoned"]),
     summary: z.string().min(1),
@@ -2944,6 +3198,13 @@ function nowIso() {
 
 // src/runtime/transitions.ts
 var MAX_HISTORY_ENTRIES = 500;
+var MAX_FEATURES_PER_PHASE = 3;
+var MAX_FAILED_REVIEW_ATTEMPTS_PER_FEATURE = 2;
+var FEATURE_REVIEW_DEPTH_RANK = {
+  quick: 0,
+  standard: 1,
+  detailed: 2
+};
 function appendHistory(history, entry) {
   const next = [...history, entry];
   return next.length > MAX_HISTORY_ENTRIES ? next.slice(next.length - MAX_HISTORY_ENTRIES) : next;
@@ -2957,11 +3218,42 @@ function historyEntryFor(worker, status) {
     artifactsChanged: worker.artifactsChanged,
     validationRun: worker.validationRun,
     validationScope: worker.validationScope,
+    featureReviewDepth: worker.featureReviewDepth,
     featureReview: worker.featureReview,
     finalReview: worker.finalReview,
     outcome: worker.outcome
   };
 }
+function initialBudgetTelemetry() {
+  return {
+    phaseStartedAt: nowIso(),
+    completedFeaturesSinceBoundary: 0,
+    reviewCount: 0,
+    failedReviewCount: 0,
+    failedReviewAttemptsByFeature: {},
+    tokenTelemetry: {
+      source: "host_unavailable",
+      visibleTokens: null,
+      cacheReadTokens: null,
+      nonCacheTokens: null
+    },
+    phaseBoundary: null
+  };
+}
+function normalizeBudgetTelemetry(session) {
+  const defaults = initialBudgetTelemetry();
+  return {
+    ...defaults,
+    ...session.budget,
+    failedReviewAttemptsByFeature: {
+      ...session.budget.failedReviewAttemptsByFeature
+    },
+    tokenTelemetry: {
+      ...defaults.tokenTelemetry,
+      ...session.budget.tokenTelemetry
+    }
+  };
+}
 function ok(value) {
   return { ok: true, value };
 }
@@ -2986,6 +3278,7 @@ function clonePlan(input) {
       title: feature.title,
       summary: feature.summary,
       status: "pending",
+      reviewDepth: feature.reviewDepth ?? "standard",
       targets: feature.targets ?? [],
       validation: feature.validation ?? [],
       dependsOn: feature.dependsOn ?? []
@@ -3039,6 +3332,7 @@ function createSession(goal) {
     plan: null,
     activeFeatureId: null,
     history: [],
+    budget: initialBudgetTelemetry(),
     closure: null,
     lastError: null,
     timestamps: {
@@ -3069,6 +3363,7 @@ function applyPlan(session, planInput) {
     plan,
     activeFeatureId: null,
     history: [],
+    budget: initialBudgetTelemetry(),
     closure: null,
     lastError: null,
     timestamps: { ...session.timestamps, completedAt: null }
@@ -3112,7 +3407,7 @@ function nextRunnableFeature(features, requestedId) {
 function updateFeature(features, featureId, status) {
   return features.map((feature) => feature.id === featureId ? { ...feature, status } : feature.status === "in_progress" && status === "in_progress" ? { ...feature, status: "pending" } : feature);
 }
-function startRun(session, featureId) {
+function startRun(session, featureId, options) {
   if (session.status === "completed") {
     return fail("This Flow session is already completed.");
   }
@@ -3122,6 +3417,10 @@ function startRun(session, featureId) {
   if (session.status === "blocked") {
     return fail("Blocked features must be reset before rerun.", "Call flow_feature_reset for the blocked feature, then start it again.");
   }
+  const budget = normalizeBudgetTelemetry(session);
+  if (budget.phaseBoundary && !options?.phaseBoundaryAck) {
+    return fail(budget.phaseBoundary.summary, budget.phaseBoundary.resumeInstructions);
+  }
   if (session.activeFeatureId) {
     if (!featureId || featureId === session.activeFeatureId) {
       const active = session.plan.features.find((feature) => feature.id === session.activeFeatureId);
@@ -3141,6 +3440,12 @@ function startRun(session, featureId) {
     ...session,
     status: "running",
     plan: nextPlan,
+    budget: budget.phaseBoundary ? {
+      ...budget,
+      phaseStartedAt: nowIso(),
+      completedFeaturesSinceBoundary: 0,
+      phaseBoundary: null
+    } : budget,
     activeFeatureId: selected.value.id,
     lastError: null
   });
@@ -3157,6 +3462,12 @@ function finalFeature(session, featureId) {
     return false;
   return session.plan.features.every((feature) => feature.id === featureId || feature.status === "completed");
 }
+function activeFeature(session, featureId) {
+  return session.plan?.features.find((feature) => feature.id === featureId) ?? null;
+}
+function reviewDepthMeetsRequirement(actual, required) {
+  return FEATURE_REVIEW_DEPTH_RANK[actual] >= FEATURE_REVIEW_DEPTH_RANK[required];
+}
 function completionFailure(session, tool, message, recovery) {
   return fail(message, recovery, {
     ...session,
@@ -3165,6 +3476,8 @@ function completionFailure(session, tool, message, recovery) {
 }
 function validateCompletion(session, worker) {
   const wasFinal = finalFeature(session, worker.featureId);
+  const feature = activeFeature(session, worker.featureId);
+  const requiredReviewDepth = feature?.reviewDepth ?? "standard";
   if (worker.validationRun.length === 0) {
     return completionFailure(session, "flow_feature_complete", "Completion requires recorded validation evidence.", "Run the targeted or broad validation command and record the result.");
   }
@@ -3174,6 +3487,9 @@ function validateCompletion(session, worker) {
   if (!wasFinal && worker.validationScope !== "targeted") {
     return completionFailure(session, "flow_feature_complete", "Non-final feature completion requires targeted validation.", "Record validationScope: targeted for ordinary feature completion.");
   }
+  if (!reviewDepthMeetsRequirement(worker.featureReviewDepth, requiredReviewDepth)) {
+    return completionFailure(session, "flow_feature_complete", `Feature review depth '${worker.featureReviewDepth}' does not meet the plan requirement '${requiredReviewDepth}'.`, "Run the feature review at the planned depth or reset/replan if the depth is wrong.");
+  }
   if (wasFinal && worker.validationScope !== "broad") {
     return completionFailure(session, "flow_feature_complete", "Final feature completion requires broad validation.", "Run the project-level gate and record validationScope: broad.");
   }
@@ -3194,6 +3510,85 @@ function validateCompletion(session, worker) {
   }
   return ok(undefined);
 }
+function incrementFailedReviewAttempt(session, worker, review, reviewKind) {
+  const budget = normalizeBudgetTelemetry(session);
+  const attempts = (budget.failedReviewAttemptsByFeature[worker.featureId] ?? 0) + 1;
+  const exhausted = attempts >= MAX_FAILED_REVIEW_ATTEMPTS_PER_FEATURE;
+  const nextBudget = {
+    ...budget,
+    failedReviewCount: budget.failedReviewCount + 1,
+    failedReviewAttemptsByFeature: {
+      ...budget.failedReviewAttemptsByFeature,
+      [worker.featureId]: attempts
+    },
+    phaseBoundary: exhausted ? {
+      reason: "review_failure_limit",
+      summary: "Review retry budget exhausted. Stop and report the blocker before making more changes.",
+      resumeInstructions: "Ask the user how to proceed, or reset the feature after an explicit decision. Do not keep auto-repairing this review failure.",
+      recordedAt: nowIso()
+    } : budget.phaseBoundary
+  };
+  if (!exhausted) {
+    return {
+      session: { ...session, budget: nextBudget },
+      attempts,
+      exhausted
+    };
+  }
+  const entry = historyEntryFor({
+    ...worker,
+    summary: `${reviewKind === "final" ? "Final review" : "Feature review"} failed after ${attempts} attempts: ${review.summary}`,
+    outcome: {
+      kind: "blocked",
+      summary: review.summary,
+      resolutionHint: "Report the review blocker and wait for explicit reset, replan, or repair approval."
+    }
+  }, "blocked");
+  return {
+    session: touch({
+      ...session,
+      status: "blocked",
+      activeFeatureId: null,
+      plan: session.plan ? {
+        ...session.plan,
+        features: updateFeature(session.plan.features, worker.featureId, "blocked")
+      } : session.plan,
+      history: appendHistory(session.history, entry),
+      budget: nextBudget
+    }),
+    attempts,
+    exhausted
+  };
+}
+function failedReviewCompletion(session, worker, review, reviewKind) {
+  const failedReview = incrementFailedReviewAttempt(session, worker, review, reviewKind);
+  const reviewName = reviewKind === "final" ? "finalReview" : "featureReview";
+  return completionFailure(failedReview.session, "flow_feature_complete", failedReview.exhausted ? "Review retry budget exhausted for this feature." : `Completion requires a passing ${reviewName} with no blocking findings.`, failedReview.exhausted ? "Stop and report the remaining review blocker. Reset or replan only after explicit user direction." : `Pause and report the review blocker. If autonomous repair was explicitly authorized, make at most one repair and retry once; this was failed review attempt ${failedReview.attempts}/${MAX_FAILED_REVIEW_ATTEMPTS_PER_FEATURE}.`);
+}
+function clearFailedReviewAttempts(budget, featureId) {
+  const { [featureId]: _cleared, ...remainingAttempts } = budget.failedReviewAttemptsByFeature;
+  return {
+    ...budget,
+    failedReviewAttemptsByFeature: remainingAttempts
+  };
+}
+function completionBudget(session, worker, allComplete) {
+  const budget = clearFailedReviewAttempts(normalizeBudgetTelemetry(session), worker.featureId);
+  const completedFeaturesSinceBoundary = budget.completedFeaturesSinceBoundary + 1;
+  const reviewCount = budget.reviewCount + (worker.finalReview ? 2 : 1);
+  const reachedFeatureLimit = !allComplete && completedFeaturesSinceBoundary >= MAX_FEATURES_PER_PHASE;
+  return {
+    ...budget,
+    completedFeaturesSinceBoundary,
+    reviewCount,
+    phaseBoundary: reachedFeatureLimit ? {
+      reason: "feature_limit",
+      summary: `Completed ${completedFeaturesSinceBoundary} features since the last Flow checkpoint. Stop this OpenCode session and resume from .flow/session.json in a fresh session.`,
+      resumeInstructions: "Start a fresh OpenCode session in this workspace, call flow_status, then call flow_run_start with phaseBoundaryAck: true to begin the next phase.",
+      recordedAt: nowIso()
+    } : budget.phaseBoundary
+  };
+}
 function completeFeature(session, input) {
   if (!session.plan || session.status !== "running" || !session.activeFeatureId) {
     return fail("No feature is currently running.");
@@ -3201,7 +3596,7 @@ function completeFeature(session, input) {
   const parsed = WorkerResultSchema.safeParse(input);
   if (!parsed.success) {
     const issues = parsed.error.issues.slice(0, 3).map((issue) => `${issue.path.join(".") || "payload"}: ${issue.message}`).join("; ");
-    return fail(`flow_feature_complete payload is invalid: ${issues}.`, 'Provide status, featureId, and summary. Results with status "ok" also need validationScope, at least one validationRun entry, and a featureReview; final features add a finalReview.');
+    return fail(`flow_feature_complete payload is invalid: ${issues}.`, 'Provide status, featureId, and summary. Results with status "ok" also need validationScope, at least one validationRun entry, featureReviewDepth, and a featureReview; final features add a finalReview.');
   }
   const worker = parsed.data;
   if (worker.featureId !== session.activeFeatureId) {
@@ -3209,6 +3604,7 @@ function completeFeature(session, input) {
   }
   if (worker.status === "needs_input") {
     const entry2 = historyEntryFor(worker, "needs_input");
+    const budget2 = normalizeBudgetTelemetry(session);
     return ok(touch({
       ...session,
       status: "blocked",
@@ -3218,9 +3614,16 @@ function completeFeature(session, input) {
         features: updateFeature(session.plan.features, worker.featureId, "blocked")
       },
       history: appendHistory(session.history, entry2),
+      budget: budget2,
       lastError: null
     }));
   }
+  if (!isPassingReview(worker.featureReview)) {
+    return failedReviewCompletion(session, worker, worker.featureReview, "feature");
+  }
+  if (finalFeature(session, worker.featureId) && worker.finalReview && !isPassingReview(worker.finalReview)) {
+    return failedReviewCompletion(session, worker, worker.finalReview, "final");
+  }
   const validation = validateCompletion(session, worker);
   if (!validation.ok)
     return validation;
@@ -3228,12 +3631,14 @@ function completeFeature(session, input) {
   const features = updateFeature(session.plan.features, worker.featureId, "completed");
   const allComplete = features.every((feature) => feature.status === "completed");
   const now = nowIso();
+  const budget = completionBudget(session, worker, allComplete);
   return ok(touch({
     ...session,
     status: allComplete ? "completed" : "ready",
     activeFeatureId: null,
     plan: { ...session.plan, features },
     history: appendHistory(session.history, entry),
+    budget,
     closure: allComplete ? { kind: "completed", summary: worker.summary, recordedAt: now } : null,
     lastError: null,
     timestamps: {
@@ -3267,6 +3672,13 @@ function resetFeature(session, featureId) {
   const affected = dependentFeatureIds(session.plan.features, featureId);
   const activeFeatureId = session.activeFeatureId && affected.has(session.activeFeatureId) ? null : session.activeFeatureId;
   const nextFeatures = session.plan.features.map((feature) => affected.has(feature.id) ? { ...feature, status: "pending" } : feature);
+  const budget = normalizeBudgetTelemetry(session);
+  const failedReviewAttemptsByFeature = {
+    ...budget.failedReviewAttemptsByFeature
+  };
+  for (const featureIdToClear of affected) {
+    delete failedReviewAttemptsByFeature[featureIdToClear];
+  }
   const nextStatus = session.approval !== "approved" ? "planning" : activeFeatureId ? "running" : nextFeatures.some((feature) => feature.status === "blocked") ? "blocked" : "ready";
   return ok(touch({
     ...session,
@@ -3276,6 +3688,11 @@ function resetFeature(session, featureId) {
       ...session.plan,
       features: nextFeatures
     },
+    budget: {
+      ...budget,
+      failedReviewAttemptsByFeature,
+      phaseBoundary: budget.phaseBoundary?.reason === "review_failure_limit" ? null : budget.phaseBoundary
+    },
     closure: null,
     lastError: null,
     timestamps: { ...session.timestamps, completedAt: null }
@@ -3323,6 +3740,7 @@ function summarizeSession(session) {
   const latestHistoryEntry = session.history.at(-1) ?? null;
   const blockedEntry = session.status === "blocked" ? latestHistoryEntry : null;
   const active = session.activeFeatureId ? features.find((feature) => feature.id === session.activeFeatureId) : null;
+  const budget = normalizeBudgetTelemetry(session);
   return {
     status: session.status,
     summary: session.closure?.summary ?? session.lastError?.summary ?? blockedEntry?.summary ?? session.plan?.summary ?? "Flow session is active.",
@@ -3336,6 +3754,30 @@ function summarizeSession(session) {
       activeFeature: active ?? null,
       progress: { completed: completed.length, total: features.length },
       features,
+      budget: {
+        phaseStartedAt: budget.phaseStartedAt,
+        completedFeaturesSinceBoundary: budget.completedFeaturesSinceBoundary,
+        reviewCount: budget.reviewCount,
+        failedReviewCount: budget.failedReviewCount,
+        failedReviewAttemptsByFeature: budget.failedReviewAttemptsByFeature,
+        tokenTelemetry: {
+          ...budget.tokenTelemetry,
+          note: budget.tokenTelemetry.source === "host_unavailable" ? "OpenCode does not expose per-turn usage to this plugin surface; Flow can enforce feature/review checkpoints, but token thresholds remain manager-observed." : undefined
+        },
+        phaseBoundary: budget.phaseBoundary
+      },
+      resumePacket: budget.phaseBoundary ? {
+        sessionId: session.id,
+        goal: session.goal,
+        status: session.status,
+        activeFeatureId: session.activeFeatureId,
+        progress: {
+          completed: completed.length,
+          total: features.length
+        },
+        phaseBoundary: budget.phaseBoundary,
+        nextAction: "Start a fresh OpenCode session in this workspace, call flow_status, then call flow_run_start with phaseBoundaryAck: true."
+      } : null,
       closure: session.closure,
       lastError: session.lastError,
       latestHistoryEntry,
@@ -3349,6 +3791,9 @@ function nextAction(session) {
     return "Save a plan with flow_plan_save.";
   if (session.approval !== "approved")
     return "Approve the plan.";
+  if (session.budget.phaseBoundary) {
+    return "Start a fresh OpenCode session, call flow_status, then acknowledge the phase boundary with flow_run_start.";
+  }
   if (session.status === "ready")
     return "Start the next feature.";
   if (session.status === "running")
@@ -3366,7 +3811,8 @@ var FlowPlanSaveSchema = z2.object({
   plan: PlanInputSchema.optional()
 }).strict();
 var FlowRunStartSchema = z2.object({
-  featureId: z2.string().min(1).optional()
+  featureId: z2.string().min(1).optional(),
+  phaseBoundaryAck: z2.boolean().optional()
 }).strict();
 var FlowFeatureResetSchema = z2.object({
   featureId: z2.string().min(1)
@@ -3382,6 +3828,7 @@ var FlowFeatureCompleteToolSchema = z2.object({
   artifactsChanged: z2.array(ArtifactSchema).optional(),
   validationRun: z2.array(ValidationRunSchema).optional(),
   validationScope: ValidationScopeSchema.optional(),
+  featureReviewDepth: FeatureReviewDepthSchema.optional(),
   featureReview: ReviewSchema.optional(),
   finalReview: FinalReviewSchema.optional(),
   outcome: z2.union([WorkerOutcomeSchema, NeedsInputOutcomeSchema]).optional()
@@ -3496,7 +3943,7 @@ async function flowRunStart(worktree, input) {
     if (!session) {
       return missingSessionResponse();
     }
-    const result = startRun(session, args.featureId);
+    const result = startRun(session, args.featureId, args.phaseBoundaryAck === undefined ? undefined : { phaseBoundaryAck: args.phaseBoundaryAck });
     if (!result.ok)
       return responseFromFailure(result);
     const saved = await saveSession(worktree, result.value.session);
@@ -3516,8 +3963,15 @@ async function flowFeatureComplete(worktree, input) {
     }
     const result = completeFeature(session, worker);
     if (!result.ok) {
-      if (result.session)
-        await saveSession(worktree, result.session);
+      if (result.session) {
+        const saved2 = await saveSession(worktree, result.session);
+        return {
+          ...summarizeSession(saved2),
+          status: "error",
+          summary: result.message,
+          ...result.recovery ? { recovery: result.recovery } : {}
+        };
+      }
       return responseFromFailure(result);
     }
     const saved = await saveSession(worktree, result.value);
@@ -3744,4 +4198,4 @@ export {
   plugin_default as default
 };
 
-//# debugId=F01203B3D1AFDF4F64756E2164756E21
+//# debugId=519CC894E2A4E68464756E2164756E21