opencode-plugin-flow 6.7.0 → 6.9.0

package/CHANGELOG.md

@@ -6,6 +6,132 @@ One short entry per release, written for users deciding whether to upgrade.
 
 No changes yet.
 
+## [6.9.0] - 2026-07-26
+
+Rules the prompts used to restate are now enforced by the runtime, and Flow no
+longer assumes an OpenCode-shaped host:
+
+- Review findings carry two typed fields instead of prose conventions. An
+  optional `scopeBlocker` boolean surfaces as `blockedFeature.scopeBlocker` and
+  is accounted for by `nextAction`, so a scope blocker checkpoints for user
+  direction at the first failed review rather than depending on the manager
+  noticing a `[scope-blocker]` marker; the marker is gone everywhere. A
+  `findingId` is set to a prior id for a recurrence and omitted for a new issue,
+  which the runtime numbers as `<feature-id>.R<revision>-<NN>` and supplies back
+  as `priorFindings` with `nextFindingIdPrefix`. A failed result that drops a
+  live prior id is rejected instead of silently losing that history.
+- The reviewer is asked to report every problem it finds and to use severity
+  purely for routing, replacing guidance that reserved `blocking` for issues
+  invalidating the outcome. Published guidance for current models indicates that
+  conservative review instructions suppress findings.
+- The delivery projection carries a runtime-rendered `report`, so every surface
+  relays one formatted handoff verbatim instead of restating the same field list
+  four times.
+- Validation on a host that reports no structured Bash exit code, or no
+  output-truncation flag, records a durable observation marked
+  `exit-code-unavailable` or `output-completeness-unknown` rather than failing the
+  capture. Such an observation never satisfies a gate, so the limitation is
+  visible instead of blocking. Worker-wave dispatch no longer instructs a single
+  assistant tool-use turn; a host that runs tasks serially is expected and
+  reported as serial.
+- A tool call rejected by the runtime guard returns the same
+  `workflowData.failure.recovery` envelope every other Flow failure uses, which is
+  what the prompts already told the model to read. `flow_guidance` answers in
+  markdown, so its rejection is markdown rather than a JSON blob.
+- `/flow-auto` on a host that reports no assistant message parentage now says so.
+  Continuation anchors on the assistant message owning the lease, so such a host
+  can never continue and correctly stops after each feature; previously that was
+  indistinguishable from a Flow defect. The warning now names the host limitation
+  and points at `/flow-run`.
+
+Prompt text is now measured rather than argued about. Total shipped prompt bytes
+drop from 42,466 to 38,495 and cross-surface near-duplicate rule statements from
+18 pairs to 12, with every removed instruction either replaced by an enforced
+guard or a runtime-rendered value, or verified against the model. `flow-run`, the
+dominant surface, loses 2,422 bytes: the elaborate revision-token protocol
+collapses to the one rule that routes (`passed: false` never arms review), the
+manager no longer reconstructs which prior findings are still live or tracks
+their disposition in prose now that the runtime supplies `priorFindings` with
+each finding's current severity and wording, and the prose describing internals
+Flow already enforces — the strict review-start schema, the derived review kind,
+the auto-continuation gate, and several statements that Flow persists no ledger —
+is gone. Absolute-rule markers in `flow-run` fall from 62 to 51, which both
+vendors' guidance treats as a compliance gain rather than a loss. `tests/prompt-quality.test.ts` and
+`tests/documentation-contract.test.ts` no longer pin ordered prose phrases; they
+assert structure, source-derived inventories, and budgets that ratchet down, so
+tightening prompts is cheap and growth is what fails. Model behaviour is measured
+by the new opt-in `evals/` harness, which drives the real slash commands against
+a real model in a throwaway OpenCode host and asserts durable session state.
+
+The harness arrived part-way through this release, so the cuts are not all
+evidenced equally. The last one — the manager-side prior-finding reconstruction,
+replaced by runtime `priorFindings` — was validated directly: `happy-path`,
+`plan-only-stops` and `goal-change-refused` each passed three of three attempts
+at the reduced footprint. Earlier cuts predate the harness and rest on the guards
+and rendered values that replaced them, checked against a repeat-3 baseline
+recorded once the harness existed. A fourth scenario, `failing-gate-blocks`,
+passes at roughly even odds; it was measured to be equally unreliable at 6.8.0,
+so it is reported but carries no signal about these prompts either way. Its cause
+is a pre-existing gap rather than a prompt defect: `exitCode` and `scope` on a
+validation observation are supplied by the model and never executed by Flow, so a
+model that misreports a red gate as green is accepted by every predicate. Treat a
+passing gate as a claim the model made, not one Flow verified.
+
+The Session v5 schema adds two optional finding fields and widens `exitCode` to
+allow `null`. Earlier v6 builds read the added fields as absent, but reject a
+document containing a `null` exit code, so finish or close active work before
+downgrading.
+
+Install or update:
+
+```bash
+opencode plugin opencode-plugin-flow@6.9.0 --global --force
+```
+
+## [6.8.0] - 2026-07-24
+
+Checkpoint-safe continuation and leaner review convergence:
+
+- `/flow-auto` now remains waiting through same-revision checkpoint replies and
+  enqueues exactly one continuation only after the same host observes an
+  accepted Flow mutation whose tool assistant resolves through cached
+  `message.updated` parentage to the authoritative user reply; missing or
+  mismatched provenance fails closed. Mechanical progress must match that
+  revision exactly, except for the single state-constrained reviewer-result
+  revision after an authenticated `flow_review_start`.
+- Compaction carries reply authority only across an authenticated trigger
+  assistant, automatic compaction marker, summary assistant, and successor user
+  lineage while authority remains unchanged; incomplete or unrelated lineage
+  fails closed.
+- From idle, auto-routing requires a same-host accepted non-replayed
+  `flow_plan_save` for the newly created Flow session; a baseline that already
+  has a pending reviewer retains a narrow temporal exception.
+- `/flow-auto stop` and `/flow-auto cancel` now revoke the process-local
+  continuation lease without closing, deferring, abandoning, or otherwise
+  mutating the durable Flow session.
+- Manager command rewrites preserve every nonblank raw request, including
+  exterior whitespace, exactly once while keeping synthetic guidance separate.
+- Initial auto/run prompts, dynamically loaded run guidance, compaction context,
+  and synthetic continuations share one concise manager kernel for reserved
+  roles, the exact `failedReviewCount === 1` retry gate, and current-source plus
+  relevant baseline evidence.
+- Guidance represents race-heavy risk checks as one transition matrix and
+  preserves stable finding IDs, relevant baseline facts, and prior dispositions.
+  Ordinary reviewer summaries keep IDs mapped to the active feature or supplied
+  explicitly in its packet; final review covers every approved requirement or
+  feature ID. Both keep each still-live prior finding through failed reviews; a
+  proven repair remains pending until a later passing review, so closure and
+  archive replay need no prerequisite detail read or unbounded historical
+  ledger. The Session v5 schema is unchanged.
+  Provider/model execution remains unverified unless the opt-in manual canary
+  is run.
+
+Install or update:
+
+```bash
+opencode plugin opencode-plugin-flow@6.8.0 --global --force
+```
+
 ## [6.7.0] - 2026-07-23
 
 Bounded auto-continuation lore keeps user-authorized goals moving while making

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.7.0 --global --force
+opencode plugin opencode-plugin-flow@6.9.0 --global --force
 ```
 
 Omit `--global` for project scope. Exact version pins do not update
-automatically. To update, replace `6.7.0` with the new release and rerun the
+automatically. To update, replace `6.9.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.7.0"]
+  "plugin": ["opencode-plugin-flow@6.9.0"]
 }
 ```
 
@@ -67,7 +67,14 @@ runnable feature at a time, validates the actual workspace, obtains an
 independent review, and repeats until it can close the session. While
 implementation remains authorized, `ready` and `completed` are internal loop
 states: `/flow-auto` does not hand back “ready for the next feature” or wait for
-another command between passing features.
+another command between passing features. From idle, auto-routing first requires
+a same-host accepted non-replayed `flow_plan_save` for the created Flow session;
+an active baseline that already has a pending reviewer retains a narrow temporal
+exception for that completion.
+
+Send `/flow-auto stop` or `/flow-auto cancel` in the same OpenCode session to
+revoke only the process-local continuation lease. This does not close, defer,
+abandon, or otherwise mutate the durable Flow session.
 
 Before every manager-owned Flow mutation, including direct `/flow-plan` and
 `/flow-run` use, the manager compares the current request with the active goal.
@@ -79,8 +86,9 @@ continue, defer, or abandon the active work. If that work is completed but not
 closed, Flow closes it as completed before starting the new request.
 
 Existing implementation authority carries across approval and feature outcomes.
-Only the first in-scope failed review may automatically reset and atomically
-start one fresh full retry; a `[scope-blocker]` checkpoints immediately. A
+Flow automatically resets and atomically starts one fresh full retry only when
+the projected `nextAction` is `flow_feature_reset`, which the runtime derives
+from `failedReviewCount` and `blockedFeature.scopeBlocker`. A
 feature whose latest relevant reviewed outcome remains failed is never selected
 implicitly. `/flow-auto` may continue untouched, dependency-independent
 features, but when only retry-required candidates remain it projects
@@ -92,22 +100,43 @@ the superseded failed feature remains, status is ready with
 `await-user-direction`; explicit retry then uses `flow_run_start` with that
 feature's exact `featureId`, because there is no blocked run left to reset. The
 active session remains authoritative while it waits. Ordinary blocking findings
-are in-scope by default; a reviewer uses `[scope-blocker]` only when the required
-repair would materially exceed the approved plan.
+are in-scope by default; a reviewer sets `scopeBlocker: true` on a finding only
+when the required repair would materially exceed the approved plan. Each finding
+also carries a runtime-issued `findingId`, and a failed result must carry every
+still-live prior ID forward, which `flow_feature_complete` enforces. After a user checkpoint, the
+process-local continuation resumes only after that same OpenCode session observes
+an accepted non-replayed Flow mutation whose tool assistant ID resolves, through
+the cached `message.updated` `parentID`, to the authoritative user reply. A
+missing or mismatched origin fails closed. Another host cannot establish that
+authority. The mechanical projection must match the credited revision exactly;
+the sole successor allowance is one revision after an authenticated
+`flow_review_start`, where the state machine admits the reserved reviewer result.
+Compaction transfers the reply authority only across an authenticated trigger
+assistant, automatic compaction marker, summary assistant, and successor user
+lineage while the authority is unchanged; an incomplete or unrelated lineage
+fails closed.
 
 Before coding each feature, Flow inventories required evidence and its
 environment, then applies an adversarial risk checklist covering failure
 ordering, repeated and interrupted operations, adjacent state transitions,
 overlapping invariants, and relevant file-mode or platform risks. While required
 behavior or environment evidence is knowingly skipped, manager policy forbids
-requesting review; the reviewer treats missing proof as blocking if the gap
-reaches its packet. Flow persists no skipped-evidence ledger. Asking the user
-remains the default when external evidence or authority is missing. At a blocked
-checkpoint, atomic reset-and-start can discard that attempt and continue the
+requesting review; the reviewer treats proof required to approve the outcome as
+blocking if it is missing from the packet. Flow persists no skipped-evidence
+ledger. Asking the user remains the default when external evidence or authority
+is missing. At a blocked checkpoint, atomic reset-and-start can discard that
+attempt and continue the
 exact authorized retry or dependency-independent feature. At a ready retry
 checkpoint, explicit feature start resumes the already superseded failure.
 Neither route adds a hold or second blocker ledger.
 
+Flow guidance represents the checklist for concurrency and state-machine work
+as one compact transition matrix shared by workers and the reviewer. Review
+packets reuse a refreshed run baseline, carry only feature-relevant file facts
+until final review, and preserve source IDs, current-source evidence, risk
+coverage, and prior finding dispositions in existing text fields—no new audit
+schema.
+
 For plan-only or advanced use, plan first:
 
 ```text
