opencode-plugin-flow 4.3.8 → 4.4.0

package/dist/cli.js

@@ -11,14 +11,18 @@ import { dirname, join, normalize, sep } from "node:path";
 var handoff_format_default = `# Flow worker handoff contract
 
 Flow managers merge only the worker's final response. Treat that response as the
-worker report of record: it must include the assigned scope, what was actually
-covered, the evidence for each useful claim, and the remaining gaps. End worker
-prompts with "Return only this Flow handoff."
-
-Empty or unstructured worker output is a failed handoff. If the worker cannot
-cover the assigned scope, verify the evidence, or satisfy the handoff shape, it
-must return \`Status: blocked\` with the missing elements, and the manager must
-not treat the slice as complete.
+worker report of record. End worker prompts with "Return only this Flow
+handoff."
+
+<!-- flow-prompt:worker-integrity:start -->
+Cite or drop every claim. Label single-source, inferred, and unsettled claims.
+When usable evidence exists but named expected coverage could not be checked,
+return the required handoff with \`## Status\` set to \`partial\` and enumerate the
+unchecked items and reasons. If the assignment or required shape is missing,
+or no usable coverage can be produced, return the required handoff with
+\`## Status\` set to \`blocked\` and name the missing elements. Empty or
+unstructured output is a failed handoff.
+<!-- flow-prompt:worker-integrity:end -->
 
 Sections: evidence/review/validation/audit worker report, verifier worker report,
 and candidate implementation worker report.
@@ -34,149 +38,144 @@ Status meanings:
 
 ## Evidence, review, validation, or audit worker report
 
-Use this for \`flow-evidence-worker\`, \`flow-reviewer\`,
-\`flow-validation-worker\`, and \`flow-audit-worker\`.
+Use the one role-specific block that matches the assigned worker.
 
-\`\`\`markdown
+<!-- flow-prompt:handoff-evidence:start -->
+Return only this Flow handoff:
 ## Status
 success | partial | blocked
-
 ## Scope
-<owned slice: path set, module, command, risk lens, route, data range, or question set>
-
+assigned slice
 ## Pass metadata
-- Pass id: <stable pass id from the manifest>
-- Manifest row id: <row id from the manifest>
-- Depends on: <upstream row ids or "none">
-- Write scope: <none | manager-serial | exact-path | isolated-worktree | mixed>
-
+pass id, manifest row id, dependencies, write scope
 ## Coverage
-- Expected: <files, ranges, questions, commands, or findings assigned>
-- Checked: <actual coverage, for example "12/12 files" or "command not run">
-- Not checked: <items skipped with reason, or "none">
-
+expected, checked, not checked with reasons
 ## Findings or facts
-- [high|med|low] <claim>; evidence: <file:line | command summary | screenshot path | URL | metric>; corroboration: <N sources or "single source">
-- [high|med|low] <claim>; evidence: <...>; corroboration: <...>
-
+confidence, atomic claim, citation, corroboration
 ## Sources
-- <paths read, commands run, docs fetched, data ranges covered, screenshots inspected>
-
+paths, commands, documents, screenshots, or data ranges inspected
 ## Confidence and verification
-- Verified: <claims directly re-run, recounted, traced, or cross-checked>
-- Single-source: <claims with exactly one supporting source>
-- Inferred: <claims derived from surrounding evidence rather than directly observed>
-- Unsettled: <claims, sources, or citations that could not be resolved>
-- Falsifier or missing input: <what would overturn or materially change the result>
-
+verified, single-source, inferred, unsettled, falsifier
 ## Open questions / gaps
-- <ambiguity, missing source, contradiction, skipped item, or out-of-scope dependency>
-
 ## Manager follow-ups
-- <concrete next tasks, verifier claims, validation commands, or Flow plan targets>
-\`\`\`
+<!-- flow-prompt:handoff-evidence:end -->
 
-Validation workers must include exact command names and raw outcome summaries
-for commands they actually ran. Audit workers must include guards checked for
-any blocking-severity candidate. Review workers must separate blocking findings
-from advisory notes. In the shared \`Findings or facts\` section, review workers
-should prefix review items with \`blocking:\` or \`advisory:\` before the claim.
+<!-- flow-prompt:handoff-validation:start -->
+Return only this Flow handoff:
+## Status
+success | partial | blocked
+## Scope
+assigned checks or validation question
+## Pass metadata
+pass id, manifest row id, dependencies, write scope
+## Coverage
+expected, checked, not checked with reasons
+## Commands and outcomes
+exact command, status, raw outcome summary, behavior covered
+## Confidence and verification
+verified, single-source, inferred, unsettled, falsifier
+## Open questions / gaps
+## Manager follow-ups
+<!-- flow-prompt:handoff-validation:end -->
 
-Example evidence quality:
+<!-- flow-prompt:handoff-audit:start -->
+Return only this Flow handoff:
+## Status
+success | partial | blocked
+## Scope
+assigned paths, risks, or candidate findings
+## Pass metadata
+pass id, manifest row id, dependencies, write scope
+## Coverage
+expected, checked, not checked with reasons
+## Findings
+severity, atomic claim, citation, corroboration, guards checked, refutation result
+## Sources
+## Confidence and verification
+verified, single-source, inferred, unsettled, falsifier
+## Open questions / gaps
+## Manager follow-ups
+<!-- flow-prompt:handoff-audit:end -->
 
-- Good fact: \`[high] public Flow command prompts include bundled instructions;
-  evidence: src/config-shared.ts:135; corroboration: single source\`.
-- Weak fact: \`[high] prompts look self-contained; evidence: read the config\`.
-- Good validation: \`bun test tests/distribution-and-surface.test.ts\`, status
-  passed, summary \`surface tests passed and covered bundled command prompts\`.
-- Weak validation: \`tests pass\`, with no command, status, or raw outcome.
+<!-- flow-prompt:handoff-review-slice:start -->
+For an assigned review slice, return only this Flow handoff:
+## Status
+success | partial | blocked
+## Scope
+assigned files, risk lens, or validation surface
+## Pass metadata
+pass id, manifest row id, dependencies, write scope
+## Coverage
+expected, checked, not checked with reasons
+## Findings
+prefix each \`blocking:\` or \`advisory:\`, then severity, claim, citation, and corroboration
+## Sources
+## Confidence and verification
+verified, single-source, inferred, unsettled, falsifier
+## Open questions / gaps
+## Manager follow-ups
+<!-- flow-prompt:handoff-review-slice:end -->
 
 ## Verifier worker report
 
-Use this for \`flow-verifier-worker\`. Give it atomic claims and the cited sources
-or commands. Do not include the generator's reasoning unless that reasoning is
-the thing being verified, and do not say which worker produced the claim.
+Use this for \`flow-verifier-worker\`.
 
-\`\`\`markdown
+<!-- flow-prompt:handoff-verifier:start -->
+Return only this Flow handoff:
 ## Status
 success | partial | blocked
-
 ## Scope
-<claim ids, sources or commands checked, and the acceptance question>
-
+atomic claim ids, sources or commands checked, acceptance question
 ## Pass metadata
-- Pass id: <stable pass id from the manifest>
-- Manifest row id: <row id from the manifest>
-- Depends on: <upstream row ids or "none">
-
+pass id, manifest row id, dependencies
 ## Verdict per claim
-- <claim id>: verdict=<supported | partly-supported | unsupported | source-not-found>
-  - claim: <claim text>
-  - evidence: <supporting snippet, path plus line, measured value, command result, or "none">
-  - source resolution: <URL, path, or command plus whether it resolved>
-  - confidence level: high | med | low
-  - recommended action: <keep, narrow, rewrite, or remove>
-
+supported | partly-supported | unsupported | source-not-found; include claim, resolved evidence, confidence, recommended action
 ## Overall
-<accept | revise | reject> because <brief reason>
-
+accept | revise | reject with reason
 ## Gaps
-- <unavailable source, ambiguous claim wording, missing oracle, or check not run>
-
 ## Manager follow-ups
-- <narrow recheck, plan adjustment, review finding, or none>
-\`\`\`
+<!-- flow-prompt:handoff-verifier:end -->
 
 ## Candidate implementation worker report
 
-Use this only with explicit user authorization, in an isolated worktree or an
-exact non-overlapping path-owned slice assigned by the manager.
+Use this only with explicit user authorization and isolated or exact-path
+ownership.
 
-\`\`\`markdown
+<!-- flow-prompt:handoff-candidate:start -->
+Return only this Flow handoff:
 ## Status
 success | partial | blocked
-
 ## Scope
-<isolated worktree or exact path-owned slice>
-
+isolated worktree or exact path-owned slice
 ## Pass metadata
-- Pass id: <stable pass id from the manifest>
-- Manifest row id: <row id from the manifest>
-- Depends on: <upstream row ids or "none">
-- Write scope: <exact-path | isolated-worktree>
-
+pass id, manifest row id, dependencies, exact-path | isolated-worktree
 ## Changed or proposed patch
-- <path>: <what changed and why>
-
+paths, change, reason
 ## Coverage
-- Assigned: <owned files/modules>
-- Touched: <files changed or proposed>
-- Skipped: <anything assigned but not changed and why, or "none">
-
+assigned, touched, skipped with reasons
 ## Verification
-live-verified | test-verified | type-check-only | not-verified
-- <command, observed outcome, pass/fail counts, or manual check>
-
+level, exact command or check, observed outcome
 ## Confidence and risk
-- Checked directly: <behavior, files, or commands verified by the worker>
-- Still open: <tests, review paths, or integration points the manager must cover>
-- Risk: low | medium | high -- <why>
-
+directly checked, still open, risk with reason
 ## Merge notes
-- <conflicts, nearby user changes, assumptions, or deviations>
-
+conflicts, user changes, assumptions, deviations
 ## Manager follow-ups
-- <merge, reject, rerun check, verifier pass, or replan task>
-\`\`\`
+<!-- flow-prompt:handoff-candidate:end -->
 
 The manager must inspect and validate any candidate patch before recording Flow
 completion.
 
 ## Manager pass accounting record
 
-The manager, not the worker, may carry compact records into
+The manager, not the worker, may carry bounded records into
 \`flow_feature_complete.orchestrationPasses\`. Use one record per material pass or
 implementation decision; keep handoffs and long artifacts outside \`.flow/**\`.
+The candidate accounting rules — which \`candidateEligibility\`,
+\`candidateDecision\`, and \`decision\` combinations validate, and what counts as
+candidate execution evidence — live in
+[parallel-decision.md](parallel-decision.md) under "Implementation pass
+decision"; note \`decision: "parallel"\` is not valid on
+\`implementation-decision\` records.
 
 \`\`\`json
 {
@@ -184,6 +183,16 @@ implementation decision; keep handoffs and long artifacts outside \`.flow/**\`.
   "kind": "discovery | audit | review | validation | verification | candidate | implementation-decision",
   "decision": "serial | parallel | candidate-exact-path | candidate-worktree | tournament | skipped",
   "decisionReason": "why this pass shape was chosen",
+  "candidateEligibility": "eligible | not_eligible | unknown",
+  "candidateDecision": "used | skipped | serial_required",
+  "decisionFactors": [
+    "shared_state",
+    "overlapping_files",
+    "small_slice",
+    "needs_manager_judgment",
+    "independent_surface",
+    "validation_available"
+  ],
   "modes": ["evidence"],
   "workerCount": 1,
   "candidateWorkerCount": 0,
@@ -193,449 +202,258 @@ implementation decision; keep handoffs and long artifacts outside \`.flow/**\`.
   "writeScope": "none | manager-serial | exact-path | isolated-worktree | mixed",
   "handoffRefs": ["/tmp/flow-handoff.md"],
   "verificationStatus": "not-needed | pending | passed | failed | mixed | downgraded",
-  "outcome": "accepted | rejected | partial | not-covered | superseded",
+  "outcome": "accepted | modified | rejected | partial | not-covered | superseded",
   "synthesisRef": "/tmp/flow-synthesis.md"
 }
 \`\`\`
 `;
 
-// skills/flow/references/parallel-orchestration.md
-var parallel_orchestration_default = `# Parallel orchestration
+// skills/flow/references/parallel-decision.md
+var parallel_decision_default = `# Parallel pass decisions
 
-Use fan-out when Flow work is broad enough that independent workers can gather
-evidence faster than one linear pass. The manager still owns the Flow session:
-only the manager calls state-changing Flow tools, approves plans, completes
-features, records reviews, or closes sessions.
+Read this reference after serial orientation and before creating a pass
+manifest. It decides whether fan-out is worth its coordination cost and records
+why implementation stays serial or uses candidate workers.
 
