opencode-plugin-flow 4.3.7 → 4.3.9

package/dist/cli.js

@@ -44,6 +44,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">
@@ -98,6 +104,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>
@@ -128,6 +139,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>
 
@@ -154,6 +171,48 @@ 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/**\`.
+The candidate accounting rules — which \`candidateEligibility\`,
+\`candidateDecision\`, and \`decision\` combinations validate, and what counts as
+candidate execution evidence — live in
+[parallel-orchestration.md](parallel-orchestration.md) under "Implementation
+pass decision"; note \`decision: "parallel"\` is not valid on
+\`implementation-decision\` records.
+
+\`\`\`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",
+  "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,
+  "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 | modified | rejected | partial | not-covered | superseded",
+  "synthesisRef": "/tmp/flow-synthesis.md"
+}
+\`\`\`
 `;
 
 // skills/flow/references/parallel-orchestration.md
@@ -206,6 +265,99 @@ 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.
+
+First classify candidate eligibility:
+
+- \`eligible\`: at least one slice is independent enough for a candidate worker.
+- \`not_eligible\`: worker isolation would not make the implementation safer or
+  cheaper because the slice shares state, files, tests, or one mental model.
+- \`unknown\`: orientation did not produce enough evidence to classify; use this
+  only for non-decision pass rows or legacy low-signal records, not for
+  \`implementation-decision\` records and not as a substitute for judgment.
+
+Then record the candidate decision:
+
+- \`used\`: candidate workers were used or a candidate pass carried the work.
+- \`skipped\`: candidates were eligible, but the manager chose serial anyway.
+  This is the underused-parallelism signal counted by Flow status; use it only
+  on \`kind: "implementation-decision"\` records.
+- \`serial_required\`: candidates were not eligible, so serial work was the
+  correct implementation shape. Use it only on \`kind: "implementation-decision"\`
+  records.
+
+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. Pair unsafe or not-useful worker cases with
+  \`candidateEligibility: "not_eligible"\` and
+  \`candidateDecision: "serial_required"\`.
+- \`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.
+- Candidate-shaped decisions (\`candidate-exact-path\`, \`candidate-worktree\`,
+  \`tournament\`) require candidate execution evidence on the same record:
+  \`kind: "candidate"\`, \`modes\` includes \`candidate-implementation\`, or
+  \`candidateWorkerCount > 0\`. The same evidence rule applies to
+  \`candidateDecision: "used"\`. Non-decision candidate rows (for example
+  \`kind: "candidate"\`) may omit \`decision\`; \`implementation-decision\` rows must
+  always set one, and when \`candidateDecision\` is \`"used"\` that decision must
+  be candidate-shaped — never \`serial\`, \`parallel\`, or \`skipped\`.
+- \`parallel\` describes multi-worker read or audit passes (discovery, audit,
+  review); it is not a valid \`implementation-decision\` value. Implementation
+  decisions use \`serial\`, \`skipped\`, or a candidate-shaped decision.
+- \`skipped\`: candidate workers were eligible but the manager chose serial
+  anyway; pair this with \`candidateEligibility: "eligible"\` and
+  \`candidateDecision: "skipped"\`. Do not use \`skipped\` for shared fixtures,
+  shared API contracts, unclear ownership, or other unsafe worker cases; use
+  \`serial\` plus \`serial_required\` for those.
+
+Use structured \`decisionFactors\` alongside prose \`decisionReason\`:
+\`shared_state\`, \`overlapping_files\`, \`small_slice\`,
+\`needs_manager_judgment\`, \`independent_surface\`, and
+\`validation_available\`. Serial-required records usually cite
+\`shared_state\`, \`overlapping_files\`, or \`needs_manager_judgment\`; eligible
+records usually cite \`independent_surface\` and \`validation_available\`, with
+\`small_slice\` explaining an eligible-but-skipped choice.
+
+### Worker decision rubric
+
+Default to considering candidate workers when:
+
+- the plan has three or more features.
+- features touch separate surfaces such as frontend, core, docs, release
+  scripts, tests, or bindings.
+- validation can run per slice.
+- the work is mostly additive or localized.
+- the final manager can review, apply, adapt, or reject the result safely.
+
+Prefer serial when:
+
+- one tight invariant crosses shared files.
+- migrations, persistence, storage, or lifecycle semantics require one mental
+  model.
+- tests require iterative local debugging in one checkout.
+- multiple slices would edit the same files or fixtures.
+- the slice is so small that prompt, handoff, merge, and verification overhead
+  costs more than direct work.
+
+Record the decision in the pass manifest with a stable pass id,
+\`candidateEligibility\`, \`candidateDecision\`, \`decisionFactors\`,
+\`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.
@@ -281,6 +433,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,
@@ -288,14 +446,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
@@ -304,11 +477,30 @@ 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\`,
+\`candidateEligibility\`, \`candidateDecision\`, \`decisionFactors\`,
+\`workerCount=0\`, \`writeScope=manager-serial\`, and a concrete \`decisionReason\`.
+Use \`decision=serial\` with \`candidateDecision=serial_required\` for ineligible
+worker cases; reserve \`decision=skipped\` for eligible candidate work that the
+manager chose not to delegate. When an implementation-decision row uses
+\`candidateDecision=used\`, it must also record actual candidate execution
+evidence: either \`modes=candidate-implementation\`, or \`candidateWorkerCount > 0\`
+with \`workerCount\` raised to cover it — a \`workerCount=0\` row cannot carry a
+positive \`candidateWorkerCount\`. Neither subtype count may exceed the total:
+\`candidateWorkerCount <= workerCount\` and \`verifierWorkerCount <= workerCount\`
+(a single worker may fill both roles).
+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
@@ -321,8 +513,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:
@@ -348,6 +542,21 @@ 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\`, \`modified\`, \`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
@@ -369,6 +578,12 @@ 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. Record the manager result as \`accepted\`, \`modified\`, or
+  \`rejected\` where that is the most precise candidate outcome.
 - Contradictions between workers are either resolved or explicitly marked as
   contested.
 
@@ -409,6 +624,11 @@ Apply the manager synthesis barrier before presenting or recording anything:
 - 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.
+- For broad implementation sessions, use one verifier worker after manager
+  synthesis when the risk is medium or high. Ask it whether every planned
+  feature landed, worker validation claims are supported, final code matches
+  the audit finding, generated bindings/docs/version metadata stayed
+  consistent, and changed files have plausible test coverage.
 - 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.
@@ -433,6 +653,56 @@ 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.",
+  "candidateEligibility": "not_eligible",
+  "candidateDecision": "serial_required",
+  "decisionFactors": ["shared_state", "overlapping_files"],
+  "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\`.
+
+Status accounting distinguishes three cases: \`candidateDecision: "used"\` means
+candidate execution evidence was recorded, \`candidateDecision:
+"serial_required"\` means workers were not safe or useful, and
+\`candidateEligibility: "eligible"\` plus \`candidateDecision: "skipped"\`
+increments \`skippedCandidateDecisionCount\`. These candidate decision counters
+come from \`kind: "implementation-decision"\` records; \`skipped\` and
+\`serial_required\` are not valid on discovery, audit, review, validation,
+verification, or candidate pass rows. \`candidatePassCount\`
+counts actual candidate pass or worker evidence (\`kind: "candidate"\`,
+\`modes\` includes \`candidate-implementation\`, or \`candidateWorkerCount > 0\`) —
+a candidate-shaped decision label without that evidence is rejected, so decision
+labels alone never count. \`verifierPassCount\` similarly counts
+actual verifier pass or worker evidence (\`kind: "verification"\`, \`modes\`
+includes \`verifier\`, or \`verifierWorkerCount > 0\`).
+
 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
@@ -451,6 +721,11 @@ 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, candidate eligibility, candidate decision, structured factors, and
+  the reason eligible workers were skipped.
 - remaining gaps are explicit and do not block the Flow artifact being produced.
 
 Start a bounded follow-up pass only when:
@@ -458,6 +733,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.
 
@@ -466,6 +744,20 @@ 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.
+
+## Worker count defaults
+
+Use caps, not a fixed feature limit:
+
+- small implementation: zero or one worker.
+- medium independent implementation: two workers.
+- broad audit: three to five workers.
+- broad implementation: two to four candidate workers, only for
+  non-overlapping slices.
+- final verifier: one worker when risk is medium or high.
+
+The target is not "more workers." The target is explicit accounting: Flow must
+justify not using workers when the work was eligible.
 `;
 
 // skills/flow/references/parallel-pass-example.md
@@ -484,21 +776,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:
@@ -508,8 +803,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:
@@ -519,8 +816,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:
@@ -531,6 +830,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
@@ -548,6 +850,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
@@ -831,15 +1139,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
 
@@ -1258,6 +1570,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
@@ -1623,7 +1940,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- Classify `candidateEligibility` (`eligible`, `not_eligible`, or `unknown`)\n  and `candidateDecision` (`used`, `skipped`, or `serial_required`) separately;\n  implementation decisions must use `eligible` or `not_eligible` and always set\n  an explicit `decision`. The valid pairings and the candidate execution\n  evidence rules are in `../flow/references/parallel-orchestration.md` under\n  "Implementation pass decision" — follow that reference when composing the\n  record.\n- Record structured `decisionFactors`: `shared_state`, `overlapping_files`,\n  `small_slice`, `needs_manager_judgment`, `independent_surface`, and\n  `validation_available`.\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 or rejects, validates, and records Flow state serially. Record whether a\ncandidate was `accepted`, `modified`, or `rejected`.\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      "candidateEligibility": "not_eligible",\n      "candidateDecision": "serial_required",\n      "decisionFactors": ["shared_state", "overlapping_files"],\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 = `---
@@ -2547,4 +2864,4 @@ main(process.argv).catch((error) => {
   process.exitCode = 1;
 });
 
-//# debugId=70ED7108866181D964756E2164756E21
+//# debugId=6088D1387043CD7A64756E2164756E21