opencode-plugin-flow 4.2.0 → 4.3.0

package/dist/cli.js

@@ -84,7 +84,7 @@ Example evidence quality:
 
 Use this for \`flow-verifier-worker\`. Give it atomic claims and the cited sources
 or commands. Do not include the generator's reasoning unless that reasoning is
-the thing being verified.
+the thing being verified, and do not say which worker produced the claim.
 
 \`\`\`markdown
 ## Status
@@ -113,8 +113,8 @@ success | partial | blocked
 
 ## Candidate implementation worker report
 
-Use this only for isolated worktrees or exact non-overlapping path ownership
-authorized by the manager.
+Use this only with explicit user authorization, in an isolated worktree or an
+exact non-overlapping path-owned slice assigned by the manager.
 
 \`\`\`markdown
 ## Status
@@ -159,76 +159,60 @@ evidence faster than one linear pass. The manager still owns the Flow session:
 only the manager calls state-changing Flow tools, approves plans, completes
 features, records reviews, or closes sessions.
 
-Sections: quick path, operational defaults, manager sequence, modes, permission
-contract, worker rules, prompt contract, handoff location, and follow-up passes.
-
-Read these companion references before a broad parallel pass:
-
-- \`parallel-pass-patterns.md\` for pass selection, effort defaults, and stop or
-  follow-up rules.
-- \`handoff-format.md\` for the exact worker response shapes.
-- \`verification-gates.md\` for the pre-fan-out coverage gate, handoff
-  acceptance, verifier triggers, and the manager synthesis barrier. Those
-  definitions are canonical; this file only points at them.
-- \`parallel-pass-example.md\` for a concrete end-to-end pass after the rules
-  below are clear (synced with the \`flow\` skill; not bundled into commands).
-
-## Quick path
-
-1. Orient serially and keep the immediate blocker local.
-2. Fan out only when two to five non-overlapping slices reduce known
-   uncertainty.
-3. Write a coverage gate before spawning workers: total scope, exact slices,
-   expected counts, and overlap/gap check.
-4. Give each worker a named mode, exact slice, expected coverage, and the
-   required handoff shape.
-5. Accept only scoped, evidenced, confidence-labeled claims; verify important
-   weak, contested, or single-source claims.
-6. Synthesize one manager-owned artifact. Raw handoffs do not become the answer,
-   Flow payload, or patch decision.
-
-## Operational defaults
-
-- Prefer serial work when the scope is small, tightly coupled, or blocked by one
-  decision that must be made before slices are meaningful.
-- A normal first pass is two to five workers with independent slices. Use more
-  only when the coverage gate is countable and the slices remain non-overlapping.
-- Run at most one routine follow-up pass. Extra passes need an explicit manager
-  reason, such as a high-stakes verifier check or a newly discovered bounded
-  slice.
-- Do not fan out just to keep agents busy. Every worker should reduce a known
-  planning, validation, review, audit, or implementation uncertainty.
-
-Skip fan-out when:
-
-- one file, command, or design question determines the next step.
-- slices would share the same contracts, fixtures, or edit targets.
-- the manager can inspect the full scope faster than writing and checking
+Every parallel pass runs the same loop:
+
+**orient → slice → manifest → fan out → account → verify → synthesize →
+extend or stop.**
+
+This file is the whole playbook; read it once and run the pass. Two companions
+stay separate:
+
+- \`handoff-format.md\` holds the worker response templates. The manager pastes
+  the matching template verbatim into every worker prompt.
+- \`parallel-pass-example.md\` walks one concrete end-to-end pass (synced with
+  the \`flow\` skill; not bundled into commands).
+
+## Choose a pass
+
+| Situation | Flow pass | Output the manager may synthesize |
+| --- | --- | --- |
+| Repo shape is unclear before planning | Discovery pass | Requirements, decisions, targets, validation entries, or a review-first feature |
+| A broad finding set needs refutation | Audit pass | Surviving findings with guards checked and gaps named |
+| Changed files or risk lenses are too broad for one review pass | Review pass | One \`featureReview\` or \`finalReview\` payload owned by the manager |
+| Test strategy or route coverage is unclear | Validation pass | Candidate commands or authorized raw command evidence |
+| A claim is single-source, surprising, high-stakes, or payload-bound | Verification pass | Per-claim keep, narrow, rewrite, or remove decisions |
+| Multiple implementation paths are plausible | Candidate pass | Candidate patches inspected and validated by the manager before use |
+
+Pass notes:
+
+- **Discovery**: workers read specific modules, routes, docs, commands, or risk
+  lenses; only evidenced claims become plan fields.
+- **Audit**: workers actively look for guards, lifecycle resets, deployment
+  constraints, and counterexamples before reporting a finding. A finding
+  without refutation work stays advisory or becomes a follow-up question.
+- **Review**: workers separate blocking findings from advisory notes; the
+  manager resolves conflicts and returns one review payload.
+- **Validation**: workers run only manager-authorized commands and report the
+  exact command, status, and raw outcome summary.
+- **Verification**: verifiers judge atomic claims against cited sources or
+  commands; do not ask a verifier to redesign the work or review the whole
+  feature.
+- **Candidate**: only with explicit user authorization plus isolated worktrees
+  or exact non-overlapping path ownership. Patches stay proposals until the
+  manager inspects, merges or rejects, and validates.
+
+## When to stay serial
+
+- One file, command, or design question determines the next step.
+- Slices would share the same contracts, fixtures, or edit targets.
+- The manager can inspect the full scope faster than writing and checking
   worker prompts.
-- the result would still need the same manual synthesis with no time saved.
-
-## Manager sequence
-
-1. Call \`flow_status\` if a Flow session may already exist.
-2. Do a serial orientation pass. Read enough files, schemas, docs, tests,
-   commands, or artifacts to identify real slices.
-3. Define the local manager task. Do not delegate the immediate blocker that
-   determines whether fan-out is even valid.
-4. Build the pre-fan-out coverage gate defined in \`verification-gates.md\`
-   ("Before fan-out"): total scope, one line per slice with expected count,
-   partition check, and overlap/gap check.
-5. Spawn only named Flow workers. Use exact slices and the required handoff
-   shape. Keep each prompt self-contained.
-6. Continue non-overlapping manager work while workers run.
-7. Read every handoff. Keep only claims that have evidence, match the assigned
-   scope, and carry confidence labels.
-8. Send important low-confidence, single-source, contested, or citation-heavy
-   claims to \`flow-verifier-worker\`.
-9. Run follow-up passes only for material gaps, conflicts, narrowed scope, or
-   verification needs.
-10. Apply the manager synthesis barrier from \`verification-gates.md\`: keep
-    only distilled, evidence-backed claims and synthesize one Flow artifact.
-    Do not paste worker handoffs as the user-facing result.
+- The result would still need the same manual synthesis with no time saved.
+
+Do not fan out to keep agents busy. Every worker should reduce a named
+planning, validation, review, audit, or implementation uncertainty. A normal
+first pass is two to five workers with independent slices; use more only when
+the manifest stays countable and non-overlapping.
 
 ## Modes
 
@@ -246,20 +230,10 @@ carry the permission boundaries for each mode.
 | \`verifier\` | \`flow-verifier-worker\` | Per-claim verdicts against cited evidence or commands | No | \`flow_status\` only if needed |
 | \`candidate-implementation\` | \`flow-candidate-worker\` | Candidate patch summary from an isolated worktree or exact path-owned slice | Only with explicit user authorization plus isolation or exact non-overlapping path ownership | No state-changing Flow tools |
 
-Mode examples:
-
-- Use \`flow-evidence-worker\` when the repo shape is unclear and the output will
-  become plan requirements, decisions, targets, or validation entries.
-- Use \`flow-reviewer\` when changed files or risk lenses can be reviewed
-  independently before the manager returns one review payload.
-- Use \`flow-validation-worker\` when the manager needs command options or raw
-  output from an explicitly authorized command.
-- Use \`flow-audit-worker\` when candidate findings must be refuted before they
-  can become a report or follow-up feature.
-- Use \`flow-verifier-worker\` for atomic claims that are contested,
-  single-sourced, high-stakes, or destined for a Flow payload.
-- Use \`flow-candidate-worker\` only after explicit user authorization and only
-  with an isolated worktree or exact non-overlapping path ownership.
+If the runtime exposes per-worker model or effort choices, spend them where
+being wrong is expensive: read-heavy discovery slices tolerate the cheapest
+configured option, while verifier and review slices deserve the strongest.
+Otherwise route by scope: give weaker slices narrower, more countable scope.
 
 ## Permission contract
 
@@ -281,27 +255,56 @@ Do not fan out parallel \`flow_plan_save\`, \`flow_plan_approve\`,
 \`flow_session_close\` calls. Runtime locking protects files, but Flow accepts only
 one active feature result at a time.
 
-## Worker rules
-
 Workers may read files, inspect docs, run authorized read-only commands, and
 summarize evidence. Candidate implementation workers may edit only when the
 manager assigned an isolated worktree or exact path ownership that does not
-overlap sibling workers or manager edits.
+overlap sibling workers or manager edits. Workers must not edit \`.flow/**\`,
+must not call state-changing Flow tools, and must not approve work, close
+sessions, record Flow validation, or claim validation they did not run. A
+worker may report raw validation output it actually ran; the manager decides
+whether it is strong enough to record.
+
+## Stage 1 — Orient (serial)
+
+Call \`flow_status\` if a Flow session may already exist. Read enough files,
+schemas, docs, tests, commands, or artifacts to identify real slices. Keep the
+immediate blocker local: do not delegate the question that determines whether
+fan-out is even valid.
+
+## Stage 2 — Slice
+
+Split along whichever axis keeps slices independent: modules or path sets,
+route or endpoint groups, risk lenses, command surfaces, data ranges, or claim
+sets. Each slice needs a one-line scope, expected coverage, and a defined
+output the manager can check.
 
-Workers must not edit \`.flow/**\` and must not call:
+## Stage 3 — Manifest (the pre-fan-out coverage gate)
 
-- \`flow_plan_save\`
-- \`flow_plan_approve\`
-- \`flow_run_start\`
-- \`flow_feature_complete\`
-- \`flow_feature_reset\`
-- \`flow_session_close\`
+Before spawning, write a pass manifest: one row per slice, plus a totals check.
 
-Workers also must not approve work, close sessions, record Flow validation, or
-claim validation they did not run. A worker may report raw validation output it
-actually ran; the manager decides whether it is strong enough to record.
+| # | 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 |
+
+- Count the total work items when countable: files, modules, routes, commands,
+  rows, findings, screenshots, or claims. Confirm slice counts add back to the
+  total, with no overlaps, gaps, empty slices, or ambiguous shared contracts.
+- If the scope cannot be counted, state the completeness rule instead, such as
+  "all changed files plus callers" or "all public commands plus release docs."
+- Assign each slice's verification tier now (see Stage 6). Deciding where a
+  wrong claim is expensive belongs before handoffs arrive, not after.
+- Fix the slice map centrally before spawning if the gate does not reconcile.
 
-## Prompt contract
+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.
+
+Write the manifest where it survives the pass: the conversation is enough for a
+single bounded pass, but when a follow-up pass or a session resume is
+plausible, persist it with the synthesis (Stage 7) so the accounting can be
+reconstructed.
+
+## Stage 4 — Fan out
 
 Every worker prompt includes:
 
@@ -318,43 +321,139 @@ Return only the Flow handoff in this exact shape:
 
 Hidden workers cannot load skills or read \`handoff-format.md\` themselves. The
 manager copies the matching handoff template into every worker prompt; a bare
-filename reference is not enough.
+filename reference is not enough. Workers also cannot read the conversation, so
+prompts cite file paths — including any synthesis file from an earlier pass —
+instead of restating chat history.
 
 For research or current-doc slices, require source checks for versioned or
 time-sensitive facts. For implementation candidates, remind workers that other
 work may be active and that they must not revert unrelated changes.
 
-## Where handoffs go
+Continue non-overlapping manager work while workers run.
+
+## Stage 5 — Account
+
+Check every manifest row off against a returned handoff before synthesis. A
+worker that never returns, errors out, or reports \`partial\` or \`blocked\` is a
+hole in the pass, and synthesizing around it silently drops a slice.
+
+Worker failure ladder:
+
+1. Re-spawn once with a narrower slice and a note about what the first attempt
+   returned.
+2. If it fails again, cover the slice directly in the manager session.
+3. If it stays blocked, carry the slice into the synthesis explicitly as
+   not-covered. Never present results as if coverage were complete.
+
+## Stage 6 — Verify
+
+\`Status: success\` only says the worker believes its slice is done. Accept a
+handoff only after a cheap manager-side pass:
+
+- \`Status\` is present and terminal: \`success\`, \`partial\`, or \`blocked\`.
+- Coverage matches the assigned slice, or skips are explicit.
+- Important claims have concrete evidence and confidence tags.
+- Cited paths, commands, screenshots, URLs, or metrics resolve.
+- The evidence supports the claim, not just the topic.
+- Findings stay inside the worker's slice.
+- Headline counts can be recounted or traced.
+- Contradictions between workers are either resolved or explicitly marked as
+  contested.
+
+Demote, drop, re-task, or verify claims that fail this pass.
+
+### Verification tiers
+
+One taxonomy decides how much verification a claim gets: the manifest assigns
+a default tier per slice, and this stage applies it per claim. Use the cheapest
+check that matches the risk:
+
+- **Accept locally**: low-risk claims with direct evidence that the manager can
+  cheaply inspect or recount.
+- **Verify once** with \`flow-verifier-worker\`: single-source, surprising,
+  inferred, low-confidence, citation-heavy, contested, or Flow-payload-bound
+  claims, including any count, benchmark, command result, or pass/fail claim a
+  Flow payload will rely on.
+- **Verify strongly**: blocking or release-sensitive claims and claims that
+  affect user data, security, persistence, permissions, public API behavior,
+  release behavior, or data loss. Use independent verifier checks, manager-run
+  commands, or direct artifact inspection strong enough to settle the claim.
+- **Do not accept**: claims without concrete evidence, claims outside the
+  assigned slice, claims contradicted by inspected artifacts, or claims where
+  the cited evidence supports only the topic rather than the assertion.
+
+Verifier prompts use stable claim ids, one atomic assertion per id, the cited
+source or command for each id, and the exact acceptance question. Do not
+include the generator's reasoning unless that reasoning is the thing being
+verified, do not say which worker produced the claim, and do not ask a
+verifier to redesign the work or review the whole feature.
+
+## Stage 7 — Synthesize
+
+Apply the manager synthesis barrier before presenting or recording anything:
+
+- Preserve confidence: verified, single-sourced, inferred, and unresolved claims
+  stay distinct when it matters.
+- When workers disagree, inspect the cited artifact or rerun the cited command
+  instead of arbitrating from summaries. Do not average conflicting claims.
+- Run the strongest practical local check for the deliverable.
+- Re-read critical files or docs that will be cited in the final decision.
+- Move only distilled, evidence-backed claims forward; raw handoffs remain
+  candidate evidence, not a plan, review, completion payload, or final answer.
+- Record gaps honestly instead of converting missing evidence into success
+  language.
+
+Where accepted evidence goes:
 
 - Planning evidence becomes \`requirements\`, \`decisions\`, feature \`targets\`,
-  feature \`validation\`, or plan notes in prose fields.
-- Execution evidence informs the active feature, but \`flow_feature_complete\` is
-  manager-owned.
-- Validation evidence may become \`validationRun\` only when the command, status,
-  and raw outcome are concrete enough to trust.
-- Review evidence informs \`featureReview\` or \`finalReview\`, but the manager owns
-  the pass/fail verdict.
-- Audit evidence becomes findings only after refutation and verification rules
-  in \`verification-gates.md\`.
-- Candidate patches are inspected, merged, and validated by the manager before
-  any Flow completion call.
-
-When worker results conflict, inspect the underlying artifact directly and rerun
-the smallest check that can settle the disagreement. The manager synthesis
-barrier in \`verification-gates.md\` applies before anything moves forward.
-
-## Follow-up passes
-
-Start a follow-up pass when first-pass handoffs reveal:
-
-- missing coverage in the original slice map.
-- conflicting findings that matter to the Flow decision.
-- a specialized follow-up that was intentionally out of scope.
-- high-stakes, low-confidence, or single-source claims needing verification.
-- bounded implementation candidates after research converges.
-
-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.
+  feature \`validation\`, or plan notes — only when the source and scope are
+  clear. Unverified broad findings become a review-first feature, not a fix
+  plan.
+- Validation evidence may become \`validationRun\` only when the worker was
+  explicitly authorized to run the command and reported the exact command,
+  status, and raw outcome summary.
+- Review evidence informs \`featureReview\` or \`finalReview\`, but the manager
+  owns the pass/fail verdict and must resolve blockers, contradictions, and
+  coverage gaps before returning the payload.
+- Audit evidence becomes findings only after refutation; blocking findings need
+  guards checked, deployment context, and evidence that the current code
+  exhibits the behavior.
+- Candidate patches are not Flow evidence until the manager inspects, merges or
+  rejects them, and validates the main Flow-managed workspace.
+
+Persist the manifest and the synthesis when another pass may follow or the
+session is long enough to be compacted or resumed: write the distilled result —
+the accounted manifest, accepted claims with evidence and confidence, dropped
+claims with one-line reasons, and open gaps — into plan prose fields or a
+manager-owned scratch file outside both \`.flow/**\` and the repository worktree,
+such as a file in the OS temporary directory. The runtime owns the \`.flow/**\`
+layout, and scratch files left in the worktree end up staged or reviewed as if
+they were project changes. Follow-up worker prompts cite that path; files are
+the only shared memory between passes.
+
+## Stage 8 — Extend or stop
+
+Stop after a pass when:
+
+- the manifest's coverage rule is satisfied and every row is accounted for.
+- accepted claims are evidenced, scoped, and confidence-labeled.
+- material single-source, contested, high-stakes, or payload-bound claims have
+  been verified or downgraded.
+- remaining gaps are explicit and do not block the Flow artifact being produced.
+
+Start a bounded follow-up pass only when:
+
+- the original slice map missed material scope.
+- workers disagree on a claim that affects the Flow decision.
+- a high-stakes or payload-bound claim needs verification.
+- a first pass exposes a narrower implementation or validation slice worth
+  isolating.
+
+Run at most one routine follow-up pass. Extra passes need an explicit manager
+reason, such as a high-stakes verifier check or a newly discovered bounded
+slice. Do not recurse by default: if a worker says it needs another worker, the
+manager decides whether that is a follow-up pass and writes the next bounded
+prompt, starting again from the manifest.
 `;
 
 // skills/flow/references/parallel-pass-example.md