-Every parallel pass runs the same loop:
+<!-- flow-prompt:manager-parallel-core:start -->
+## Conditional parallel pass
 
-**orient → slice → manifest → fan out → account → verify → synthesize →
-extend or stop.**
+Use a parallel pass only when independent coverage is worth its coordination
+cost. Orient serially first. Before fan-out record a stable pass id, purpose,
+bounded worker count, exact non-overlapping slices, expected coverage, named
+Flow worker roles, dependencies, write scope, handoff kind, verification plan,
+and stop condition.
 
-This file is the whole playbook; read it once and run the pass. Two companions
-stay separate:
-
-- \`handoff-format.md\` holds the worker response templates. The manager pastes
-  the matching template verbatim into every worker prompt.
-- \`parallel-pass-example.md\` walks one concrete end-to-end pass (synced with
-  the \`flow\` skill; not bundled into commands).
+Use \`flow-evidence-worker\` for discovery, \`flow-validation-worker\` for commands,
+\`flow-audit-worker\` for adversarial findings, \`flow-verifier-worker\` for
+high-impact claim checks, and \`flow-reviewer\` for independent review. Account
+for every manifest row. A missing, empty, malformed, partial, or blocked
+handoff is a coverage gap, not success. Verify high-impact or single-source
+claims, then let only the manager synthesize the result and mutate Flow state.
+<!-- flow-prompt:manager-parallel-core:end -->
 
 ## Choose a pass
 
-| Situation | Flow pass | Output the manager may synthesize |
+| Situation | Flow pass | Manager-owned result |
 | --- | --- | --- |
-| Repo shape is unclear before planning | Discovery pass | Requirements, decisions, targets, validation entries, or a review-first feature |
-| A broad finding set needs refutation | Audit pass | Surviving findings with guards checked and gaps named |
-| Changed files or risk lenses are too broad for one review pass | Review pass | One feature review packet or \`finalReview\` payload owned by the manager |
-| Test strategy or route coverage is unclear | Validation pass | Candidate commands or authorized raw command evidence |
-| A claim is single-source, surprising, high-stakes, or payload-bound | Verification pass | Per-claim keep, narrow, rewrite, or remove decisions |
-| Multiple implementation paths are plausible | Candidate pass | Candidate patches inspected and validated by the manager before use |
-
-Pass notes:
-
-- **Discovery**: workers read specific modules, routes, docs, commands, or risk
-  lenses; only evidenced claims become plan fields.
-- **Audit**: workers actively look for guards, lifecycle resets, deployment
-  constraints, and counterexamples before reporting a finding. A finding
-  without refutation work stays advisory or becomes a follow-up question.
-- **Review**: workers separate blocking findings from advisory notes; the
-  manager resolves conflicts and returns one review payload.
-- **Validation**: workers run only manager-authorized commands and report the
-  exact command, status, and raw outcome summary.
-- **Verification**: verifiers judge atomic claims against cited sources or
-  commands; do not ask a verifier to redesign the work or review the whole
-  feature.
-- **Candidate**: only with explicit user authorization plus isolated worktrees
-  or exact non-overlapping path ownership. Patches stay proposals until the
-  manager inspects, merges or rejects, and validates.
+| Repo shape is unclear before planning | Discovery | Evidenced requirements, decisions, targets, validation, or a review-first feature |
+| A broad finding set needs refutation | Audit | Findings that survive guard and counterexample checks |
+| Changed files or risk lenses exceed one review pass | Review | One feature review or final review payload |
+| Test strategy or route coverage is unclear | Validation | Candidate commands or authorized raw command evidence |
+| A claim is surprising, high-stakes, single-source, or payload-bound | Verification | Per-claim keep, narrow, rewrite, or remove decisions |
+| Multiple independent implementation paths are plausible | Candidate | Inspected candidate patches, never direct Flow completion |
+
+Discovery, audit, review, validation, and verification passes are read-only.
+Validation workers run only manager-authorized commands. Verification workers
+judge atomic claims rather than redesigning the work. Candidate passes require
+explicit user authorization plus an isolated worktree or exact non-overlapping
+path ownership; patches remain proposals until manager inspection and
+validation.
 
 ## Implementation pass decision
 
-Before implementing a broad, risky, or multi-target feature, record one manager
-decision. This is required even when the answer is "stay serial"; the point is
-to make the skipped parallelism visible instead of relying on memory.
-
-Use one of these decisions:
-
-- \`serial\`: the manager implements directly because slices overlap, the next
-  edit depends on one shared contract, or prompt/merge overhead would exceed the
-  value.
-- \`candidate-exact-path\`: one or more candidate workers may edit exact
-  non-overlapping paths or modules named by the manager.
-- \`candidate-worktree\`: one or more candidate workers may edit in isolated
-  worktrees, then the manager inspects and merges or rejects.
-- \`tournament\`: several isolated candidate implementations compete for the same
-  outcome; the manager filters by tests, review, and source inspection before
-  accepting one.
-- \`skipped\`: candidate workers were considered but rejected; include the reason,
-  such as shared fixtures, shared API contracts, unclear ownership, or no user
-  authorization for worker edits.
-
-Record the decision in the pass manifest with a stable pass id,
-\`decisionReason\`, \`writeScope\`, expected verification, and where any handoff or
-synthesis artifact will live. If the feature completes, include the compact
-record in the \`orchestrationPasses\` array of the \`flow_feature_complete\`
-payload. The runtime stores only compact accounting; full worker handoffs stay
-in manager-owned scratch files or the conversation.
-
-## When to stay serial
-
-- One file, command, or design question determines the next step.
-- Slices would share the same contracts, fixtures, or edit targets.
-- The manager can inspect the full scope faster than writing and checking
-  worker prompts.
-- The result would still need the same manual synthesis with no time saved.
-
-Do not fan out to keep agents busy. Every worker should reduce a named
-planning, validation, review, audit, or implementation uncertainty. A normal
-first pass is two to five workers with independent slices; use more only when
-the manifest stays countable and non-overlapping.
-
-## Modes
-
-When fanning out Flow work, select the matching hidden Flow agent by name. These
-workers are injected by the plugin config; invoke the named worker when it is
-available. Do not use generic subagents for Flow slices because Flow workers
-carry the permission boundaries for each mode.
-
-| Mode | Use agent | Worker output | Write access | Flow tools |
-| --- | --- | --- | --- | --- |
-| \`evidence\` | \`flow-evidence-worker\` | Coverage, facts, files inspected, confidence, gaps, suggested plan targets | No | \`flow_status\` only if needed |
-| \`review\` | \`flow-reviewer\` | Coverage, candidate findings or review slice summary, confidence, gaps | No | \`flow_status\` only if needed |
-| \`validation\` | \`flow-validation-worker\` | Command options or manager-authorized raw output, coverage, confidence, gaps | No code edits; commands only when explicitly allowed | \`flow_status\` only if needed |
-| \`audit\` | \`flow-audit-worker\` | Refuted or surviving finding candidates, guards checked, confidence, gaps | No | \`flow_status\` only if needed |
-| \`verifier\` | \`flow-verifier-worker\` | Per-claim verdicts against cited evidence or commands | No | \`flow_status\` only if needed |
-| \`candidate-implementation\` | \`flow-candidate-worker\` | Candidate patch summary from an isolated worktree or exact path-owned slice | Only with explicit user authorization plus isolation or exact non-overlapping path ownership | No state-changing Flow tools |
-
-Use worker-specific model routing where the installation can support it:
-\`OPENCODE_FLOW_READONLY_WORKER_MODEL\` for evidence, validation, and audit
-workers; \`OPENCODE_FLOW_REVIEW_WORKER_MODEL\` for reviewer and verifier workers;
-\`OPENCODE_FLOW_CANDIDATE_WORKER_MODEL\` for candidate implementation workers; and
-\`OPENCODE_FLOW_WORKER_MODEL\` as a fallback for all hidden Flow workers. Model IDs
-are OpenCode installation-specific (\`provider/model\`), so leave these unset when
-the configured provider is unknown. Spend stronger models where being wrong is
-expensive; read-heavy discovery slices tolerate the cheapest configured option,
-while verifier and review slices deserve the strongest.
-
-## Permission contract
-
-The plugin injects these hidden workers with the following permission values.
-\`Flow state tools\` means the \`flow_*\` rule, while \`Flow status\` documents the
-explicit \`flow_status\` exception.
-
-| Worker | Edit | Bash | Task | Skill | Flow state tools | Flow status |
-| --- | --- | --- | --- | --- | --- | --- |
-| \`flow-reviewer\` | deny | deny | deny | deny | deny | allow |
-| \`flow-evidence-worker\` | deny | deny | deny | deny | deny | allow |
-| \`flow-validation-worker\` | deny | ask | deny | deny | deny | allow |
-| \`flow-audit-worker\` | deny | ask | deny | deny | deny | allow |
-| \`flow-candidate-worker\` | ask | ask | deny | deny | deny | allow |
-| \`flow-verifier-worker\` | deny | ask | deny | deny | deny | allow |
-
-Do not fan out parallel \`flow_plan_save\`, \`flow_plan_approve\`,
-\`flow_run_start\`, \`flow_feature_complete\`, \`flow_feature_reset\`, or
-\`flow_session_close\` calls. Runtime locking protects files, but Flow accepts only
-one active feature result at a time.
-
-Workers may read files, inspect docs, run authorized read-only commands, and
-summarize evidence. Candidate implementation workers may edit only when the
-manager assigned an isolated worktree or exact path ownership that does not
-overlap sibling workers or manager edits. Workers must not edit \`.flow/**\`,
-must not call state-changing Flow tools, and must not approve work, close
-sessions, record Flow validation, or claim validation they did not run. A
-worker may report raw validation output it actually ran; the manager decides
-whether it is strong enough to record.
-
-## Stage 1 — Orient (serial)
-
-Call \`flow_status\` if a Flow session may already exist. Read enough files,
-schemas, docs, tests, commands, or artifacts to identify real slices. Keep the
-immediate blocker local: do not delegate the question that determines whether
-fan-out is even valid.
-
-Treat orientation as uncertainty reduction. Resolve environment uncertainty by
-inspecting the repo, running cheap commands, or assigning evidence workers; ask
-the user only when the remaining specification uncertainty would make a wrong
-slice expensive to undo. Do not split a vague goal into workers until the
-candidate slices have concrete targets, dependencies, and verification signals.
-
-## Stage 2 — Slice
-
-Split along whichever axis keeps slices independent: modules or path sets,
-route or endpoint groups, risk lenses, command surfaces, data ranges, or claim
-sets. Each slice needs a one-line scope, expected coverage, and a defined
-output the manager can check.
-
-For implementation slices, also name dependencies and write ownership before
-spawning. A real dependency edge means the later slice waits for a verified
-handoff or manager synthesis from the earlier slice; a shared file, fixture,
-schema, or public contract usually means the work should stay serial unless an
-isolated worktree is used. The manifest owns those edges through \`dependsOn\`
-and \`writeScope\`.
-
-## Stage 3 — Manifest (the pre-fan-out coverage gate)
-
-Before spawning, write a pass manifest: one row per slice, plus a totals check.
-Give the pass a stable id so later handoffs, verifier claims, and completion
-payloads can refer to the same work without replaying chat.
+Before editing a broad, risky, or multi-target feature, record one manager
+decision even when implementation stays serial. Keep \`candidateEligibility\`,
+\`candidateDecision\`, and \`decision\` as distinct fields.
 
-| Row id | Slice scope | Expected coverage | Mode | Depends on | Write scope | Verification tier | Handoff ref | Verification status | Synthesis ref |
+Classify candidate eligibility separately from the decision:
+
+| Eligibility | Meaning |
+| --- | --- |
+| \`eligible\` | At least one slice has independent ownership and practical validation. |
+| \`not_eligible\` | Shared state, files, tests, or judgment make isolation unsafe or wasteful. |
+| \`unknown\` | Orientation is incomplete; never use this on an \`implementation-decision\` record. |
+
+Use only these pairings on \`implementation-decision\` records:
+
+| Eligibility | Candidate decision | Implementation decision |
+| --- | --- | --- |
+| \`eligible\` | \`used\` | \`candidate-exact-path\`, \`candidate-worktree\`, or \`tournament\` |
+| \`eligible\` | \`skipped\` | \`skipped\` |
+| \`not_eligible\` | \`serial_required\` | \`serial\` |
+
+Candidate-shaped decisions and \`candidateDecision: "used"\` require execution
+evidence on the same record: \`kind: "candidate"\`, \`modes\` containing
+\`candidate-implementation\`, or \`candidateWorkerCount > 0\`. Keep
+\`candidateWorkerCount <= workerCount\` and
+\`verifierWorkerCount <= workerCount\`; one worker may fill both subtype counts.
+Never use \`parallel\` as an implementation decision. Reserve \`parallel\` for
+multi-worker read, audit, review, validation, or verification passes.
+
+Implementation decision meanings:
+
+- \`serial\`: the manager implements directly because work overlaps or depends on
+  one shared contract or mental model.
+- \`candidate-exact-path\`: workers own exact, disjoint path sets in one checkout.
+- \`candidate-worktree\`: isolated workers propose patches for manager integration.
+- \`tournament\`: isolated candidates compete; the manager selects using source
+  inspection, validation, and review.
+- \`skipped\`: candidate work was eligible, but coordination cost outweighed its
+  value. Do not use it for unsafe ownership; those cases are \`serial\`.
+
+Record \`decisionReason\` plus the applicable structured \`decisionFactors\`:
+\`shared_state\`, \`overlapping_files\`, \`small_slice\`,
+\`needs_manager_judgment\`, \`independent_surface\`, and
+\`validation_available\`. Also record a stable pass id, write scope, expected
+verification, and the handoff or synthesis location. Carry the bounded record
+into \`flow_feature_complete.orchestrationPasses\` when it materially shaped the
+feature; keep full handoffs and logs outside Flow state.
+
+## Candidate judgment
+
+Consider candidate workers when ownership is additive or localized, validation
+can run per slice, and the manager can safely inspect or reject the result.
+Separate frontend, core, docs, release, test, or binding surfaces are useful
+signals, but the actual path and contract boundaries decide eligibility.
+
+Stay serial when any of these apply:
+
+- One file, command, contract, migration, or design question determines the
+  next step.
+- Slices share state, callers, fixtures, generated output, lockfiles, tests, or
+  edit targets.
+- Persistence or lifecycle behavior requires one mental model.
+- Iterative debugging must happen in one checkout.
+- Prompt, handoff, merge, and verification cost exceeds direct work.
+- The manager would still need the same full synthesis with no coverage gain.
+
+Do not fan out to keep workers busy. Every worker must reduce a named
+uncertainty.
+
+## Worker count defaults
+
+Use bounded caps rather than worker-count targets:
+
+- Small implementation: zero or one worker.
+- Medium independent implementation: at most two workers.
+- Broad audit: three to five workers.
+- Broad implementation: two to four candidate workers with non-overlapping
+  ownership.
+- Medium- or high-risk final verification: one verifier.
+
+Use more only when the manifest remains countable and non-overlapping.
+`;
+
+// skills/flow/references/parallel-execution.md
+var parallel_execution_default = "# Parallel pass execution\n\nRead this after a pass decision and complete manifest. It defines Flow-native\nworker routing, permissions, and launch prompts. Do not use generic workers for\nFlow slices when the named hidden Flow worker is available.\n\n## Modes\n\n| Mode | Use worker | Output | Write access |\n| --- | --- | --- | --- |\n| `evidence` | `flow-evidence-worker` | Facts, coverage, confidence, gaps | None |\n| `review` | `flow-reviewer` | Review slice findings and coverage | None |\n| `validation` | `flow-validation-worker` | Proposed checks or authorized raw command evidence | Commands only when explicitly allowed |\n| `audit` | `flow-audit-worker` | Refuted or surviving findings and guards checked | None |\n| `verifier` | `flow-verifier-worker` | Per-claim verdicts against cited evidence | None |\n| `candidate-implementation` | `flow-candidate-worker` | Candidate patch from isolated or exact-path ownership | Explicitly authorized owned paths only |\n\n## Worker role contracts\n\nThese marked blocks are the canonical role instructions compiled into hidden\nworker prompts.\n\n<!-- flow-prompt:worker-role-evidence:start -->\n### Flow evidence worker\n\nInspect only the assigned read-only slice. Report observed facts and coverage;\ndo not edit files, expand scope, or synthesize the whole pass. Only the root\nmanager may mutate Flow state.\n<!-- flow-prompt:worker-role-evidence:end -->\n\n<!-- flow-prompt:worker-role-validation:start -->\n### Flow validation worker\n\nRun only manager-specified commands or propose focused checks. Do not edit\nfiles, expand scope, or synthesize completion. Only the root manager may mutate\nFlow state. Distinguish commands actually run from checks merely proposed.\n<!-- flow-prompt:worker-role-validation:end -->\n\n<!-- flow-prompt:worker-role-audit:start -->\n### Flow audit worker\n\nInspect only the assigned read-only slice and actively try to refute candidate\nfindings. Do not edit files, expand scope, or synthesize the whole audit. Only\nthe root manager may mutate Flow state. A blocking candidate must name the\nguards and mitigating paths checked.\n<!-- flow-prompt:worker-role-audit:end -->\n\n<!-- flow-prompt:worker-role-candidate:start -->\n### Flow candidate implementation worker\n\nWork only in the manager-assigned isolated worktree or exact non-overlapping\npath set. Preserve unrelated user changes. Never edit `.flow/**`, expand\nownership, claim completion, integrate other slices, commit, push, or publish.\nOnly the root manager may mutate Flow state. Your patch is a candidate for\nmanager inspection.\n<!-- flow-prompt:worker-role-candidate:end -->\n\n<!-- flow-prompt:worker-role-verifier:start -->\n### Flow verifier worker\n\nVerify only the assigned atomic claims against provided sources, commands,\ncounts, or current documentation. Resolve each source independently. Do not\ngenerate new scope, edit files, identify the originating worker, or synthesize\nthe whole pass. Only the root manager may mutate Flow state.\n<!-- flow-prompt:worker-role-verifier:end -->\n\n## Permission contract\n\nThe plugin injects these hidden workers. `Flow state tools` means every\nstate-changing `flow_*` call; `flow_status` is the explicit read-only exception.\n\n| Worker | Edit | Bash | Task | Skill | Flow state tools | `flow_status` |\n| --- | --- | --- | --- | --- | --- | --- |\n| `flow-reviewer` | deny | deny | deny | deny | deny | allow |\n| `flow-evidence-worker` | deny | deny | deny | deny | deny | allow |\n| `flow-validation-worker` | deny | ask | deny | deny | deny | allow |\n| `flow-audit-worker` | deny | ask | deny | deny | deny | allow |\n| `flow-candidate-worker` | ask | ask | deny | deny | deny | allow |\n| `flow-verifier-worker` | deny | ask | deny | deny | deny | allow |\n\nNever fan out `flow_plan_save`, `flow_plan_approve`, `flow_run_start`,\n`flow_feature_complete`, `flow_feature_reset`, or `flow_session_close`. Workers\nmust not edit `.flow/**`, approve work, record Flow evidence, or claim commands\nthey did not run. Candidate workers may edit only their authorized isolation or\nexact path scope.\n\n## Launch\n\nEvery worker prompt contains:\n\n```text\nOverall goal, context only: <goal>\nMode: evidence | review | validation | audit | verifier | candidate-implementation\nPass id and manifest row id: <stable ids>\nYour exact slice: <paths, modules, commands, claims, risk lens, or worktree>\nExpected coverage: <count, paths, range, or completeness rule>\nDependencies and write scope: <verified dependencies; approved write scope>\nDo: <bounded actions>\nDo not: call state-changing Flow tools, edit .flow/**, own sibling slices, or make the final Flow verdict.\nReturn only the Flow handoff in this exact shape:\n<matching handoff template copied verbatim from handoff-format.md>\n```\n\nHidden workers cannot load skills, references, or conversation history. Copy the\nmatching block from `handoff-format.md`; a filename alone is insufficient. Cite\npaths to any prerequisite synthesis artifact instead of restating accumulated\nchat. For current-doc research, require checks for versioned or time-sensitive\nfacts. Remind candidate workers not to revert unrelated changes.\n\nContinue only non-overlapping manager work while workers run.\n\n## Model routing\n\nWhen the installation supports worker-specific models, use\n`OPENCODE_FLOW_READONLY_WORKER_MODEL` for evidence, validation, and audit;\n`OPENCODE_FLOW_REVIEW_WORKER_MODEL` for review and verification;\n`OPENCODE_FLOW_CANDIDATE_WORKER_MODEL` for candidate implementation; and\n`OPENCODE_FLOW_WORKER_MODEL` as fallback. Model ids are installation-specific\n`provider/model` values. Leave overrides unset when the provider is unknown and\nprefer stronger models where incorrect findings or patches are expensive.\n";
+
+// skills/flow/references/parallel-manifest.md
+var parallel_manifest_default = `# Parallel pass manifest
+
+Read this only after \`parallel-decision.md\` selects a parallel or candidate
+pass. The manifest is the pre-fan-out coverage gate and the accounting contract
+for every worker result.
+
+## Orient and slice
+
+Call \`flow_status\` when a Flow session may exist. Read enough code, schemas,
+docs, tests, commands, or artifacts to identify real slices. Keep the question
+that determines whether fan-out is valid in manager context.
+
+Split by an axis that keeps work independent: modules or paths, routes or
+endpoints, risk lenses, commands, data ranges, or atomic claims. Give each slice
+a one-line scope, expected coverage, checkable output, dependencies, write
+scope, and verification tier. Shared files, fixtures, schemas, and public
+contracts normally stay serial unless candidate work uses isolated worktrees.
+
+## Write the manifest
+
+Before spawning, write one row per slice plus a totals or completeness check.
+Use stable pass and row ids so later handoffs, verification, synthesis, and
+completion accounting refer to the same work without replaying conversation
+history.
+
+| Row id | Slice | Expected coverage | Mode | Depends on | Write scope | Verification tier | Handoff ref | Verification status | Synthesis ref |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| \`runtime-read\` | \`src/core/**\` plus its tests | 14 files | \`evidence\` | none | none | accept locally | pending | pending | pending |
-| \`release-read\` | release contract: CI workflows, \`package.json\`, changelog | 6 files | \`evidence\` | none | none | verify once | pending | pending | pending |
-
-\`writeScope\` values in runtime accounting are \`none\`, \`manager-serial\`,
-\`exact-path\`, \`isolated-worktree\`, or \`mixed\`. Use \`manager-serial\` for a
-recorded serial implementation decision, \`exact-path\` for disjoint candidate
-edits in one checkout, and \`isolated-worktree\` for candidate work that must be
-merged back by the manager.
-
-- Count the total work items when countable: files, modules, routes, commands,
-  rows, findings, screenshots, or claims. Confirm slice counts add back to the
-  total, with no overlaps, gaps, empty slices, or ambiguous shared contracts.
-- If the scope cannot be counted, state the completeness rule instead, such as
-  "all changed files plus callers" or "all public commands plus release docs."
-- Assign each slice's verification tier now (see Stage 6). Deciding where a
-  wrong claim is expensive belongs before handoffs arrive, not after.
-- Record dependency edges now. A row may be spawned only after every \`depends on\`
-  row it names has returned a verified handoff or a manager synthesis that
-  explicitly settles the dependency.
-- Fix the slice map centrally before spawning if the gate does not reconcile.
-
-The manifest is also the accounting contract for the pass: N rows spawned means
-N handoffs collected and checked in Stage 5 before anything is synthesized.
-
-For implementation decisions, add a manifest row even when no worker is spawned:
-\`kind=implementation-decision\`, \`decision=serial\` or \`decision=skipped\`,
-\`workerCount=0\`, \`writeScope=manager-serial\`, and a concrete \`decisionReason\`.
-This is how Flow distinguishes deliberate serial work from forgotten candidate
-or verifier passes.
-
-Write the manifest where it survives the pass: the conversation is enough for a
-single bounded pass, but when a follow-up pass or a session resume is
-plausible, persist it with the synthesis (Stage 7) so the accounting can be
-reconstructed.
-
-## Stage 4 — Fan out
-
-Every worker prompt includes:
+| \`runtime-read\` | \`src/core/**\` plus tests | 14 files | \`evidence\` | none | none | accept locally | pending | pending | pending |
+| \`release-read\` | CI, package metadata, changelog | 6 files | \`audit\` | none | none | verify once | pending | pending | pending |
 
-\`\`\`text
-Overall goal, context only: <goal>
-Mode: evidence | review | validation | audit | verifier | candidate-implementation
-Pass id and manifest row id: <stable ids from the manifest>
-Your exact slice: <paths, modules, command, claim ids, risk lens, or worktree>
-Expected coverage: <count, paths, range, or complete question set>
-Dependencies and write scope: <verified dependencies, if any; none | manager-serial | exact-path | isolated-worktree>
-Do: <bounded actions>
-Do not: call state-changing Flow tools, edit .flow/**, own sibling slices, or make the final Flow verdict.
-Return only the Flow handoff in this exact shape:
-<matching handoff template copied verbatim from handoff-format.md>
-\`\`\`
+Use runtime \`writeScope\` values exactly: \`none\`, \`manager-serial\`, \`exact-path\`,
+\`isolated-worktree\`, or \`mixed\`.
 
-Hidden workers cannot load skills or read \`handoff-format.md\` themselves. The
-manager copies the matching handoff template into every worker prompt; a bare
-filename reference is not enough. Workers also cannot read the conversation, so
-prompts cite file paths — including any synthesis file from an earlier pass —
-instead of restating chat history.
-
-For research or current-doc slices, require source checks for versioned or
-time-sensitive facts. For implementation candidates, remind workers that other
-work may be active and that they must not revert unrelated changes.
-
-Continue non-overlapping manager work while workers run.
-
-## Stage 5 — Account
-
-Check every manifest row off against a returned handoff before synthesis. A
-worker that never returns, errors out, returns empty or unstructured output, or
-reports \`partial\` or \`blocked\` is a hole in the pass, and synthesizing around it
-silently drops a slice.
-
-For each row, fill in:
-
-- \`handoffRefs\`: worker ids, handoff file paths, command output artifacts, or
-  review packet location that the manager can re-open.
-- \`verificationStatus\`: \`not-needed\`, \`pending\`, \`passed\`, \`failed\`, \`mixed\`,
-  or \`downgraded\`.
-- \`outcome\`: \`accepted\`, \`rejected\`, \`partial\`, \`not-covered\`, or \`superseded\`.
-- \`synthesisRef\`: the manager-owned synthesis file or plan field that carries
-  the accepted result forward.
-
-Rows with no worker, such as serial or skipped implementation decisions, still
-need a row id, decision, reason, and outcome. They are not handoffs, but they
-are accounting.
-
-Worker failure ladder:
-
-1. Re-spawn once with a narrower slice and a note about what the first attempt
-   returned.
-2. If it fails again, cover the slice directly in the manager session.
-3. If it stays blocked, carry the slice into the synthesis explicitly as
-   not-covered. Never present results as if coverage were complete.
-
-## Stage 6 — Verify
-
-\`Status: success\` only says the worker believes its slice is done. Accept a
-handoff only after a cheap manager-side pass:
-
-- \`Status\` is present and terminal: \`success\`, \`partial\`, or \`blocked\`; empty or
-  unstructured output fails this check.
-- Coverage matches the assigned slice, or skips are explicit.
-- Important claims have concrete evidence and confidence tags.
-- Cited paths, commands, screenshots, URLs, or metrics resolve.
-- The evidence supports the claim, not just the topic.
-- Findings stay inside the worker's slice.
-- Headline counts can be recounted or traced.
-- Dependency claims cite the verified upstream handoff, synthesis, or source
-  artifact they depend on.
-- Candidate implementation claims identify whether they came from exact path
-  ownership or an isolated worktree, and whether the manager inspected the
-  resulting patch.
-- Contradictions between workers are either resolved or explicitly marked as
-  contested.
-
-Demote, drop, re-task, or verify claims that fail this pass.
-
-### Verification tiers
-
-One taxonomy decides how much verification a claim gets: the manifest assigns
-a default tier per slice, and this stage applies it per claim. Use the cheapest
-check that matches the risk:
-
-- **Accept locally**: low-risk claims with direct evidence that the manager can
-  cheaply inspect or recount.
-- **Verify once** with \`flow-verifier-worker\`: single-source, surprising,
-  inferred, low-confidence, citation-heavy, contested, or Flow-payload-bound
-  claims, including any count, benchmark, command result, or pass/fail claim a
-  Flow payload will rely on.
-- **Verify strongly**: blocking or release-sensitive claims and claims that
-  affect user data, security, persistence, permissions, public API behavior,
-  release behavior, or data loss. Use independent verifier checks, manager-run
-  commands, or direct artifact inspection strong enough to settle the claim.
-- **Do not accept**: claims without concrete evidence, claims outside the
-  assigned slice, claims contradicted by inspected artifacts, or claims where
-  the cited evidence supports only the topic rather than the assertion.
-
-Verifier prompts use stable claim ids, one atomic assertion per id, the cited
-source or command for each id, and the exact acceptance question. Do not
-include the generator's reasoning unless that reasoning is the thing being
-verified, do not say which worker produced the claim, and do not ask a
-verifier to redesign the work or review the whole feature.
-
-## Stage 7 — Synthesize
-
-Apply the manager synthesis barrier before presenting or recording anything:
-
-- Preserve confidence: verified, single-sourced, inferred, and unresolved claims
-  stay distinct when it matters.
-- When workers disagree, inspect the cited artifact or rerun the cited command
-  instead of arbitrating from summaries. Do not average conflicting claims.
-- Run the strongest practical local check for the deliverable.
-- Re-read critical files or docs that will be cited in the final decision.
-- Move only distilled, evidence-backed claims forward; raw handoffs remain
-  candidate evidence, not a plan, review, completion payload, or final answer.
-- Record gaps honestly instead of converting missing evidence into success
-  language.
-
-Where accepted evidence goes:
-
-- Planning evidence becomes \`requirements\`, \`decisions\`, feature \`targets\`,
-  feature \`validation\`, or plan notes — only when the source and scope are
-  clear. Unverified broad findings become a review-first feature, not a fix
-  plan.
-- Validation evidence may become \`validationRun\` only when the worker was
-  explicitly authorized to run the command and reported the exact command,
-  status, and raw outcome summary.
-- Review evidence informs \`featureReviewDepth\` plus \`featureReview\`, or \`finalReview\`, but the manager
-  owns the pass/fail verdict and must resolve blockers, contradictions, and
-  coverage gaps before returning the payload.
-- Audit evidence becomes findings only after refutation; blocking findings need
-  guards checked, deployment context, and evidence that the current code
-  exhibits the behavior.
-- Candidate patches are not Flow evidence until the manager inspects, merges or
-  rejects them, and validates the main Flow-managed workspace.
-
-When completing a feature, include compact pass accounting in
-\`flow_feature_complete.orchestrationPasses\` for any pass or implementation
-decision that materially affected the feature:
+Before launch:
 
-\`\`\`json
-{
-  "id": "feature-id-implementation-decision",
-  "kind": "implementation-decision",
-  "decision": "serial",
-  "decisionReason": "Shared schema and tests made exact path ownership unsafe.",
-  "modes": [],
-  "workerCount": 0,
-  "candidateWorkerCount": 0,
-  "verifierWorkerCount": 0,
-  "sliceIds": ["manager-implementation"],
-  "dependsOn": [],
-  "writeScope": "manager-serial",
-  "handoffRefs": [],
-  "verificationStatus": "not-needed",
-  "outcome": "accepted",
-  "synthesisRef": "/tmp/flow-pass-synthesis.md"
-}
-\`\`\`
+- Reconcile countable work such as files, routes, commands, rows, findings,
+  screenshots, or claims. Slice totals must have no overlaps, gaps, or empty
+  rows.
+- When scope is not countable, state a completeness rule such as "all changed
+  files plus callers" or "all public commands plus release docs."
+- Assign a verification tier before handoffs arrive.
+- Record dependency edges. Spawn a dependent row only after its prerequisite
+  has a verified handoff or manager synthesis that settles the dependency.
+- Fix an unreconciled slice map centrally before fan-out.
+
+N spawned rows require N collected and checked handoffs before synthesis.
+
+## Implementation decision rows
 
-For candidate and verifier passes, use \`kind: "candidate"\` or
-\`kind: "verification"\`, list the worker modes used, worker counts, slice ids,
-handoff refs, dependency ids, verification status, and whether the manager
-accepted, rejected, downgraded, or superseded the pass. The runtime aggregates
-these compact records into \`session.budget.orchestration\` and stores them on
-the feature history entry. Do not store full handoffs, long logs, or scratch
-tables in \`.flow/session.json\`.
-
-Persist the manifest and the synthesis when another pass may follow or the
-session is long enough to be compacted or resumed: write the distilled result —
-the accounted manifest, accepted claims with evidence and confidence, dropped
-claims with one-line reasons, and open gaps — into plan prose fields or a
-manager-owned scratch file outside both \`.flow/**\` and the repository worktree,
-such as a file in the OS temporary directory. The runtime owns the \`.flow/**\`
-layout, and scratch files left in the worktree end up staged or reviewed as if
-they were project changes. Follow-up worker prompts cite that path; files are
-the only shared memory between passes.
-
-## Stage 8 — Extend or stop
-
-Stop after a pass when:
-
-- the manifest's coverage rule is satisfied and every row is accounted for.
-- accepted claims are evidenced, scoped, and confidence-labeled.
-- material single-source, contested, high-stakes, or payload-bound claims have
-  been verified or downgraded.
-- every dependency edge named in the manifest has either a verified upstream
-  result or an explicit not-covered outcome.
-- implementation pass decisions are recorded, including skipped candidate
-  workers and the reason they were skipped.
-- remaining gaps are explicit and do not block the Flow artifact being produced.
-
-Start a bounded follow-up pass only when:
-
-- the original slice map missed material scope.
-- workers disagree on a claim that affects the Flow decision.
-- a high-stakes or payload-bound claim needs verification.
-- a dependency has just become verified and now unlocks a dependent slice.
-- a candidate patch was rejected and an isolated alternative is still cheaper
-  than serial repair.
-- a first pass exposes a narrower implementation or validation slice worth
-  isolating.
-
-Run at most one routine follow-up pass. Extra passes need an explicit manager
-reason, such as a high-stakes verifier check or a newly discovered bounded
-slice. Do not recurse by default: if a worker says it needs another worker, the
-manager decides whether that is a follow-up pass and writes the next bounded
-prompt, starting again from the manifest.
+Add an implementation decision row even when no worker is spawned. Record:
+
+- \`kind: "implementation-decision"\`
+- the valid decision, eligibility, and candidate-decision pairing from
+  \`parallel-decision.md\`
+- \`decisionFactors\`, \`decisionReason\`, and \`writeScope: "manager-serial"\`
+- \`workerCount: 0\`, a stable row id, verification status, and outcome
+
+When \`candidateDecision\` is \`used\`, record actual candidate execution evidence
+and raise worker counts accordingly. A zero-worker record cannot claim candidate
+use. Subtype counts may not exceed total worker count.
+
+## Persistence
+
+The conversation is sufficient for one bounded pass. When a follow-up pass or
+session resume is plausible, persist the accounted manifest with the synthesis
+in a manager-owned temporary artifact outside \`.flow/**\` and outside the repo
+worktree. The runtime stores bounded accounting, not complete worker handoffs.
+`;
+
+// skills/flow/references/parallel-orchestration.md
+var parallel_orchestration_default = `# Parallel orchestration
+
+Use this index after a serial orientation pass shows that independent slices
+may reduce a named discovery, validation, review, audit, verification, or
+implementation uncertainty. The root manager owns the Flow session and every
+state-changing \`flow_*\` call throughout the pass.
+
+## Load only the selected branch
+
+1. Read \`parallel-decision.md\` whenever deciding whether work should fan out.
+2. Stop loading parallel references when the decision is serial. Record the
+   implementation decision when the active feature requires one.
+3. After selecting a parallel or candidate pass, read
+   \`parallel-manifest.md\`, then \`parallel-execution.md\`.
+4. When handoffs return, read \`parallel-synthesis.md\` before accepting claims,
+   recording evidence, or presenting a result.
+5. Copy exactly one matching worker response template from \`handoff-format.md\`
+   into each worker prompt. Hidden workers cannot load skills or references.
+6. Read \`parallel-pass-example.md\` only when a concrete end-to-end example is
+   needed.
+
+Do not preload the manifest, worker, and synthesis runbooks merely because a
+task could be parallel. The decision reference is enough to keep serial work
+serial.
+
+## Pass routing
+
+| Situation | Pass | Typical worker |
+| --- | --- | --- |
+| Repo shape is unclear before planning | Discovery | \`flow-evidence-worker\` |
+| A broad finding set needs refutation | Audit | \`flow-audit-worker\` |
+| Changed files or risk lenses exceed one review pass | Review | \`flow-reviewer\` |
+| Test strategy or route coverage is unclear | Validation | \`flow-validation-worker\` |
+| A claim is surprising, high-stakes, single-source, or payload-bound | Verification | \`flow-verifier-worker\` |
+| An authorized independent implementation slice exists | Candidate | \`flow-candidate-worker\` |
+
+Only the manager synthesizes the pass, decides whether evidence is sufficient,
+integrates candidate patches, records Flow state, or returns the final verdict.
 `;
 
 // skills/flow/references/parallel-pass-example.md
 var parallel_pass_example_default = `# Parallel pass example
 
-Use this example after \`parallel-orchestration.md\` when a broad Flow task needs a
-concrete pass shape. The project below is illustrative; derive your own slices
-from the actual repo during serial orientation.
+Use this example only after \`parallel-orchestration.md\` routes a broad Flow task
+to fan-out. It illustrates the manifest, execution, and synthesis references;
+derive real slices from the actual repo during serial orientation.
 
 Goal: review whether a web app's API error handling is consistent before
 planning a refactor.
@@ -721,18 +539,21 @@ keeps only verified or clearly labeled claims, and records one artifact such as
 a plan decision, review payload, or docs patch. Raw handoffs and unverified
 suggestions do not move into the next pass or user-facing answer.
 
-If the pass shaped feature execution, the manager records compact accounting in
+If the pass shaped feature execution, the manager records bounded accounting in
 \`flow_feature_complete.orchestrationPasses\`, such as pass id
 \`api-error-handling-read\`, kind \`review\`, worker count \`3\`, slice ids
 \`routes-auth\`, \`routes-billing\`, and \`routes-admin\`, verification status
 \`mixed\` or \`passed\`, and a synthesis ref pointing to the manager-owned summary.
 `;
 