@@ -147,8 +176,10 @@ inactive, errored, and unprojected waits are excluded.
    not reopened or vetoed later at close.
 6. The reviewer inspects adjacent and repeated state transitions, overlapping
    feature invariants, the changed artifacts, and the packet's base-diff and
-   file-mode inventory. Missing proof is recorded as a precise blocking
-   evidence request.
+   file-mode inventory. Stable finding IDs survive retries; reviewer guidance
+   requires checking prior dispositions and completing the supplied risk
+   checklist, represented as a bounded matrix when applicable. Missing proof is
+   a precise blocker only when it is required to approve the outcome.
 7. A passing feature advances the plan. A failed feature is not selected again
    by default. From blocked status, reset atomically starts the exact authorized
    retry or independent feature through optional `nextFeatureId`. From ready
@@ -156,7 +187,18 @@ inactive, errored, and unprojected waits are excluded.
    `flow_run_start(featureId)` begins its retry. The final passing feature allows
    explicit closure. Every accepted close returns a concise delivery summary
    with each feature's attempt count, latest outcome, and terminal findings,
-   derived from Flow's recorded state.
+   derived from Flow's recorded state. Ordinary reviewer summaries carry IDs
+   mapped to the active feature or explicitly supplied in its packet; final
+   review carries every approved requirement or feature ID. Both carry each
+   still-live prior finding with its severity and disposition into the latest
+   `outcomeSummary`. Terminal
+   `fixed` requires a later passing review and current evidence. If a failed
+   retry proves one repair but finds another blocker, it carries that ID and a
+   concise evidence reference forward as terminal fixed pending pass; it cannot
+   drop the ID or call it fixed. Unproven fixes stay unverified, `recurring`
+   confirms recurrence, and `residual` requires a confirmed nonblocker. Only a
+   passing review may remove fixed history from the live carry-forward set.
+   Terminal findings retain unresolved blockers and the handoff stays bounded.
 
 State lives in `.flow/session.json`, so `/flow-status` can recover the next
 action after a restart or context change.
