opencode-plugin-flow 6.3.0 → 6.4.0

package/CHANGELOG.md

@@ -6,6 +6,56 @@ One short entry per release, written for users deciding whether to upgrade.
 
 No changes yet.
 
+## [6.4.0] - 2026-07-21
+
+Continuous-flow lore keeps an authorized goal inside Flow while preserving the
+small, single-run architecture:
+
+- `/flow-auto` is the normal end-to-end driver. An active session remains
+  authoritative until explicit completed, deferred, or abandoned closure, and
+  existing implementation authority carries across plan approval, feature
+  outcomes, qualifying worker waves, and in-scope failed-review repair.
+- Direct `/flow-run` remains a one-feature advanced or recovery control. Work
+  stays inside the active feature, serial execution remains the default, and
+  bounded parallel waves still add no scheduler, durable wave state, telemetry,
+  or concurrent active features.
+- Reviewers now receive every applicable passing validation while final review
+  still requires a broad gate. Reviewer guidance explicitly permits
+  workspace-local non-shell inspection, removing an ambiguity that could block
+  valid reviews.
+- Deterministic coverage now exercises concurrent completion replay,
+  configuration collisions and warnings, the documented 1-through-1000 review
+  step range, temporary-workspace cleanup, and release-version derivation.
+- Real-provider evidence completed an overlapping two-worker wave, a serial
+  integration feature, failed-review reset and repair, and ten ordinary
+  `/flow-auto` sessions through explicit closure.
+
+Install or update:
+
+```bash
+opencode plugin opencode-plugin-flow@6.4.0 --global --force
+```
+
+## [6.3.1] - 2026-07-21
+
+Read-only retry lore closes the recovery and documentation gaps in 6.3.0:
+
+- While Session v5 remains active, every caller with tool access now receives an
+  exact accepted completion through the read-only replay path before a new
+  reviewer submission is considered. Reviewer retries no longer cancel
+  validation capture or write session state.
+- Replay documentation now states the active Session v5 boundary, and release
+  language accurately describes secret avoidance as manager guidance rather
+  than runtime filtering or redaction.
+- The documentation contract keeps the rolling `Unreleased` changelog heading
+  without requiring its contents to remain `No changes yet.`
+
+Install or update:
+
+```bash
+opencode plugin opencode-plugin-flow@6.3.1 --global --force
+```
+
 ## [6.3.0] - 2026-07-21
 
 Reviewer-owned submission lore strengthens independent review without turning
@@ -20,8 +70,8 @@ Flow back into a heavy orchestration framework:
   revalidation, and fingerprint failures fail closed with repair guidance.
 - Final reviewers receive the approved plan targets and validation intent,
   completed feature IDs, and only assignment-linked evidence. Broad validation
-  is treated as a coverage claim; durable commands exclude secrets, and raw
-  output is reduced to completeness plus a digest.
+  is treated as a coverage claim; manager guidance warns against putting secrets
+  in durable commands, and raw output is reduced to completeness plus a digest.
 - Closed-world permission tests and the pinned OpenCode host smoke cover every
   registered Flow tool. Documentation distinguishes lifecycle mutation from
   fail-closed quarantine maintenance.

package/README.md

@@ -11,16 +11,20 @@ Flow keeps one durable active feature run at a time. When implementation divides
 cleanly, the manager may ask a small host-native worker cohort to contribute in
 parallel before it validates and reviews the combined result.
 
+Once a Flow session starts, it remains the workflow for that goal until Flow
+records completed, deferred, or abandoned closure. It never silently falls back
+to ordinary non-Flow coding.
+
 ## Install
 
 Install the exact npm release through OpenCode:
 
 ```bash
-opencode plugin opencode-plugin-flow@6.3.0 --global --force
+opencode plugin opencode-plugin-flow@6.4.0 --global --force
 ```
 
 Omit `--global` for project scope. Exact version pins do not update
-automatically. To update, replace `6.3.0` with the new release and rerun the
+automatically. To update, replace `6.4.0` with the new release and rerun the
 command.
 
 Before upgrading from Flow v5 or earlier, finish or explicitly close any active
@@ -32,7 +36,7 @@ The equivalent manual project configuration is:
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-plugin-flow@6.3.0"]
+  "plugin": ["opencode-plugin-flow@6.4.0"]
 }
 ```
 
@@ -53,9 +57,11 @@ Start a complete workflow:
 Flow inspects the worktree, proposes a feature plan, and asks for approval
 unless your request already authorized implementation. It then runs one
 runnable feature at a time, validates the actual workspace, obtains an
-independent review, and repeats until it can close the session.
+independent review, and repeats until it can close the session. Existing
+implementation authority carries across approval, feature outcomes, and
+in-scope failed-review repairs; Flow does not ask for the same permission again.
 
-For more control, plan first:
+For plan-only or advanced use, plan first:
 
 ```text
 /flow-plan add rate limiting to the public API