+// skills/flow/references/parallel-synthesis.md
+var parallel_synthesis_default = "# Parallel pass synthesis\n\nRead this when worker handoffs return. Account for every manifest row, verify\nmaterial claims, and let only the root manager synthesize or mutate Flow state.\n\n## Account for handoffs\n\nCheck each manifest row before synthesis. A missing, errored, empty,\nunstructured, malformed, `partial`, or `blocked` response is a coverage gap.\nFor each row record:\n\n- `handoffRefs`: worker ids or reopenable artifact locations.\n- `verificationStatus`: `not-needed`, `pending`, `passed`, `failed`, `mixed`,\n  or `downgraded`.\n- `outcome`: `accepted`, `modified`, `rejected`, `partial`, `not-covered`, or\n  `superseded`.\n- `synthesisRef`: the manager-owned result that carries accepted work forward.\n\nSerial and skipped decision rows have no handoff, but still require an id,\ndecision, reason, verification status, and outcome.\n\nWorker failure ladder:\n\n1. Retry once with a narrower slice and the first attempt's concrete gap.\n2. Cover the slice directly in manager context if the retry fails.\n3. Carry a persistent blocker into synthesis as `not-covered`.\n\nNever present incomplete coverage as a complete pass.\n\n## Accept and verify\n\nTreat worker `Status: success` as a claim, not proof. Accept a handoff only when:\n\n- status is exactly `success`, `partial`, or `blocked` and every required\n  section is non-empty;\n- coverage matches the assigned slice or names every omission;\n- important claims have concrete evidence and confidence;\n- paths, commands, screenshots, URLs, counts, and metrics resolve;\n- evidence supports the assertion rather than merely its topic;\n- findings stay inside the assigned slice;\n- dependency claims cite a verified upstream handoff or synthesis;\n- candidate work identifies exact-path or isolated-worktree ownership and the\n  manager's patch inspection result;\n- contradictions are settled from source evidence or marked contested.\n\nDemote, drop, retry, or independently verify claims that fail these checks.\n\n### Verification tiers\n\nAssign the cheapest tier that matches the consequence of error:\n\n- **Accept locally**: direct, low-risk evidence the manager can cheaply inspect\n  or recount.\n- **Verify once**: use `flow-verifier-worker` for surprising, inferred,\n  low-confidence, citation-heavy, contested, single-source, or\n  Flow-payload-bound claims, including counts and command results.\n- **Verify strongly**: independently inspect or rerun evidence for blocking,\n  release-sensitive, data-loss, security, persistence, permissions, or public\n  API claims.\n- **Do not accept**: unsupported, out-of-scope, contradicted, or topic-only\n  evidence.\n\nVerifier prompts use stable ids, one atomic assertion and cited source or\ncommand per id, and one exact acceptance question. Do not reveal the generating\nworker or ask the verifier to redesign the work.\n\n## Synthesize\n\nBefore presenting or recording a result:\n\n- Preserve meaningful distinctions between verified, single-source, inferred,\n  and unresolved claims.\n- Resolve worker conflicts from the cited artifact or command; never average\n  contradictory summaries.\n- Run the strongest practical local check for the deliverable.\n- For medium- or high-risk broad implementation, use one verifier after manager\n  synthesis to check planned coverage, worker validation claims, changed code,\n  generated artifacts, and plausible test coverage.\n- Re-read critical sources that support the final decision.\n- Move only distilled evidence forward and name remaining gaps honestly.\n\nPlanning evidence may become requirements, decisions, targets, validation, or a\nreview-first feature. Authorized command evidence may become `validationRun`\nonly with exact command, status, and observed result. Review workers inform but\ndo not own the final review payload. Audit findings must survive refutation.\nCandidate patches become usable only after manager inspection, integration, and\nvalidation in the Flow-managed workspace.\n\n## Record bounded accounting\n\nUse the canonical manager record in `handoff-format.md` for every material pass\nor implementation decision. Runtime semantics are:\n\n- `candidateDecision: \"used\"` requires actual candidate execution evidence.\n- `candidateDecision: \"serial_required\"` means candidate work was ineligible.\n- `candidateEligibility: \"eligible\"` plus `candidateDecision: \"skipped\"`\n  increments skipped-candidate accounting.\n- Candidate and verifier pass counts come from actual pass kind, mode, or worker\n  count evidence, never a decision label alone.\n\nKeep full handoffs, scratch tables, and long logs out of `.flow/session.json`.\nWhen another pass or resume is likely, persist the accounted manifest, accepted\nclaims with evidence and confidence, dropped claims with short reasons, and\nopen gaps in a manager-owned temporary file outside `.flow/**` and the repo\nworktree. Follow-up prompts cite that artifact; do not replay the transcript.\n\n## Extend or stop\n\nStop when every manifest row and dependency is accounted for, accepted claims\nare evidenced and scoped, material claims have the required verification, and\nremaining gaps are explicit but non-blocking.\n\nStart at most one routine follow-up pass when material scope was missed,\nworkers disagree on a decision-changing claim, a high-impact claim needs more\nverification, a newly verified dependency unlocks a slice, or a rejected\ncandidate still has a cheaper isolated alternative. Extra passes require a\nspecific high-impact reason. Workers never recursively launch workers; the\nmanager creates any follow-up manifest and prompt.\n";
+
 // skills/flow/references/recovery-playbook.md
 var recovery_playbook_default = '# Recovery playbook\n\nUse this when a Flow tool returns `status: "error"`, a blocker, or a `nextAction` that conflicts with memory.\n\n## First response\n\n1. Re-anchor with `flow_status`.\n2. Read the returned `summary`, `recovery`, `lastError`, and active feature.\n3. Fix the cause, then retry the smallest valid Flow action.\n\n## Common cases\n\n- `missing_session`: start with `flow_plan_save` using the user\'s goal.\n- `missing_goal`: ask for a concrete goal before planning.\n- `Approved plans cannot be changed`: use `flow_feature_reset` when only affected features need another pass; otherwise close and start a new goal.\n- `No feature is currently running`: call `flow_run_start` before completing.\n- `already in progress`: finish, reset, or block the active feature before starting another.\n- `Completion requires recorded validation evidence`: run real validation and include at least one passing `validationRun`.\n- `Completion requires all recorded validation to pass`: fix failures and rerun. Do not relabel failed checks as passed.\n- `Non-final feature completion requires targeted validation`: use `validationScope: "targeted"` for ordinary features.\n- `Final feature completion requires broad validation`: run the project-level gate and use `validationScope: "broad"`.\n- `Feature review depth ... does not meet the plan requirement`: rerun review\n  at the feature\'s planned depth or reset/replan if the depth was chosen\n  incorrectly.\n- `Completion requires a passing featureReview`: run or request a real review and include a passing `featureReview` only when there are no blocking findings.\n- `Review retry budget exhausted`: stop and report the remaining blocker. Do\n  not keep patching; reset or replan only after explicit user direction.\n- `Final feature completion requires a finalReview`: perform final review and include `finalReview`.\n- `Final review depth must match the plan policy`: use `reviewDepth` equal to the approved plan\'s `finalReviewPolicy`; valid final-review values are `broad` and `detailed`.\n- `Cannot close ... unfinished features`: complete, reset, defer, or abandon honestly. Do not mark completed while work remains.\n\n## Reset guidance\n\nUse `flow_feature_reset` when the active or completed work was built on the wrong assumption, validation revealed a design issue, dependencies need to be rerun, or dependent features must be invalidated. Resetting a feature also resets its dependents.\n\n## Closure guidance\n\nUse `flow_session_close`:\n\n- `completed`: only after all planned features are complete.\n- `deferred`: the user intentionally postpones unfinished work.\n- `abandoned`: the session should be archived without claiming delivery.\n\nAfter closure, the active `.flow/session.json` is removed and the archived JSON is stored under `.flow/history/`.\n';
 
 // skills/flow/SKILL.md
