opencode-plugin-flow 6.5.0 → 6.6.0

package/CHANGELOG.md

@@ -6,6 +6,36 @@ One short entry per release, written for users deciding whether to upgrade.
 
 No changes yet.
 
+## [6.6.0] - 2026-07-22
+
+Projection-guided recovery lore makes Flow's next step easier to understand
+without adding persisted diagnostics or more orchestration:
+
+- `/flow-run` now follows one ordered compact-status route, handles idle and
+  planning entry explicitly, and refreshes execution state before dispatching a
+  recovered reviewer assignment so stale work is reset rather than redispatched.
+- Status failures report the exact summary and optional recovery guidance.
+  Post-review uncertainty no longer incorrectly claims that no lifecycle
+  mutation occurred.
+- Blocked-review handoffs now explain attempts, recurring and new findings,
+  validation evidence, Flow-reported artifacts, completed and untouched work,
+  the exact next action, and whether another repair attempt needs authorization.
+  `/flow-status` obtains that evidence through one detail read.
+- Typed status, execution, reviewer, detail, delivery, operation, and close
+  recovery projections replace broad record casts. Accepted archive retry,
+  accepted manual recovery, unconfirmed replay, and archive lookup collision
+  remain distinct without changing Session v5 or persisted state.
+- OpenCode tool serialization preserves those specialized response types while
+  requiring every handler to return the Flow response envelope. Expanded prompt,
+  runtime, close-recovery, and integration tests cover the contracts; the
+  failed-review retry boundary and bounded worker waves remain unchanged.
+
+Install or update:
+
+```bash
+opencode plugin opencode-plugin-flow@6.6.0 --global --force
+```
+
 ## [6.5.0] - 2026-07-22
 
 Convergence-safe recovery lore makes long Flow sessions easier to trust

package/README.md

@@ -21,11 +21,11 @@ into the active goal.
 Install the exact npm release through OpenCode:
 
 ```bash
-opencode plugin opencode-plugin-flow@6.5.0 --global --force
+opencode plugin opencode-plugin-flow@6.6.0 --global --force
 ```
 
 Omit `--global` for project scope. Exact version pins do not update
-automatically. To update, replace `6.5.0` with the new release and rerun the
+automatically. To update, replace `6.6.0` with the new release and rerun the
 command.
 
 Before upgrading from Flow v5 or earlier, finish or explicitly close any active