@@ -372,11 +471,14 @@ twelve API route modules, one shared error middleware, and an integration test
 directory. The manager keeps the middleware local because it is one file and
 anchors every other judgment.
 
-Coverage gate: twelve countable route modules remain after the local check.
+Pass manifest: twelve countable route modules remain after the local check, and
+4 + 3 + 5 adds back to 12 with no overlaps or gaps.
 
-- Slice A: auth and account routes, expected 4/12.
-- Slice B: billing and subscription routes, expected 3/12.
-- Slice C: remaining content and admin routes, expected 5/12.
+| # | 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 |
 
 Worker prompts:
 
@@ -413,6 +515,11 @@ Return only the Flow handoff in this exact shape:
 <matching handoff template copied verbatim from handoff-format.md>
 \`\`\`
 
+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.
+
 Handoff checks: the manager accepts only reports with terminal status, matching
 coverage counts, concrete file:line evidence, confidence tags, and claims inside
 the assigned slice. A claim such as \`[high] billing routes bypass the error
@@ -431,295 +538,11 @@ a plan decision, review payload, or docs patch. Raw handoffs and unverified
 suggestions do not move into the next pass or user-facing answer.
 `;
 
-// skills/flow/references/parallel-pass-patterns.md
-var parallel_pass_patterns_default = `# Parallel pass patterns
-
-Flow uses parallel workers to reduce uncertainty, not to delegate decisions.
-Each pass has a bounded purpose, an explicit coverage rule, and one
-manager-owned synthesis result.
-
-## Choose a pass
-
-| Situation | Flow pass | Output the manager may synthesize |
-| --- | --- | --- |
-| Repo shape is unclear before planning | Discovery pass | Requirements, decisions, targets, validation entries, or a review-first feature |
-| A broad finding set needs refutation | Audit pass | Surviving findings with guards checked and gaps named |
-| Changed files or risk lenses are too broad for one review pass | Review pass | One \`featureReview\` or \`finalReview\` payload owned by the manager |
-| Test strategy or route coverage is unclear | Validation pass | Candidate commands or authorized raw command evidence |
-| A claim is single-source, surprising, high-stakes, or payload-bound | Verification pass | Per-claim keep, narrow, rewrite, or remove decisions |
-| Multiple implementation paths are plausible | Candidate pass | Candidate patches inspected and validated by the manager before use |
-
-Prefer serial work when one file, command, or design question determines the
-next step. A parallel pass should reduce a named planning, validation, review,
-audit, or implementation uncertainty.
-
-## Pass Shapes
-
-### Discovery pass
-
-Use before planning when the manager has oriented enough to name disjoint slices
-but not enough to write reliable plan fields. Workers read specific modules,
-routes, docs, commands, or risk lenses. The manager turns only evidenced claims
-into plan fields.
-
-### Audit pass
-
-Use when a report starts from candidate findings. Workers actively look for
-guards, lifecycle resets, deployment constraints, and counterexamples before
-reporting a finding. A finding that lacks refutation work stays advisory or
-becomes a follow-up question.
-
-### Review pass
-
-Use when changed files or risks can be reviewed independently. Review workers
-separate blocking findings from advisory notes. The manager resolves conflicts,
-checks cited artifacts, and returns one review payload.
-
-### Validation pass
-
-Use when coverage is unclear or command evidence can be gathered independently.
-Validation workers may run only manager-authorized commands and must report
-exact command, status, raw outcome summary, coverage, confidence, and gaps.
-
-### Verification pass
-
-Use for atomic claims. Give the verifier claim ids, cited sources or commands,
-and the acceptance question. Do not ask a verifier to redesign the work or
-review the whole feature.
-
-### Candidate pass
-
-Use only with explicit user authorization plus isolated worktrees or exact
-non-overlapping path ownership. Candidate patches are proposals until the
-manager inspects, merges or rejects them, and validates the main workspace.
-
-## Effort Defaults
-
-- Start with two to five workers. Use more only when the coverage gate is
-  countable and the manager can verify every handoff.
-- Run at most one routine follow-up pass. Extra passes need a stated reason,
-  such as a high-stakes verification check or a newly discovered bounded slice.
-- Spend effort where being wrong costs more: public API, persistence, security,
-  permissions, release behavior, data loss, and Flow payload claims.
-- Do not fan out to keep agents busy. Worker setup and synthesis have real cost.
-
-## Stop And Extend
-
-Stop after a pass when:
-
-- the coverage rule is satisfied.
-- accepted claims are evidenced, scoped, and confidence-labeled.
-- material single-source, contested, high-stakes, or payload-bound claims have
-  been verified or downgraded.
-- remaining gaps are explicit and do not block the Flow artifact being produced.
-
-Start a bounded follow-up pass only when:
-
-- the original slice map missed material scope.
-- workers disagree on a claim that affects the Flow decision.
-- a high-stakes or payload-bound claim needs verification.
-- a first pass exposes a narrower implementation or validation slice worth
-  isolating.
-
-After every pass, the manager synthesis barrier from \`verification-gates.md\`
-applies before any handoff content moves forward.
-`;
-
 // skills/flow/references/recovery-playbook.md
 var recovery_playbook_default = '# Recovery playbook\n\nUse this when a Flow tool returns `status: "error"`, a blocker, or a `nextAction` that conflicts with memory.\n\n## First response\n\n1. Re-anchor with `flow_status`.\n2. Read the returned `summary`, `recovery`, `lastError`, and active feature.\n3. Fix the cause, then retry the smallest valid Flow action.\n\n## Common cases\n\n- `missing_session`: start with `flow_plan_save` using the user\'s goal.\n- `missing_goal`: ask for a concrete goal before planning.\n- `Approved plans cannot be changed`: use `flow_feature_reset` when only affected features need another pass; otherwise close and start a new goal.\n- `No feature is currently running`: call `flow_run_start` before completing.\n- `already in progress`: finish, reset, or block the active feature before starting another.\n- `Completion requires recorded validation evidence`: run real validation and include at least one passing `validationRun`.\n- `Completion requires all recorded validation to pass`: fix failures and rerun. Do not relabel failed checks as passed.\n- `Non-final feature completion requires targeted validation`: use `validationScope: "targeted"` for ordinary features.\n- `Final feature completion requires broad validation`: run the project-level gate and use `validationScope: "broad"`.\n- `Completion requires a passing featureReview`: run or request a real review and include a passing `featureReview` only when there are no blocking findings.\n- `Final feature completion requires a finalReview`: perform final review and include `finalReview`.\n- `Final review depth must match the plan policy`: use `reviewDepth` equal to the approved plan\'s `finalReviewPolicy`; valid final-review values are `broad` and `detailed`.\n- `Cannot close ... unfinished features`: complete, reset, defer, or abandon honestly. Do not mark completed while work remains.\n\n## Reset guidance\n\nUse `flow_feature_reset` when the active or completed work was built on the wrong assumption, validation revealed a design issue, dependencies need to be rerun, or dependent features must be invalidated. Resetting a feature also resets its dependents.\n\n## Closure guidance\n\nUse `flow_session_close`:\n\n- `completed`: only after all planned features are complete.\n- `deferred`: the user intentionally postpones unfinished work.\n- `abandoned`: the session should be archived without claiming delivery.\n\nAfter closure, the active `.flow/session.json` is removed and the archived JSON is stored under `.flow/history/`.\n';
 