-var SKILL_default = "---\nname: flow\ndescription: Manage the end-to-end Flow loop for skills-first OpenCode work. Use when a user asks for Flow-guided delivery from goal to completion, resumable autonomous delivery, or resuming or closing a Flow session. For plan-only work use flow-plan; for executing one approved feature use flow-run.\n---\n\n# Flow\n\nUse Flow as a minimal state ledger, not as a framework. Skills provide judgment; the runtime only records the approved plan, active feature, validation evidence, review evidence, and closure.\n\nRouting: this manager skill owns the whole loop and every state-changing `flow_*` call. Load `flow-plan` alone for plan-only requests and `flow-run` alone when an approved plan needs one feature executed. Answer status-only questions with `flow_status`; no skill load is needed. `flow-test`, `flow-deslop`, and `flow-ui-quality` are optional helpers loaded from inside the loop; `flow-commit` is user-triggered only and never part of the autonomous loop.\n\n## Loop\n\n1. Call `flow_status` first. Trust its active session and next action over conversation memory.\n   If the result includes `setup.skills`, follow the Skill Availability rules\n   below before loading any Flow skill.\n   If it includes `session.resumePacket` or `session.budget.phaseBoundary`, stop\n   and report the resume instructions unless this is a fresh user invocation\n   explicitly resuming the session. Only then may the next `flow_run_start` use\n   `phaseBoundaryAck: true`.\n2. If there is no active session and the user gave a goal, load `flow-plan`, save a plan with `flow_plan_save`, then approve it with `flow_plan_approve` only after explicit user approval or prior authorization for autonomous implementation. If there is no goal, ask for one.\n3. Load `flow-run`, call `flow_run_start`, implement exactly one feature, validate it, and prepare a `flow_feature_complete` payload. For validation-heavy, regression-sensitive, browser QA, route QA, or failure-prone work, use `flow-test` to choose and summarize evidence before completion.\n4. Load `flow-review` for the required feature review. Send a compact review\n   packet, not the accumulated root transcript. The reviewer reports\n   `featureReviewDepth` and `featureReview`; the manager records both inside\n   `flow_feature_complete`.\n5. On the final feature, run broad validation and include `finalReview` in the same `flow_feature_complete` call. Its `reviewDepth` must match the plan's `finalReviewPolicy`.\n6. After all features are complete, archive the session with `flow_session_close` using `kind: \"completed\"`.\n\nUse `references/parallel-orchestration.md` for broad read-only discovery, audit, validation, review, verification, or candidate implementation passes. It is the whole pass playbook — orient, slice, manifest, fan out, account, verify, synthesize, extend or stop — and its `references/handoff-format.md` companion holds the worker report templates the manager pastes into prompts. Hidden Flow workers are injected by plugin config; invoke the named worker when it is available. The manager owns every `flow_*` state change.\n\nDo not commit, push, amend, rebase, publish, or mutate releases during the\nautonomous Flow loop. Load `flow-commit` only when the user explicitly asks for\ncommit preparation or commit creation.\n\n## Skill Availability\n\nIf `flow_status` returns `setup.skills`, report that setup status and stop\nnative-loading Flow skills in the current OpenCode startup. Missing, incomplete,\nor outdated managed skills require a sync/restart cycle before their native skill\ninstructions can be trusted by the running process. Public command bundles are\nself-contained and may continue when the command prompt already embeds the\nrequired Flow instructions.\n\nIf optional helper skills such as `flow-test`, `flow-deslop`, or\n`flow-ui-quality` are unavailable, continue only with explicit coverage gaps. Do\nnot copy their rubrics into another skill and do not claim their quality checks\nwere completed.\n\n## Runtime Surface\n\n- `flow_status`: read the active session.\n- `flow_plan_save`: create a session and/or save a draft plan.\n- `flow_plan_approve`: lock the draft plan.\n- `flow_run_start`: start one runnable feature.\n- `flow_feature_complete`: record completion or a real blocker with validation and review evidence.\n- `flow_feature_reset`: reset one feature and its dependents.\n- `flow_session_close`: archive the active session as `completed`, `deferred`, or `abandoned`.\n\nThere is no `flow_context`, no separate review-record tool, and no multi-session activation surface. The single active source of truth is `.flow/session.json`; closed sessions are archived under `.flow/history/`.\n\nPlanning and running require loaded Flow tools; do not simulate plan approval or feature completion when the runtime is unavailable. Review may still return advisory output when tools, skills, or references are stale or unavailable, but the manager must not record it as Flow-gated evidence.\n\n## Hard Gates\n\n- Approved plans are immutable. To change direction, reset affected features or close the session and start a new goal.\n- Only one feature can be active at a time.\n- Each feature's planned `reviewDepth` is the minimum accepted\n  `featureReviewDepth` for completion.\n- Completion requires at least one passing `validationRun` entry.\n- Non-final completion requires `validationScope: \"targeted\"`.\n- Final completion requires `validationScope: \"broad\"` and a passing `finalReview`.\n- Every completed feature requires a passing `featureReview` with no blocking findings.\n- Failed reviews pause the loop by default. Autonomous repair may make at most\n  one repair plus one retry review before stopping.\n- Phase boundaries stop the current root session; resume from\n  `.flow/session.json` in a fresh OpenCode session.\n- `flow_session_close` accepts `kind: \"completed\"` only after an approved plan has passed final completion.\n\n## Budget And Retry Boundaries\n\nFlow enforces review retry counts in the runtime ledger and tracks completed\nfeature counts as telemetry only. The current OpenCode plugin surface does not\nexpose per-turn token usage to Flow; when usage is visible in the host UI or\nlogs, stop the current autonomous loop once the root session is large enough to\nthreaten latency or cost and report a compact handoff instead of continuing.\nTreat high visible tokens, high non-cache tokens, or repeated reviewer fan-out\nas a reason to finish the current feature, emit the resume packet, and continue\nin a fresh session.\n\n## Recovery\n\n- Confused state: call `flow_status` and follow `nextAction`.\n- Wrong assumption or failed implementation path: use `flow_feature_reset` for the feature and dependents, then rerun from the corrected plan.\n- Missing validation or review evidence: gather real evidence, then call `flow_feature_complete`.\n- Approved plan is materially wrong: reset the affected features, save a revised plan if the session is back in planning; otherwise close and start a new goal.\n- Unknown runtime error: read `summary` and `recovery`; see `references/recovery-playbook.md` for common cases.\n\nNever fabricate validation output, backfill review approval you did not perform, or close as `deferred`/`abandoned` merely to avoid an unfinished-work blocker.\n";
+var SKILL_default = "---\nname: flow\ndescription: Manage the end-to-end Flow loop for skills-first OpenCode work. Use when a user asks for Flow-guided delivery from goal to completion, resumable autonomous delivery, or resuming or closing a Flow session. For plan-only work use flow-plan; for executing one approved feature use flow-run.\n---\n\n# Flow\n\nUse Flow as a minimal state ledger, not as a framework. Skills provide judgment; the runtime only records the approved plan, active feature, validation evidence, review evidence, and closure.\n\nRouting: this manager skill owns the whole loop and every state-changing `flow_*` call. Load `flow-plan` alone for plan-only requests and `flow-run` alone when an approved plan needs one feature executed. Answer status-only questions with `flow_status`; no skill load is needed. `flow-test`, `flow-deslop`, and `flow-ui-quality` are optional helpers loaded from inside the loop; `flow-commit` is user-triggered only and never part of the autonomous loop.\n\n## Loop\n\n1. Call `flow_status` first. Trust its active session and next action over conversation memory.\n   If the result includes `setup.skills`, follow the Skill Availability rules\n   below before loading any Flow skill.\n   If it includes `session.resumePacket` or `session.budget.phaseBoundary`, stop\n   and report the resume instructions unless this is a fresh user invocation\n   explicitly resuming the session. Only then may the next `flow_run_start` use\n   `phaseBoundaryAck: true`.\n2. If there is no active session and the user gave a goal, load `flow-plan`, save a plan with `flow_plan_save`, then approve it with `flow_plan_approve` only after explicit user approval or prior authorization for autonomous implementation. If there is no goal, ask for one.\n3. Load `flow-run`, call `flow_run_start`, implement exactly one feature, validate it, and prepare a `flow_feature_complete` payload. For validation-heavy, regression-sensitive, browser QA, route QA, or failure-prone work, use `flow-test` to choose and summarize evidence before completion.\n4. Load `flow-review` for the required feature review. Send a bounded review\n   packet, not the accumulated root transcript. The reviewer reports\n   `featureReviewDepth` and `featureReview`; the manager records both inside\n   `flow_feature_complete`.\n5. On the final feature, run broad validation and include `finalReview` in the same `flow_feature_complete` call. Its `reviewDepth` must match the plan's `finalReviewPolicy`.\n6. After all features are complete, archive the session with `flow_session_close` using `kind: \"completed\"`.\n\nFor broad discovery, audit, validation, review, verification, or candidate work,\nuse `references/parallel-orchestration.md` as the routing index. Read\n`references/parallel-decision.md` first. Load\n`references/parallel-manifest.md` and `references/parallel-execution.md` only\nafter selecting fan-out, then read `references/parallel-synthesis.md` when\nhandoffs return. Paste one matching template from\n`references/handoff-format.md` into each worker prompt. Hidden Flow workers are\ninjected by plugin config; invoke the named worker when available. The manager\nowns every `flow_*` state change.\n\nDo not commit, push, amend, rebase, publish, or mutate releases during the\nautonomous Flow loop. Load `flow-commit` only when the user explicitly asks for\ncommit preparation or commit creation.\n\n## Skill Availability\n\nIf `flow_status` returns `setup.skills`, report that setup status and stop\nnative-loading Flow skills in the current OpenCode startup. Missing, incomplete,\nor outdated managed skills require a sync/restart cycle before their native skill\ninstructions can be trusted by the running process. Public command bundles are\nself-contained and may continue when the command prompt already embeds the\nrequired Flow instructions.\n\nIf optional helper skills such as `flow-test`, `flow-deslop`, or\n`flow-ui-quality` are unavailable, continue only with explicit coverage gaps. Do\nnot copy their rubrics into another skill and do not claim their quality checks\nwere completed.\n\n## Runtime Surface\n\n- `flow_status`: read the active session.\n- `flow_plan_save`: create a session and/or save a draft plan.\n- `flow_plan_approve`: lock the draft plan.\n- `flow_run_start`: start one runnable feature.\n- `flow_feature_complete`: record completion or a real blocker with validation and review evidence.\n- `flow_feature_reset`: reset one feature and its dependents.\n- `flow_session_close`: archive the active session as `completed`, `deferred`, or `abandoned`.\n\nThere is no `flow_context`, no separate review-record tool, and no multi-session activation surface. The single active source of truth is `.flow/session.json`; closed sessions are archived under `.flow/history/`.\n\nPlanning and running require loaded Flow tools; do not simulate plan approval or feature completion when the runtime is unavailable. Review may still return advisory output when tools, skills, or references are stale or unavailable, but the manager must not record it as Flow-gated evidence.\n\n## Hard Gates\n\n- Approved plans are immutable. To change direction, reset affected features or close the session and start a new goal.\n- Only one feature can be active at a time.\n- Each feature's planned `reviewDepth` is the minimum accepted\n  `featureReviewDepth` for completion.\n- Completion requires at least one passing `validationRun` entry.\n- Non-final completion requires `validationScope: \"targeted\"`.\n- Final completion requires `validationScope: \"broad\"` and a passing `finalReview`.\n- Every completed feature requires a passing `featureReview` with no blocking findings.\n- Failed reviews pause the loop by default. Autonomous repair may make at most\n  one repair plus one retry review before stopping.\n- Phase boundaries stop the current root session; resume from\n  `.flow/session.json` in a fresh OpenCode session.\n- `flow_session_close` accepts `kind: \"completed\"` only after an approved plan has passed final completion.\n\n## Recovery\n\n- Confused state: call `flow_status` and follow `nextAction`.\n- Wrong assumption or failed implementation path: use `flow_feature_reset` for the feature and dependents, then rerun from the corrected plan.\n- Missing validation or review evidence: gather real evidence, then call `flow_feature_complete`.\n- Approved plan is materially wrong: reset the affected features, save a revised plan if the session is back in planning; otherwise close and start a new goal.\n- Unknown runtime error: read `summary` and `recovery`; see `references/recovery-playbook.md` for common cases.\n\nNever fabricate validation output, backfill review approval you did not perform, or close as `deferred`/`abandoned` merely to avoid an unfinished-work blocker.\n";
 
 // skills/flow-commit/SKILL.md
 var SKILL_default2 = `---
@@ -981,9 +802,13 @@ var parallel_discovery_default = `# Parallel discovery
 
 Use this only after a serial orientation pass has identified the repo shape and the likely slices. Workers are read-only evidence gatherers; the planner owns the plan.
 