@@ -43,7 +43,7 @@ The equivalent manual project configuration is:
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-plugin-flow@6.5.0"]
+  "plugin": ["opencode-plugin-flow@6.6.0"]
 }
 ```
 

package/dist/index.js

@@ -328,47 +328,63 @@ independent review and submits its own result.
 ## Start and scope
 
 1. Call \`flow_status { request: { view: "compact" } }\` first. Treat
-   \`nextAction\` as the durable default workflow direction, not as a permission
-   grant.
-2. If compact status contains \`archiveRetry\`, call \`flow_session_close\` once
-   with that projected request byte-for-byte. Report \`workflowData.delivery\`;
-   if archive publication still fails, refresh compact status. This exact
-   cleanup grants no new work, so it precedes goal alignment. Stop after the
-   cleanup outcome either way.
-3. Before any other manager-owned lifecycle mutation, align the compact-projected
-   goal with the current direct \`/flow-run\` request. Continue only for the same
-   goal or a compatible narrowing. Compatible narrowing changes method or
-   emphasis only; it must not add, drop, reorder, or weaken an approved
-   requirement or feature outcome. A completed-but-unclosed session must close
-   as completed before a new request proceeds. Otherwise, for materially new
-   or expanded work, perform no mutation, say the request has not started, and
-   offer to continue the active goal, defer it, or abandon it. Keep this
-   comparison conversational; create no classifier or state.
-4. If compact status is \`completed\`, call \`flow_session_close\` once with its
-   session id and revision, a fresh operation id, and \`kind: "completed"\`.
-   Report \`workflowData.delivery\`. If archive publication is unconfirmed,
-   follow the projected \`archiveRetry\` once byte-for-byte and stop on any
-   remaining failure. Then stop. A materially new request can enter the
-   appropriate Flow planning route afterward; do not fabricate a run.
-5. If compact status is already \`blocked\`, load
-   \`flow_status { request: { view: "detail" } }\` exactly once before any reset.
-   Apply the retry and checkpoint rule under **Review and record**. If it permits
-   a fresh run, call \`flow_feature_reset\`, refresh compact status, and continue
-   this invocation. Otherwise report the checkpoint and stop.
-6. If compact status is \`running\` and \`nextAction\` is \`flow_feature_reset\`, the
-   pending review is source-stale. Call \`flow_feature_reset\`, refresh compact
-   status, and continue with a fresh run. Do not redispatch that assignment.
-7. If compact status is \`running\` and \`nextAction\` is
-   \`dispatch-flow-reviewer\`, skip run start, implementation, and validation;
-   continue at **Review and record** with the existing pending assignment.
-8. A durable \`nextAction\` can still be rejected after status by an
-   environment-sensitive guard. On rejection, refresh compact status and
-   handle the exact error instead of forcing a stale action.
-9. Call \`flow_run_start\` when a ready feature is not already running.
-10. Read \`flow_status { request: { view: "execution" } }\` and use that
-   projection as the active scope and source of revision guards.
-11. Read the feature summary, targets, validation, dependencies, requirements,
-   and decisions before editing.
+   \`nextAction\` as the durable default workflow direction, not as permission.
+2. If the top-level response status is \`error\`, report its exact summary and
+   recovery when present. State that this initial read made no lifecycle, Git,
+   or release mutation, and stop. Do not route an error projection's
+   \`nextAction\` as feature recovery.
+3. If compact status contains \`archiveRetry\`, call \`flow_session_close\` once
+   with that projected request byte-for-byte and report
+   \`workflowData.delivery\`. If archive publication remains unconfirmed, refresh
+   compact status. Stop after this cleanup outcome either way; it grants no new
+   work and therefore precedes goal alignment.
+4. When the projection contains an active goal, align it with the current
+   direct \`/flow-run\` request before any other manager-owned lifecycle mutation.
+   Continue only for the same goal or a compatible narrowing. Compatible
+   narrowing may change method or emphasis, but must not add, drop, reorder, or
+   weaken an approved requirement or feature outcome. A completed-but-unclosed
+   session must close as completed before a new request proceeds. For other
+   materially new or expanded work, make no mutation, say the request has not
+   started, and offer to continue the active goal, defer it, or abandon it.
+   Keep this comparison conversational; add no classifier or state.
+5. If status is \`idle\` or \`planning\`, report its projected planning action,
+   explain that \`/flow-run\` requires an approved feature, and stop without
+   mutation.
+
+Route every other compact projection in this order:
+
+- \`flow_session_close\`: close a completed session with its projected session id
+  and revision, a fresh operation id, and \`kind: "completed"\`. Report
+  \`workflowData.delivery\`, follow one projected exact \`archiveRetry\` if needed,
+  and stop. A materially new request can enter Flow planning afterward; do not
+  fabricate a run.
+- Blocked \`await-user-direction\` or blocked \`flow_feature_reset\`: call
+  \`flow_status { request: { view: "detail" } }\` exactly once before any reset,
+  then apply **Blocked review** below. If it permits a fresh run, reset, refresh
+  compact status, and route again; otherwise report the checkpoint and stop.
+- Running \`flow_feature_reset\`: the pending review is source-stale. Reset,
+  refresh compact status, and route again. Never redispatch that assignment.
+- \`dispatch-flow-reviewer\`: read execution status. If that read errors, report
+  its exact summary and recovery when present and stop without dispatching; do
+  not infer a projection. Otherwise route that refreshed projection before
+  acting. Dispatch the recovered pending assignment under **Review and record**
+  only if \`nextAction\` is still \`dispatch-flow-reviewer\`. If it is now running
+  \`flow_feature_reset\`, follow the source-stale reset route and never dispatch
+  that assignment. Skip run start, implementation, and validation.
+- \`flow_run_start\`: start the ready feature, refresh compact status, and read
+  execution status.
+- \`flow_validation_start\`: read execution status and resume integration or
+  validation from the current worktree.
+- \`flow_review_start\`: read execution status and continue at **Review and
+  record** without fabricating another validation.
+- Any other action: report it and stop unless the runtime explicitly identifies
+  an active execution path.
+
+Use execution status as the active scope and source of revision guards. Read
+the feature summary, targets, validation, dependencies, requirements, and
+decisions before editing. A projected action may still fail an
+environment-sensitive guard; refresh compact status and handle that exact
+rejection instead of forcing the stale action.
 
 Preserve unrelated worktree changes and stay inside the active feature. Leave
 changes owned by another planned feature for that feature. If implementation
@@ -483,35 +499,39 @@ verdict. The reviewer reads its assignment, inspects the workspace, and calls
 reviewer remains workspace-read-only and may make only this exact result
 submission as its sole lifecycle mutation.
 
-After the reviewer returns, read compact status rather than treating prose as
-the outcome. If it records a blocked outcome, immediately load
-\`flow_status { request: { view: "detail" } }\` exactly once for the handoff or
-checkpoint. Redispatch the same pending assignment after interruption or an
-unconfirmed reviewer return only while compact status is \`running\` and
-\`nextAction\` is \`dispatch-flow-reviewer\`. If status remains \`running\` with that
-pending assignment and \`nextAction\` is \`flow_feature_reset\`, or submission
-reports \`Workspace content changed after review started\`, call
-\`flow_feature_reset\` and do not redispatch the source-stale assignment; start a
-fresh run and repeat full validation and review. Never fabricate a verdict. A
-submitted pass completes the feature; a submitted blocking finding records a
-blocked outcome.
-
-Use compact \`blockedFeature.failedReviewCount\` and that one detail projection
-together. A \`[scope-blocker]\` checkpoints immediately and must not reset
-automatically. Otherwise treat the first recorded failed review as in-scope;
-when implementation is already authorized, it may receive one automatic
-\`flow_feature_reset\`. Fix only its blocking findings, then repeat full
-validation and full review in a fresh run. A second recorded failed review
-awaits explicit user direction; report recurring and new blockers, possible
-feature mis-sizing, and any repair that would exceed approved scope while
-remaining inside Flow. A current aligned request counts as direction only when
-it explicitly authorizes one additional attempt. If that review fails,
-checkpoint again.
-
-Read compact status after every recorded outcome. When invoked directly through
-\`/flow-run\`, report that one feature's outcome and \`nextAction\`, then stop. When
-the active driver is \`/flow-auto\`, return to its loop so it can start the next
-feature, report a blocker, or close the completed session.
+After dispatch, read compact status rather than trusting reviewer prose. If the
+top-level response is an error, report its exact summary and recovery when
+present, say the latest lifecycle state could not be confirmed, and stop
+without further mutation. Do not claim this invocation made no lifecycle
+mutation: it may already have started review or recorded a reviewer result.
+Never invent or submit a verdict. If status remains running, apply the
+\`dispatch-flow-reviewer\` or running \`flow_feature_reset\` route above. If status
+is blocked, load detail through the single blocked route above. A recorded pass
+completes the feature.
+
+### Blocked review
+
+Use compact \`blockedFeature.failedReviewCount\` with that one detail projection.
+
+- A \`[scope-blocker]\` checkpoints immediately. Do not reset automatically.
+- On the first ordinary failed review, existing implementation authority
+  permits one automatic \`flow_feature_reset\`. Fix only its blocking findings,
+  then run full validation and full independent review in a fresh run.
+- After the second failed review, reset only when the current aligned request
+  explicitly authorizes one additional attempt. If that attempt fails,
+  checkpoint again.
+
+When stopping blocked, label the result overall incomplete. Report what the
+latest repair fixed; recurring and new blocking findings; the goal and progress;
+the blocked feature, attempt, and failure count; completed and untouched
+features; latest validations and \`artifactsChanged\` as Flow-reported artifact
+evidence; Git and release mutation status; whether the current request started,
+mapped to the active goal, or was held; the exact \`nextAction\`; and whether
+another attempt requires explicit authorization.
+
+Use that already-loaded compact status after every recorded outcome. Direct
+\`/flow-run\` reports this one feature's cumulative outcome and \`nextAction\`, then
+stops. Under \`/flow-auto\`, return to its lifecycle loop.
 `;
 
 // src/guidance/ids.ts
