opencode-plugin-flow 4.3.8 → 4.3.9

package/dist/index.js

@@ -168,6 +168,12 @@ completion.
 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
 {
@@ -175,6 +181,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,
@@ -184,7 +200,7 @@ 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"
 }
 \`\`\`
@@ -246,11 +262,32 @@ 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.
+  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
@@ -258,11 +295,54 @@ Use one of these decisions:
 - \`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.
+- 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\`
@@ -398,7 +478,17 @@ 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.
 
@@ -449,7 +539,8 @@ For each row, fill in:
   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\`.
+- \`outcome\`: \`accepted\`, \`modified\`, \`rejected\`, \`partial\`, \`not-covered\`, or
+  \`superseded\`.
 - \`synthesisRef\`: the manager-owned synthesis file or plan field that carries
   the accepted result forward.
 
@@ -482,7 +573,8 @@ handoff only after a cheap manager-side pass:
   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.
+  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.
 
@@ -523,6 +615,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.
@@ -557,6 +654,9 @@ decision that materially affected the feature:
   "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,
@@ -579,6 +679,21 @@ 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
@@ -600,7 +715,8 @@ Stop after a pass when:
 - 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.
+  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:
@@ -619,6 +735,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
@@ -1801,7 +1931,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- 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 = '---\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 = `---
@@ -2847,6 +2977,24 @@ var OrchestrationDecisionSchema = z.enum([
   "tournament",
   "skipped"
 ]);