@@ -63,9 +69,10 @@ For more control, plan first:
 
 Review the proposed plan and approve it conversationally. `/flow-plan` does not
 silently grant permission to implement, commit, push, or publish. After
-approval, use `/flow-run` to run or resume one feature.
+approval of a plan-only request, `/flow-run` can run or recover one feature.
 
-At any point, `/flow-status` reports the durable state and next action.
+`/flow-run` and `/flow-status` are advanced/recovery controls. At any point,
+`/flow-status` reports the durable state and next action.
 
 ## How Flow works
 
@@ -86,7 +93,8 @@ action after a restart or context change.
 Parallel contribution is optional and local to one active feature. The manager
 may launch two or three `flow-worker` instances only for exact,
 non-overlapping slices, then inspect and integrate their work. At most one
-targeted follow-up wave may address a concrete gap.
+targeted follow-up wave may address a concrete gap. Once implementation is
+authorized, a qualifying wave needs no separate approval.
 
 Workers cannot delegate, call Flow lifecycle tools, or approve their own work.
 Flow persists no wave state: the manager remains responsible for the combined
@@ -97,20 +105,20 @@ integration-heavy tasks stay serial.
 
 | Command | Purpose |
 | --- | --- |
-| `/flow-auto <goal>` | Drive the authorized lifecycle; stop after planning if implementation was not authorized. |
-| `/flow-plan <goal>` | Create, revise, or approve a plan through conversation. |
-| `/flow-run` | Run or resume one approved feature. |
+| `/flow-auto <goal>` | Normal end-to-end driver for the authorized lifecycle; stop after planning if implementation was not authorized. |
+| `/flow-plan <goal>` | Plan-only/advanced creation, revision, and approval. |
+| `/flow-run` | Advanced/recovery execution of one approved feature. |
 | `/flow-review` | Internal/recovery dispatch for a runtime-created reviewer assignment. |
-| `/flow-status` | Inspect the active session and next action. |
+| `/flow-status` | Advanced/recovery inspection of the active session and next action. |
 
-Ordinary workflows start with `/flow-auto`, `/flow-plan`, `/flow-run`, or
-`/flow-status`. `/flow-review` remains public for runtime dispatch and recovery,
-but it is not an ordinary starting point.
+Use `/flow-auto` for the ordinary end-to-end workflow. The other commands expose
+plan-only, advanced, internal, or recovery controls.
 
 ## Recovery
 
-Start with `/flow-status`; its next action is authoritative. Do not hand-edit
-`.flow/session.json` to bypass a gate. If validation, review, locking,
+Start with `/flow-status`; its next action is authoritative workflow state, not
+permission to exceed the user's authority. Do not hand-edit `.flow/session.json`
+to bypass a gate. If validation, review, locking,
 fingerprinting, or archive publication fails, follow the focused steps in
 [troubleshooting](docs/troubleshooting.md).
 

package/dist/index.js