-// skills/flow/references/verification-gates.md
-var verification_gates_default = `# Verification gates
-
-Verification is how Flow keeps parallel work from turning into parallel
-guesswork. Worker handoffs are candidate evidence; the manager decides what can
-enter the plan, validation record, review payload, audit report, or final
-answer.
-
-Sections: before fan-out, every handoff, verifier triggers, verification tiers,
-Flow payload acceptance, and manager synthesis barrier.
-
-## Before fan-out
-
-Run a pre-fan-out gate after serial orientation and before spawning workers:
-
-- Count the total work items when countable: files, modules, routes, commands,
-  rows, findings, screenshots, or claims.
-- List every slice with path/range/lens and expected count.
-- Check that countable slices add back to the total.
-- Check for overlapping ownership, missing areas, empty slices, and ambiguous
-  shared contracts.
-- Fix the slice map centrally before spawning if the gate does not reconcile.
-
-If the scope cannot be counted, state the completeness rule instead, such as
-"all changed files plus callers" or "all public commands plus release docs."
-
-## Every handoff
-
-Accept a handoff only after a cheap manager-side pass:
-
-- \`Status\` is terminal: \`success\`, \`partial\`, or \`blocked\`.
-- Coverage matches the assigned slice, or skips are explicit.
-- Important claims have concrete evidence and confidence tags.
-- Cited paths, commands, screenshots, URLs, or metrics resolve.
-- The evidence supports the claim, not just the topic.
-- Findings stay inside the worker's slice.
-- Headline counts can be recounted or traced.
-- Contradictions between workers are either resolved or explicitly marked as
-  contested.
-
-Demote, drop, re-task, or verify claims that fail this pass.
-
-## Verifier triggers
-
-Use \`flow-verifier-worker\` when a claim is:
-
-- blocking or release-sensitive.
-- high-stakes for user data, security, persistence, permissions, or public API
-  behavior.
-- low-confidence, inferred, surprising, or single-sourced.
-- citation-heavy enough that source drift would change the conclusion.
-- contradicted by another worker or by manager inspection.
-- a count, benchmark, command result, or pass/fail claim that a Flow payload will
-  rely on.
-
-Give the verifier atomic claims, cited sources or commands, and the acceptance
-question. Do not ask it to redesign the work or review the whole feature.
-
-## Verification tiers
-
-Use the cheapest check that matches the risk:
-
-- **Accept locally**: low-risk claims with direct evidence that the manager can
-  cheaply inspect or recount.
-- **Verify once**: single-source, surprising, inferred, citation-heavy, or
-  Flow-payload-bound claims.
-- **Verify strongly**: claims that affect security, persistence, permissions,
-  public API behavior, release behavior, data loss, or blocking review outcome.
-  Use independent verifier checks, manager-run commands, or direct artifact
-  inspection strong enough to settle the claim.
-- **Do not accept**: claims without concrete evidence, claims outside the
-  assigned slice, claims contradicted by inspected artifacts, or claims where the
-  cited evidence supports only the topic rather than the assertion.
-
-Verifier prompts should use stable claim ids, one atomic assertion per id, the
-cited source or command for each id, and the exact acceptance question.
-
-## Flow payload acceptance
-
-Planning fields may use worker evidence only when the source and scope are clear.
-Unverified broad findings should become a review-first feature, not a fix plan.
-
-\`validationRun\` entries may use worker-reported commands only when the worker
-was explicitly authorized to run the command and reported the exact command,
-status, and raw outcome summary.
-
-\`featureReview\` and \`finalReview\` may use worker review slices, but the manager
-owns the pass/fail decision and must resolve blockers, contradictions, and
-coverage gaps before returning the payload.
-
-Audit reports may include only findings that survived refutation. Blocking audit
-findings need guards checked, deployment context, and evidence that the current
-code exhibits the behavior.
-
-Candidate implementation patches are not Flow evidence until the manager
-inspects, merges or rejects them, and runs suitable validation in the main
-Flow-managed workspace.
-
-## Manager synthesis barrier
-
-Before presenting or recording the result:
-
-- Preserve confidence: verified, single-sourced, inferred, and unresolved claims
-  stay distinct when it matters.
-- When workers disagree, inspect the cited artifact or rerun the cited command
-  instead of arbitrating from summaries.
-- Run the strongest practical local check for the deliverable.
-- Re-read critical files or docs that will be cited in the final decision.
-- Move only distilled, evidence-backed claims forward; raw handoffs remain
-  candidate evidence, not a plan, review, completion payload, or final answer.
-- Record gaps honestly instead of converting missing evidence into success
-  language.
-
-\`Status: success\` only says the worker believes its slice is done. The manager
-still checks coverage and evidence before trusting the result.
-`;
-
 // skills/flow/SKILL.md