-For broad parallel passes, also load \`../../flow/references/parallel-orchestration.md\`.
-Use its pass manifest as the pre-fan-out coverage gate and
-\`../../flow/references/handoff-format.md\` response shapes.
+For broad parallel passes, start with
+\`../../flow/references/parallel-orchestration.md\`. If it selects fan-out, use
+\`../../flow/references/parallel-manifest.md\` as the coverage gate,
+\`../../flow/references/parallel-execution.md\` for worker prompts, and
+\`../../flow/references/parallel-synthesis.md\` when handoffs return. Copy the
+matching \`../../flow/references/handoff-format.md\` response shape into each
+prompt.
 
 ## Good slices
 
@@ -1007,8 +832,8 @@ config, or release surfaces in the pass manifest.
 
 ## Manifest and prompts
 
-Write the pass manifest and the worker prompts exactly as Stages 3 and 4 of
-\`../../flow/references/parallel-orchestration.md\` define them: one manifest row
+Write the pass manifest and worker prompts as \`parallel-manifest.md\` and
+\`parallel-execution.md\` define them: one manifest row
 per slice with expected coverage, dependencies, write scope, and a verification
 tier, and a self-contained prompt per worker naming the mode (usually
 \`evidence\`), the exact slice, and the expected coverage. Discovery-specific
@@ -1035,7 +860,7 @@ Convert only evidence-backed work into plan fields:
 If workers disagree, inspect the source artifact yourself. If a candidate finding lacks a concrete citation or refutation pass, make it a review-first deliverable rather than a fix feature.
 
 Apply the manager synthesis barrier from
-\`../../flow/references/parallel-orchestration.md\`: only distilled,
+\`../../flow/references/parallel-synthesis.md\`: only distilled,
 evidence-backed claims become plan fields.
 `;
 