@@ -1,12 +1,14 @@
 // skills/flow/SKILL.md
 var SKILL_default = `---
 name: flow
-description: Manage a Flow goal from planning through implementation, validation, independent review, and closure. Use for end-to-end or resumed Flow work; use flow-plan for plan-only work and flow-run for one approved feature.
+description: Drive a Flow goal from planning through implementation, validation, independent review, and explicit closure. Use flow-auto as the normal end-to-end interface; use flow-plan for plan-only work and flow-run or flow-status for advanced recovery.
 ---
 
 # Flow
 
-Flow is a small state ledger around ordinary coding work. The root manager owns
+Flow is a small state ledger around coding work. An active Flow session is
+authoritative for its goal until completed, deferred, or abandoned closure; do
+not silently fall back to ordinary non-Flow coding. The root manager owns
 the session, integration, validation, review dispatch, reset, closure, and every
 lifecycle mutation except review submission. Bounded \`flow-worker\`
 instances may contribute disjoint work inside the active feature. The reserved
@@ -17,7 +19,9 @@ lifecycle mutation.
 ## Route from status
 
 1. Call \`flow_status { request: { view: "compact" } }\` first. Trust its
-   projection over conversation memory.
+   projection over conversation memory. Treat \`nextAction\` as authoritative
+   workflow state, not permission to exceed or a reason to discard existing
+   user authority.
 2. If there is no session or the plan is still a draft, call
    \`flow_guidance { id: "flow-plan" }\` and follow that contract. Stop after
    planning when the user asked for a plan only.
@@ -25,8 +29,15 @@ lifecycle mutation.
    \`flow_guidance { id: "flow-run" }\` and follow that contract for exactly that
    feature.
 4. After the feature outcome, read compact status again. Start the next ready
-   feature, report the real blocker, or close a completed session with one
-   \`flow_session_close\` request.
+   feature, repair an in-scope failed review, report a real blocker, or close a
+   completed session with one \`flow_session_close\` request.
+
+Within existing implementation authority, continue after approval, every
+feature outcome, and an in-scope failed-review reset and repair without asking
+again. Pause only for a material product or scope choice, missing authority for
+an external Git or release action, a hard operational failure, or the user's
+explicit selection of deferred or abandoned closure. Only the user may choose
+either non-completed closure kind.
 
 Core contracts are bundled in the plugin; load them through \`flow_guidance\` and
 do not depend on native skill discovery. If a required Flow tool is unavailable,
@@ -34,8 +45,10 @@ report that the plugin is not fully loaded instead of simulating state changes.
 
 ## Invariants
 
-- Approved plans do not change. Reset affected work or close the session before
-  changing direction.
+- Approved plans do not change. If implementation requires material scope
+  outside the plan, stop editing. Finish the approved plan or have the user
+  explicitly choose deferred or abandoned closure before starting a new plan;
+  do not replan in place.
 - Only one durable feature run is active at a time. Conversation-local worker
   waves do not create additional runs or Flow state.
 - Work stays inside the active feature and preserves unrelated user changes.
@@ -141,14 +154,15 @@ description: Independently review one runtime-owned Flow assignment. Reserved fo
 # Flow Review
 
 You are the independent \`flow-reviewer\`. Review the assigned work; do not fix
-it. You may read relevant files and supplied evidence, but must not edit files,
-read outside the workspace, run commands, or launch workers. You may call only
-\`flow_status\` to read this assignment and \`flow_feature_complete\` to submit its
-exact result. The latter is your sole lifecycle mutation.
+it. Use workspace-local, non-shell inspection tools to read relevant files and
+supplied evidence, but do not edit files, read outside the workspace, run
+commands, or launch workers. Among Flow lifecycle tools, call only \`flow_status\`
+to read this assignment and \`flow_feature_complete\` to submit its exact result.
+The latter is your sole lifecycle mutation.
 
 ## Recover the assignment
 
-When given an assignment id, call only
+When given an assignment id, first call
 \`flow_status { request: { view: "reviewer", assignmentId: "..." } }\`. Use its
 bounded packet, assignment-linked validations, approved-plan context, and
 completed feature IDs instead of reconstructing feature, source,
@@ -231,7 +245,7 @@ a reason to lower the bar.
 // skills/flow-run/SKILL.md
 var SKILL_default4 = `---
 name: flow-run
-description: Implement, validate, independently review, and record one approved Flow feature. Use only after a Flow plan is approved.
+description: Implement, validate, independently review, and record one approved Flow feature. Use after plan approval as an advanced or recovery control; flow-auto is the normal end-to-end driver.
 ---
 
 # Flow Run
@@ -244,17 +258,21 @@ independent review and submits its own result.
 
 ## Start and scope
 