-var SKILL_default = `---
-name: flow
-description: Run the end-to-end Flow loop for skills-first OpenCode work. Use when a user asks for Flow-guided planning through implementation, resumable autonomous delivery, session status, or completion with validation and review gates.
----
-
-# Flow
-
-Use Flow as a minimal state ledger, not as a framework. Skills provide judgment; the runtime only records the approved plan, active feature, validation evidence, review evidence, and closure.
-
-## Loop
-
-1. Call \`flow_status\` first. Trust its active session and next action over conversation memory.
-   If the result includes \`setup.skills\`, follow the Skill Availability rules
-   below before loading any Flow skill.
-2. If there is no active session and the user gave a goal, load \`flow-plan\`, save a plan with \`flow_plan_save\`, then approve it with \`flow_plan_approve\` only after explicit user approval or prior authorization for autonomous implementation. If there is no goal, ask for one.
-3. Load \`flow-run\`, call \`flow_run_start\`, implement exactly one feature, validate it, and prepare a \`flow_feature_complete\` payload. For validation-heavy, regression-sensitive, browser QA, route QA, or failure-prone work, use \`flow-test\` to choose and summarize evidence before completion.
-4. Load \`flow-review\` for the required feature review. The reviewer reports a \`featureReview\` payload; the manager records it inside \`flow_feature_complete\`.
-5. On the final feature, run broad validation and include \`finalReview\` in the same \`flow_feature_complete\` call. Its \`reviewDepth\` must match the plan's \`finalReviewPolicy\`.
-6. After all features are complete, archive the session with \`flow_session_close\` using \`kind: "completed"\`.
-
-Use \`references/parallel-orchestration.md\` for broad read-only discovery, audit, validation, review, verification, or candidate implementation passes. Hidden Flow workers are injected by plugin config; invoke the named worker when it is available. Its \`references/parallel-pass-patterns.md\`, \`references/handoff-format.md\`, and \`references/verification-gates.md\` companions define pass selection, worker contracts, and claim acceptance. The manager owns every \`flow_*\` state change.
-
-Do not commit, push, amend, rebase, publish, or mutate releases during the
-autonomous Flow loop. Load \`flow-commit\` only when the user explicitly asks for
-commit preparation or commit creation.
-
-## Skill Availability
-
-If \`flow_status\` returns \`setup.skills\`, report that setup status and stop
-native-loading Flow skills in the current OpenCode startup. Missing, incomplete,
-or outdated managed skills require a sync/restart cycle before their native skill
-instructions can be trusted by the running process. Public command bundles are
-self-contained and may continue when the command prompt already embeds the
-required Flow instructions.
-
-If optional helper skills such as \`flow-test\`, \`flow-deslop\`, or
-\`flow-ui-quality\` are unavailable, continue only with explicit coverage gaps. Do
-not copy their rubrics into another skill and do not claim their quality checks
-were completed.
-
-## Runtime Surface
-
-- \`flow_status\`: read the active session.
-- \`flow_plan_save\`: create a session and/or save a draft plan.
-- \`flow_plan_approve\`: lock the draft plan.
-- \`flow_run_start\`: start one runnable feature.
-- \`flow_feature_complete\`: record completion or a real blocker with validation and review evidence.
-- \`flow_feature_reset\`: reset one feature and its dependents.
-- \`flow_session_close\`: archive the active session as \`completed\`, \`deferred\`, or \`abandoned\`.
-
-There is no \`flow_context\`, no separate review-record tool, and no multi-session activation surface. The single active source of truth is \`.flow/session.json\`; closed sessions are archived under \`.flow/history/\`.
-
-Planning and running require loaded Flow tools; do not simulate plan approval or feature completion when the runtime is unavailable. Review may still return advisory output when tools, skills, or references are stale or unavailable, but the manager must not record it as Flow-gated evidence.
-
-## Hard Gates
-
-- Approved plans are immutable. To change direction, reset affected features or close the session and start a new goal.
-- Only one feature can be active at a time.
-- Completion requires at least one passing \`validationRun\` entry.
-- Non-final completion requires \`validationScope: "targeted"\`.
-- Final completion requires \`validationScope: "broad"\` and a passing \`finalReview\`.
-- Every completed feature requires a passing \`featureReview\` with no blocking findings.
-- \`flow_session_close\` accepts \`kind: "completed"\` only after an approved plan has passed final completion.
-
-## Recovery
-
-- Confused state: call \`flow_status\` and follow \`nextAction\`.
-- Wrong assumption or failed implementation path: use \`flow_feature_reset\` for the feature and dependents, then rerun from the corrected plan.
-- Missing validation or review evidence: gather real evidence, then call \`flow_feature_complete\`.
-- Approved plan is materially wrong: reset the affected features, save a revised plan if the session is back in planning; otherwise close and start a new goal.
-- Unknown runtime error: read \`summary\` and \`recovery\`; see \`references/recovery-playbook.md\` for common cases.
-
-Never fabricate validation output, backfill review approval you did not perform, or close as \`deferred\`/\`abandoned\` merely to avoid an unfinished-work blocker.
-`;
+var SKILL_default = "---\nname: flow\ndescription: Manage the end-to-end Flow loop for skills-first OpenCode work. Use when a user asks for Flow-guided delivery from goal to completion, resumable autonomous delivery, or resuming or closing a Flow session. For plan-only work use flow-plan; for executing one approved feature use flow-run.\n---\n\n# Flow\n\nUse Flow as a minimal state ledger, not as a framework. Skills provide judgment; the runtime only records the approved plan, active feature, validation evidence, review evidence, and closure.\n\nRouting: this manager skill owns the whole loop and every state-changing `flow_*` call. Load `flow-plan` alone for plan-only requests and `flow-run` alone when an approved plan needs one feature executed. Answer status-only questions with `flow_status`; no skill load is needed. `flow-test`, `flow-deslop`, and `flow-ui-quality` are optional helpers loaded from inside the loop; `flow-commit` is user-triggered only and never part of the autonomous loop.\n\n## Loop\n\n1. Call `flow_status` first. Trust its active session and next action over conversation memory.\n   If the result includes `setup.skills`, follow the Skill Availability rules\n   below before loading any Flow skill.\n2. If there is no active session and the user gave a goal, load `flow-plan`, save a plan with `flow_plan_save`, then approve it with `flow_plan_approve` only after explicit user approval or prior authorization for autonomous implementation. If there is no goal, ask for one.\n3. Load `flow-run`, call `flow_run_start`, implement exactly one feature, validate it, and prepare a `flow_feature_complete` payload. For validation-heavy, regression-sensitive, browser QA, route QA, or failure-prone work, use `flow-test` to choose and summarize evidence before completion.\n4. Load `flow-review` for the required feature review. The reviewer reports a `featureReview` payload; the manager records it inside `flow_feature_complete`.\n5. On the final feature, run broad validation and include `finalReview` in the same `flow_feature_complete` call. Its `reviewDepth` must match the plan's `finalReviewPolicy`.\n6. After all features are complete, archive the session with `flow_session_close` using `kind: \"completed\"`.\n\nUse `references/parallel-orchestration.md` for broad read-only discovery, audit, validation, review, verification, or candidate implementation passes. It is the whole pass playbook — orient, slice, manifest, fan out, account, verify, synthesize, extend or stop — and its `references/handoff-format.md` companion holds the worker report templates the manager pastes into prompts. Hidden Flow workers are injected by plugin config; invoke the named worker when it is available. The manager owns every `flow_*` state change.\n\nDo not commit, push, amend, rebase, publish, or mutate releases during the\nautonomous Flow loop. Load `flow-commit` only when the user explicitly asks for\ncommit preparation or commit creation.\n\n## Skill Availability\n\nIf `flow_status` returns `setup.skills`, report that setup status and stop\nnative-loading Flow skills in the current OpenCode startup. Missing, incomplete,\nor outdated managed skills require a sync/restart cycle before their native skill\ninstructions can be trusted by the running process. Public command bundles are\nself-contained and may continue when the command prompt already embeds the\nrequired Flow instructions.\n\nIf optional helper skills such as `flow-test`, `flow-deslop`, or\n`flow-ui-quality` are unavailable, continue only with explicit coverage gaps. Do\nnot copy their rubrics into another skill and do not claim their quality checks\nwere completed.\n\n## Runtime Surface\n\n- `flow_status`: read the active session.\n- `flow_plan_save`: create a session and/or save a draft plan.\n- `flow_plan_approve`: lock the draft plan.\n- `flow_run_start`: start one runnable feature.\n- `flow_feature_complete`: record completion or a real blocker with validation and review evidence.\n- `flow_feature_reset`: reset one feature and its dependents.\n- `flow_session_close`: archive the active session as `completed`, `deferred`, or `abandoned`.\n\nThere is no `flow_context`, no separate review-record tool, and no multi-session activation surface. The single active source of truth is `.flow/session.json`; closed sessions are archived under `.flow/history/`.\n\nPlanning and running require loaded Flow tools; do not simulate plan approval or feature completion when the runtime is unavailable. Review may still return advisory output when tools, skills, or references are stale or unavailable, but the manager must not record it as Flow-gated evidence.\n\n## Hard Gates\n\n- Approved plans are immutable. To change direction, reset affected features or close the session and start a new goal.\n- Only one feature can be active at a time.\n- Completion requires at least one passing `validationRun` entry.\n- Non-final completion requires `validationScope: \"targeted\"`.\n- Final completion requires `validationScope: \"broad\"` and a passing `finalReview`.\n- Every completed feature requires a passing `featureReview` with no blocking findings.\n- `flow_session_close` accepts `kind: \"completed\"` only after an approved plan has passed final completion.\n\n## Recovery\n\n- Confused state: call `flow_status` and follow `nextAction`.\n- Wrong assumption or failed implementation path: use `flow_feature_reset` for the feature and dependents, then rerun from the corrected plan.\n- Missing validation or review evidence: gather real evidence, then call `flow_feature_complete`.\n- Approved plan is materially wrong: reset the affected features, save a revised plan if the session is back in planning; otherwise close and start a new goal.\n- Unknown runtime error: read `summary` and `recovery`; see `references/recovery-playbook.md` for common cases.\n\nNever fabricate validation output, backfill review approval you did not perform, or close as `deferred`/`abandoned` merely to avoid an unfinished-work blocker.\n";
 
 // skills/flow-commit/SKILL.md
 var SKILL_default2 = `---
@@ -919,13 +742,15 @@ Rate as blocking only when the smell materially raises defect risk, blocks plann
 // skills/flow-deslop/SKILL.md
 var SKILL_default3 = `---
 name: flow-deslop
