opencode-plugin-flow 5.1.1 → 5.2.0

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 One short entry per release, written for users deciding whether to upgrade.
 
+## [5.2.0] - 2026-07-19
+
+Runtime-owned review assignment lore removes the recovery loops seen in long
+Flow runs while preserving independent review and stale-source protection:
+
+- Session v4 separates plan features from execution runs. Reset preserves old
+  evidence and attempts as audit history but gives restarted work fresh run and
+  retry identity. It is the sole supported session contract; every other version
+  is generic unsupported input rather than a migration or compatibility path.
+- New manager-only `flow_review_start` records source-bound validation and
+  creates a durable reviewer assignment. Reviewers recover only by assignment
+  id and no longer invent attempt, pass, packet, evidence, snapshot, start-time,
+  or review-depth fields.
+- `flow_feature_complete` now accepts one nested `completed` or `blocked`
+  result. Invalid or stale input is mutation-free and leaves its operation id
+  reusable; a genuine review blocker is an accepted mutation that consumes the
+  bounded run-scoped retry budget.
+- Final assignments retain the exact passing feature-assignment result as a
+  durable bound prerequisite. A broad final feature outcome submits only the
+  final-assignment result; Flow records both review executions atomically even
+  after manager context loss. Same-source final-review retries recover the first
+  binding from detail status; compact and reviewer status keep it out.
+- Reported validation and review times must follow active-execution,
+  validation, and assignment order and cannot postdate runtime acceptance.
+- Completed, deferred, and abandoned closure are quiescent. If archive
+  publication is interrupted, compact status exposes one retry operation id;
+  retry needs no reconstructed summary or causal guards. New close ids are
+  unique across active and canonical archived mutation history.
+- Saving a different goal never silently archives or replaces an unclosed
+  session, including an unapproved draft. Explicit deferred or abandoned close
+  owns that disposition before the next goal begins.
+- Archive publication and canonical history now require non-null explicit
+  closure; closureless Session v4 archives fail closed.
+- Lifecycle tools expose strict nested `request` unions. Application,
+  registered, emitted, executed, prompt, and documented contracts now exercise
+  the same semantic request set with no flat compatibility adapter. Registered
+  handlers validate again at entry because schema advertisement alone does not
+  stop every invalid host invocation.
+- Validation applicability uses source identity plus feature run instead of the
+  latest review-ledger revision. Distinct silent validation commands retain
+  distinct command identities, while source edits and reset still stale prior
+  assignments.
+- Manager, reviewer, recovery, README, lifecycle, causal-state, and maintainer
+  contracts now describe the nine-tool assignment handshake and final-feature
+  economy order. Deterministic lifecycle, transport-budget, prompt, package,
+  persistence, and schema coverage exercise the cutover.
+
 ## [5.1.1] - 2026-07-19
 
 Durable ignore publication lore keeps concurrent restricted-evidence setup

package/README.md

@@ -17,7 +17,7 @@ Full project documentation is available in the
 ## Quick start
 
 ```bash
-opencode plugin opencode-plugin-flow@5.1.1 --global --force
+opencode plugin opencode-plugin-flow@5.2.0 --global --force
 ```
 
 Start or restart OpenCode, then give Flow a goal:
@@ -32,6 +32,10 @@ implement one feature → validate it → review it → record evidence → next
 feature. `/flow-status` shows where you are at any point, including after a
 restart.
 
+`/flow-auto` still respects the scope of the request. If you ask for a plan
+only or explicitly say not to implement, it saves and summarizes the plan and
+stops before `flow_run_start`.
+
 ## What a session looks like
 
 ```text
@@ -42,14 +46,22 @@ restart.
   (you approve the plan)
   flow_plan_approve plan locked — features are now immutable
   flow_run_start    mutation acknowledged
-  flow_status       view: execution, feature: rate-limit-middleware
+  flow_status       request.view: execution, feature: rate-limit-middleware
   ... implementation, tests ...
+  flow_review_start request.validations: focused checks passed
+                    request.reviewKind: feature
+                    request.validationScope: targeted
+                    assignmentId: review-assignment:runtime-id
+  flow_status       request.view: reviewer
+                    request.assignmentId: review-assignment:runtime-id
+  ... independent review ...
   flow_feature_complete
-                    validationRun: "bun test tests/middleware.test.ts" passed
-                    featureReviewDepth: standard
-                    featureReview: passed
+                    request.result.kind: completed
+                    request.result.validationScope: targeted
+                    request.result.featureReview.assignmentId: review-assignment:runtime-id
+                    request.result.featureReview.verdict: passed
   flow_run_start    mutation acknowledged
-  flow_status       view: execution, feature: per-route-config
+  flow_status       request.view: execution, feature: per-route-config
   ...
 
 > /flow-status
@@ -59,7 +71,7 @@ restart.
   workflowData.projection.progress: { completed: 1, total: 3, remaining: 2 }
 
 > /flow-run
-  flow_status       view: execution
+  flow_status       request.view: execution
                     workflowData.projection: full active-feature scope
 ```
 