-1. Call \`flow_status { request: { view: "compact" } }\` first.
+1. Call \`flow_status { request: { view: "compact" } }\` first. Treat
+   \`nextAction\` as authoritative workflow state, not as a permission grant.
 2. Call \`flow_run_start\` when a ready feature is not already running.
 3. Read \`flow_status { request: { view: "execution" } }\` and use that
    projection as the active scope and source of revision guards.
 4. Read the feature summary, targets, validation, dependencies, requirements,
    and decisions before editing.
 
-Preserve unrelated worktree changes. Stop and replan when implementation needs
-material scope outside the active feature. Use \`flow_feature_reset\` when a
-wrong design or invalid assumption requires a fresh run; do not layer a retry
-onto a bad execution.
+Preserve unrelated worktree changes and stay inside the active feature. Leave
+changes owned by another planned feature for that feature. If implementation
+needs material scope outside the approved plan, stop editing. Finish the
+approved plan or have the user explicitly choose deferred or abandoned closure
+before starting a new plan; never replan the active approved session in place.
+Use \`flow_feature_reset\` when a wrong design or invalid assumption requires a
+fresh run within the active feature; do not layer a retry onto a bad execution.
 
 ## Implement
 
@@ -268,8 +286,10 @@ that separate action.
 
 ## Bounded worker waves
 
-Work serially by default. After manager orientation, fan out only when at least
-two genuinely independent slices can be named. Run one cohort of two or three
+Work serially by default. Existing implementation authority covers a qualifying
+worker wave; do not ask for separate approval. After manager orientation, fan
+out only when two or three genuinely independent, non-overlapping slices can be
+named and parallel execution has clear benefit. Run one cohort of two or three
 \`flow-worker\` instances at a time. Issue every cohort Task call in the same
 assistant tool-use turn before consuming any result. If the host or model
 serializes those calls, treat and report that execution as serial instead of
@@ -320,6 +340,12 @@ secrets. Raw output is deliberately neither persisted nor projected: the
 durable evidence is the command, exit code, output completeness, and output
 digest, while the manager must inspect the live output.
 
+Every host-observed validation advances the session revision through the
+after-hook. Immediately refresh
+\`flow_status { request: { view: "compact" } }\` after the command and before the
+next \`flow_validation_start\` or \`flow_review_start\` mutation; the revision used
+to arm the command is stale.
+
 Use focused validation for ordinary features. For the final feature, run the
 repository's broad applicable gate after the last relevant edit. A source edit
 invalidates earlier applicability. Failed or unavailable checks are blockers,
@@ -352,11 +378,14 @@ 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.
 
-If repair is authorized after a failed review, reset the feature, fix it, and
-repeat full validation and full review in a fresh run.
+When implementation is already authorized, an in-scope failed review needs no
+new permission: reset the feature, fix it, and repeat full validation and full
+review in a fresh run.
 
-Read compact status after every recorded outcome. Follow runtime state to start
-the next feature, report a blocker, or close the completed session.
+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.
 `;
 
 // src/guidance/ids.ts