@@ -1044,7 +869,7 @@ var plan_quality_checklist_default = `# Plan quality checklist
 
 Use this checklist before \`flow_plan_save\` and again before approval if the plan
 changed during discussion. The goal is not a long planning artifact; it is a
-compact plan another agent can execute without rediscovering the work.
+concise plan another agent can execute without rediscovering the work.
 
 ## Must pass
 
@@ -1347,14 +1172,19 @@ description: "Use when Flow work needs planning before implementation: a new goa
 
 # Flow Plan
 
-Use this skill before implementation. The output is a compact plan the runtime can enforce and future agents can execute without rediscovering the goal.
+Use this skill before implementation. The output is a concise plan the runtime can enforce and future agents can execute without rediscovering the goal.
+
+## Planning runtime availability
 
 If \`flow_plan_save\` or \`flow_plan_approve\` is unavailable, stop and tell the user to check that \`opencode-plugin-flow\` is loaded in OpenCode. Planning requires the loaded Flow runtime.
 
 ## Inspect first
 
 - Read the files, docs, tests, package scripts, and local conventions that determine the work.
-- For broad discovery, read \`references/parallel-discovery.md\` after a serial orientation pass. Use \`../flow/references/parallel-orchestration.md\` when discovery needs multiple workers, and write its pass manifest before fan-out.
+- For broad discovery, read \`references/parallel-discovery.md\` after a serial
+  orientation pass. When multiple workers may help, start with
+  \`../flow/references/parallel-orchestration.md\` and load only the branch it
+  selects.
 - Helper rule: when a named helper skill is unavailable, record a planning gap
   and keep the corresponding claims conservative instead of simulating its
   checks.
@@ -1458,6 +1288,65 @@ See \`references/planning-examples.md\` for payload examples and decomposition
 anti-patterns.
 `;
 