-description: Clean up and refactor code with evidence-backed code-smell analysis. Use for AI-slop removal, overengineering reduction, maintainability refactors, behavior-preserving cleanup, duplicated or bloated code, speculative abstractions, dead code, or broad cleanup/refactor review.
+description: Clean up and refactor code with evidence-backed code-smell analysis. Use for AI-slop removal, overengineering reduction, maintainability refactors, behavior-preserving cleanup, duplicated or bloated code, speculative abstractions, and dead code. Review verdicts on cleanup work stay in flow-review, which loads this skill to judge cleanup claims.
 ---
 
 # Flow deslop
 
 Use this skill when the Flow work is about improving code quality rather than adding a new user-visible feature. The job is to make the code easier to change without changing behavior unless the approved plan explicitly says behavior changes.
 
+This is a helper skill: it produces cleanup findings and evidence only. The manager owns every state-changing \`flow_*\` call, and cleanup review verdicts are returned through \`flow-review\`.
+
 ## Ground the cleanup
 
 - Start from concrete evidence: duplicated code, unnecessary abstraction, long or tangled functions, dead branches, confusing ownership, repeated conditionals, excessive coupling, or validation gaps that hide maintainability risk.
@@ -967,7 +792,7 @@ var parallel_discovery_default = `# Parallel discovery
 Use this only after a serial orientation pass has identified the repo shape and the likely slices. Workers are read-only evidence gatherers; the planner owns the plan.
 
 For broad parallel passes, also load \`../../flow/references/parallel-orchestration.md\`.
-Use its pre-fan-out coverage gate and
+Use its pass manifest as the pre-fan-out coverage gate and
 \`../../flow/references/handoff-format.md\` response shapes.
 
 ## Good slices
@@ -988,35 +813,21 @@ config, and docs. Name each slice by the paths it owns, for example "runtime:
 
 Treat derived slices as starting points, not a simultaneous coverage map.
 Before fan-out, choose the relevant entries and de-overlap shared docs,
-config, or release surfaces in the coverage gate.
+config, or release surfaces in the pass manifest.
 
-## Coverage gate
+## Manifest and prompts
 
-Before spawning workers, state the total discovery scope and one line per slice.
-For countable scopes, confirm that slice counts add back to the total and that
-there are no overlaps, gaps, or empty slices. If the scope is not countable,
-state the completeness rule, such as "all changed files plus callers."
+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:
 
-## Worker prompt
-
-\`\`\`text
-Inspect <slice> for <goal>. Read-only. Do not edit files or call
-state-changing Flow tools. Return only the Flow handoff in this exact shape:
-<matching handoff template copied verbatim from handoff-format.md>
-\`\`\`
-
-For validation-oriented discovery:
-
-\`\`\`text
-Inspect <slice> for validation risk. Read-only. Do not edit files or call
-state-changing Flow tools. You may report commands that should be run, and
-include raw output only for commands you actually ran. Return only the Flow
-handoff in this exact shape:
-<matching handoff template copied verbatim from handoff-format.md>
-\`\`\`
-
-Workers cannot read reference files themselves; paste the matching handoff
-template from \`../../flow/references/handoff-format.md\` into the prompt.
+- 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.
 
 ## Synthesis
 
@@ -1030,8 +841,8 @@ Convert only evidence-backed work into plan fields:
 If workers disagree, inspect the source artifact yourself. If a candidate finding lacks a concrete citation or refutation pass, make it a review-first deliverable rather than a fix feature.
 
 Apply the manager synthesis barrier from
-\`../../flow/references/verification-gates.md\`: only distilled, evidence-backed
-claims become plan fields.
+\`../../flow/references/parallel-orchestration.md\`: only distilled,
+evidence-backed claims become plan fields.
 `;
 
 // skills/flow-plan/references/planning-examples.md