@@ -194,8 +236,8 @@ plan-only, advanced, internal, or recovery controls.
 
 Start with `/flow-status`; its next action is durable default workflow
 direction, not permission to exceed the user's authority. For a first failed
-review, read detail once before reset because scope-blocker findings refine the
-compact default. Pass the exact retry or dependency-independent choice as
+review, read detail once before reset to see the findings the retry must fix.
+Pass the exact retry or dependency-independent choice as
 `nextFeatureId` so reset and run start are atomic; do not reset and then rely on
 default selection. If status is ready with `await-user-direction`, read detail
 once and pass the explicitly authorized retry's exact `featureId` to
@@ -206,11 +248,19 @@ mutation is attempted. Do not hand-edit
 fingerprinting, or archive publication fails, follow the focused steps in
 [troubleshooting](docs/troubleshooting.md).
 
-For an interrupted accepted close, replay the projected `archiveRetry.request`
-exactly once. Flow confirms the existing bytes without rewriting Session v5 and
-re-confirms archive cleanup. A real archive collision removes the automatic
-retry instruction and requires manual inspection; preserve both documents and
-do not overwrite, delete, or loop the request.
+For an interrupted accepted close, compact `/flow-status` supplies
+`archiveRetry.request`. Replay that request exactly once before any additional
+or detail recovery read. Flow confirms the existing bytes without rewriting
+Session v5, re-confirms archive cleanup, and returns the existing concise
+`workflowData.delivery`. Relay its `report` lines verbatim, and reconstruct only
+the plan-bounded, terminal disposition
+map from its latest `outcomeSummary` and terminal findings. If delivery is absent,
+report the exact recovery and claim no map. On a close revision conflict,
+refresh compact status and retry only after confirming the same session and goal
+and that status still permits the selected
+closure kind; never close a replacement. A real archive collision removes the
+automatic retry instruction and requires manual inspection; preserve both
+documents and do not overwrite, delete, or loop the request.
 
 ## Development