@@ -618,7 +638,16 @@ function compileFlowPromptSurface(surface) {
     case "flow-run":
       return managerCommand(surface);
     case "flow-status":
-      return 'Call `flow_status { request: { view: "compact" } }` and report the runtime projection plus its durable default next action. Do not mutate. For a first blocked review, say that `/flow-run` must read detail before reset because a `[scope-blocker]` may refine that default.';
+      return [
+        'Call `flow_status { request: { view: "compact" } }` first.',
+        "Do not mutate.",
+        "If the top-level response status is `error`, report its exact summary and `workflowData.failure.recovery` when present; otherwise say no recovery guidance was supplied. State that `/flow-status` made no Git or release mutation, report any lifecycle state effect disclosed by the response, and stop. Do not interpret recovery guidance as a blocked review.",
+        'If `projection.status` is `blocked`, call `flow_status { request: { view: "detail" } }` exactly once and label the result overall incomplete.',
+        "From that detail projection, report the goal and progress; blocked feature, attempt, `failedReviewCount`, and findings; completed and untouched features; validations and `artifactsChanged` as Flow-reported artifact evidence; and the exact `nextAction`.",
+        "For a blocked first failed review, explain that `flow_feature_reset` is only the default and `/flow-run` must inspect any `[scope-blocker]` before reset.",
+        "For blocked `await-user-direction`, explain that another attempt requires explicit user direction.",
+        "Otherwise report the compact projection and its exact `nextAction`, state that `/flow-status` made no lifecycle, Git, or release mutation, and stop."
+      ].join(" ");
     case "flow-review":
       return [
         "# Flow review command",
@@ -2786,17 +2815,18 @@ function ok(summary, workflowData) {
   return {
     status: "ok",
     summary,
-    workflowData: { dataNote: dataNote(), ...workflowData }
+    workflowData: { ...workflowData, dataNote: dataNote() }
   };
 }
 function errorResponse(error, recovery) {
+  const summary = error instanceof Error ? error.message : String(error);
   return {
     status: "error",
-    summary: error instanceof Error ? error.message : String(error),
+    summary,
     workflowData: {
       dataNote: dataNote(),
       failure: {
-        summary: error instanceof Error ? error.message : String(error),
+        summary,
         ...recovery ? { recovery } : {}
       }
     }
@@ -2987,16 +3017,7 @@ function reviewerProjection(session, assignmentId) {
     completedFeatureIds: plan?.features.filter((candidate) => isFeatureComplete(session, candidate.id)).map((candidate) => candidate.id) ?? []
   };
 }
-function project(session, request, pendingReviewSourceStale = false) {
-  if (request.view === "compact") {
-    return compactProjection(session, pendingReviewSourceStale);
-  }
-  if (request.view === "execution") {
-    return executionProjection(session, pendingReviewSourceStale);
-  }
-  if (request.view === "reviewer") {
-    return reviewerProjection(session, request.assignmentId);
-  }
+function detailProjection(session, pendingReviewSourceStale = false) {
   return {
     ...compactProjection(session, pendingReviewSourceStale),
     view: "detail",
@@ -3006,6 +3027,26 @@ function project(session, request, pendingReviewSourceStale = false) {
     operations: session.operations
   };
 }
+function idleProjection(view) {
+  return {
+    view,
+    status: "idle",
+    revision: 0,
+    nextAction: "flow_plan_save"
+  };
+}
+function project(session, request, pendingReviewSourceStale = false) {
+  switch (request.view) {
+    case "compact":
+      return compactProjection(session, pendingReviewSourceStale);
+    case "detail":
+      return detailProjection(session, pendingReviewSourceStale);
+    case "execution":
+      return executionProjection(session, pendingReviewSourceStale);
+    case "reviewer":
+      return reviewerProjection(session, request.assignmentId);
+  }
+}
 
 // src/application/session-close.ts
 async function loadExactArchivedClose(transaction, request) {
@@ -3041,18 +3082,19 @@ function successfulCloseResponse(session, request, replayed, summary) {
 }
 function archivePendingResponse(error, session, request, replayed) {
   const failure = error instanceof Error ? error.message : String(error);
+  const closeState = {
+    durableAccepted: true,
+    archiveConfirmed: false,
+    retryExactRequest: true,
+    retryRequest: request
+  };
   return {
     status: "error",
     summary: "Session close was durably accepted, but archive publication was not confirmed.",
     workflowData: {
       dataNote: dataNote(),
       operation: operationResult(session, request.operationId, replayed, session.closure),
-      closeState: {
-        durableAccepted: true,
-        archiveConfirmed: false,
-        retryExactRequest: true,
-        retryRequest: request
-      },
+      closeState,
       projection: compactProjection(session),
       delivery: deliveryProjection(session),
       failure: {
@@ -3078,19 +3120,35 @@ function manualRecoveryProjection(projection) {
   };
 }
 function archiveCollisionResponse(error, session, request, replayed, durableAccepted = true) {
+  const operation = operationResult(session, request.operationId, replayed, session.closure);
+  const projection = manualRecoveryProjection(compactProjection(session));
+  const failure = {
+    summary: error.message,
+    recovery: "Preserve both active and archived state, inspect the collision, and do not overwrite or delete either document automatically."
+  };
+  if (durableAccepted) {
+    return {
+      status: "error",
+      summary: "Session close was durably accepted, but conflicting Flow state requires manual recovery.",
+      workflowData: {
+        dataNote: dataNote(),
+        operation,
+        closeState: manualRecoveryCloseState(true),
+        projection,
+        delivery: deliveryProjection(session),
+        failure
+      }
+    };
+  }
   return {
     status: "error",
-    summary: durableAccepted ? "Session close was durably accepted, but conflicting Flow state requires manual recovery." : "Session close replay could not confirm durable active state; manual recovery is required.",
+    summary: "Session close replay could not confirm durable active state; manual recovery is required.",
     workflowData: {
       dataNote: dataNote(),
-      operation: operationResult(session, request.operationId, replayed, session.closure),
-      closeState: manualRecoveryCloseState(durableAccepted),
-      projection: manualRecoveryProjection(compactProjection(session)),
-      ...durableAccepted ? { delivery: deliveryProjection(session) } : {},
-      failure: {
-        summary: error.message,
-        recovery: "Preserve both active and archived state, inspect the collision, and do not overwrite or delete either document automatically."
-      }
+      operation,
+      closeState: manualRecoveryCloseState(false),
+      projection,
+      failure
     }
   };
 }
@@ -3117,11 +3175,13 @@ function archiveLookupCollisionResponse(error, request) {
     workflowData: {
       dataNote: dataNote(),
       closeState: manualRecoveryCloseState(false),
-      projection: manualRecoveryProjection({
+      projection: {
         view: "compact",
         sessionId: request.sessionId,
-        status: "unknown"
-      }),
+        status: "unknown",
+        nextAction: "await-user-direction",
+        archiveRetry: null
+      },
       failure: {
         summary: error.message,
         recovery: "Preserve active and archived state, inspect the requested archive, and do not overwrite or delete either document automatically."
@@ -3214,12 +3274,7 @@ function createFlowService(repository, environment) {
         const session = await repository.read();
         if (!session) {
           return ok("No active Flow session.", {
-            projection: {
-              view: request.view,
-              status: "idle",
-              revision: 0,
-              nextAction: "flow_plan_save"
-            }
+            projection: idleProjection(request.view)
           });
         }
         if (request.view !== "reviewer" && (activePendingReview(session) || session.closure)) {
@@ -3227,12 +3282,7 @@ function createFlowService(repository, environment) {
             const current = await transaction.load();
             if (!current) {
               return ok("No active Flow session.", {
-                projection: {
-                  view: request.view,
-                  status: "idle",
-                  revision: 0,
-                  nextAction: "flow_plan_save"
-                }
+                projection: idleProjection(request.view)
               });
             }
             const collisionResponse = await closedArchiveCollisionStatus(transaction, current, request);
@@ -3558,7 +3608,11 @@ var SessionCloseArgs = {
   }).strict()
 };
 function json(value) {
-  return JSON.stringify(value, null, 2);
+  const serialized = JSON.stringify(value, null, 2);
+  if (serialized === undefined) {
+    throw new Error("Flow tool response could not be serialized.");
+  }
+  return serialized;
 }
 function toolError(error) {
   return json({
@@ -3912,4 +3966,4 @@ export {
   plugin_default as default
 };
 
-//# debugId=2A3C0C87419414A064756E2164756E21
+//# debugId=D5A6EFA1B223B77864756E2164756E21