+// skills/flow-review/references/hidden-reviewer-contract.md
+var hidden_reviewer_contract_default = `# Hidden Flow reviewer contract
+
+This is the canonical role-safe contract bundled into \`flow-reviewer\`. It does
+not grant manager capabilities and does not tell the hidden reviewer to load
+skills, run commands, edit files, or launch workers.
+
+## Role and availability
+
+You are an independent read-only reviewer. Call \`flow_status\` when available,
+prefer the manager's bounded review packet, and inspect the actual changed
+artifacts and supplied validation evidence. Only the root manager may mutate
+Flow state; return findings without fixing them. Your permissions intentionally
+exclude edits, shell commands, skill loading, and nested workers. Record missing
+evidence as a gap or blocker instead of claiming coverage.
+
+If Flow setup or required evidence is stale or unavailable, label the result
+advisory and do not present it as Flow-gated evidence.
+
+## Feature review depths
+
+- \`quick\`: docs, comments, config-only changes, generated output, or mechanical
+  changes fully covered by tooling.
+- \`standard\`: read every changed file and relevant test; this is the default for
+  ordinary implementation work.
+- \`detailed\`: inspect risky behavior, persistence, security, cross-module
+  refactors, migrations, releases, weak validation, and expensive edge cases.
+
+The actual feature-review depth must meet or exceed the approved feature's
+\`reviewDepth\`. Final reviews use \`reviewDepth: "broad"\` or \`"detailed"\` and must
+match the plan's \`finalReviewPolicy\`. Claim only the depth actually performed.
+
+## Direct review outputs
+
+For a direct feature review, return only \`featureReviewDepth\` plus
+\`featureReview\`. For a direct final review, return only \`status\`, \`summary\`,
+\`blockingFindings\`, and \`reviewDepth\`. Use \`status: "failed"\` whenever a
+blocking finding remains. Advisory notes belong in the summary, while
+\`blockingFindings\` contains only blockers.
+
+## Special-case evidence
+
+- Cleanup/refactor: verify that the smell was real, refutation paths were
+  checked, and behavior was preserved. If helper evidence is unavailable,
+  record a coverage gap instead of approving the cleanup claim.
+- UI/frontend: verify relevant states and supplied visual evidence. When visual
+  evidence is missing, record a coverage gap and do not claim visual polish was
+  verified.
+- Audit reports: findings must survive refutation against cited code, guards,
+  and mitigating paths before they can drive fixes.
+
+## Completion checkpoint
+
+Before returning, confirm that the stated depth matches work actually
+inspected, every blocker has concrete evidence, missing coverage is explicit,
+and the response uses exactly the direct-review payload or assigned-slice
+handoff requested.
+`;
+
 // skills/flow-review/references/review-rubric.md
 var review_rubric_default = `# Review rubric
 
@@ -1610,13 +1499,15 @@ These instructions run in two contexts, and only one of them can load helpers:
   subagents. In this context, skip every "load" and "fan out" instruction
   below: judge from the diff, the plan fields, and the recorded validation
   evidence, and record a coverage gap for any judgment that would have needed
-  a helper skill or a command run.
+  a helper skill or a command run. The bundled hidden reviewer prompt uses the
+  canonical role-safe contract in
+  \`references/hidden-reviewer-contract.md\`.
 
 ## Start
 
 - Call \`flow_status\` when available.
 - Identify whether this is a feature review or final review.
-- Prefer the manager's compact review packet over parent-session memory. The
+- Prefer the manager's bounded review packet over parent-session memory. The
   packet should name the active feature, minimum \`reviewDepth\`, changed files,
   diff summary, validation evidence, and targeted paths or risk lenses. If the
   packet is missing important scope or evidence, record that as a coverage gap
@@ -1677,14 +1568,15 @@ Use \`status: "failed"\` when any blocking finding remains. Advisory findings ma
 - Cleanup/refactor: in manager context, load \`flow-deslop\`; verify the smell was real, refutation paths were checked, and behavior was preserved. If it is unavailable or you are the hidden reviewer, record a coverage gap instead of approving cleanup claims.
 - UI/frontend: in manager context, load \`flow-ui-quality\`; verify state coverage and visual evidence when a local target was available. If it is unavailable or you are the hidden reviewer, record a coverage gap and do not claim visual polish was verified.
 - Audit reports: use \`../flow-run/references/audit-rubric.md\`; findings must survive refutation before they can drive fix features.
-- Large reviews (manager context only): use
+- Large reviews (manager context only): start with
   \`../flow/references/parallel-orchestration.md\` for read-only slices by
-  changed-file group, risk lens, or validation surface. Use the named review,
-  audit, evidence, or validation agents from that reference instead of generic
-  subagents. Write its pass manifest before fan-out and apply its Stage 6
-  handoff acceptance and verification tiers; only the manager
-  returns the final \`featureReview\` or \`finalReview\` payload. If that reference
-  is unavailable in the current context (for example in a bundled public Flow
+  changed-file group, risk lens, or validation surface. If fan-out is selected,
+  use \`../flow/references/parallel-manifest.md\`,
+  \`../flow/references/parallel-execution.md\`, and
+  \`../flow/references/parallel-synthesis.md\` with the named review, audit,
+  evidence, or validation workers; only the manager returns the final
+  \`featureReview\` or \`finalReview\` payload. If those references are unavailable
+  in the current context (for example in a bundled public Flow
   command that does not include it), review serially and record the skipped
   fan-out as a coverage gap instead of improvising worker contracts. The hidden
   reviewer cannot spawn workers; it reviews its assigned scope directly and
@@ -1712,7 +1604,7 @@ A finding that survives this pass is worth reporting. A finding you did not try
 
 ## Parallel audit slices
 
-For broad audits, use \`../../flow/references/parallel-orchestration.md\` to split
+For broad audits, start with \`../../flow/references/parallel-orchestration.md\` to split
 read-only slices by module, data flow, or risk lens. Workers surface candidates;
 the audit author owns the report. Apply its handoff format and verification
 gates. Before blocking severity, dedupe, trace guards, fill cross-layer checks,
@@ -1768,7 +1660,9 @@ Use the strongest practical tier. For risky work, combine tiers.
 - Each \`validationRun\` entry has \`command\`, \`status\`, and \`summary\`.
 - Completion accepts only passing entries. Failed or skipped checks belong in the summary/notes and must be resolved or explained as blockers.
 - Do not claim a command was run unless it was run in this session or directly reported by a trusted worker with raw output.
-- Worker-reported command output must satisfy the verification stage of \`../../flow/references/parallel-orchestration.md\`: exact command, status, raw outcome summary, coverage, and manager acceptance.
+- Worker-reported command output must satisfy the acceptance and verification
+  rules in \`../../flow/references/parallel-synthesis.md\`: exact command, status,
+  raw outcome summary, coverage, and manager acceptance.
 - Include scope in the summary: what behavior, files, routes, or states the check covered.
 - UI work should include browser or screenshot evidence when the app can run locally.
 - Cleanup/refactor work should show behavior preservation, not only formatting success.
@@ -1810,7 +1704,170 @@ Never trim failing output, relabel a failed command as passed, or use "not run"
 `;
 
 // skills/flow-run/SKILL.md
