opencode-plugin-flow 4.3.4 → 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 = `---
@@ -1198,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": []
@@ -1209,6 +1210,14 @@ 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
@@ -1228,6 +1237,10 @@ to execute.
   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
 
@@ -1312,9 +1325,12 @@ 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": []
+  }
 }
 \`\`\`
 
@@ -1322,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"
+      }
+    ]
+  }
 }
 \`\`\`
 
@@ -1389,6 +1408,11 @@ 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
@@ -1410,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
@@ -1571,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 = `---
@@ -2091,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."
@@ -2111,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",
@@ -2657,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),
@@ -2683,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([])
@@ -2699,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()
@@ -2722,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()
@@ -2733,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
@@ -2754,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."),
@@ -2767,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),
@@ -3204,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;
@@ -3217,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 };
 }
@@ -3246,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 ?? []
@@ -3299,6 +3332,7 @@ function createSession(goal) {
     plan: null,
     activeFeatureId: null,
     history: [],
+    budget: initialBudgetTelemetry(),
     closure: null,
     lastError: null,
     timestamps: {
@@ -3329,6 +3363,7 @@ function applyPlan(session, planInput) {
     plan,
     activeFeatureId: null,
     history: [],
+    budget: initialBudgetTelemetry(),
     closure: null,
     lastError: null,
     timestamps: { ...session.timestamps, completedAt: null }
@@ -3372,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.");
   }
@@ -3382,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);
@@ -3401,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
   });
@@ -3417,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,
@@ -3425,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.");
   }
@@ -3434,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.");
   }
@@ -3454,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.");
@@ -3461,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) {
@@ -3469,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",
@@ -3478,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;
@@ -3488,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: {
@@ -3527,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,
@@ -3536,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 }
@@ -3583,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.",
@@ -3596,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,
@@ -3609,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")
@@ -3626,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)
@@ -3642,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()
@@ -3756,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);
@@ -3776,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);
@@ -4004,4 +4198,4 @@ export {
   plugin_default as default
 };
 
-//# debugId=72872E938F875B1A64756E2164756E21
+//# debugId=519CC894E2A4E68464756E2164756E21