opencode-plugin-flow 5.2.1 → 5.3.0

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 One short entry per release, written for users deciding whether to upgrade.
 
+## [5.3.0] - 2026-07-20
+
+Single-version harness lore makes the installed package, runtime authority,
+validation evidence, correction review, and audit promotion path explicit:
+
+- `activation-check` inventories Flow activation across OpenCode config,
+  plugin directories, and package cache. `activation-apply` plans by default,
+  then uses an exact canonical pin, backups, quarantine, and a recovery journal
+  with `--apply`; ambiguous or externally managed sources require manual
+  remediation. Post-mutation failure attempts exact safe rollback and records
+  whether recovery converged or needs journal-backed manual repair.
+- Process-global runtime leadership permits one operational Flow instance.
+  Duplicate versions fail closed; a deterministic highest-version identity is
+  diagnostic only and cannot silently take control.
+- Three bounded harness profiles (`control`, `standard`, and `assurance`) and
+  three rollout modes (`control`, `observe`, and `enforce`) now drive optional
+  worker admission through a trusted runtime-policy footer. Worker model and
+  current OpenCode `steps` routing are configurable by role.
+- Validation is runtime-attested: `flow_validation_start` binds the current run
+  and source to the exact next Bash command, which emits an immutable receipt
+  reference consumed through `flow_review_start.request.validationRefs`.
+  Failed, incomplete, stale, altered, or duplicate receipts cannot become
+  review evidence.
+- Correction review binds the latest recorded failure to authoritative source
+  manifests and a deterministic delta. Narrow correction context is used only
+  when complete and safe; broad, security-sensitive, persistence-sensitive,
+  missing, unavailable, or oversized context falls back to full review. A
+  bounded correction-only public-contract/cross-layer hint can elevate semantic
+  scope to full without overriding more specific runtime reasons. The existing
+  two-failure run-scoped cap remains authoritative.
+- `AuditLedgerV1` now provides bounded typed findings, conservative severity
+  rules, explicit refutations and falsifiers, derived summaries, and
+  deterministic reconciled Markdown through `flow_audit_render`.
+- Privacy-safe bounded host observation and the sanitized full-repository audit
+  oracle separate observed zero from unavailable data and require same-source,
+  same-model quality parity plus lower observed work before a candidate profile
+  can be promoted. The checked-in standard and assurance observations remain
+  unavailable, so enforcement is not yet a release claim.
+
+## [5.2.2] - 2026-07-19
+
+Code-quality and persistence-hardening lore makes Flow safer at its input,
+replay, packaging, and filesystem boundaries without changing valid Session v4
+workflows:
+
+- Lifecycle admission now applies exact UTF-8 and collection bounds before
+  state I/O, reserves reachable execution and reviewer projections including
+  the longest persisted run identity, validates dependency graphs iteratively,
+  rejects duplicate pending assignments, and requires explicit timestamp
+  offsets.
+- Optional orchestration telemetry has bounded raw and retained collections,
+  keeps malformed optional records warning-only, and saturates aggregate
+  counters instead of allowing valid large observations to corrupt persisted
+  state.
+- Replay validates session identity, complete mutation sequencing, crash and
+  recovery revision ownership, and monotonic durable revision, digest, and
+  status observations while preserving deterministic report bytes.
+- Source and evidence persistence use bounded descriptor reads, identity and
+  topology revalidation, streaming traversal, exact filename checks, and
+  deterministic publication, collision, growth, and ancestor-substitution
+  probes.
+- Release and package gates validate exact metadata, prune internal declaration
+  output, assert the complete packed-file allowlist, audit high-severity
+  advisories separately, pin workflow tooling, and keep Linux, macOS, Windows,
+  Node 24/26, and the real OpenCode host as blocking compatibility signals.
+- Maintained documentation is indexed and source-checked; stale guidance,
+  confirmed dead exports and aliases, debug-era wrappers, and test cleanup
+  leaks are removed while uncertain external surfaces remain intact.
+
 ## [5.2.1] - 2026-07-19
 
 Desktop helper runtime lore restores durable session closure under OpenCode

package/README.md

@@ -8,18 +8,36 @@ model switches, and context loss.
 
 The design is guidance-first: package-owned Markdown carries planning,
 execution, validation, review, and orchestration judgment, while the plugin