@@ -525,17 +554,17 @@ var FLOW_CORE_AGENTS = {
 };
 var FLOW_CORE_COMMANDS = {
   "flow-auto": {
-    description: "Drive the authorized Flow lifecycle",
+    description: "Drive one authorized Flow goal end to end",
     subtask: false,
     template: compileFlowPromptSurface("flow-auto")
   },
   "flow-plan": {
-    description: "Create or approve a Flow plan",
+    description: "Plan-only or advanced Flow planning",
     subtask: false,
     template: compileFlowPromptSurface("flow-plan")
   },
   "flow-run": {
-    description: "Run one approved Flow feature",
+    description: "Advanced or recovery execution of one Flow feature",
     subtask: false,
     template: compileFlowPromptSurface("flow-run")
   },
@@ -546,7 +575,7 @@ var FLOW_CORE_COMMANDS = {
     template: compileFlowPromptSurface("flow-review")
   },
   "flow-status": {
-    description: "Inspect the active Flow session",
+    description: "Advanced or recovery inspection of Flow state",
     subtask: false,
     template: compileFlowPromptSurface("flow-status")
   }
@@ -559,7 +588,7 @@ function reviewerSteps(env, onWarning) {
   const raw = envValue(env, "OPENCODE_FLOW_REVIEWER_STEPS");
   if (!raw)
     return;
-  if (!/^[1-9][0-9]{0,2}$/.test(raw) || Number(raw) > 1000) {
+  if (!/^[1-9][0-9]*$/.test(raw) || Number(raw) > 1000) {
     onWarning?.("OPENCODE_FLOW_REVIEWER_STEPS must be an integer from 1 through 1000; ignoring it.");
     return;
   }
@@ -1087,8 +1116,9 @@ function startReview(session, input, environment) {
     fail("Reset the feature before starting another full review.");
   }
   const kind = isFinalFeatureRun(session, run) ? "final" : "feature";
-  const applicable = run.validations.filter((validation) => validation.exitCode === 0 && validation.outputComplete && validation.sourceDigest === input.sourceDigest && (kind === "feature" || validation.scope === "broad"));
-  if (applicable.length === 0) {
+  const applicable = run.validations.filter((validation) => validation.exitCode === 0 && validation.outputComplete && validation.sourceDigest === input.sourceDigest);
+  const hasRequiredValidation = kind === "feature" ? applicable.length > 0 : applicable.some((validation) => validation.scope === "broad");
+  if (!hasRequiredValidation) {
     fail(kind === "final" ? "Final review requires passing broad validation for the current workspace content." : "Review requires passing validation for the current workspace content.");
   }
   const assignmentId = environment.newId("review");
@@ -2672,6 +2702,17 @@ function featureCompleteResponse(session, request, run, replayed) {
     projection: compactProjection(session)
   });
 }
+function exactFeatureCompleteReplay(session, request) {
+  const priorOperation = session.operations.find((operation) => operation.id === request.operationId);
+  if (priorOperation?.kind !== "feature-complete" || priorOperation.inputDigest !== operationInputDigest(request)) {
+    return null;
+  }
+  const result = completeFeature(session, request);
+  if (!result.replayed) {
+    throw new Error("Expected an exact feature-completion replay.");
+  }
+  return { session: result.session, run: result.value };
+}
 async function loadExactArchivedClose(transaction, request) {
   const archived = await transaction.loadArchive(request.sessionId);
   const operation = archived?.operations.find((item) => item.id === request.operationId);
@@ -2856,10 +2897,21 @@ function createFlowService(repository, environment) {
     async featureComplete(input) {
       try {
         const request = FeatureCompleteInputSchema.parse(input).request;
+        const current = await repository.read();
+        if (current) {
+          const replay = exactFeatureCompleteReplay(current, request);
+          if (replay) {
+            return featureCompleteResponse(replay.session, request, replay.run, true);
+          }
+        }
         return await repository.transact(async (transaction) => {
           const session = await transaction.load();
           if (!session)
             throw new Error("No active Flow session exists.");
+          const racedReplay = exactFeatureCompleteReplay(session, request);
+          if (racedReplay) {
+            return featureCompleteResponse(racedReplay.session, request, racedReplay.run, true);
+          }
           const priorOperation = session.operations.find((operation) => operation.id === request.operationId);
           if (!priorOperation) {
             const assignment = session.runs.flatMap((run) => run.reviews).find((review) => review.id === request.assignmentId);
@@ -2883,15 +2935,11 @@ function createFlowService(repository, environment) {
         const session = await repository.read();
         if (!session)
           throw new Error("No active Flow session exists.");
-        const priorOperation = session.operations.find((operation) => operation.id === request.operationId);
-        if (priorOperation?.kind !== "feature-complete" || priorOperation.inputDigest !== operationInputDigest(request)) {
+        const replay = exactFeatureCompleteReplay(session, request);
+        if (!replay) {
           throw new Error("Only the Flow reviewer may submit a new feature completion; other agents may replay only an exact previously accepted request.");
         }
-        const result = completeFeature(session, request);
-        if (!result.replayed) {
-          throw new Error("Expected an exact feature-completion replay.");
-        }
-        return featureCompleteResponse(result.session, request, result.value, true);
+        return featureCompleteResponse(replay.session, request, replay.run, true);
       } catch (error) {
         return errorResponse(error);
       }
@@ -3101,11 +3149,11 @@ function executeMutation(context, validation, handler) {
   validation.cancel(context.sessionID);
   return execute(context, handler);
 }
-function executeReviewerMutation(context, validation, handler, replayHandler) {
+function executeReviewerMutation(context, handler, replayHandler) {
   if (context.agent !== "flow-reviewer") {
     return execute(context, replayHandler);
   }
-  return executeMutation(context, validation, handler);
+  return execute(context, handler);
 }
 function createTools(_ctx, options) {
   return {
@@ -3162,9 +3210,9 @@ function createTools(_ctx, options) {
       execute: (args, context) => executeMutation(context, options.validation, (workspace) => flowReviewStart(workspace, args))
     }),
     flow_feature_complete: tool({
-      description: "Submit a pending review result; only the reviewer may create a new completion, while exact accepted requests remain replayable.",
+      description: "Submit a pending review result; only the reviewer may create a new completion, while exact accepted requests remain replayable for an active Session v5 workflow.",
       args: FeatureCompleteArgs,
-      execute: (args, context) => executeReviewerMutation(context, options.validation, (workspace) => flowFeatureComplete(workspace, args), (workspace) => flowFeatureCompleteReplay(workspace, args))
+      execute: (args, context) => executeReviewerMutation(context, (workspace) => flowFeatureComplete(workspace, args), (workspace) => flowFeatureCompleteReplay(workspace, args))
     }),
     flow_feature_reset: tool({
       description: "Reset a feature and dependents for a fresh full retry.",
@@ -3430,4 +3478,4 @@ export {
   plugin_default as default
 };
 
-//# debugId=E5E0649B3D35337264756E2164756E21
+//# debugId=57F2808662DBAC8E64756E2164756E21