@@ -1125,7 +936,7 @@ Better plan:
 // skills/flow-plan/SKILL.md
 var SKILL_default4 = `---
 name: flow-plan
-description: "Plan Flow work for the v4 skills-first runtime: inspect the repo, decompose a user goal into right-sized features, save a draft with flow_plan_save, and approve it with flow_plan_approve."
+description: "Use when Flow work needs planning before implementation: a new goal to turn into an approved Flow feature plan, a draft plan to revise, or a decomposition or plan-approval decision in the v4 skills-first runtime. For executing an approved feature use flow-run; for the full goal-to-completion loop use flow."
 ---
 
 # Flow Plan
@@ -1137,7 +948,7 @@ If \`flow_plan_save\` or \`flow_plan_approve\` is unavailable, stop and tell the
 ## Inspect first
 
 - Read the files, docs, tests, package scripts, and local conventions that determine the work.
-- For broad discovery, read \`references/parallel-discovery.md\` after a serial orientation pass. Use \`../flow/references/parallel-orchestration.md\` when discovery needs multiple workers, and apply its coverage gate before fan-out.
+- For broad discovery, read \`references/parallel-discovery.md\` after a serial orientation pass. Use \`../flow/references/parallel-orchestration.md\` when discovery needs multiple workers, and write its pass manifest before fan-out.
 - Helper rule: when a named helper skill is unavailable, record a planning gap
   and keep the corresponding claims conservative instead of simulating its
   checks.
@@ -1147,6 +958,25 @@ If \`flow_plan_save\` or \`flow_plan_approve\` is unavailable, stop and tell the
 - For UI/frontend goals, load \`flow-ui-quality\`.
 - Do not invent findings. Broad "review and fix" goals start with a review-first feature whose deliverable is evidence-backed findings.
 
+## Reduce uncertainty before decomposing
+
+A vague goal does not slice into reliable features yet. Name what is uncertain,
+because the two kinds resolve differently:
+
+- **Specification uncertainty** — what the user wants: ambiguous goal, missing
+  acceptance criteria, unstated constraints. Resolve by stating an explicit
+  assumption in \`decisions\` and proceeding, or by asking only when a wrong
+  guess would be expensive to undo.
+- **Environment uncertainty** — facts the repo, docs, commands, or data can
+  answer: code shape, schema, API behavior, current conventions. Resolve by
+  inspecting or by a discovery pass, never by asking the user.
+
+Spend the cheapest probe that removes the most uncertainty first: local reads
+before worker fan-out, fan-out before user questions. Decompose into features
+only once the remaining uncertainty is low enough that \`targets\` and
+\`validation\` can be stated concretely; otherwise the first feature is a
+review-first or discovery deliverable that produces the missing evidence.
+
 ## Plan shape
 
 Call \`flow_plan_save\` with:
@@ -1288,7 +1118,7 @@ Approve only on evidence actually inspected. A review is a claim of coverage, no
 // skills/flow-review/SKILL.md
 var SKILL_default5 = `---
 name: flow-review