@@ -67,7 +79,9 @@ restart.
 routing-only, execution is the full active-feature working scope, detail is
 diagnostic, and reviewer is narrow assignment context. State-changing tools
 return `workflowData.receipt` acknowledgements; a receipt never replaces a
-fresh status projection.
+fresh status projection. Rejected mutations explicitly report
+`operationAccepted: false` and `operationIdConsumed: false`; accepted results,
+including durable review blockers, report the corresponding accepted receipt.
 
 Interrupt at any point; `/flow-run` resumes the next approved feature. On the
 final feature Flow requires broad project-level validation and a final review
@@ -78,7 +92,7 @@ completed.
 
 | Command | Purpose |
 | --- | --- |
-| `/flow-auto <goal>` | Drive the full guidance-driven loop. |
+| `/flow-auto <goal>` | Drive the authorized loop; stop after planning when requested. |
 | `/flow-plan <goal>` | Create or approve a plan. |
 | `/flow-run` | Execute one approved feature. |
 | `/flow-review` | Run a read-only review. |
@@ -96,23 +110,37 @@ loop.
 
 ## Tools
 
-The plugin exposes eight tools. `flow_guidance` is read-only and returns embedded
-Markdown; the other seven form the stateful runtime surface:
+The plugin exposes nine tools. `flow_guidance` is read-only and returns embedded
+Markdown; the other eight form the runtime surface:
 
 | Tool | Purpose |
 | --- | --- |
 | `flow_guidance` | Load exact package-owned guidance by stable id. |
 | `flow_status` | Read the active session and next action. |
-| `flow_plan_save` | Create a session and/or save a draft plan. |
+| `flow_plan_save` | Create a session or update its active same-goal draft. |
 | `flow_plan_approve` | Approve the draft plan. |
 | `flow_run_start` | Start the next runnable feature. |
-| `flow_feature_complete` | Record completion or blocker evidence for the active feature. |
+| `flow_review_start` | Bind validation to current source and create a runtime-owned reviewer assignment; final review also binds the passing feature result. |
+| `flow_feature_complete` | Atomically record a completed or blocked assignment result. |
 | `flow_feature_reset` | Reset one feature and its dependents. |
 | `flow_session_close` | Archive the active session as completed, deferred, or abandoned. |
 
-Review evidence is part of `flow_feature_complete`: every completed feature
-needs a passing `featureReview` at the feature's planned `reviewDepth`, and the
-final feature also needs a passing `finalReview`.
+Only the root manager calls `flow_review_start`. Reviewers recover the exact
+assignment with
+`flow_status { request: { view: "reviewer", assignmentId } }` and return only
+the assignment id, verdict, typed findings, reported time, and terminal
+disposition. The runtime derives all attempt, pass, source, packet, run,
+start-time, and required-depth identity. Final assignment creation durably binds
+the exact passing feature-assignment result. The final feature outcome submits
+only the final-assignment result; Flow records both results atomically from the
+durable binding.
+
+The first final assignment pins that binding for every same-source final-review
+retry. A manager recovering context loads detail status and copies
+`workflowData.projection.finalReviewRetry.prerequisite.result` unchanged into
+the new final review start's `request.featureReview`. Compact and reviewer views
+omit the aggregate. A mismatch records nothing and leaves its operation id
+reusable; a source edit requires a new targeted feature-review sequence.
 
 ## What the runtime enforces
 
@@ -121,22 +149,47 @@ The runtime owns only safety; judgment lives in package-owned guidance:
 - `.flow/session.json` is the single source of truth; writes are locked and
   atomic, and closed sessions are archived under `.flow/history/`.
 - Plans cannot be changed after approval.
