opencode-plugin-flow 4.3.7 → 4.3.8

package/dist/index.js

@@ -35,6 +35,12 @@ success | partial | blocked
 ## Scope
 <owned slice: path set, module, command, risk lens, route, data range, or question set>
 
+## 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>
+
 ## Coverage
 - Expected: <files, ranges, questions, commands, or findings assigned>
 - Checked: <actual coverage, for example "12/12 files" or "command not run">
@@ -89,6 +95,11 @@ success | partial | blocked
 ## Scope
 <claim ids, sources or commands checked, and the 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">
+
 ## Verdict per claim
 - <claim id>: verdict=<supported | partly-supported | unsupported | source-not-found>
   - claim: <claim text>
@@ -119,6 +130,12 @@ success | partial | blocked
 ## Scope
 <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>
+
 ## Changed or proposed patch
 - <path>: <what changed and why>
 
@@ -145,6 +162,32 @@ live-verified | test-verified | type-check-only | not-verified
 
 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
+\`flow_feature_complete.orchestrationPasses\`. Use one record per material pass or
+implementation decision; keep handoffs and long artifacts outside \`.flow/**\`.
+
+\`\`\`json
+{
+  "id": "stable-pass-id",
+  "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",
+  "modes": ["evidence"],
+  "workerCount": 1,
+  "candidateWorkerCount": 0,
+  "verifierWorkerCount": 0,
+  "sliceIds": ["manifest-row-id"],
+  "dependsOn": [],
+  "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",
+  "synthesisRef": "/tmp/flow-synthesis.md"
+}
+\`\`\`
 `;
 
 // skills/flow/references/parallel-orchestration.md
@@ -197,6 +240,35 @@ Pass notes:
   or exact non-overlapping path ownership. Patches stay proposals until the
   manager inspects, merges or rejects, and validates.
 
+## 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.
@@ -272,6 +344,12 @@ 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,
@@ -279,14 +357,29 @@ 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.
 