-description: "Review Flow work in the v4 runtime: inspect feature or final-session changes, classify findings, and return featureReview or finalReview payloads for flow_feature_complete."
+description: "Use when Flow work needs a review verdict in the v4 runtime: a completed feature awaiting its featureReview, a final session review, or an assigned review slice. Validation evidence gathering stays in flow-test; cleanup judgment stays in flow-deslop."
 ---
 
 # Flow Review
@@ -1303,9 +1133,9 @@ recorded.
 
 These instructions run in two contexts, and only one of them can load helpers:
 
-- **Manager context**: the manager reviews inside \`flow-run\` or \`flow-auto\`
-  before recording evidence. The manager may load helper skills and fan out
-  read-only workers.
+- **Manager context**: the manager reviews inside the Flow loop (the \`flow\` or
+  \`flow-run\` skills, or a bundled public Flow command) before recording
+  evidence. The manager may load helper skills and fan out read-only workers.
 - **Hidden reviewer context**: \`/flow-review\` runs as the \`flow-reviewer\`
   subagent, whose permissions deny skill loading, shell commands, and
   subagents. In this context, skip every "load" and "fan out" instruction
@@ -1367,8 +1197,12 @@ Use \`status: "failed"\` when any blocking finding remains. Advisory findings ma
   \`../flow/references/parallel-orchestration.md\` for read-only slices by
   changed-file group, risk lens, or validation surface. Use the named review,
   audit, evidence, or validation agents from that reference instead of generic
-  subagents. Apply its handoff format and verification gates; only the manager
-  returns the final \`featureReview\` or \`finalReview\` payload. The hidden
+  subagents. Write its pass manifest before fan-out and apply its Stage 6
+  handoff acceptance and verification tiers; only the manager
+  returns the final \`featureReview\` or \`finalReview\` payload. If that reference
+  is unavailable in the current context (for example in a bundled public Flow
+  command that does not include it), review serially and record the skipped
+  fan-out as a coverage gap instead of improvising worker contracts. The hidden
   reviewer cannot spawn workers; it reviews its assigned scope directly and
   reports coverage gaps for the rest.
 
@@ -1450,7 +1284,7 @@ Use the strongest practical tier. For risky work, combine tiers.
 - Each \`validationRun\` entry has \`command\`, \`status\`, and \`summary\`.
 - Completion accepts only passing entries. Failed or skipped checks belong in the summary/notes and must be resolved or explained as blockers.
 - Do not claim a command was run unless it was run in this session or directly reported by a trusted worker with raw output.
-- Worker-reported command output must satisfy \`../../flow/references/verification-gates.md\`: exact command, status, raw outcome summary, coverage, and manager acceptance.
+- Worker-reported command output must satisfy the verification stage of \`../../flow/references/parallel-orchestration.md\`: exact command, status, raw outcome summary, coverage, and manager acceptance.
 - Include scope in the summary: what behavior, files, routes, or states the check covered.
 - UI work should include browser or screenshot evidence when the app can run locally.
 - Cleanup/refactor work should show behavior preservation, not only formatting success.
@@ -1494,7 +1328,7 @@ Never trim failing output, relabel a failed command as passed, or use "not run"
 // skills/flow-run/SKILL.md
 var SKILL_default6 = `---
 name: flow-run
