opencode-plugin-flow 4.3.8 → 4.4.0

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 One short entry per release, written for users deciding whether to upgrade.
 
+## [4.4.0] - 2026-07-17
+
+Prompt economy lore makes Flow's instructions smaller, more role-specific, and
+easier to verify without weakening runtime, validation, or review gates:
+
+- Public commands and hidden workers now compile role- and phase-specific
+  prompts from canonical skill fragments instead of concatenating whole skills
+  or maintaining parallel prompt copies in TypeScript.
+- Parallel guidance uses progressive disclosure: a short routing index loads
+  decision rules first, manifest and execution rules only after fan-out is
+  selected, and synthesis rules only when handoffs return. Serial-decision
+  context is about 76% smaller while the complete advanced contract remains
+  available.
+- Each hidden worker receives one role contract and one matching handoff schema;
+  empty, malformed, partial, and blocked handoffs remain explicit coverage gaps,
+  and candidate implementation stays subordinate to the root `flow-run`
+  manager.
+- Runtime-unavailable guards, planned review depth, cleanup/UI/audit evidence,
+  bounded review repair, and root-manager state ownership are covered across
+  the compiled surfaces.
+- Skills no longer estimate context pressure or request host compaction, and
+  the experimental compaction hook and environment switch have been removed;
+  durable runtime phase boundaries remain the continuation mechanism.
+- New deterministic prompt-quality tooling covers 18 scenarios and 52 static
+  criteria, with an opt-in structured model evaluator for GPT-5.4, GPT-5.6 Sol,
+  and other configured OpenCode models.
+
+## [4.3.9] - 2026-07-08
+
+Candidate accounting coherence lore makes the 4.3.8 orchestration accounting
+rules self-consistent, so valid manager records stop bouncing off the schema:
+
+- `decision: "parallel"` on implementation-decision records is now rejected
+  with one clear message (it stays valid for discovery, audit, and review
+  passes); previously every `candidateDecision` pairing produced contradictory
+  errors.
+- Candidate-shaped decisions now require candidate execution evidence on every
+  pass kind, so a decision label alone can no longer validate while being
+  excluded from `candidatePassCount`.
+- Candidate and verifier worker counts are checked per subtype instead of
+  summed, so one worker may fill both roles on a single pass row.
+- Orchestration pass dedup now remembers every recorded pass id in
+  `recordedPassIds`, so resubmitted completions no longer double-count
+  telemetry after the recent-pass window rolls over.
+- The candidate accounting rules are documented once, in
+  `skills/flow/references/parallel-orchestration.md`; the run skill, handoff
+  format, and wiki point there instead of restating them, and the two doc
+  instructions that contradicted the schema (omitted `decision` on decision
+  records, `workerCount=0` with positive `candidateWorkerCount`) are fixed.
+
 ## [4.3.8] - 2026-07-08
 
 Parallel orchestration accounting lore makes broad worker use visible without

package/README.md

@@ -17,8 +17,8 @@ Full project documentation is available in the
 ## Quick start
 
 ```bash
-opencode plugin opencode-plugin-flow@4.3.8 --global --force
-npx -y opencode-plugin-flow@4.3.8 sync
+opencode plugin opencode-plugin-flow@4.4.0 --global --force
+npx -y opencode-plugin-flow@4.4.0 sync
 ```
 
 Restart OpenCode, then give Flow a goal:
@@ -71,9 +71,11 @@ completed.
 | `/flow-review` | Run a read-only review. |
 | `/flow-status` | Show the active session and next action. |
 
-Commands are bundled entrypoints: they carry their own instructions, so they
-keep working even when OpenCode's native skill discovery lags behind a fresh
-install (see [docs/troubleshooting.md](docs/troubleshooting.md)).
+Commands are compiled entrypoints: manager commands carry only their applicable
+core instructions, while `/flow-review` runs against the reserved reviewer's
+role-specific agent contract. They keep working even when OpenCode's native
+skill discovery lags behind a fresh install (see
+[docs/troubleshooting.md](docs/troubleshooting.md)).
 
 `flow-test`, `flow-deslop`, `flow-ui-quality`, and `flow-commit` are managed
 helper skills, not public commands.