+var OrchestrationCandidateEligibilitySchema = z.enum([
+  "eligible",
+  "not_eligible",
+  "unknown"
+]);
+var OrchestrationCandidateDecisionSchema = z.enum([
+  "used",
+  "skipped",
+  "serial_required"
+]);
+var OrchestrationDecisionFactorSchema = z.enum([
+  "shared_state",
+  "overlapping_files",
+  "small_slice",
+  "needs_manager_judgment",
+  "independent_surface",
+  "validation_available"
+]);
 var OrchestrationWriteScopeSchema = z.enum([
   "none",
   "manager-serial",
@@ -2864,16 +3012,34 @@ var OrchestrationVerificationStatusSchema = z.enum([
 ]);
 var OrchestrationOutcomeSchema = z.enum([
   "accepted",
+  "modified",
   "rejected",
   "partial",
   "not-covered",
   "superseded"
 ]);
+var CANDIDATE_SHAPED_DECISIONS = new Set([
+  "candidate-exact-path",
+  "candidate-worktree",
+  "tournament"
+]);
+function isCandidateShapedDecision(decision) {
+  return decision !== undefined && CANDIDATE_SHAPED_DECISIONS.has(decision);
+}
+function hasCandidateExecutionEvidence(pass) {
+  return pass.kind === "candidate" || pass.modes.includes("candidate-implementation") || pass.candidateWorkerCount > 0;
+}
+function hasVerifierExecutionEvidence(pass) {
+  return pass.kind === "verification" || pass.modes.includes("verifier") || pass.verifierWorkerCount > 0;
+}
 var OrchestrationPassRecordSchema = z.object({
   id: z.string().min(1),
   kind: OrchestrationPassKindSchema,
   decision: OrchestrationDecisionSchema.optional(),
   decisionReason: z.string().min(1).optional(),
+  candidateEligibility: OrchestrationCandidateEligibilitySchema.default("unknown"),
+  candidateDecision: OrchestrationCandidateDecisionSchema.optional(),
+  decisionFactors: z.array(OrchestrationDecisionFactorSchema).default([]),
   modes: z.array(OrchestrationModeSchema).default([]),
   workerCount: z.number().int().nonnegative().default(0),
   candidateWorkerCount: z.number().int().nonnegative().default(0),
@@ -2885,13 +3051,81 @@ var OrchestrationPassRecordSchema = z.object({
   verificationStatus: OrchestrationVerificationStatusSchema.default("not-needed"),
   outcome: OrchestrationOutcomeSchema.default("accepted"),
   synthesisRef: z.string().min(1).optional()
-}).strict();
+}).strict().superRefine((value, ctx) => {
+  const issue = (path, message) => ctx.addIssue({ code: "custom", path: [path], message });
+  const isImplementationDecision = value.kind === "implementation-decision";
+  const candidateEligibilityIsUnknown = value.candidateEligibility === "unknown";
+  if (value.candidateWorkerCount > value.workerCount) {
+    issue("candidateWorkerCount", "candidateWorkerCount cannot exceed total workerCount.");
+  }
+  if (value.verifierWorkerCount > value.workerCount) {
+    issue("verifierWorkerCount", "verifierWorkerCount cannot exceed total workerCount.");
+  }
+  if (isCandidateShapedDecision(value.decision) && !hasCandidateExecutionEvidence(value)) {
+    issue("decision", "Candidate-shaped decisions require candidate execution evidence: a candidate pass, candidate-implementation mode, or candidateWorkerCount > 0.");
+  }
+  if (isImplementationDecision) {
+    if (value.decision === "parallel") {
+      issue("decision", "Implementation decisions cannot use decision 'parallel'; use 'serial', 'skipped', or a candidate-shaped decision.");
+    }
+    if (candidateEligibilityIsUnknown) {
+      issue("candidateEligibility", "Implementation decisions must include explicit candidateEligibility.");
+    }
+    if (!value.candidateDecision) {
+      issue("candidateDecision", "Implementation decisions must include explicit candidateDecision.");
+    }
+    if (!value.decision) {
+      issue("decision", "Implementation decisions must include explicit decision.");
+    }
+    if (value.decisionFactors.length === 0) {
+      issue("decisionFactors", "Implementation decisions must include at least one decisionFactor.");
+    }
+  }
+  if (!value.candidateDecision)
+    return;
+  if (!isImplementationDecision && candidateEligibilityIsUnknown) {
+    issue("candidateEligibility", "Candidate eligibility must be explicit when candidateDecision is set.");
+  }
+  if (!isImplementationDecision && (value.candidateDecision === "skipped" || value.candidateDecision === "serial_required")) {
+    issue("candidateDecision", "Candidate decisions 'skipped' and 'serial_required' are only valid on implementation-decision records.");
+  }
+  if (value.candidateEligibility === "not_eligible" && value.candidateDecision === "used") {
+    issue("candidateDecision", "Candidate decision 'used' requires eligible candidate work.");
+  }
+  if (value.candidateEligibility === "eligible" && value.candidateDecision === "serial_required") {
+    issue("candidateDecision", "Candidate decision 'serial_required' requires not_eligible candidate work.");
+  }
+  if (value.candidateDecision === "skipped" && value.candidateEligibility !== "eligible") {
+    issue("candidateDecision", "Candidate decision 'skipped' requires eligible candidate work.");
+  }
+  if (isImplementationDecision && value.decision === "skipped" && value.candidateDecision !== "skipped") {
+    issue("decision", "Implementation decision 'skipped' requires candidateDecision 'skipped'.");
+  }
+  if (isImplementationDecision && value.candidateDecision === "skipped" && value.decision && value.decision !== "skipped") {
+    issue("candidateDecision", "Candidate decision 'skipped' requires implementation decision 'skipped'.");
+  }
+  if (isImplementationDecision && value.candidateDecision === "serial_required" && value.decision && value.decision !== "serial") {
+    issue("candidateDecision", "Candidate decision 'serial_required' requires implementation decision 'serial'.");
+  }
+  if (value.candidateDecision === "used") {
+    if (!hasCandidateExecutionEvidence(value)) {
+      issue("candidateDecision", "Candidate decision 'used' requires a candidate pass, candidate mode, or candidate worker count.");
+    }
+    if (value.decision && !isCandidateShapedDecision(value.decision)) {
+      issue("decision", "Candidate decision 'used' requires an omitted or candidate-shaped decision.");
+    }
+  }
+});
 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),
+  candidateEligibleCount: z.number().int().nonnegative().default(0),
+  candidateUsedDecisionCount: z.number().int().nonnegative().default(0),
+  candidateSerialRequiredDecisionCount: z.number().int().nonnegative().default(0),
   skippedCandidateDecisionCount: z.number().int().nonnegative().default(0),
+  recordedPassIds: z.array(z.string().min(1)).default([]),
   latestPasses: z.array(OrchestrationPassRecordSchema).default([])
 }).strict();
 var ReviewFindingSchema = z.object({
@@ -3026,14 +3260,7 @@ var BudgetTelemetrySchema = z.object({
     cacheReadTokens: null,
     nonCacheTokens: null
   }),
-  orchestration: OrchestrationTelemetrySchema.default({
-    passCount: 0,
-    workerCount: 0,
-    candidatePassCount: 0,
-    verifierPassCount: 0,
-    skippedCandidateDecisionCount: 0,
-    latestPasses: []
-  }),
+  orchestration: OrchestrationTelemetrySchema.prefault({}),
   phaseBoundary: PhaseBoundarySchema.nullable().default(null)
 }).strict();
 var SessionSchema = z.object({
@@ -3045,28 +3272,7 @@ var SessionSchema = z.object({
   plan: PlanSchema.nullable(),
   activeFeatureId: z.string().regex(FEATURE_ID_PATTERN, FEATURE_ID_MESSAGE).nullable(),
   history: z.array(ExecutionHistoryEntrySchema).default([]),
-  budget: BudgetTelemetrySchema.default({
-    phaseStartedAt: "unknown",
-    completedFeaturesSinceBoundary: 0,
-    reviewCount: 0,
-    failedReviewCount: 0,
-    failedReviewAttemptsByFeature: {},
-    tokenTelemetry: {
-      source: "host_unavailable",
-      visibleTokens: null,
-      cacheReadTokens: null,
-      nonCacheTokens: null
-    },
-    orchestration: {
-      passCount: 0,
-      workerCount: 0,
-      candidatePassCount: 0,
-      verifierPassCount: 0,
-      skippedCandidateDecisionCount: 0,
-      latestPasses: []
-    },
-    phaseBoundary: null
-  }),
+  budget: BudgetTelemetrySchema.prefault({}),
   closure: z.object({
     kind: z.enum(["completed", "deferred", "abandoned"]),
     summary: z.string().min(1),
@@ -3532,28 +3738,7 @@ function historyEntryFor(worker, status) {
   };
 }
 function initialBudgetTelemetry() {
-  return {
-    phaseStartedAt: nowIso(),
-    completedFeaturesSinceBoundary: 0,
-    reviewCount: 0,
-    failedReviewCount: 0,
-    failedReviewAttemptsByFeature: {},
-    tokenTelemetry: {
-      source: "host_unavailable",
-      visibleTokens: null,
-      cacheReadTokens: null,
-      nonCacheTokens: null
-    },
-    orchestration: {
-      passCount: 0,
-      workerCount: 0,
-      candidatePassCount: 0,
-      verifierPassCount: 0,
-      skippedCandidateDecisionCount: 0,
-      latestPasses: []
-    },
-    phaseBoundary: null
-  };
+  return { ...BudgetTelemetrySchema.parse({}), phaseStartedAt: nowIso() };
 }
 function normalizeBudgetTelemetry(session) {
   const defaults = initialBudgetTelemetry();
@@ -3570,20 +3755,20 @@ function normalizeBudgetTelemetry(session) {
     orchestration: {
       ...defaults.orchestration,
       ...session.budget.orchestration,
+      recordedPassIds: [
+        ...session.budget.orchestration?.recordedPassIds ?? []
+      ],
       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 seenPassIds = new Set([
+    ...budget.orchestration.recordedPassIds,
+    ...budget.orchestration.latestPasses.map((pass) => pass.id)
+  ]);
   const newPasses = [];
   for (const pass of passes) {
     if (seenPassIds.has(pass.id))
@@ -3593,15 +3778,52 @@ function recordOrchestrationPasses(budget, passes) {
   }
   if (newPasses.length === 0)
     return budget;
+  const tally = {
+    workerCount: 0,
+    candidatePassCount: 0,
+    verifierPassCount: 0,
+    candidateEligibleCount: 0,
+    candidateUsedDecisionCount: 0,
+    candidateSerialRequiredDecisionCount: 0,
+    skippedCandidateDecisionCount: 0
+  };
+  for (const pass of newPasses) {
+    tally.workerCount += pass.workerCount;
+    if (hasCandidateExecutionEvidence(pass))
+      tally.candidatePassCount += 1;
+    if (hasVerifierExecutionEvidence(pass))
+      tally.verifierPassCount += 1;
+    if (pass.kind !== "implementation-decision")
+      continue;
+    if (pass.candidateEligibility === "eligible") {
+      tally.candidateEligibleCount += 1;
+    }
+    if (pass.candidateDecision === "used") {
+      tally.candidateUsedDecisionCount += 1;
+    }
+    if (pass.candidateDecision === "serial_required") {
+      tally.candidateSerialRequiredDecisionCount += 1;
+    }
+    if (pass.candidateDecision === "skipped") {
+      tally.skippedCandidateDecisionCount += 1;
+    }
+  }
   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,
+      workerCount: budget.orchestration.workerCount + tally.workerCount,
+      candidatePassCount: budget.orchestration.candidatePassCount + tally.candidatePassCount,
+      verifierPassCount: budget.orchestration.verifierPassCount + tally.verifierPassCount,
+      candidateEligibleCount: budget.orchestration.candidateEligibleCount + tally.candidateEligibleCount,
+      candidateUsedDecisionCount: budget.orchestration.candidateUsedDecisionCount + tally.candidateUsedDecisionCount,
+      candidateSerialRequiredDecisionCount: budget.orchestration.candidateSerialRequiredDecisionCount + tally.candidateSerialRequiredDecisionCount,
+      skippedCandidateDecisionCount: budget.orchestration.skippedCandidateDecisionCount + tally.skippedCandidateDecisionCount,
+      recordedPassIds: [
+        ...budget.orchestration.recordedPassIds,
+        ...newPasses.map((pass) => pass.id)
+      ],
       latestPasses: latestPasses.length > MAX_LATEST_ORCHESTRATION_PASSES ? latestPasses.slice(latestPasses.length - MAX_LATEST_ORCHESTRATION_PASSES) : latestPasses
     }
   };
@@ -4581,4 +4803,4 @@ export {
   plugin_default as default
 };
 
-//# debugId=283DE939C516DF8064756E2164756E21
+//# debugId=C77708A78E8740C664756E2164756E21