-- Only one feature can be active at a time.
-- Completion requires passing validation evidence: `targeted` scope for
-  ordinary features, `broad` scope plus a passing final review for the last
-  one.
-- Completion records `featureReviewDepth`; the runtime rejects review evidence
-  that is shallower than the approved feature requires.
-- Failed reviews are bounded: a failed review pauses by default, and autonomous
-  repair is limited to one repair plus one retry before the feature blocks.
+- A different-goal plan save cannot replace an unclosed session, including an
+  unapproved draft. Close it explicitly as `deferred` or `abandoned` and finish
+  archive publication before saving the new goal.
+- Only one feature run can be active at a time; reset preserves its audit
+  history but the next start receives a fresh run id.
+- Reviewer assignment requires source-bound passing validation: `targeted` for
+  feature review and `broad` for final review. A source edit invalidates stale
+  pending review work when its replacement is created.
+- Feature outcome uses a nested `completed` or `blocked` result. Invalid or stale
+  input records nothing and does not consume its operation id.
+- Each OpenCode handler validates the registered nested schema again at entry;
+  invalid host invocations fail as tool errors before Flow state I/O.
+- The runtime derives review depth from the approved plan and owns assignment,
+  attempt, logical-pass, packet, source, and start-time identity.
+- Failed reviews are bounded: an accepted blocker returns operation status
+  `ok`, and autonomous repair is limited to one repair plus one retry before
+  the feature blocks.
 - Review exhaustion uses the ordinary blocked-feature state; continuing requires
   an explicit `flow_feature_reset`, not a second checkpoint protocol.
+- A passing final feature outcome marks progress completed but leaves closure null;
+  `flow_session_close` exclusively records and archives it.
 - Once a closure is recorded, the session is archive-only. If publication fails,
-  retry `flow_session_close`; no run, reset, approval, or replan can reopen it.
-- A session can close as `completed` only after final completion has passed.
+  compact status supplies `closure.retryOperationId`; retry only with
+  `flow_session_close { request: { mode: "retry", operationId } }`. No new
+  close, run, reset, approval, or replan can reopen or adopt it.
+- A new close operation id must be absent from the active causal chain and every
+  mutation in canonical Session v4 workspace history. Any archived match is a
+  collision; malformed or ambiguous canonical history fails closed before
+  active state changes.
+- Archive publication requires explicit non-null closure. Closureless Session
+  v4 state may remain active, but it is rejected as canonical history and makes
+  canonical lookup fail closed if found there.
+- Every closure is quiescent: no active execution or pending review assignment
+  remains. A session can close as `completed` only after the final feature
+  outcome has passed.
+- Actor-reported validation and review times must follow run, validation, and
+  assignment order and cannot postdate the runtime acceptance time.
 - Session locks fail closed: Flow never guesses that an old lock is abandoned,
-  and only the unique owner may release it. Unreadable session files are
-  quarantined with recovery guidance, never silently deleted.
+  and only the unique owner may release it. Only a valid Session v4 document can
+  become active state; canonical history additionally requires explicit
+  non-null closure.
 - Flow writes `.flow/.gitignore` so session state stays out of Git by default.
 - `.flow/session.json` is the only active-state representation. Canonical Flow
   commands call `flow_status` before acting; plugin configuration does not read,
@@ -166,7 +219,7 @@ see
 For broad implementation, the manager records whether work stayed serial,
 used exact-path candidate workers, used isolated worktrees, ran a tournament, or
 skipped eligible candidates. Feature completion can carry bounded
-`orchestrationPasses` with candidate eligibility, decision, and structured
+`result.orchestrationPasses` with candidate eligibility, decision, and structured
 factors. Bounded projections report the relevant aggregate while full worker
 handoffs remain outside `.flow/**`.
 
@@ -182,7 +235,7 @@ or sync command is required. To preview recoverable migration of pristine v4
 global skill folders:
 
 ```bash
-npx -y opencode-plugin-flow@5.1.1 legacy-cleanup --dry-run
+npx -y opencode-plugin-flow@5.2.0 legacy-cleanup --dry-run
 ```
 
 ## Development

package/dist/application/errors.d.ts

@@ -3,3 +3,8 @@ export declare class UnreadableFlowSessionError extends Error {
     readonly reason: string;
     constructor(message: string, reason: string);
 }
+export declare class UnsupportedFlowSessionVersionError extends Error {
+    readonly code = "UNSUPPORTED_FLOW_SESSION_VERSION";
+    readonly actualVersion: unknown;
+    constructor(actualVersion: unknown);
+}