@@ -114,8 +116,10 @@ The runtime owns only safety; judgment lives in the skills:
   repair is limited to one repair plus one retry before the feature blocks.
 - Completed feature counts are telemetry only; Flow does not stop an approved
   plan just because several features have completed. Review retry boundaries
-  still return a compact resume packet and require explicit `phaseBoundaryAck`
+  still return a bounded resume packet and require explicit `phaseBoundaryAck`
   before starting the next feature.
+- Skills do not estimate context pressure or request host compaction. Only a
+  runtime-issued phase boundary stops the current loop for a fresh invocation.
 - A session can close as `completed` only after final completion has passed.
 - Crash recovery is built in: stale session locks expire automatically and
   unreadable session files are quarantined with recovery guidance, never
@@ -126,7 +130,7 @@ The runtime owns only safety; judgment lives in the skills:
 
 ## Hidden workers
 
-For broad work, Flow's manager can fan out read-only workers
+For broad work, Flow's manager can fan out isolated hidden workers
 (`flow-evidence-worker`, `flow-validation-worker`, `flow-audit-worker`,
 `flow-candidate-worker`, `flow-verifier-worker`, and the `flow-reviewer`) with
 locked-down permissions. Workers gather evidence; they never approve plans,
@@ -134,10 +138,22 @@ complete features, or close sessions. Flow reserves those agent ids and the
 public command ids while the plugin is enabled, and warns if they collide with
 your own config.
 
+Each hidden worker receives only its applicable handoff schema. The manager
+contract treats empty or malformed handoffs as coverage gaps instead of
+success. The offline handoff validator detects missing headings, empty sections,
+unresolved placeholders, and invalid statuses; current OpenCode worker output
+remains plain text, so runtime acceptance still depends on the manager applying
+that contract. Inspect rendered surfaces and static contracts with
+`bun run prompt:quality`; run opt-in model decisions with
+`bun run prompt:model-eval -- --model <provider/model> --timeout-ms 300000`;
+see
+[docs/prompt-quality.md](docs/prompt-quality.md).
+
 For broad implementation, the manager records whether work stayed serial,
 used exact-path candidate workers, used isolated worktrees, ran a tournament, or
-skipped candidates. Feature completion can carry compact
-`orchestrationPasses`; `flow_status` reports the aggregate under
+skipped eligible candidates. Feature completion can carry bounded
+`orchestrationPasses` with candidate eligibility, decision, and structured
+factors; `flow_status` reports the aggregate under
 `session.budget.orchestration`.
 
 ## Install details, doctor, repair, uninstall
@@ -150,17 +166,9 @@ To update a pinned Flow version, rerun the install command with the new
 version. To inspect skill health:
 
 ```bash
-npx -y opencode-plugin-flow@4.3.8 doctor
+npx -y opencode-plugin-flow@4.4.0 doctor
 ```
 