-runtime stays deliberately small — it keeps the session ledger and enforces the
-hard gates prompts should not be trusted to remember.
+runtime stays bounded and policy-focused — it keeps the session ledger and
+enforces the hard gates prompts should not be trusted to remember.
 
-Full project documentation is available in the
-[Flow OpenCode wiki](https://github.com/ddv1982/flow-opencode/wiki).
+The maintained documentation starts at [docs/index.md](docs/index.md). The
+tracked `droid-wiki/` tree is an archived generated snapshot and is not a
+current product or contributor contract.
 
 ## Quick start
 
 ```bash
-opencode plugin opencode-plugin-flow@5.2.1 --global --force
+npx -y opencode-plugin-flow@5.3.0 activation-apply \
+  --project "$PWD" --scope global
+npx -y opencode-plugin-flow@5.3.0 activation-apply \
+  --project "$PWD" --scope global --apply
+npx -y opencode-plugin-flow@5.3.0 activation-check --project "$PWD"
 ```
 
+The first command is a read-only plan. Review it before running the second;
+the final check must report exactly one active `opencode-plugin-flow@5.3.0`
+source and no proven inactive Flow cache artifacts. Use `--scope project` when
+the one canonical pin should live with the project instead of in global config.
+Flow refuses ambiguous local wrappers, cache entries, unsafe links, and config
+it cannot change conservatively rather than guessing which copy is authoritative.
+
+To select npm's current release instead of this release-pinned example, replace
+`@5.3.0` with `@latest` on the `npx` invocations; do not pass
+`--target latest`. The fetched CLI resolves its own embedded exact version and
+converges every mutable Flow activation to that one pin, so latest replaces an
+older active version rather than loading beside it.
+
 Start or restart OpenCode, then give Flow a goal:
 
 ```text
@@ -48,7 +66,12 @@ stops before `flow_run_start`.
   flow_run_start    mutation acknowledged
   flow_status       request.view: execution, feature: rate-limit-middleware
   ... implementation, tests ...
-  flow_review_start request.validations: focused checks passed
+  flow_validation_start
+                    command: exact next Bash command
+                    coverageScope: focused
+  bash              exact armed command
+                    [flow-validation-receipt] immutable receipt reference
+  flow_review_start request.validationRefs: [receipt reference]
                     request.reviewKind: feature
                     request.validationScope: targeted
                     assignmentId: review-assignment:runtime-id
@@ -110,8 +133,9 @@ loop.
 
 ## Tools
 
-The plugin exposes nine tools. `flow_guidance` is read-only and returns embedded
-Markdown; the other eight form the runtime surface:
+The plugin exposes 12 tools. Nine own the durable lifecycle; three add bounded
+harness admission, runtime-attested validation, and deterministic audit
+rendering:
 
 | Tool | Purpose |
 | --- | --- |
@@ -124,6 +148,9 @@ Markdown; the other eight form the runtime surface:
 | `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. |
+| `flow_orchestration_admit` | Evaluate and arm one bounded optional-worker proposal for the active harness profile. |
+| `flow_validation_start` | Arm capture for the exact next Bash command against current causal guards, feature run, and source. |
+| `flow_audit_render` | Validate `AuditLedgerV1` and render its reconciled Markdown deterministically. |
 
 Only the root manager calls `flow_review_start`. Reviewers recover the exact
 assignment with
@@ -135,6 +162,15 @@ 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.
 
+Validation input is no longer a caller-authored success claim. Immediately
+before a check, call `flow_validation_start` with the exact command and current
+guards, execute that exact command as the next Bash call, and copy the emitted
+immutable receipt reference into `flow_review_start.request.validationRefs`.
+Flow verifies receipt bytes, run, feature, current source, host-observed exit,
+output completeness, and scope before materializing Session v4 evidence. A
+failed, truncated, missing, stale, altered, or duplicate receipt is rejected
+without consuming the review-start operation id.
+
 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
@@ -157,6 +193,9 @@ The runtime owns only safety; judgment lives in package-owned guidance:
 - 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.
+- Validation receipts are host-attested from the exact next Bash execution.
+  Callers cannot supply validation timestamps, exit status, command class, or
+  output digest to `flow_review_start`.
 - 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;
@@ -184,8 +223,8 @@ The runtime owns only safety; judgment lives in package-owned guidance:
 - 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.
+- Host-observed validation times and reviewer-reported result times must follow
+  run, validation, and assignment order and cannot postdate runtime acceptance.
 - Session locks fail closed: Flow never guesses that an old lock is abandoned,
   and only the unique owner may release it. Only a valid Session v4 document can
   become active state; canonical history additionally requires explicit
@@ -194,6 +233,9 @@ The runtime owns only safety; judgment lives in package-owned guidance:
 - `.flow/session.json` is the only active-state representation. Canonical Flow
   commands call `flow_status` before acting; plugin configuration does not read,
   refresh, or project workspace state.
+- Exactly one Flow runtime instance may operate in an OpenCode process. If
+  duplicate copies load, every copy fails closed; the highest semantic version
+  is named only as a diagnostic leader and does not become operational.
 
 ## Hidden workers
 
@@ -216,6 +258,27 @@ that contract. Inspect rendered surfaces and static contracts with
 see
 [docs/prompt-quality.md](docs/prompt-quality.md).
 
+The trusted command footer selects one harness profile with
+`OPENCODE_FLOW_HARNESS_PROFILE=control|standard|assurance` (default
+`standard`) and one admission rollout with
+`OPENCODE_FLOW_ROLLOUT_MODE=control|observe|enforce` (default `observe`).
+`control` preserves discretionary optional-worker behavior without admission
+ceremony. `standard` admits a small bounded discovery/challenge path;
+`assurance` permits broader bounded evidence and audit coverage when risk
+justifies it. In `observe`, a policy violation is reported but does not block;
+in `enforce`, the exact admitted optional worker class and count must be
+dispatched. Lifecycle-required reviewer and validation workers are not optional
+passes and do not use orchestration admission. Validation receipts remain
+mandatory in every profile.
+
+Hidden worker routing can be tuned without changing the domain contract. Set
+`OPENCODE_FLOW_READONLY_WORKER_MODEL`,
+`OPENCODE_FLOW_REVIEW_WORKER_MODEL`, or
+`OPENCODE_FLOW_CANDIDATE_WORKER_MODEL`, with
+`OPENCODE_FLOW_WORKER_MODEL` as the fallback. Matching `*_WORKER_STEPS`
+variables set OpenCode's current `steps` limit; values must be integers from 1
+through 1000.
+
 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
@@ -226,23 +289,37 @@ handoffs remain outside `.flow/**`.
 ## Install details and legacy cleanup
 
 See [docs/troubleshooting.md](docs/troubleshooting.md) for updates,
-older-OpenCode install fallback, stuck session recovery, and removal of global
-Flow skill folders left by v4.
-
-To update a pinned Flow version, rerun the install command with the new version.
-Flow starts with the new package-owned guidance immediately; no second restart
-or sync command is required. To preview recoverable migration of pristine v4
-global skill folders:
+activation refusal and duplicate-runtime recovery, stuck session recovery, and
+removal of global Flow skill folders left by v4.
+
+To update, run the same `activation-apply` dry-run/apply/check sequence with the
+new exact package version. The activator inventories OpenCode's global, project,
+`.opencode`, custom, inline, and readable managed configuration; singular and
+plural plugin directories; and the Flow package cache. It preserves unrelated
+plugins, removes recognized Flow config entries outside the selected canonical
+scope, and moves only marker-proven wrappers and proven inactive cache artifacts
+to recovery locations. Applied changes receive backups and a recovery journal.
+Sources that cannot be proved safe—including unknown wrappers, ambiguous cache
+artifacts, JSONC that would require a lossy rewrite, inline config, and
+administrator-managed config—produce manual remediation instead of mutation.
+If an applied multi-source change fails, Flow attempts exact safe rollback and
+records either `rolled-back` or `rollback-failed` in the recovery journal;
+concurrent or unsafe state is preserved for manual recovery. Remote and
+managed-preference sources that cannot be decoded offline remain covered by
+fail-closed runtime leadership.
+
+To preview recoverable migration of pristine v4 global skill folders:
 
 ```bash
-npx -y opencode-plugin-flow@5.2.1 legacy-cleanup --dry-run
+npx -y opencode-plugin-flow@5.3.0 legacy-cleanup --dry-run
 ```
 
 ## Development
 
 ```bash
 bun install
-bun run check        # typecheck + lint + prompt quality + build + tests
+bun run check        # typecheck + lint + release metadata + prompt quality + build + tests
+bun run harness:report # sanitized control/candidate resource and quality status
 bun run smoke:live   # boots a real OpenCode server against the packed tarball
 ```