-| # | Slice scope | Expected coverage | Mode | Verification tier |
-| --- | --- | --- | --- | --- |
-| 1 | \`src/core/**\` plus its tests | 14 files | \`evidence\` | accept locally |
-| 2 | release contract: CI workflows, \`package.json\`, changelog | 6 files | \`evidence\` | verify once |
+| Row id | Slice scope | 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
@@ -295,11 +388,20 @@ Before spawning, write a pass manifest: one row per slice, plus a totals check.
   "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
@@ -312,8 +414,10 @@ Every worker prompt includes:
 \`\`\`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:
@@ -339,6 +443,20 @@ 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
@@ -360,6 +478,11 @@ handoff only after a cheap manager-side pass:
 - 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.
 
@@ -424,6 +547,38 @@ Where accepted evidence goes:
 - 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:
+
+\`\`\`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"
+}
+\`\`\`
+
+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
@@ -442,6 +597,10 @@ Stop after a pass when:
 - 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:
@@ -449,6 +608,9 @@ 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.
 
@@ -475,21 +637,24 @@ directory. The manager keeps the middleware local because it is one file and
 anchors every other judgment.
 
 Pass manifest: twelve countable route modules remain after the local check, and
-4 + 3 + 5 adds back to 12 with no overlaps or gaps.
+4 + 3 + 5 adds back to 12 with no overlaps or gaps. The pass id is
+\`api-error-handling-read\`.
 
-| # | Slice scope | Expected coverage | Mode | Verification tier |
-| --- | --- | --- | --- | --- |
-| A | auth and account routes | 4/12 modules | \`evidence\` | accept locally |
-| B | billing and subscription routes | 3/12 modules | \`review\` | verify once |
-| C | remaining content and admin routes | 5/12 modules | \`audit\` | verify once |
+| Row id | Slice scope | Expected coverage | Mode | Depends on | Write scope | Verification tier | Handoff ref | Verification status | Synthesis ref |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| \`routes-auth\` | auth and account routes | 4/12 modules | \`evidence\` | none | none | accept locally | pending | pending | pending |
+| \`routes-billing\` | billing and subscription routes | 3/12 modules | \`review\` | none | none | verify once | pending | pending | pending |
+| \`routes-admin\` | remaining content and admin routes | 5/12 modules | \`audit\` | none | none | verify once | pending | pending | pending |
 
 Worker prompts:
 
 \`\`\`text
 Overall goal, context only: confirm API error handling is consistent.
 Mode: evidence
+Pass id and manifest row id: api-error-handling-read / routes-auth
 Your exact slice: the four auth and account route modules under src/routes/.
 Expected coverage: 4/4 modules.
+Dependencies and write scope: none; none.
 Do: report each route's error paths, status codes, and middleware usage with file:line evidence.
 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:
@@ -499,8 +664,10 @@ Return only the Flow handoff in this exact shape:
 \`\`\`text
 Overall goal, context only: confirm API error handling is consistent.
 Mode: review
+Pass id and manifest row id: api-error-handling-read / routes-billing
 Your exact slice: the three billing and subscription route modules under src/routes/.
 Expected coverage: 3/3 modules.
+Dependencies and write scope: none; none.
 Do: separate blocking findings from advisory notes and cite file:line evidence.
 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:
@@ -510,8 +677,10 @@ Return only the Flow handoff in this exact shape:
 \`\`\`text
 Overall goal, context only: confirm API error handling is consistent.
 Mode: audit
+Pass id and manifest row id: api-error-handling-read / routes-admin
 Your exact slice: the five content and admin route modules under src/routes/.
 Expected coverage: 5/5 modules.
+Dependencies and write scope: none; none.
 Do: check each claimed error path against the shared middleware contract and report divergences with evidence.
 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:
@@ -522,6 +691,9 @@ Accounting: three manifest rows spawned means three handoffs collected before
 synthesis. If slice B returned \`partial\`, the manager would re-spawn it once
 with a narrower scope, then cover it directly, and as a last resort carry it
 into the synthesis explicitly as not-covered.
+The manager fills \`handoffRefs\`, \`verificationStatus\`, \`outcome\`, and
+\`synthesisRef\` for each row before any claim becomes a plan decision or review
+payload.
 
 Handoff checks: the manager accepts only reports with terminal status, matching
 coverage counts, concrete file:line evidence, confidence tags, and claims inside
@@ -539,6 +711,12 @@ Final synthesis: the manager re-reads the relevant route and middleware lines,
 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
+\`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/recovery-playbook.md
@@ -822,15 +1000,19 @@ config, or release surfaces in the pass manifest.
 
 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
-per slice with expected coverage 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 rules:
+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
+rules:
 
 - Workers are read-only. For validation-oriented discovery, workers may report
   commands that should be run, and include raw output only for commands they
   actually ran.
 - Workers cannot read reference files themselves; paste the matching handoff
   template from \`../../flow/references/handoff-format.md\` into the prompt.
+- If discovery finds later features with disjoint path ownership, preserve that
+  fact in feature \`targets\` and \`dependsOn\` so execution can make an explicit
+  serial or candidate-pass decision instead of rediscovering ownership.
 
 ## Synthesis
 
@@ -1249,6 +1431,11 @@ to execute.
   validation entry should name the expected test level, such as targeted unit,
   integration, browser/e2e, package/build, docs/static, cleanup preservation, or
   broad project gate.
+- When a feature may benefit from parallel implementation, make \`targets\`
+  precise enough for later ownership decisions: name exact modules, docs,
+  commands, or route groups, and use \`dependsOn\` to preserve prerequisite order.
+  Broad shared-contract work should stay in one feature or an earlier foundation
+  feature so later candidate passes can own disjoint paths safely.
 - Assign \`reviewDepth\` from risk. Use \`detailed\` for persistence, migration,
   concurrency, security, final-delivery-adjacent, or cross-module slices; use
   \`standard\` for normal code changes; reserve \`quick\` for low-risk non-behavioral
@@ -1614,7 +1801,7 @@ 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- 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.\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}\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 = '---\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';
 
 // skills/flow-test/SKILL.md
 var SKILL_default7 = `---
@@ -2635,6 +2822,78 @@ var FeatureReviewDepthSchema = z.enum([
   "detailed"
 ]);
 var FinalReviewPolicySchema = z.enum(["broad", "detailed"]);