-## Experimental: compaction context
-
-Flow's ambient context uses stable OpenCode configuration by default. If you
-want the active session summary injected into OpenCode's session compaction as
-well, opt in with the environment variable `FLOW_EXPERIMENTAL_COMPACTION=1`.
-This uses OpenCode's experimental compaction hook and may change with OpenCode
-versions; the default remains hook-free.
-
 ## Development
 
 ```bash

package/dist/adapters/opencode/tools.d.ts

@@ -158,29 +158,47 @@ export declare function createTools(ctx: unknown): {
             orchestrationPasses: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
                 id: import("zod").ZodString;
                 kind: import("zod").ZodEnum<{
-                    discovery: "discovery";
+                    validation: "validation";
                     audit: "audit";
+                    candidate: "candidate";
+                    discovery: "discovery";
                     review: "review";
-                    validation: "validation";
                     verification: "verification";
-                    candidate: "candidate";
                     "implementation-decision": "implementation-decision";
                 }>;
                 decision: import("zod").ZodOptional<import("zod").ZodEnum<{
-                    serial: "serial";
                     parallel: "parallel";
+                    serial: "serial";
                     "candidate-exact-path": "candidate-exact-path";
                     "candidate-worktree": "candidate-worktree";
                     tournament: "tournament";
                     skipped: "skipped";
                 }>>;
                 decisionReason: import("zod").ZodOptional<import("zod").ZodString>;
+                candidateEligibility: import("zod").ZodDefault<import("zod").ZodEnum<{
+                    eligible: "eligible";
+                    not_eligible: "not_eligible";
+                    unknown: "unknown";
+                }>>;
+                candidateDecision: import("zod").ZodOptional<import("zod").ZodEnum<{
+                    skipped: "skipped";
+                    used: "used";
+                    serial_required: "serial_required";
+                }>>;
+                decisionFactors: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodEnum<{
+                    shared_state: "shared_state";
+                    overlapping_files: "overlapping_files";
+                    small_slice: "small_slice";
+                    needs_manager_judgment: "needs_manager_judgment";
+                    independent_surface: "independent_surface";
+                    validation_available: "validation_available";
+                }>>>;
                 modes: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodEnum<{
-                    audit: "audit";
-                    review: "review";
-                    validation: "validation";
                     evidence: "evidence";
+                    validation: "validation";
+                    audit: "audit";
                     verifier: "verifier";
+                    review: "review";
                     "candidate-implementation": "candidate-implementation";
                 }>>>;
                 workerCount: import("zod").ZodDefault<import("zod").ZodNumber>;
@@ -206,6 +224,7 @@ export declare function createTools(ctx: unknown): {
                 }>>;
                 outcome: import("zod").ZodDefault<import("zod").ZodEnum<{
                     accepted: "accepted";
+                    modified: "modified";
                     rejected: "rejected";
                     partial: "partial";
                     "not-covered": "not-covered";
@@ -256,8 +275,10 @@ export declare function createTools(ctx: unknown): {
             } | undefined;
             orchestrationPasses?: {
                 id: string;
-                kind: "discovery" | "audit" | "review" | "validation" | "verification" | "candidate" | "implementation-decision";
-                modes: ("audit" | "review" | "validation" | "evidence" | "verifier" | "candidate-implementation")[];
+                kind: "validation" | "audit" | "candidate" | "discovery" | "review" | "verification" | "implementation-decision";
+                candidateEligibility: "eligible" | "not_eligible" | "unknown";
+                decisionFactors: ("shared_state" | "overlapping_files" | "small_slice" | "needs_manager_judgment" | "independent_surface" | "validation_available")[];
+                modes: ("evidence" | "validation" | "audit" | "verifier" | "review" | "candidate-implementation")[];
                 workerCount: number;
                 candidateWorkerCount: number;
                 verifierWorkerCount: number;
@@ -266,9 +287,10 @@ export declare function createTools(ctx: unknown): {
                 writeScope: "none" | "manager-serial" | "exact-path" | "isolated-worktree" | "mixed";
                 handoffRefs: string[];
                 verificationStatus: "pending" | "passed" | "failed" | "mixed" | "not-needed" | "downgraded";
-                outcome: "accepted" | "rejected" | "partial" | "not-covered" | "superseded";
-                decision?: "serial" | "parallel" | "candidate-exact-path" | "candidate-worktree" | "tournament" | "skipped" | undefined;
+                outcome: "accepted" | "modified" | "rejected" | "partial" | "not-covered" | "superseded";
+                decision?: "parallel" | "serial" | "candidate-exact-path" | "candidate-worktree" | "tournament" | "skipped" | undefined;
                 decisionReason?: string | undefined;
+                candidateDecision?: "skipped" | "used" | "serial_required" | undefined;
                 synthesisRef?: string | undefined;
             }[] | undefined;
         }, context: ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;