-description: "Execute one approved Flow feature in the v4 runtime: start a feature with flow_run_start, make scoped changes, gather real validation evidence, obtain review payloads, and complete with flow_feature_complete."
+description: "Use when an approved Flow plan has a feature to implement, validate, or complete in the v4 runtime, and the work is scoped to one active feature. For planning a goal first use flow-plan; for the full goal-to-completion loop or resuming a session use flow."
 ---
 
 # Flow Run
@@ -1539,7 +1373,9 @@ If \`flow_run_start\` is unavailable, stop and tell the user to check that \`ope
 For broad validation research, risky changes, or unclear coverage, use
 \`../flow/references/parallel-orchestration.md\` to fan out named Flow workers.
 Use the mode-to-agent mapping in that reference instead of generic subagents.
-Workers must use the handoff format and verification gates from that reference.
+Write its pass manifest before fan-out, paste the matching handoff template
+from \`../flow/references/handoff-format.md\` into every worker prompt, and
+apply its verification tiers to the handoffs that come back.
 They may report command output they actually ran or propose focused checks; the
 manager decides what is strong enough to record.
 
@@ -1584,7 +1420,7 @@ If genuinely blocked, call \`flow_feature_complete\` with \`status: "needs_input
 // skills/flow-test/SKILL.md
 var SKILL_default7 = `---
 name: flow-test
-description: Test, validate, make test plans, triage failures, and gather Flow validation evidence. Use when selecting checks, running tests, running browser QA for UI changes, classifying failures, or preparing validationRun evidence for flow_feature_complete.
+description: Choose, run, and summarize validation checks for Flow features. Use when selecting validation coverage, running tests or browser/e2e QA, classifying test failures, or preparing validationRun evidence for flow_feature_complete. Visual design judgment stays in flow-ui-quality and review verdicts stay in flow-review.
 ---
 
 # Flow Test
@@ -1801,13 +1637,15 @@ Do not claim visual polish was verified if no visual artifact was inspected.
 // skills/flow-ui-quality/SKILL.md
 var SKILL_default8 = `---
 name: flow-ui-quality
-description: Review and improve frontend UI quality for Flow work. Use for UX/UI design, frontend polish, visual quality review, responsive and accessible interfaces, interaction states, screenshots, browser-verified UI work, and avoiding generic AI-generated UI.
+description: Review and improve frontend UI quality for Flow work. Use for UX/UI design, frontend polish, visual quality review, responsive and accessible interfaces, interaction states, screenshot assessment, and avoiding generic AI-generated UI. Browser-run mechanics and validationRun summaries stay in flow-test.
 ---
 
 # Flow UI quality
 
 Use this skill when Flow work changes what a user sees or how they interact with an interface. The goal is production UI quality: useful, coherent, accessible, responsive, and visually intentional.
 
+This is a helper skill: it contributes UI judgment and visual evidence only. The manager owns every state-changing \`flow_*\` call.
+
 ## Establish the interface intent
 
 - Identify the user, job-to-be-done, primary workflow, density needs, device constraints, and brand/product tone before choosing visuals.
@@ -1863,10 +1701,6 @@ var FLOW_SKILL_DEFINITIONS = [
         relativePath: "references/parallel-orchestration.md",
         content: parallel_orchestration_default
       },
-      {
-        relativePath: "references/parallel-pass-patterns.md",
-        content: parallel_pass_patterns_default
-      },
       {
         relativePath: "references/parallel-pass-example.md",
         content: parallel_pass_example_default
@@ -1874,10 +1708,6 @@ var FLOW_SKILL_DEFINITIONS = [
       {
         relativePath: "references/handoff-format.md",
         content: handoff_format_default
-      },
-      {
-        relativePath: "references/verification-gates.md",
-        content: verification_gates_default
       }
     ]
   },
@@ -2423,4 +2253,4 @@ main(process.argv).catch((error) => {
   process.exitCode = 1;
 });
 
-//# debugId=8ECEECE32879216C64756E2164756E21
+//# debugId=A231A45541CC089364756E2164756E21