-var SKILL_default6 = '---\nname: flow-run\ndescription: "Use when an approved Flow plan has a feature to implement, validate, or complete in the v4 runtime, and the work is scoped to one active feature. For planning a goal first use flow-plan; for the full goal-to-completion loop or resuming a session use flow."\n---\n\n# Flow Run\n\nUse this skill for implementation after a Flow plan is approved. Work one feature at a time.\n\nIf `flow_run_start` is unavailable, stop and tell the user to check that `opencode-plugin-flow` is loaded in OpenCode.\n\n## Start\n\n- Call `flow_status`.\n- If `flow_status` returns a `session.resumePacket` or\n  `session.budget.phaseBoundary`, stop the current autonomous loop and report\n  the resume instructions. Only call `flow_run_start` with\n  `phaseBoundaryAck: true` at the start of a fresh user invocation that is\n  explicitly resuming the Flow session; do not acknowledge a boundary inside\n  the same uninterrupted loop that created it.\n- Call `flow_run_start` with no `featureId` unless the user or plan requires a specific runnable feature.\n- Treat the returned feature as the sole scope until it is completed, blocked, or reset.\n- Helper rule: when a named helper skill is unavailable, record the gap and\n  keep the corresponding claims conservative instead of simulating its checks.\n- Load `flow-deslop` for cleanup/refactor features.\n- Load `flow-ui-quality` for frontend, UX, responsive, accessibility, or visual work.\n\n## Implement\n\n- Read the feature `targets`, `summary`, `validation`, dependencies, and plan `requirements`/`decisions`.\n- Treat the feature\'s `reviewDepth` as the minimum feature-review depth that\n  must be recorded in `flow_feature_complete`.\n- For broad, risky, or multi-target work, record an implementation pass\n  decision before editing: `serial`, `candidate-exact-path`,\n  `candidate-worktree`, `tournament`, or `skipped`. Use\n  `../flow/references/parallel-orchestration.md` for the decision rules,\n  manifest fields, and compact `orchestrationPasses` record.\n- If candidate workers are skipped, record the reason, such as overlapping\n  targets, shared contracts, missing isolation, or no explicit authorization\n  for worker edits.\n- Keep edits scoped to the active feature. If new scope appears, stop and replan or defer it to another feature.\n- Preserve unrelated user changes in the worktree.\n- When a wrong assumption invalidates the feature, use `flow_feature_reset`; do not pile patches onto a bad path.\n- Do not stage, commit, push, amend, rebase, publish, or mutate releases as part\n  of feature execution. If the user explicitly asks for commit preparation, load\n  `flow-commit` only after `flow_feature_complete` has been recorded, unless the\n  user explicitly asks for a WIP commit path. Keep Git boundaries separate from\n  Flow state recording.\n\n## Validate\n\n- For complex validation, regression-sensitive changes, browser QA, route QA,\n  failure-prone checks, unclear coverage, exploratory QA, or\n  `validationRun` summarization, load `flow-test` (helper rule applies).\n- Read `references/validation-rubric.md` before completing.\n- Run the strongest practical checks for the changed behavior.\n- Record concrete command names, status, and observed results. "Tests pass" is not evidence.\n- Non-final features complete with `validationScope: "targeted"`.\n- The final feature must run a broad project-level gate and use `validationScope: "broad"`.\n\nFor broad validation research, risky changes, or unclear coverage, use\n`../flow/references/parallel-orchestration.md` to fan out named Flow workers.\nUse the mode-to-agent mapping in that reference instead of generic subagents.\nWrite its pass manifest before fan-out, paste the matching handoff template\nfrom `../flow/references/handoff-format.md` into every worker prompt, and\napply its verification tiers to the handoffs that come back.\nThey may report command output they actually ran or propose focused checks; the\nmanager decides what is strong enough to record.\n\nFor independent implementation attempts, use candidate workers only with\nexplicit user authorization plus isolated worktrees or exact non-overlapping\npath ownership. Treat their output as candidate patches. The manager inspects,\nmerges, validates, and records Flow state serially.\nWhen a candidate pass or serial/skipped implementation decision materially\nshaped the feature, include its compact record in\n`flow_feature_complete.orchestrationPasses`. Do not paste full worker handoffs\nor long logs into the runtime payload.\n\n## Review and complete\n\nBefore `flow_feature_complete`, obtain a `featureReview` payload. Load\n`flow-review`; for read-only subagent reviews, the manager receives the review\npacket and records both `featureReviewDepth` and `featureReview`.\n\nSend reviewers a compact review packet. Do not rely on the accumulated parent\nconversation. Include only:\n\n- active feature id, title, summary, `reviewDepth`, targets, validation, and dependencies\n- relevant plan requirements, decisions, and final review policy\n- changed files and a short diff summary\n- validation evidence with exact commands, status, and observed result\n- targeted paths or risk lenses the reviewer must inspect\n\nIf the review returns `status: "failed"`, do not fix inside the review pass.\nRecord the failed attempt by calling `flow_feature_complete` with the otherwise\nprepared completion payload, the failed `featureReview`, and the attempted\n`featureReviewDepth`; the runtime will reject completion and update the retry\nbudget. Default to stopping and reporting the blocker. When the user already\nauthorized autonomous implementation, make at most one repair and run one retry\nreview. If the retry fails or the runtime reports review retry budget\nexhausted, stop with the blocker.\n\nIf `flow_status` reports `setup.skills` or `flow-review` cannot be loaded, do\nnot record a Flow-gated `featureReview` or `finalReview`. You may perform an\nadvisory review using available context or the bundled review fallback provided\nby plugin config, then complete with `status: "needs_input"` if review evidence\nis required to proceed.\n\nFor the final feature, also obtain a `finalReview` payload whose `reviewDepth` equals the approved plan\'s `finalReviewPolicy`.\n\nComplete with:\n\n```json\n{\n  "status": "ok",\n  "featureId": "active-feature-id",\n  "summary": "what changed",\n  "artifactsChanged": [{ "path": "src/file.ts" }],\n  "validationRun": [\n    { "command": "bun test tests/foo.test.ts", "status": "passed", "summary": "3 pass, exercised foo behavior" }\n  ],\n  "validationScope": "targeted",\n  "featureReviewDepth": "standard",\n  "featureReview": { "status": "passed", "summary": "review summary", "blockingFindings": [] },\n  "orchestrationPasses": [\n    {\n      "id": "active-feature-id-implementation-decision",\n      "kind": "implementation-decision",\n      "decision": "serial",\n      "decisionReason": "Shared contract edits made worker ownership unsafe.",\n      "writeScope": "manager-serial",\n      "verificationStatus": "not-needed",\n      "outcome": "accepted"\n    }\n  ]\n}\n```\n\nIf `flow_feature_complete` returns a `session.resumePacket` or\n`session.budget.phaseBoundary`, stop after reporting the compact handoff. If\ngenuinely blocked, call `flow_feature_complete` with `status: "needs_input"` and\nan `outcome` that explains the blocker and next step. Never fabricate validation\nor review evidence to force progress.\n';
+var SKILL_default6 = `---
+name: flow-run
+description: "Use when an approved Flow plan has a feature to implement, validate, or complete in the v4 runtime, and the work is scoped to one active feature. For planning a goal first use flow-plan; for the full goal-to-completion loop or resuming a session use flow."
+---
+
+# Flow Run
+
+Use this skill for implementation after a Flow plan is approved. Work one feature at a time.
+
+## Execution runtime availability
+
+If \`flow_run_start\` is unavailable, stop and tell the user to check that \`opencode-plugin-flow\` is loaded in OpenCode.
+
+## Start
+
+- Call \`flow_status\`.
+- If \`flow_status\` returns a \`session.resumePacket\` or
+  \`session.budget.phaseBoundary\`, stop the current autonomous loop and report
+  the resume instructions. Only call \`flow_run_start\` with
+  \`phaseBoundaryAck: true\` at the start of a fresh user invocation that is
+  explicitly resuming the Flow session; do not acknowledge a boundary inside
+  the same uninterrupted loop that created it.
+- Call \`flow_run_start\` with no \`featureId\` unless the user or plan requires a specific runnable feature.
+- Treat the returned feature as the sole scope until it is completed, blocked, or reset.
+- Helper rule: when a named helper skill is unavailable, record the gap and
+  keep the corresponding claims conservative instead of simulating its checks.
+- Load \`flow-deslop\` for cleanup/refactor features.
+- Load \`flow-ui-quality\` for frontend, UX, responsive, accessibility, or visual work.
+
+## Implement
+
+- Read the feature \`targets\`, \`summary\`, \`validation\`, dependencies, and plan \`requirements\`/\`decisions\`.
+- Treat the feature's \`reviewDepth\` as the minimum feature-review depth that
+  must be recorded in \`flow_feature_complete\`.
+- Keep edits scoped to the active feature. If new scope appears, stop and replan or defer it to another feature.
+- Preserve unrelated user changes in the worktree.
+- When a wrong assumption invalidates the feature, use \`flow_feature_reset\`; do not pile patches onto a bad path.
+- Do not stage, commit, push, amend, rebase, publish, or mutate releases as part
+  of feature execution. If the user explicitly asks for commit preparation, load
+  \`flow-commit\` only after \`flow_feature_complete\` has been recorded, unless the
+  user explicitly asks for a WIP commit path. Keep Git boundaries separate from
+  Flow state recording.
+
+## Candidate implementation
+
+\`flow-run\` remains the candidate-implementation manager entry route. Invoke the
+hidden \`flow-candidate-worker\` only after feature start and a complete pass
+manifest; never route the user's feature request directly to it.
+
+For broad, risky, or multi-target work, record an implementation pass decision
+before editing: \`serial\`, \`candidate-exact-path\`, \`candidate-worktree\`,
+\`tournament\`, or \`skipped\`. Candidate implementation requires explicit user
+authorization and either an isolated worktree or exact non-overlapping path
+ownership. It is eligible only when the slice has an independent surface and
+practical validation, with no shared state, overlapping files, or unresolved
+manager judgment. Shared contracts, migrations, lockfiles, generated outputs,
+tightly coupled callers, unclear ownership, and small slices remain serial.
+
+Classify \`candidateEligibility\` (\`eligible\`, \`not_eligible\`, or \`unknown\`) and
+\`candidateDecision\` (\`used\`, \`skipped\`, or \`serial_required\`) separately. Read
+\`../flow/references/parallel-decision.md\` for valid pairings and factors. After
+selecting fan-out, read \`../flow/references/parallel-manifest.md\` and
+\`../flow/references/parallel-execution.md\`, then
+\`../flow/references/parallel-synthesis.md\` when handoffs return.
+Set \`decision\`, \`decisionReason\`, \`decisionFactors\`, and \`writeScope\`.
+
+Candidate workers return patches for manager inspection. The manager accepts,
+modifies, or rejects them, integrates accepted work, validates, reviews, and
+records Flow state serially. Record the candidate outcome as \`accepted\`,
+\`modified\`, or \`rejected\`. When a candidate pass or serial/skipped decision
+materially shaped the feature, include its bounded record in
+\`flow_feature_complete.orchestrationPasses\`; keep full handoffs and long logs
+outside the runtime payload.
+
+## Validate
+
+- For complex validation, regression-sensitive changes, browser QA, route QA,
+  failure-prone checks, unclear coverage, exploratory QA, or
+  \`validationRun\` summarization, load \`flow-test\` (helper rule applies).
+- Read \`references/validation-rubric.md\` before completing.
+- Run the strongest practical checks for the changed behavior.
+- Record concrete command names, status, and observed results. "Tests pass" is not evidence.
+- Non-final features complete with \`validationScope: "targeted"\`.
+- The final feature must run a broad project-level gate and use \`validationScope: "broad"\`.
+
+For broad validation research, risky changes, or unclear coverage, start with
+\`../flow/references/parallel-orchestration.md\`. If it routes to fan-out, write
+the manifest from \`../flow/references/parallel-manifest.md\`, use the named Flow
+workers and prompt contract in \`../flow/references/parallel-execution.md\`, paste
+the matching handoff template from \`../flow/references/handoff-format.md\`, and
+apply \`../flow/references/parallel-synthesis.md\` when the handoffs return.
+They may report command output they actually ran or propose focused checks; the
+manager decides what is strong enough to record.
+
+## Review and complete
+
+Before \`flow_feature_complete\`, obtain a \`featureReview\` payload. Load
+\`flow-review\`; for read-only subagent reviews, the manager receives the review
+packet and records both \`featureReviewDepth\` and \`featureReview\`.
+
+Send reviewers a bounded review packet. Do not rely on the accumulated parent
+conversation. Include only:
+
+- active feature id, title, summary, \`reviewDepth\`, targets, validation, and dependencies
+- relevant plan requirements, decisions, and final review policy
+- changed files and a short diff summary
+- validation evidence with exact commands, status, and observed result
+- targeted paths or risk lenses the reviewer must inspect
+
+If the review returns \`status: "failed"\`, do not fix inside the review pass.
+Record the failed attempt by calling \`flow_feature_complete\` with the otherwise
+prepared completion payload, the failed \`featureReview\`, and the attempted
+\`featureReviewDepth\`; the runtime will reject completion and update the retry
+budget. Default to stopping and reporting the blocker. When the user already
+authorized autonomous implementation, make at most one repair and run one retry
+review. If the retry fails or the runtime reports review retry budget
+exhausted, stop with the blocker.
+
+If \`flow_status\` reports \`setup.skills\` or \`flow-review\` cannot be loaded, do
+not record a Flow-gated \`featureReview\` or \`finalReview\`. You may perform an
+advisory review using available context or the bundled review fallback provided
+by plugin config, then complete with \`status: "needs_input"\` if review evidence
+is required to proceed.
+
+For the final feature, also obtain a \`finalReview\` payload whose \`reviewDepth\` equals the approved plan's \`finalReviewPolicy\`.
+
+Complete with:
+
+\`\`\`json
+{
+  "status": "ok",
+  "featureId": "active-feature-id",
+  "summary": "what changed",
+  "artifactsChanged": [{ "path": "src/file.ts" }],
+  "validationRun": [
+    { "command": "bun test tests/foo.test.ts", "status": "passed", "summary": "3 pass, exercised foo behavior" }
+  ],
+  "validationScope": "targeted",
+  "featureReviewDepth": "standard",
+  "featureReview": { "status": "passed", "summary": "review summary", "blockingFindings": [] },
+  "orchestrationPasses": [
+    {
+      "id": "active-feature-id-implementation-decision",
+      "kind": "implementation-decision",
+      "decision": "serial",
+      "decisionReason": "Shared contract edits made worker ownership unsafe.",
+      "candidateEligibility": "not_eligible",
+      "candidateDecision": "serial_required",
+      "decisionFactors": ["shared_state", "overlapping_files"],
+      "writeScope": "manager-serial",
+      "verificationStatus": "not-needed",
+      "outcome": "accepted"
+    }
+  ]
+}
+\`\`\`
+
+If \`flow_feature_complete\` returns a \`session.resumePacket\` or
+\`session.budget.phaseBoundary\`, stop after reporting the runtime-provided resume
+packet. If
+genuinely blocked, call \`flow_feature_complete\` with \`status: "needs_input"\` and
+an \`outcome\` that explains the blocker and next step. Never fabricate validation
+or review evidence to force progress.
+`;
 
 // skills/flow-test/SKILL.md
 var SKILL_default7 = `---
@@ -2096,6 +2153,22 @@ var FLOW_SKILL_DEFINITIONS = [
         relativePath: "references/parallel-orchestration.md",
         content: parallel_orchestration_default
       },
+      {
+        relativePath: "references/parallel-decision.md",
+        content: parallel_decision_default
+      },
+      {
+        relativePath: "references/parallel-manifest.md",
+        content: parallel_manifest_default
+      },
+      {
+        relativePath: "references/parallel-execution.md",
+        content: parallel_execution_default
+      },
+      {
+        relativePath: "references/parallel-synthesis.md",
+        content: parallel_synthesis_default
+      },
       {
         relativePath: "references/parallel-pass-example.md",
         content: parallel_pass_example_default
@@ -2146,6 +2219,10 @@ var FLOW_SKILL_DEFINITIONS = [
     name: "flow-review",
     files: [
       { relativePath: "SKILL.md", content: SKILL_default5 },
+      {
+        relativePath: "references/hidden-reviewer-contract.md",
+        content: hidden_reviewer_contract_default
+      },
       {
         relativePath: "references/review-rubric.md",
         content: review_rubric_default
@@ -2734,4 +2811,4 @@ main(process.argv).catch((error) => {
   process.exitCode = 1;
 });
 
-//# debugId=F8C7F51F0C6F267C64756E2164756E21
+//# debugId=62569BF7C9EAD96D64756E2164756E21