+var OrchestrationPassKindSchema = z.enum([
+  "discovery",
+  "audit",
+  "review",
+  "validation",
+  "verification",
+  "candidate",
+  "implementation-decision"
+]);
+var OrchestrationModeSchema = z.enum([
+  "evidence",
+  "review",
+  "validation",
+  "audit",
+  "verifier",
+  "candidate-implementation"
+]);
+var OrchestrationDecisionSchema = z.enum([
+  "serial",
+  "parallel",
+  "candidate-exact-path",
+  "candidate-worktree",
+  "tournament",
+  "skipped"
+]);
+var OrchestrationWriteScopeSchema = z.enum([
+  "none",
+  "manager-serial",
+  "exact-path",
+  "isolated-worktree",
+  "mixed"
+]);
+var OrchestrationVerificationStatusSchema = z.enum([
+  "not-needed",
+  "pending",
+  "passed",
+  "failed",
+  "mixed",
+  "downgraded"
+]);
+var OrchestrationOutcomeSchema = z.enum([
+  "accepted",
+  "rejected",
+  "partial",
+  "not-covered",
+  "superseded"
+]);
+var OrchestrationPassRecordSchema = z.object({
+  id: z.string().min(1),
+  kind: OrchestrationPassKindSchema,
+  decision: OrchestrationDecisionSchema.optional(),
+  decisionReason: z.string().min(1).optional(),
+  modes: z.array(OrchestrationModeSchema).default([]),
+  workerCount: z.number().int().nonnegative().default(0),
+  candidateWorkerCount: z.number().int().nonnegative().default(0),
+  verifierWorkerCount: z.number().int().nonnegative().default(0),
+  sliceIds: z.array(z.string().min(1)).default([]),
+  dependsOn: z.array(z.string().min(1)).default([]),
+  writeScope: OrchestrationWriteScopeSchema.default("none"),
+  handoffRefs: z.array(z.string().min(1)).default([]),
+  verificationStatus: OrchestrationVerificationStatusSchema.default("not-needed"),
+  outcome: OrchestrationOutcomeSchema.default("accepted"),
+  synthesisRef: z.string().min(1).optional()
+}).strict();
+var OrchestrationTelemetrySchema = z.object({
+  passCount: z.number().int().nonnegative().default(0),
+  workerCount: z.number().int().nonnegative().default(0),
+  candidatePassCount: z.number().int().nonnegative().default(0),
+  verifierPassCount: z.number().int().nonnegative().default(0),
+  skippedCandidateDecisionCount: z.number().int().nonnegative().default(0),
+  latestPasses: z.array(OrchestrationPassRecordSchema).default([])
+}).strict();
 var ReviewFindingSchema = z.object({
   summary: z.string().min(1),
   severity: z.enum(["blocking", "advisory"]).default("blocking")
@@ -2704,7 +2963,8 @@ var WorkerResultSchema = z.discriminatedUnion("status", [
     featureReviewDepth: FeatureReviewDepthSchema,
     featureReview: ReviewSchema,
     finalReview: FinalReviewSchema.optional(),
-    outcome: WorkerOutcomeSchema.optional()
+    outcome: WorkerOutcomeSchema.optional(),
+    orchestrationPasses: z.array(OrchestrationPassRecordSchema).default([])
   }).strict(),
   z.object({
     status: z.literal("needs_input"),
@@ -2716,7 +2976,8 @@ var WorkerResultSchema = z.discriminatedUnion("status", [
     featureReviewDepth: FeatureReviewDepthSchema.optional(),
     featureReview: ReviewSchema.optional(),
     finalReview: FinalReviewSchema.optional(),
-    outcome: NeedsInputOutcomeSchema
+    outcome: NeedsInputOutcomeSchema,
+    orchestrationPasses: z.array(OrchestrationPassRecordSchema).default([])
   }).strict()
 ]).superRefine((value, ctx) => {
   if (value.status === "ok" && value.outcome?.kind && value.outcome.kind !== "completed") {
@@ -2738,7 +2999,8 @@ var ExecutionHistoryEntrySchema = z.object({
   featureReviewDepth: FeatureReviewDepthSchema.optional(),
   featureReview: ReviewSchema.optional(),
   finalReview: FinalReviewSchema.optional(),
-  outcome: WorkerOutcomeSchema.optional()
+  outcome: WorkerOutcomeSchema.optional(),
+  orchestrationPasses: z.array(OrchestrationPassRecordSchema).default([])
 }).strict();
 var TokenTelemetrySchema = z.object({
   source: z.enum(["host_unavailable", "reported"]).default("host_unavailable"),
@@ -2764,6 +3026,14 @@ var BudgetTelemetrySchema = z.object({
     cacheReadTokens: null,
     nonCacheTokens: null
   }),
+  orchestration: OrchestrationTelemetrySchema.default({
+    passCount: 0,
+    workerCount: 0,
+    candidatePassCount: 0,
+    verifierPassCount: 0,
+    skippedCandidateDecisionCount: 0,
+    latestPasses: []
+  }),
   phaseBoundary: PhaseBoundarySchema.nullable().default(null)
 }).strict();
 var SessionSchema = z.object({
@@ -2787,6 +3057,14 @@ var SessionSchema = z.object({
       cacheReadTokens: null,
       nonCacheTokens: null
     },
+    orchestration: {
+      passCount: 0,
+      workerCount: 0,
+      candidatePassCount: 0,
+      verifierPassCount: 0,
+      skippedCandidateDecisionCount: 0,
+      latestPasses: []
+    },
     phaseBoundary: null
   }),
   closure: z.object({
@@ -3227,6 +3505,7 @@ function nowIso() {
 // src/runtime/transitions.ts
 var MAX_HISTORY_ENTRIES = 500;
 var MAX_FAILED_REVIEW_ATTEMPTS_PER_FEATURE = 2;
+var MAX_LATEST_ORCHESTRATION_PASSES = 50;
 var FEATURE_REVIEW_DEPTH_RANK = {
   quick: 0,
   standard: 1,
@@ -3248,7 +3527,8 @@ function historyEntryFor(worker, status) {
     featureReviewDepth: worker.featureReviewDepth,
     featureReview: worker.featureReview,
     finalReview: worker.finalReview,
-    outcome: worker.outcome
+    outcome: worker.outcome,
+    orchestrationPasses: worker.orchestrationPasses
   };
 }
 function initialBudgetTelemetry() {
@@ -3264,6 +3544,14 @@ function initialBudgetTelemetry() {
       cacheReadTokens: null,
       nonCacheTokens: null
     },
+    orchestration: {
+      passCount: 0,
+      workerCount: 0,
+      candidatePassCount: 0,
+      verifierPassCount: 0,
+      skippedCandidateDecisionCount: 0,
+      latestPasses: []
+    },
     phaseBoundary: null
   };
 }
@@ -3278,9 +3566,50 @@ function normalizeBudgetTelemetry(session) {
     tokenTelemetry: {
       ...defaults.tokenTelemetry,
       ...session.budget.tokenTelemetry
+    },
+    orchestration: {
+      ...defaults.orchestration,
+      ...session.budget.orchestration,
+      latestPasses: [...session.budget.orchestration?.latestPasses ?? []]
     }
   };
 }
+function passUsesCandidate(pass) {
+  return pass.kind === "candidate" || pass.modes.includes("candidate-implementation") || pass.decision === "candidate-exact-path" || pass.decision === "candidate-worktree" || pass.decision === "tournament";
+}
+function passUsesVerifier(pass) {
+  return pass.kind === "verification" || pass.modes.includes("verifier");
+}
+function recordOrchestrationPasses(budget, passes) {
+  if (passes.length === 0)
+    return budget;
+  const seenPassIds = new Set(budget.orchestration.latestPasses.map((pass) => pass.id));
+  const newPasses = [];
+  for (const pass of passes) {
+    if (seenPassIds.has(pass.id))
+      continue;
+    seenPassIds.add(pass.id);
+    newPasses.push(pass);
+  }
+  if (newPasses.length === 0)
+    return budget;
+  const latestPasses = [...budget.orchestration.latestPasses, ...newPasses];
+  return {
+    ...budget,
+    orchestration: {
+      passCount: budget.orchestration.passCount + newPasses.length,
+      workerCount: budget.orchestration.workerCount + newPasses.reduce((total, pass) => total + pass.workerCount, 0),
+      candidatePassCount: budget.orchestration.candidatePassCount + newPasses.filter(passUsesCandidate).length,
+      verifierPassCount: budget.orchestration.verifierPassCount + newPasses.filter(passUsesVerifier).length,
+      skippedCandidateDecisionCount: budget.orchestration.skippedCandidateDecisionCount + newPasses.filter((pass) => pass.kind === "implementation-decision" && pass.decision === "skipped").length,
+      latestPasses: latestPasses.length > MAX_LATEST_ORCHESTRATION_PASSES ? latestPasses.slice(latestPasses.length - MAX_LATEST_ORCHESTRATION_PASSES) : latestPasses
+    }
+  };
+}
+function sessionWithOrchestrationPasses(session, passes) {
+  const budget = recordOrchestrationPasses(normalizeBudgetTelemetry(session), passes);
+  return budget === session.budget ? session : { ...session, budget };
+}
 function ok(value) {
   return { ok: true, value };
 }
@@ -3640,48 +3969,49 @@ function completeFeature(session, input) {
   if (worker.featureId !== session.activeFeatureId) {
     return fail(`Worker result feature '${worker.featureId}' does not match active feature '${session.activeFeatureId}'.`);
   }
+  const sessionWithPasses = sessionWithOrchestrationPasses(session, worker.orchestrationPasses);
   if (worker.status === "needs_input") {
     const entry2 = historyEntryFor(worker, "needs_input");
-    const budget2 = normalizeBudgetTelemetry(session);
+    const budget2 = normalizeBudgetTelemetry(sessionWithPasses);
     return ok(touch({
-      ...session,
+      ...sessionWithPasses,
       status: "blocked",
       activeFeatureId: null,
       plan: {
         ...session.plan,
         features: updateFeature(session.plan.features, worker.featureId, "blocked")
       },
-      history: appendHistory(session.history, entry2),
+      history: appendHistory(sessionWithPasses.history, entry2),
       budget: budget2,
       lastError: null
     }));
   }
   if (!isPassingReview(worker.featureReview)) {
-    return failedReviewCompletion(session, worker, worker.featureReview, "feature");
+    return failedReviewCompletion(sessionWithPasses, worker, worker.featureReview, "feature");
   }
-  if (finalFeature(session, worker.featureId) && worker.finalReview && !isPassingReview(worker.finalReview)) {
-    return failedReviewCompletion(session, worker, worker.finalReview, "final");
+  if (finalFeature(sessionWithPasses, worker.featureId) && worker.finalReview && !isPassingReview(worker.finalReview)) {
+    return failedReviewCompletion(sessionWithPasses, worker, worker.finalReview, "final");
   }
-  const validation = validateCompletion(session, worker);
+  const validation = validateCompletion(sessionWithPasses, worker);
   if (!validation.ok)
     return validation;
   const entry = historyEntryFor(worker, "completed");
   const features = updateFeature(session.plan.features, worker.featureId, "completed");
   const allComplete = features.every((feature) => feature.status === "completed");
   const now = nowIso();
-  const budget = completionBudget(session, worker);
+  const budget = completionBudget(sessionWithPasses, worker);
   return ok(touch({
-    ...session,
+    ...sessionWithPasses,
     status: allComplete ? "completed" : "ready",
     activeFeatureId: null,
     plan: { ...session.plan, features },
-    history: appendHistory(session.history, entry),
+    history: appendHistory(sessionWithPasses.history, entry),
     budget,
     closure: allComplete ? { kind: "completed", summary: worker.summary, recordedAt: now } : null,
     lastError: null,
     timestamps: {
-      ...session.timestamps,
-      completedAt: allComplete ? now : session.timestamps.completedAt
+      ...sessionWithPasses.timestamps,
+      completedAt: allComplete ? now : sessionWithPasses.timestamps.completedAt
     }
   }));
 }
@@ -3808,6 +4138,7 @@ function summarizeSession(session) {
         reviewCount: budget.reviewCount,
         failedReviewCount: budget.failedReviewCount,
         failedReviewAttemptsByFeature: budget.failedReviewAttemptsByFeature,
+        orchestration: budget.orchestration,
         tokenTelemetry: {
           ...budget.tokenTelemetry,
           note: budget.tokenTelemetry.source === "host_unavailable" ? "OpenCode does not expose per-turn usage to this plugin surface; Flow can enforce review checkpoints, but token thresholds remain manager-observed." : undefined
@@ -3882,7 +4213,8 @@ var FlowFeatureCompleteToolSchema = z2.object({
   featureReviewDepth: FeatureReviewDepthSchema.optional(),
   featureReview: ReviewSchema.optional(),
   finalReview: FinalReviewSchema.optional(),
-  outcome: z2.union([WorkerOutcomeSchema, NeedsInputOutcomeSchema]).optional()
+  outcome: z2.union([WorkerOutcomeSchema, NeedsInputOutcomeSchema]).optional(),
+  orchestrationPasses: z2.array(OrchestrationPassRecordSchema).optional()
 }).strict();
 function missingSessionResponse() {
   return {
@@ -4249,4 +4581,4 @@ export {
   plugin_default as default
 };
 
-//# debugId=F409E930A69EDF5A64756E2164756E21
+//# debugId=283DE939C516DF8064756E2164756E21